Provided by: manpages-fr-dev_4.13-4_all bug

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.

         •    Un caractère modificateur de type optionnel. Par exemple, le modificateur de type l
              est utilisé avec  les  conversions  d'entrée  telles  que  %d  pour  spécifier  que
              l'argument  pointeur correspondant fait référence à un long plutôt qu'à un pointeur
              sur un 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      Indique  que  la  conversion  sera de type d, i, o, u, x, X ou n et que le pointeur
              suivant est un pointeur sur un short ou un unsigned short (plutôt que sur un 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      Indique que la conversion sera de type d, i, o, u, x, X ou n  et  que  le  pointeur
              suivant est un pointeur sur un long ou un unsigned long (plutôt que sur un int), ou
              que la conversion sera de type e, f ou g et que le pointeur suivant est un pointeur
              sur  un double (plutôt que sur un float). Indiquer deux caractères l successifs est
              équivalent à indiquer L. Si c'est utilisé avec %c ou %s, le paramètre correspondant
              est  considéré,  respectivement,  comme  un pointeur vers un caractère large ou une
              chaîne de caractères larges.

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

       ┌─────────────────────┬──────────────────────┬────────────────┐
       │InterfaceAttributValeur         │
       ├─────────────────────┼──────────────────────┼────────────────┤
       │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 ⟨⟩.