Provided by: manpages-fr-dev_3.32d0.2p4-1_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 *stream, const char *format, ...);
       int sscanf(const char *str, const char *format, ...);

       #include <stdarg.h>

       int vscanf(const char *format, va_list ap);
       int vsscanf(const char *str, const char *format, va_list ap);
       int vfscanf(FILE *stream, const char *format, va_list ap);

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

       vscanf(), vsscanf(), vfscanf() :
           _XOPEN_SOURCE >= 600 || _ISOC99_SOURCE ||
           _POSIX_C_SOURCE >= 200112L
           ou cc -std=c99

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 stream, et
       sscanf() lit ses entrées dans la chaîne de caractères pointée par str.

       La fonction vfscanf() est analogue à vfprintf(3) et lit  ses  arguments
       depuis  le  flux  pointé  par  stream  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
       comme 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() revient. Un
       « échec »  peut  être  soit  un  chec  d'entre  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  spcification  de  conversion dans format commence avec soit le
       caractère « % », soit 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().

       ·      Un   caractère   « a »   optionnel.  Il  est  utilisé  dans  les
              conversions de chaînes 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.  Ceci  est  une extension GNU ; C99
              emploie le caractère « a » comme un spécificateur de  conversion
              (il   peut   également   être  utilisé  en  tant  que  tel  dans
              l'implémentation GNU).

       ·      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 lorsque on trouve un caractère qui  ne
              correspond  pas,  celui  qui  arrive  le 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 de terminaison
              nul (« \0 ») pour  marquer  la  fin  de  l'entrée ;  la  largeur
              maximale du champ n'inclut pas ce caractère de terminaison.

       ·      Un  caractre  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  int  plutôt  qu'à  un
              pointeur sur un int.

       ·      Un   spcificateur   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 caractres 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 int ou un
              unsigned short int (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  int  ou  un
              unsigned  long int (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 spcificateurs 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
              assignation n'a lieu.

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

       D      Équivalent  à ld, utilisé uniquement pour compatibilité avec des
              versions précédentes (et seulement dans  libc4.  Dans  libc5  et
              glibc,   le  %D  est  ignoré  silencieusement,  ce  qui  conduit
              d'anciens programmes à échouer mystérieusement).

       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é.  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  correspondant  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
              nul final (« \0 ») qui est ajouté automatiquement. La conversion
              s'arrête  au  premier caractère blanc, ou à la longueur maximale
              du champ.

       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 char, et il  doit
              y  avoir  suffisamment  de  place  dans  la chaîne pour tous les
              caractères. Aucun octet nul 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 char 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  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 à 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 correspondant, qui doit être un pointeur
              vers  un int. Ce n'est pas une conversion, mais le stockage peut
              quand    même    être     supprimé     avec     le     caractère
              d'affectation-suppression    *.    Le   standard   C   indique :
              « L'exécution d'une directive %n n'incrémente  pas  le  compteur
              d'assignations renvoyé à la fin de l'exécution ». Mais il semble
              qu'il y ait des contradictions sur ce point. Il est probablement
              sage  de  ne  pas  faire  de  suppositions  sur  l'effet  de  la
              conversion %n sur la valeur renvoyée.

VALEUR RENVOYÉE

       Ces fonctions renvoient le nombre d'éléments d'entrées correctement mis
       en  correspondance  et  assignés. Ce nombre peut être plus petit que le
       nombre d'éléments attendus, et même être nul, s'il y a  une  erreur  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 stream sous-jacent est non bloquant et
              l'opération de lecture bloquerait.

       EBADF  Le descripteur de fichier stream 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 de mémoire disponible.

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

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

       Pour  utiliser  cette  fonctionnalité, indiquez a comme modificateur de
       longueur (par conséquent %as ou  %a[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("%a[a-z]", &p);
           if (n == 1) {
               printf("read: %s\n", p);
               free(p);
           } else if (errno != 0) {
               perror("scanf");
           } else {
               fprintf(stderr, "No matching characters\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.

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

       Depuis la version 2.7, la glibc fournit aussi le  modificateur  m  pour
       faire  la  même  chose  que  le modificateur a. Le modificateur m a les
       avantages suivants :

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

       * Il est spécifié dans la version POSIX.1 à venir.

BOGUES

       Toutes ces fonctions sont totalement conformes à C89, mais lui ajoutent
       les  spécificateurs  q et a ainsi que des 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.

VOIR AUSSI

       getc(3), printf(3), setlocale(3), strtod(3), strtol(3), strtoul(3)

COLOPHON

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

TRADUCTION

       Depuis 2010, cette traduction est maintenue à l'aide  de  l'outil  po4a
       <URL:http://po4a.alioth.debian.org/>   par   l'équipe   de   traduction
       francophone       au       sein        du        projet        perkamon
       <URL:http://perkamon.alioth.debian.org/>.

       Christophe  Blaess  <URL:http://www.blaess.fr/christophe/> (1996-2003),
       Alain  Portal  <URL:http://manpagesfr.free.fr/>  (2003-2006).   Nicolas
       François et l'équipe francophone de traduction de Debian (2006-2009).

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