Loading

NOM

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

SYNOPSIS

       #include <stdlib.h>

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

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

   Exigences  de  macros  de  test  de  fonctionnalités  pour  la  glibc (voir
   feature_test_macros(7)) :

       strtoll() : XOPEN_SOURCE >= 600 || _BSD_SOURCE || _SVID_SOURCE ||
       _ISOC99_SOURCE ; ou cc -std=c99

       La  fonction  strtol()  convertit  la  chaîne nptr en un entier long 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
       cette base. Dans les bases supérieures à 10, la lettre « A » (majuscule
       ou  minuscule)  représente  10,  « B » représente 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".

VALEUR RENVOYÉE

       La  fonction  strtol()  renvoie  le  résultat de la conversion, à moins
       qu’un débordement supérieur  (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.

ERREURS

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

       ERANGE La valeur retournée est hors limites.

       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).

CONFORMITÉ

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

NOTES

       Comme  strtol()  peut  légitimement  renvoyer  0,  LONG_MAX ou LONG_MIN
       (LLONG_MAX ou LLONG_MIN pour strtoll()) à la fois en cas de  succès  et
       d’échec,  le  programme  appelant  doit  positionner  errno  à  0 avant
       l’appel, et déterminer si une erreur s’est  produite  en  vérifiant  si
       errno a 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().

EXEMPLE

       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 interface plus simple que 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
           Caractères trouvés après le nombre : abc
           $ ./a.out 123abc 55
           strtol: Invalid argument
           $ ./a.out ''
           Pas de chiffre trouvé
           $ ./a.out 4000000000
           strtol: Numerical result out of range

   Source du programme

       #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;    /* Pour distinguer la réussite/échec après l’appel */
           val = strtol(str, &endptr, base);

           /* Vérification de certaines erreurs possibles */

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

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

           /* Si nous sommes ici, strtol() a analysé un nombre avec succès */

           printf("strtol() a renvoyé %ld\n", val);

           if (*endptr != '\0')        /* Pas nécessairement une erreur... */
               printf("Caractères trouvés après le nombre : %s\n", endptr);

           exit(EXIT_SUCCESS);
       }

VOIR AUSSI

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

COLOPHON

       Cette page fait partie de  la  publication  3.23  du  projet  man-pages
       Linux.  Une description du projet et des instructions pour signaler des
       anomalies      peuvent      être       trouvées       à       l’adresse
       http://www.kernel.org/doc/man-pages/.

TRADUCTION

       Cette  page  de  manuel  a  été  traduite et mise à jour par Christophe
       Blaess <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis  par
       Alain  Portal  <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et mise à
       disposition sur http://manpagesfr.free.fr/.

       Les mises à jour et corrections de la version présente dans Debian sont
       directement         gérées         par         Nicolas         François
       <nicolas.francois@centraliens.net>   et   l’équipe    francophone    de
       traduction de Debian.

       Veuillez   signaler   toute   erreur   de   traduction  en  écrivant  à
       <debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
       paquet manpages-fr.

       Vous  pouvez  toujours avoir accès à la version anglaise de ce document
       en utilisant la commande « man -L C <section> <page_de_man> ».