Provided by: manpages-fr-dev_2.80.1-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  pour les macros de test de fonctionnalité de la glibc (consultez
   feature_test_macros(7)) :

       vscanf(),    vsscanf(),     vfscanf() :     _XOPEN_SOURCE >= 600     ||
       _ISOC99_SOURCE ; 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,  voir  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  dentre  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. ; voir 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 diouxX 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 diouxX 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  efg  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 efg et  que  le  pointeur
              suivant  est un pointeur sur un long double ou que la conversion
              sera de type dioux 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, 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 (voir ferror(3)) est  positionné  et
       errno est remplie en conséquence

CONFORMITÉ

       Les  fonctions  fscanf(),  scanf(), et sscanf() sont conformes à C89 et
       C99.

       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  oeil  sur  la documentation info de la libc GNU
       (glibc-1.08) pour une description complète.

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 diouxX 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  2.80  du  projet  man-pages
       Linux.  Une description du projet et des instructions pour signaler des
       anomalies      peuvent      être       trouvées       à       l’adresse
       http://www.kernel.org/doc/man-pages/.

TRADUCTION

       Cette  page  de  manuel  a  été  traduite et mise à jour par Christophe
       Blaess <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis  par
       Alain  Portal  <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et mise à
       disposition sur http://manpagesfr.free.fr/.

       Les mises à jour et corrections de la version présente dans Debian sont
       directement         gérées         par         Nicolas         François
       <nicolas.francois@centraliens.net>   et   l’équipe    francophone    de
       traduction de Debian.

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