Loading

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 (voir
   feature_test_macros(7)) :

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

       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 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 (voir 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 ; voir signal(7).

       EINVAL Pas suffisamment de paramètres ; ou bien format est NULL.

       ENOMEM Pas suffisamment 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 oeil 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.23 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> ».