strtol, strtoll, strtoq − Convertir une chaîne en un entier long.

#include <stdlib.h>

long int strtol (const char *nptr, char **endptr, int base);

long long int
strtoll(const char *nptr, char **endptr, int base);

La fonction strtol() convertit la chaîne nptr en un long int en fonction de l’argument base, qui doit être dans l’intervalle 2 à 36 (bornes comprises), ou avoir la valeur spéciale 0.

La chaîne peut commencer par un nombre quelconque d’espaces ou de caractères interprétés comme tels par isspace(3). Un signe éventuel « + » ou « − » peut suivre. Si base vaut 0 ou 16, la chaîne peut inclure un préfixe « 0x » et le nombre sera interprété en base 16. Sinon, une base valant zéro est interprétée comme 10 (décimale) sauf si le caractère suivant est « 0 », auquel cas la base est 8 (octale).

Le reste de la chaîne est converti en une valeur long int, en s’arrêtant au premier caractère qui ne soit pas un chiffre valide. Dans les bases supérieures à 10, la lettre « A » (majuscule ou minuscule) représente 10, « B » represente 11, et ainsi de suite jusqu’à « Z » représentant 35.

Si endptr n’est pas NULL, strtol() stocke l’adresse du premier caractère invalide dans *endptr. S’il n’y avait aucun chiffre valide, strtol() stocke la valeur originale de nptr dans *endptr (et renvoie 0). En particulier, si *nptr n’est pas « \0 » et si **endptr vaut « \0 » en retour, la chaîne entière est valide.

La fonction strtoll() travaille comme strtol() mais renvoie une valeur entière de type "long long".

La fonction strtol() renvoie le résultat de la conversion, à moins qu’un débordement superieur (overflow) ou inférieur (underflow) se produise. Si un dépassement inférieur se produit, strtol() renvoie LONG_MIN. Si un dépassement supérieur se produit, strtol() renvoie LONG_MAX. Dans les deux cas, errno contient le code d’erreur ERANGE. La même chose est vraie pour strtoll() avec LLONG_MIN et LLONG_MAX à la place de LONG_MIN et LONG_MAX.

EINVAL

(pas dans C99) La base donnée n’est pas supportée.

ERANGE

La chaîne n’était pas dans l’intervalle acceptable, la valeur a été arrondie.

L’implémentation peut aussi mettre errno à EINVAL si aucune conversion n’a été réalisée (pas de chiffres trouvés, et renvoyé zéro).

Puisque strtol() peut légitimement renvoyer 0, LONG_MAX ou LONG_MIN (LLONG_MAX ou LLONG_MIN pour strtoll()) en cas d’échec ou dee succès, le programme appelant devrait écrire 0 dans errno avant l’appel et déterminer si une erreur est survenue en vérifiant si errno à une valeur non nulle après l’appel.

Dans des localisations autre que « C », d’autres chaînes peuvent être acceptées. (Par exemple, un signe séparateur de milliers peut être accepté).

BSD a aussi

quad_t
strtoq(const char *nptr, char **endptr, int base);

avec une définition exactement analogue. Suivant l’architecture, cela peut être équivalent à strtoll() ou strtol().

strol() est conforme à SVr4, BSD 4.3, C99 et POSIX.1-2001, et strtoll() à C99 et POSIX.1-2001.

Le programme suivant montre l’utilisation de strtol(). Le premier argument de la ligne de commande spécifie une chaîne dans laquelle strtol() analysera un nombre. Le second argument, optionnel, spécifie la base à utiliser pour la conversion. (Cet argument est converti sous forme numérique avec atoi(3), une fonction qui n’effectue aucune vérification d’erreur et qui a une strtol().) Voici plusieurs exemples de résultats produits par ce programme :

$ ./a.out 123
strtol() a renvoyé 123
$ ./a.out ’    123’
strtol() a renvoyé 123
$ ./a.out 123abc
strtol() a renvoyé 123
Plusieurs caractères après le nombre : abc
$ ./a.out 123abc 55
strtol: Argument invalide
$ ./a.out ’’
Aucun chiffre trouvé
$ ./a.out 4000000000
strtol: Résultat numérique hors intervalle

Le code source du programme est le suivant :

#include <stdlib.h>
#include <limits.h>
#include <stdio.h>
#include <errno.h>

int
main(int argc, char *argv[])
{
    int base;
    char *endptr, *str;
    long val;

   if (argc < 2) {
        fprintf(stderr, "Usage: %s str [base]\n", argv[0]);
        exit(EXIT_FAILURE);
    }

   str = argv[1];
    base = (argc > 2) ? atoi(argv[2]) : 10;

   errno = 0;    /* To distinguish success/failure after call */
    val = strtol(str, &endptr, base);

   /* Check for various possible errors */

   if ((errno == ERANGE && (val == LONG_MAX || val == LONG_MIN))
            || (errno != 0 && val == 0)) {
        perror("strtol");
        exit(EXIT_FAILURE);
    }

   if (endptr == str) {
        fprintf(stderr, "Aucun chiffre trouvé\n");
        exit(EXIT_FAILURE);
    }

   /* If we got here, strtol() successfully parsed a number */
    printf("strtol() a renvoyé %ld\n", val);

   if (*endptr != ’\0’)        /* Not necessarily an error... */
        printf("Plusieurs caractères après le nombre : %s\n", endptr);

   exit(EXIT_SUCCESS);
}

atof(3), atoi(3), atol(3), strtod(3), strtoul(3)

Ce document est une traduction réalisée par Christophe Blaess <http://www.blaess.fr/christophe/> le 10 novembre 1996 et révisée le 14 août 2006.

L’équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 3 strtol ». N’hésitez pas à signaler à l’auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.