scanf

SCANF(3)                   Manuel du programmeur Linux                  SCANF(3)



NOM
       scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - Entrées formatées

SYNOPSIS
       #include <stdio.h>

       int scanf(const char *format, ...);
       int fscanf(FILE *flux, const char *format, ...);
       int sscanf(const char *chaîne, const char *format, ...);

       #include <stdarg.h>

       int vscanf(const char *format, va_list ap);
       int vsscanf(const char *chaîne, const char *format, va_list ap);
       int vfscanf(FILE *flux, const char *format, va_list ap);

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

       vscanf(), vsscanf(), vfscanf() :
           _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L

DESCRIPTION
       Les fonctions de la famille scanf() analysent leurs entrées conformément
       au format décrit plus bas. Ce format peut contenir des indicateurs de
       conversion. Les résultats des conversions, s'il y en a, sont stockés dans
       des endroits pointés par des arguments pointeurs qui suivent le format.
       Chaque argument pointeur doit être du type approprié pour la valeur
       retournée par la spécification de conversion correspondante.

       Si le nombre de spécifications de conversion dans format excède le nombre
       d'arguments pointeur, le résultat est indéterminé. Si le nombre
       d'arguments pointeur excède le nombre de spécifications de conversion,
       les arguments pointeur en excès sont évalués mais ignorés.

       La fonction scanf() lit ses données depuis le flux d'entrée standard
       stdin, fscanf() lit ses entrées depuis le flux pointé par flux, et
       sscanf() lit ses entrées dans la chaîne de caractères pointée par chaîne.

       La fonction vfscanf() est analogue à vfprintf(3) et lit ses arguments
       depuis le flux pointé par flux en utilisant une liste variable
       d'arguments pointeurs, consultez stdarg(3). La fonction vscanf() examine
       l'entrée standard en utilisant une liste variable d'arguments pointeurs
       et la fonction vsscanf() examine une chaîne. Elles sont respectivement
       analogues aux fonctions vprintf(3) et vsprintf(3).

       La chaîne format consiste en une séquence de directives qui décrit
       comment traiter la séquence des caractères d'entrée. Si le traitement des
       directives échoue, aucune autre entrée n'est lue et scanf() renvoie. Un
       « échec » peut être soit un échec d'entrée signifiant que les caractères
       d'entrée ne sont pas disponibles, soit un échec de correspondance
       signifiant que l'entrée n'est pas appropriée (voir plus loin).

       Une directive peut être :

       •      Une séquence de caractères blancs (espace, tabulation, nouvelle
              ligne, etc. ; consultez isspace(3)). Cette directive correspond à
              un nombre quelconque de caractères blancs, y compris aucun, dans
              l'entrée.

       •      Un caractère ordinaire (c'est-à-dire autre qu'un caractère blanc
              et que le caractère « % ». Ce caractère doit exactement
              correspondre au caractère suivant de l'entrée.

       •      Une spécification de conversion qui débute avec le caractère
              « % ». Une séquence de caractères de l'entrée est convertie
              conformément à la spécification et le résultat est placé dans
              l'argument pointeur correspondant. Si l'élément suivant de
              l'entrée ne correspond pas à la spécification de conversion, la
              conversion échoue — c'est un échec de correspondance.

       Chaque spécification de conversion dans format commence soit avec le
       caractère « % », soit avec la séquence de caractères « %n$ » (voir plus
       loin pour la distinction) suivie par :

       •      Un caractère d'affectation-suppression optionnel « * » : scanf()
              lit l'entrée comme indiqué par la spécification de conversion mais
              ne tient pas compte de l'entrée. Aucun argument pointeur n'est
              nécessaire et cette spécification n'est pas comptabilisée dans le
              nombre d'affectations réussies renvoyé par scanf().

       •      Pour les conversions décimales, un caractère apostrophe « ' ». Il
              indique que le nombre en entrée peut comporter des séparateurs de
              milliers tels que défini par la catégorie LC_NUMERIC de la locale
              courante. Le caractère apostrophe peut précéder ou suivre le
              caractère d'affectation-suppression « * ».

       •      Un caractère « m » optionnel. Il est utilisé dans les conversions
              de chaînes (%s, %c, %[) et soulage l'appelant du besoin d'allouer
              un tampon correspondant pour conserver l'entrée : à la place,
              scanf() alloue un tampon de taille suffisante et affecte l'adresse
              de ce tampon à l'argument pointeur correspondant qui doit être un
              pointeur vers une variable char * (il n'est pas nécessaire que
              cette variable soit initialisée avant l'appel). L'appelant doit
              par la suite libérer (free(3)) ce tampon lorsqu'il devient
              inutile.

       •      Un entier décimal optionnel qui indique la taille maximum du
              champ. La lecture des caractères s'arrête, soit lorsque ce maximum
              est atteint, soit lorsqu'on trouve un caractère qui ne correspond
              pas, quelque soit la condition vérifiée en premier. La plupart des
              conversions abandonnent les caractères blancs de tête (les
              exceptions sont notées plus loin), et ces caractère abandonnés
              n'entrent pas en compte dans la taille maximale du champ. Les
              conversions d'entrée de chaînes stocke un octet NULL final
              (« \0 ») pour marquer la fin de l'entrée ; la largeur maximale du
              champ n'inclut pas ce caractère de terminaison.

       •      An optional type modifier character.  For example, the l type
              modifier is used with integer conversions such as %d to specify
              that the corresponding pointer argument refers to a long rather
              than a pointer to an int.

       •      Un spécificateur de conversion qui spécifie le type de conversion
              d'entrée à effectuer.

       Les spécifications de conversion dans format sont de deux formes : soit
       elles commencent par « % », soit elles commencent par « %n$ ». Les deux
       formes ne doivent pas être mélangées dans la même chaîne format, excepté
       qu'une chaîne contenant les spécifications « %n$ » peut inclure %% et %*.
       Si format contient des spécifications « % », celles-ci correspondent,
       dans l'ordre, aux arguments pointeur successifs. Dans la forme « %n$ »
       (qui est spécifiée par POSIX.1-2001 mais pas par C99), n est un entier
       décimal qui spécifie que l'entrée convertie devrait être placée à
       l'endroit référencé par le n-ième argument pointeur suivant format.

   Conversions
       Les caractères modificateurs de type suivant peuvent se apparaître dans
       une spécification de conversion :

       h      Indicates that the conversion will be one of d, i, o, u, x, X, or
              n and the next pointer is a pointer to a short or unsigned short
              (rather than int).

       hh     Comme pour h, sauf que le pointeur suivant est un pointeur sur un
              signed char ou un unsigned char.

       j      Comme pour h, sauf que le pointeur suivant est un pointeur sur un
              intmax_t ou un uintmax_t. Ce modificateur a été introduit dans
              C99.

       l      Indicates either that the conversion will be one of d, i, o, u, x,
              X, or n and the next pointer is a pointer to a long or unsigned
              long (rather than int), or that the conversion will be one of e,
              f, or g and the next pointer is a pointer to double (rather than
              float).  Specifying two l characters is equivalent to L.  If used
              with %c or %s, the corresponding parameter is considered as a
              pointer to a wide character or wide-character string respectively.

       L      Indique que la conversion sera de type e, f ou g et que le
              pointeur suivant est un pointeur sur un long double ou que la
              conversion sera de type d, i, o, u, ou x et que le pointeur
              suivant est un pointeur sur un long long.

       q      Est équivalent à L. Ce spécificateur n'existe pas en C ANSI.

       t      Comme pour h, mais le pointeur suivant est un pointeur vers un
              ptrdiff_t. Ce modificateur a été introduit dans C99.

       z      Comme pour h, mais le pointeur suivant est un pointeur vers un
              size_t. Ce modificateur a été introduit dans C99.

       Les spécificateurs de conversion suivant sont disponibles :

       %      Correspond à un caractère « % ». Ceci signifie qu'un spécificateur
              %% dans la chaîne de format correspond à un seul caractère « % »
              dans la chaîne d'entrée. Aucune conversion (mais les caractères
              blancs de début sont ignorés) et aucune affectation n'a lieu.

       d      Correspond à un entier décimal éventuellement signé, le pointeur
              correspondant doit être un pointeur vers un int.

       i      Correspond à un entier éventuellement signé. Le pointeur suivant
              doit être du type int. L'entier est en base 16 (hexadécimal) s'il
              commence par 0x ou 0X, en base 8 (octal) s'il commence par un 0,
              et en base 10 sinon. Seuls les caractères correspondants à la base
              concernée sont utilisés.

       o      Correspond à un entier octal non signé. Le pointeur correspondant
              doit être un pointeur vers un unsigned int.

       u      Correspond à un entier décimal non signé. Le pointeur suivant doit
              être un pointeur vers un unsigned int.

       x      Correspond à un entier hexadécimal non signé. Il peut
              éventuellement commencer par le préfixe 0x ou 0X qui sera alors
              écarté. Le pointeur suivant doit être un pointeur vers un unsigned
              int.

       X      Équivalent à x.

       f      Correspond à un nombre réel éventuellement signé. Le pointeur
              correspondant doit être un pointeur vers un float.

       e      Équivalent à f.

       g      Équivalent à f.

       E      Équivalent à f.

       a      (C99) Équivalent à f.

       s      Correspond à une séquence de caractères différents des caractères
              blancs. Le pointeur suivant doit être un pointeur sur un tableau
              de caractères qui doit être assez large pour accueillir toute la
              séquence d'entrée, ainsi que l'octet NULL final (« \0 ») qui est
              ajouté automatiquement. La conversion s'arrête soit au premier
              caractère blanc, soit à la longueur maximale du champ, quelle que
              soit la condition vérifiée en premier.

       c      Correspond à une séquence de caractères dont la longueur est
              spécifiée par la largeur maximum de champ (par défaut 1). Le
              pointeur suivant doit être un pointeur vers un caractère, et il
              doit y avoir suffisamment de place dans la chaîne pour tous les
              caractères. Aucun octet NULL final n'est ajouté. Les caractères
              blancs de début ne sont pas supprimés. Si on veut les éliminer, il
              faut utiliser une espace dans le format.

       [      Correspond à une séquence non vide de caractères appartenant à un
              ensemble donné. Le pointeur correspondant doit être un pointeur
              vers un caractère et il doit y avoir suffisamment de place dans le
              tableau de caractères pour accueillir la chaîne ainsi qu'un octet
              nul final. Les caractères blancs du début ne sont pas supprimés.
              La chaîne est constituées de caractères inclus ou exclus d'un
              ensemble donné. L'ensemble est composé des caractères compris
              entre les deux crochets [ et ]. L'ensemble exclut ces caractères
              si le premier après le crochet ouvrant est un accent circonflexe
              (^). Pour inclure un crochet fermant dans l'ensemble, il suffit de
              le placer en première position après le crochet ouvrant ou
              l'accent circonflexe ; à tout autre emplacement, il servira à
              terminer l'ensemble. Le caractère tiret - a également une
              signification particulière. Quand il est placé entre deux autres
              caractères, il ajoute à l'ensemble tous les caractères
              intermédiaires. Pour inclure un tiret dans l'ensemble, il faut le
              placer en dernière position avant le crochet fermant. Par exemple,
              [^]0-9-] correspond à l'ensemble « tout sauf le crochet fermant,
              les chiffres de 0 à 9 et le tiret ». La chaîne se termine dès
              l'occurrence d'un caractère exclu (ou inclus s'il y a un accent
              circonflexe ) de l'ensemble ou dès qu'on atteint la longueur
              maximale du champ.

       p      Correspond à une valeur de pointeur (comme affichée par %p dans
              printf(3). Le pointeur suivant doit être un pointeur sur un
              pointeur sur void.

       n      Aucune lecture n'est faite. Le nombre de caractères déjà lus est
              stocké dans le pointeur suivant, qui doit être un pointeur vers un
              int. Il ne s'agit pas d'une conversion et le compteur
              d'assignations renvoyé à la fin de l'exécution n'est pas
              incrémente. L'assignation peut être supprimée par le caractère
              d'assignation-suppression *, mais l'effet sur la valeur renvoyée
              n'est alors pas définit. Par conséquent, les conversions %*n ne
              devraient pas être utilisées.

VALEUR RENVOYÉE
       En cas de succès, ces fonctions renvoient le nombre d'éléments d'entrées
       correctement mis en correspondance et affectés. Ce nombre peut être plus
       petit que le nombre d'éléments attendus, et même être nul, dans le cas
       d'une erreur précoce de mise en correspondance.

       La valeur EOF est renvoyée si la fin de l'entrée est atteinte avant la
       première conversion réussie ou si un échec de correspondance survient.
       EOF est également renvoyé si une erreur de lecture survient, auquel cas
       l'indicateur d'erreur pour le flux (consultez ferror(3)) est positionné
       et errno est remplie en conséquence

ERREURS
       EAGAIN Le descripteur de fichier flux sous-jacent est non bloquant et
              l'opération de lecture bloquerait.

       EBADF  Le descripteur de fichier flux sous-jacent n'est pas valide ou
              bien n'est pas ouvert en lecture.

       EILSEQ La séquence d'octet en entrée ne constitue pas un caractère
              valable.

       EINTR  La lecture a été interrompue par un signal ; consultez signal(7).

       EINVAL Pas suffisamment de paramètres ; ou bien format est NULL.

       ENOMEM Plus assez de mémoire.

       ERANGE Le résultat de la conversion entière est plus grand que la taille
              pouvant être stockée dans le type entier correspondant.

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

       ┌─────────────────────┬──────────────────────┬────────────────┐
       │Interface            Attribut             Valeur         │
       ├─────────────────────┼──────────────────────┼────────────────┤
       │scanf(), fscanf(),   │ Sécurité des threads │ MT-Safe locale │
       │sscanf(), vscanf(),  │                      │                │
       │vsscanf(), vfscanf() │                      │                │
       └─────────────────────┴──────────────────────┴────────────────┘

CONFORMITÉ
       Les fonctions fscanf(), scanf(), et sscanf() sont conformes à C89, C99 et
       POSIX.1-2001. Ces normes ne spécifient pas l'erreur ERANGE.

       Le spécificateur q est une notation BSD 4.4 pour long long, alors que ll
       ou l'utilisation de L dans les conversions entières sont des notations
       GNU.

       Les versions Linux de ces fonctions sont basées sur la bibliothèque libio
       GNU. Jetez un œil sur la documentation info de la libc GNU (glibc-1.08)
       pour une description complète.

NOTES
   Le modificateur d'affectation-allocation « a »
       Initialement, la bibliothèque C de GNU prenait en charge l'allocation
       dynamique des chaînes de caractères en entrée (comme une extension non
       standard) au moyen du caractère a (cette fonctionnalité remonte au moins
       à la version 2.0 de la glibc). Ainsi, il était possible, grâce au code
       suivant, de faire que scanf() alloue un tampon pour une chaîne en entrée,
       et renvoie un pointeur vers ce tampon dans *buf:

           char *buf;
           scanf("%as", &buf);

       L'utilisation de la lettre a dans ce but posait problème étant donné que
       a est également synonyme de f dans le standard ISO C (entrée de nombre à
       virgule flottante). POSIX.1-2008 spécifie en revanche que le modificateur
       m doit être utilisée pour l'affectation allocation (comme indiqué dans la
       DESCRIPTION plus haut).

       Notez que le modificateur a n'est pas disponible si le programme a été
       compilé avec gcc -std=c99 ou gcc -D_ISOC99_SOURCE (à moins que
       _GNU_SOURCE n'ait également été indiqué), auquel cas a est interprété
       comme un spécificateur de nombres en virgule flottante (voir plus haut).

       Le modificateur m est pris en charge depuis la version 2.7 de la glibc et
       les nouveaux programmes doivent utiliser ce modificateur plutôt que a.

       En plus d'être un standard de POSIX, le modificateur m présente les
       avantages suivants par rapport au modificateur a :

       * Il peut être appliqué aux spécificateurs de conversion %c (par exemple
         %3mc).

       * Il lève toute ambiguité avec le spécificateur de conversion en virgule
         flottante %a (et n'est pas affecté par gcc -std=c99 etc.).

BOGUES
       Toutes ces fonctions sont totalement conformes à C89, mais lui ajoutent
       les spécificateurs q et a ainsi que les comportements supplémentaires des
       spécificateurs L et l. Ce derniers doivent être considérés comme des
       bogues, car ils modifient le comportement de spécificateurs définis dans
       C89.

       Certaines combinaisons de modificateurs de type et de spécificateurs de
       conversion définis par le C ANSI n'ont pas de sens (par exemple %Ld).
       Bien qu'elles aient un comportement bien défini sous Linux, ce n'est peut
       être pas le cas sur d'autres architectures. Il vaut donc mieux n'utiliser
       que des modificateurs définis en C ANSI, c'est-à-dire, utilisez q à la
       place de L avec les conversions d, i, o, u, x et X ou ll.

       L'utilisation q n'est pas la même sous BSD 4.4, car il peut être utilisé
       avec des conversions de réels de manière équivalente à L. [NDT] La
       conversion %s devrait toujours être accompagnée d'une longueur maximale
       de chaîne de caractères. En effet, il existe un risque de débordement de
       tampon, qui peut conduire à un trou de sécurité important dans un
       programme setuid ou setgid.

EXEMPLES
       Pour utiliser l'indicateur de conversion d'allocation dynamique, indiquez
       m comme modificateur de longueur (par conséquent %ms ou %m[range]).
       L'appelant doit libérer (free(3)) l'espace occupé par la chaîne renvoyée,
       comme dans l'exemple suivant :

           char *p;
           int n;

           errno = 0;
           n = scanf("%m[a-z]", &p);
           if (n == 1) {
               printf("read: %s\n", p);
               free(p);
           } else if (errno != 0) {
               perror("scanf");
           } else {
               fprintf(stderr, "Pas de caractères correspondants\n");
           }

       Comme montré dans cet exemple, il n'est nécessaire d'appeler free(3) que
       si l'appel à scanf() a réussi à lire une chaîne.

VOIR AUSSI
       getc(3), printf(3), setlocale(3), strtod(3), strtol(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>, Frédéric Hantrais
       <fhantrais@gmail.com> 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 ⟨⟩.




GNU                               13 août 2020                          SCANF(3)