NOM

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

SYNOPSIS

       #include <stdlib.h>

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

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

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

       strtoll() :
           _ISOC99_SOURCE
               || /* Versions de la glibc <= 2.19 : */ _SVID_SOURCE || _BSD_SOURCE

DESCRIPTION

       La  fonction  strtol()  convertit  la  partie initiale de 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 (tels que définis par isspace(3)) suivi d'un
       éventuel signe « + » ou « - ». Si base vaut 0 ou 16, la chaîne peut inclure un préfixe « 0x »  ou  « 0X »
       et  le  nombre  sera  interprété  en  base 16. Sinon, une base valant zéro est interprétée comme 10 (base
       décimale) sauf si le caractère suivant est « 0 », auquel cas la base est 8 (base octale).

       Le reste de la chaîne est converti en une valeur long, en s'arrêtant au premier caractère qui ne soit pas
       un  chiffre  autorisé  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 non valable dans  *endptr.  S'il
       n'y  avait  aucun  chiffre,  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
       valable.

       La fonction strtoll() fonctionne 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 prise en charge.

       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 0 renvoyé).

ATTRIBUTS

       Pour une explication des termes utilisés dans cette section, consulter attributes(7).

       ┌──────────────────────────────┬──────────────────────┬────────────────┐
       │Interface                     │ Attribut             │ Valeur         │
       ├──────────────────────────────┼──────────────────────┼────────────────┤
       │strtol(), strtoll(), strtoq() │ Sécurité des threads │ MT-Safe locale │
       └──────────────────────────────┴──────────────────────┴────────────────┘

CONFORMITÉ

       strtol() : POSIX.1-2001, POSIX.1-2008, C89, C99 SVr4, 4.3BSD.

       strtoll() : POSIX.1-2001, POSIX.1-2008, C99.

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.

       POSIX.1 spécifie que dans le cas de locales autres que « C » et « POSIX », ces fonctions peuvent accepter
       des chaînes numériques propres à l'implémentation.

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

EXEMPLES

       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: Argument non valable
           $ ./a.out ''
           Pas de chiffre trouvé
           $ ./a.out 4000000000
           strtol: Résultat numérique hors intervalle

   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]) : 0;

           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 != 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), strtoimax(3), strtoul(3),

COLOPHON

       Cette page fait partie de la publication 5.10 du projet man-pages Linux. Une description du projet et des
       instructions  pour  signaler  des  anomalies et la dernière version de cette page peuvent être trouvées à
       l'adresse https://www.kernel.org/doc/man-pages/.

TRADUCTION

       La  traduction  française   de   cette   page   de   manuel   a   été   créée   par   Christophe   Blaess
       <https://www.blaess.fr/christophe/>,   Stéphan   Rafin   <stephan.rafin@laposte.net>,   Thierry   Vignaud
       <tvignaud@mandriva.com>, François Micaux, Alain Portal  <aportal@univ-montp2.fr>,  Jean-Philippe  Guérard
       <fevrier@tigreraye.org>,   Jean-Luc   Coulon   (f5ibh)   <jean-luc.coulon@wanadoo.fr>,   Julien   Cristau
       <jcristau@debian.org>,     Thomas     Huriaux      <thomas.huriaux@gmail.com>,      Nicolas      François
       <nicolas.francois@centraliens.net>,     Florentin     Duneau    <fduneau@gmail.com>,    Simon    Paillard
       <simon.paillard@resel.enst-bretagne.fr>,    Denis    Barbier    <barbier@debian.org>,    David     Prévot
       <david@tilapin.org> et Grégoire Scano <gregoire.scano@malloc.fr>

       Cette  traduction  est  une  documentation libre ; veuillez vous reporter à la GNU General Public License
       version 3  ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩  concernant  les  conditions  de   copie   et   de
       distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

       Si  vous  découvrez  un  bogue  dans la traduction de cette page de manuel, veuillez envoyer un message à
       debian-l10n-french@lists.debian.org ⟨⟩.