Provided by: manpages-fr-dev_2.64.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 du type 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 du type unsigned int *.

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

       x      Correspond  à  un  entier  hexadécimal  non  signé.  Le pointeur
              suivant doit être du type unsigned int *.

       X      Équivalent à x

       f      Correspond à un nombre réel éventuellement  signé.  Le  pointeur
              correspondant doit être du type 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 de type 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)

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