Provided by: manpages-fr-dev_3.27fr1.4-1_all bug

NOM

       scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - Entrees formatees

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 fonctionnalites 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  entrees
       conformement au format decrit plus bas. Ce  format  peut  contenir  des
       indicateurs  de conversion. Les resultats des conversions, s'il y en a,
       sont stockes dans des endroits pointes par des arguments pointeurs  qui
       suivent le format. Chaque argument pointeur doit etre du type approprie
       pour  la  valeur  retournee  par   la   specification   de   conversion
       correspondante.

       Si  le  nombre  de  specifications  de conversion dans format excede le
       nombre d'arguments pointeur, le resultat est indetermine. Si le  nombre
       d'arguments  pointeur excede le nombre de specifications de conversion,
       les arguments pointeur en exces sont evalues mais ignores.

       La fonction scanf() lit ses donnees depuis le  flux  d'entree  standard
       stdin,  fscanf()  lit  ses entrees depuis le flux pointe par stream, et
       sscanf() lit ses entrees dans la chaine de caracteres pointee par str.

       La fonction vfscanf() est analogue a vfprintf(3) et lit  ses  arguments
       depuis  le  flux  pointe  par  stream  en  utilisant une liste variable
       d'arguments  pointeurs,  consultez  stdarg(3).  La  fonction   vscanf()
       examine  l'entree  standard en utilisant une liste variable d'arguments
       pointeurs et la fonction  vsscanf()  examine  une  chaine.  Elles  sont
       respectivement analogues aux fonctions vprintf(3) et vsprintf(3).

       La  chaine  format  consiste  en  une sequence de directives qui decrit
       comme traiter la sequence des caracteres d'entree. Si le traitement des
       directives echoue, aucune autre entree n'est lue et scanf() revient. Un
       << echec >> peut  etre  soit  un  'echec  d'entr'ee  signifiant  que  les
       caracteres   d'entree  ne  sont  pas  disponibles,  soit  un  'echec  de
       correspondance signifiant que l'entree n'est pas appropriee (voir  plus
       loin)

       Une directive peut etre :

       o      Une  sequence de caracteres blancs (espace, tabulation, nouvelle
              ligne, etc. ; consultez isspace(3)). Cette directive  correspond
              a  un  nombre  quelconque de caracteres blancs, y compris aucun,
              dans l'entree.

       o      Un caractere ordinaire (c'est-a-dire autre qu'un caractere blanc
              et  que  le  caractere  << % >>.  Ce  caractere  doit exactement
              correspondre au caractere suivant de l'entree.

       o      Une specification de conversion qui  debute  avec  le  caractere
              << % >>.  Une  sequence  de caracteres de l'entree est convertie
              conformement a la specification et le resultat  est  place  dans
              l'argument  pointeur  correspondant.  Si  l'element  suivant  de
              l'entree ne correspond pas a la specification de conversion,  la
              conversion echoue -- c'est un 'echec de correspondance.

       Chaque  sp'ecification  de  conversion dans format commence avec soit le
       caractere << % >>, soit la sequence de caracteres << %n$ >> (voir  plus
       loin pour la distinction) suivie par :

       o      Un   caractere   d'affectation-suppression  optionnel  << * >> :
              scanf() lit l'entree  comme  indique  par  la  specification  de
              conversion  mais ne tient pas compte de l'entree. Aucun argument
              pointeur n'est  necessaire  et  cette  specification  n'est  pas
              comptabilisee dans le nombre d'affectations reussies renvoye par
              scanf().

       o      Un  caractere  << a >>  optionnel.  Il  est  utilise  dans   les
              conversions de chaines et soulage l'appelant du besoin d'allouer
              un tampon correspondant pour conserver l'entree :  a  la  place,
              scanf()  alloue  un  tampon  de  taille  suffisante  et  affecte
              l'adresse de ce tampon a l'argument pointeur  correspondant  qui
              doit  etre  un  pointeur  vers une variable char * (il n'est pas
              necessaire que cette variable soit initialisee  avant  l'appel).
              L'appelant  doit  par  la  suite  liberer  (free(3))  ce  tampon
              lorsqu'il devient inutile. Ceci  est  une  extension  GNU ;  C99
              emploie   le   caractere   << a >>  comme  un  specificateur  de
              conversion (il peut egalement etre utilise en tant que tel  dans
              l'implementation GNU).

       o      Un  entier  decimal  optionnel  qui indique la taille maximum du
              champ. La  lecture  des  caracteres  s'arrete  soit  lorsque  ce
              maximum  est atteint, soit lorsque on trouve un caractere qui ne
              correspond pas, celui qui arrive  le  premier.  La  plupart  des
              conversions  abandonnent  les  caracteres  blancs  de  tete (les
              exceptions sont notees plus loin), et ces  caractere  abandonnes
              n'entrent  pas  en  compte dans la taille maximale du champ. Les
              conversions d'entree de chaines stocke un octet  de  terminaison
              nul  (<< \0 >>)  pour  marquer  la  fin de l'entree ; la largeur
              maximale du champ n'inclut pas ce caractere de terminaison.

       o      Un caract`ere modificateur de type  optionnel.  Par  exemple,  le
              modificateur de type l est utilise avec les conversions d'entree
              telles  que  %d   pour   specifier   que   l'argument   pointeur
              correspondant  fait  reference  a  un  long  int  plutot qu'a un
              pointeur sur un int.

       o      Un  sp'ecificateur  de  conversion  qui  specifie  le   type   de
              conversion d'entree a effectuer.

       Les specifications de conversion dans format sont de deux formes : soit
       elles commencent par << % >>, soit elles commencent par << %n$ >>.  Les
       deux  formes  ne doivent pas etre melangees dans la meme chaine format,
       excepte qu'une  chaine  contenant  les  specifications  << %n$ >>  peut
       inclure  %%  et  %*.  Si  format  contient  des specifications << % >>,
       celles-ci  correspondent,  dans   l'ordre,   aux   arguments   pointeur
       successifs. Dans la forme << %n$ >> (qui est specifiee par POSIX.1-2001
       mais pas par C99), n est un entier decimal qui  specifie  que  l'entree
       convertie  devrait  etre  placee  a  l'endroit  reference par le n-ieme
       argument pointeur suivant format.

   Conversions
       Les caract`eres modificateurs de type suivant peuvent se apparaitre dans
       une specification 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 (plutot 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 ete 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 (plutot 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 (plutot que sur un float). Indiquer  deux
              caracteres  l  successifs  est equivalent a indiquer L. Si c'est
              utilise avec %c ou %s, le parametre correspondant est considere,
              respectivement, comme un pointeur vers un caractere large ou une
              chaine de caracteres 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 equivalent a L. Ce specificateur n'existe pas en C ANSI.

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

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

       Les sp'ecificateurs de conversion suivant sont disponibles :

       %      Correspond   a   un   caractere  << % >>.  Ceci  signifie  qu'un
              specificateur %% dans la chaine de format correspond a  un  seul
              caractere  << % >>  dans  la  chaine d'entree. Aucune conversion
              (mais les caracteres blancs de debut sont  ignores),  et  aucune
              assignation n'a lieu.

       d      Correspond a un entier decimal eventuellement signe, le pointeur
              correspondant doit etre un pointeur vers un int.

       D      Equivalent a ld, utilise uniquement pour compatibilite avec  des
              versions  precedentes  (et  seulement  dans libc4. Dans libc5 et
              glibc,  le  %D  est  ignore  silencieusement,  ce  qui   conduit
              d'anciens programmes a echouer mysterieusement).

       i      Correspond a un entier eventuellement signe. Le pointeur suivant
              doit etre du type int. L'entier est  en  base  16  (hexadecimal)
              s'il  commence par 0x ou 0X, en base 8 (octal) s'il commence par
              un 0, et en base 10 sinon. Seuls les caracteres correspondants a
              la base concernee sont utilises.

       o      Correspond   a   un   entier   octal   non  signe.  Le  pointeur
              correspondant doit etre un pointeur vers un unsigned int.

       u      Correspond a un entier decimal non signe.  Le  pointeur  suivant
              doit etre un pointeur vers un unsigned int.

       x      Correspond  a  un  entier  hexadecimal  non  signe.  Le pointeur
              suivant doit etre un pointeur vers un unsigned int.

       X      Equivalent a x

       f      Correspond a un nombre reel eventuellement  signe.  Le  pointeur
              correspondant doit etre un pointeur vers un float.

       e      Equivalent a f.

       g      Equivalent a f.

       E      Equivalent a f.

       a      (C99) Equivalent a f.

       s      Correspond   a   une   sequence  de  caracteres  differents  des
              caracteres  blancs.  Le  pointeur  correspondant  doit  etre  un
              pointeur  sur un tableau de caracteres qui doit etre assez large
              pour accueillir toute la sequence d'entree,  ainsi  que  l'octet
              nul   final   (<< \0 >>)  qui  est  ajoute  automatiquement.  La
              conversion s'arrete au premier caractere blanc, ou a la longueur
              maximale du champ.

       c      Correspond  a  une  sequence  de caracteres dont la longueur est
              specifiee par la largeur maximum de champ  (par  defaut  1).  Le
              pointeur  suivant doit etre un pointeur vers un char, et il doit
              y avoir suffisamment de place  dans  la  chaine  pour  tous  les
              caracteres.  Aucun  octet nul final n'est ajoute. Les caracteres
              blancs de debut ne sont pas supprimes. Si on veut les  eliminer,
              il faut utiliser une espace dans le format.

       [      Correspond  a  une sequence non vide de caracteres appartenant a
              un ensemble  donne.  Le  pointeur  correspondant  doit  etre  un
              pointeur  vers  un char et il doit y avoir suffisamment de place
              dans le tableau de caracteres pour accueillir  la  chaine  ainsi
              qu'un  octet  nul  final. Les caracteres blancs du debut ne sont
              pas supprimes. La chaine est constituees de caracteres inclus ou
              exclus   d'un   ensemble   donne.  L'ensemble  est  compose  des
              caracteres compris entre les deux crochets [  et  ].  L'ensemble
              exclut ces caracteres si le premier apres le crochet ouvrant est
              un accent circonflexe (^). Pour inclure un crochet fermant  dans
              l'ensemble, il suffit de le placer en premiere position apres le
              crochet  ouvrant,  ou  l'accent  circonflexe ;  a   tout   autre
              emplacement il servira a terminer l'ensemble. Le caractere tiret
              - a egalement une signification particuliere. Quand il est place
              entre  deux  autres  caracteres,  il  ajoute  a  l'ensemble  les
              caracteres  intermediaires.   Pour   inclure   un   tiret   dans
              l'ensemble,  il  faut  le  placer  en derniere position avant le
              crochet fermant. Par exemple, [^]0-9-] correspond  a  l'ensemble
              << Tout  sauf  le  crochet fermant, les chiffres de 0 a 9, et le
              tiret >>. La chaine se termine des l'occurrence  d'un  caractere
              exclu (ou inclus s'il y a un accent circonflexe ) de l'ensemble,
              ou des qu'on atteint la longueur maximale du champ.

       p      Correspond a une valeur de pointeur (comme affichee par %p  dans
              printf(3).  Le  pointeur  suivant  doit  etre un pointeur sur un
              pointeur sur void.

       n      Aucune lecture n'est faite. Le nombre de caracteres deja lus est
              stocke dans le pointeur correspondant, qui doit etre un pointeur
              vers un int. Ce n'est pas une conversion, mais le stockage  peut
              quand     meme     etre     supprime     avec    le    caractere
              d'affectation-suppression   *.   Le   standard    C    indique :
              << L'execution  d'une  directive %n n'incremente pas le compteur
              d'assignations renvoye a  la  fin  de  l'execution >>.  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 renvoyee.

VALEUR RENVOY'EE

       Ces fonctions renvoient le nombre d'elements d'entrees correctement mis
       en correspondance et assignes. Ce nombre peut etre plus  petit  que  le
       nombre  d'elements  attendus,  et meme etre nul, s'il y a une erreur de
       mise en correspondance.

       La valeur EOF est renvoyee si la fin de l'entree est atteinte avant  la
       premiere  conversion reussie ou si un echec de correspondance survient.
       EOF est egalement renvoye si une erreur de lecture survient, auquel cas
       l'indicateur d'erreur pour le flux (consultez ferror(3)) est positionne
       et errno est remplie en consequence

ERREURS

       EAGAIN Le descripteur de fichier stream sous-jacent est non bloquant et
              l'operation 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 sequence d'octet en entree  ne  constitue  pas  un  caractere
              valable.

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

       EINVAL Pas suffisamment de parametres ; ou bien format est NULL.

       ENOMEM Plus de memoire disponible.

       ERANGE Le resultat de la conversion  entiere  est  plus  grand  que  la
              taille pouvant etre stockee dans le type entier correspondant.

CONFORMIT'E

       Les  fonctions fscanf(), scanf(), et sscanf() sont conformes a C89, C99
       et POSIX.1-2001. Ces normes ne specifient pas l'erreur ERANGE.

       Le specificateur q est une notation BSD 4.4 pour long long,  alors  que
       ll  ou  l'utilisation  de  L  dans  les  conversions  entieres sont des
       notations GNU.

       Les versions Linux de ces fonctions sont  basees  sur  la  bibliotheque
       libio  GNU.  Jetez  un  oeil  sur  la documentation info de la libc GNU
       (glibc-1.08) pour une description complete.

NOTES

       Pour utiliser cette fonctionnalite, indiquez a  comme  modificateur  de
       longueur  (par  consequent  %as  ou %a[range]). L'appelant doit liberer
       (free(3)) l'espace occupe par la chaine renvoyee, 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  montre  dans  cet exemple, il n'est necessaire d'appeler free(3)
       que si l'appel a scanf() a reussi a lire une chaine.

       Le modificateur a n'est pas disponible si le programme  a  ete  compile
       avec  gcc  -std=c99  ou  gcc  -D_ISOC99_SOURCE (a moins que _GNU_SOURCE
       n'ait egalement ete indique), auquel cas  a  est  interprete  comme  un
       specificateur de nombres en virgule flottante (voir plus haut).

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

       * Il  peut  etre  applique  aux  specificateurs  de  conversion %c (par
         exemple %3mc).

       * Il leve toute  ambiguite  avec  le  specificateur  de  conversion  en
         virgule flottante %a (et n'est pas affecte par gcc -std=c99 etc.)

       * Il est specifie dans la version POSIX.1 a venir.

BOGUES

       Toutes ces fonctions sont totalement conformes a C89, mais lui ajoutent
       les specificateurs q et a ainsi que des  comportements  supplementaires
       des  specificateurs  L  et l. Ce derniers doivent etre consideres comme
       des bogues, car ils modifient le comportement de specificateurs definis
       dans C89.

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

       L'utilisation  q  n'est  pas  la  meme  sous  BSD 4.4, car il peut etre
       utilise avec des conversions de reels de maniere equivalente a L. [NDT]
       La  conversion  %s  devrait  toujours  etre  accompagnee d'une longueur
       maximale de chaine de caracteres. En effet,  il  existe  un  risque  de
       debordement  de  tampon,  qui  peut  conduire  a  un  trou  de securite
       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.27  du  projet  man-pages
       Linux.  Une description du projet et des instructions pour signaler des
       anomalies      peuvent      etre       trouvees       a       l'adresse
       <URL:http://www.kernel.org/doc/man-pages/>.

TRADUCTION

       Depuis  2010,  cette  traduction est maintenue a l'aide de l'outil po4a
       <URL:http://po4a.alioth.debian.org/>   par   l'equipe   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
       Francois et l'equipe francophone de traduction de Debian (2006-2009).

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

       Vous pouvez toujours avoir acces a la version anglaise de  ce  document
       en utilisant la commande << man -L C <section> <page_de_man> >>.