Provided by: manpages-fr-dev_3.57d1p1-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'entrée
       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 spécification 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  « m » optionnel. Il est utilisé dans les conversions de chaînes (%s,
              %c, %[) 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.

       •      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 nul (« \0 »)
              final  pour  marquer la fin de l'entrée ; la largeur maximale du champ n'inclut pas
              ce caractère de terminaison.

       •      Un caractère 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  spécificateur  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  caractères 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 spécificateurs 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

   Le modificateur d'affectation-allocation « a »
       Initialement,  la  bibliothèque  C  de  GNU  prenait  en charge l'allocation dynamique des
       chaînes de caractères en entrée (comme une extension non standard) au moyen du caractère a
       (cette  fonctionnalité  remonte  au  moins  à  la  version  2.0 de glibc). Ainsi, il était
       possible, grâce au code suivant, de faire que scanf() alloue un tampon pour une chaîne  en
       entrée, et renvoie un pointeur vers ce tampon dans *buf:

           char *buf;
           scanf("%as", &buf);

       L'utilisation  de  la lettre a dans ce but posait problème étant donné que a est également
       synonyme de f dans le standard ISO C (entrée de nombre à virgule flottante).  POSIX.1-2008
       spécifie  en  revanche  que  le  modificateur  m  doit  être  utilisée  pour l'affectation
       allocation (comme indiqué dans la DESCRIPTION plus haut).

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

       Le  modificateur  m  est  pris  en  charge  depuis la version 2.7 de glibc et les nouveaux
       programmes doivent utiliser ce modificateur plutôt que a.

       En plus d'être un standard de POSIX, le modificateur m présente les avantages suivants par
       rapport au modificateur a:

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

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.

EXEMPLE

       Pour  utiliser  l'indicateur  de  conversion  d'allocation  dynamique,  indiquez  m  comme
       modificateur de longueur (par  conséquent  %ms  ou  %m[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("%m[a-z]", &p);
           if (n == 1) {
               printf("read: %s\n", p);
               free(p);
           } else if (errno != 0) {
               perror("scanf");
           } else {
               fprintf(stderr, "Pas de caractères correspondants\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.

VOIR AUSSI

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

COLOPHON

       Cette page fait partie de la publication 3.57 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

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

       Christophe   Blaess   <http://www.blaess.fr/christophe/>   (1996-2003),    Alain    Portal
       <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> ».