Man Sscanf en français
SCANF(3)                  Manuel du programmeur Linux                 SCANF(3)



 

NOM


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

 

SYNOPSIS


       #include 
       int scanf (const char * format, ...);
       int fscanf (FILE * stream, const char * format, ...);
       int sscanf (const char * str, const char * format, ...);

       #include 
       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);

 

DESCRIPTION






       Les  fonctions  de la famille scanf() analysent leurs entrees conforme-
       ment 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 suiv-
       ent  le  format.   Chaque argument pointeur doit etre du type approprie
       pour la valeur retournee par la specification de conversion  correspon-
       dante.

       Si le nombre de specifications de conversion dans format excede le nom-
       bre 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,  voir  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() et vsprintf().

       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'entree signifiant que
       les caracteres d'entree ne sont pas disponibles, soit un echec de  cor-
       respondance  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. ; voir 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  corre-
              spondre 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  con-
              formement  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 specification 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 lorqu'il qu'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 lorque ce maxi-
              mum est atteint, soit lorsque on trouve un caractere qui ne cor-
              respond pas, celui qui arrive le premier. La plupart des conver-
              sions 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  caractere 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 correspon-
              dant fait reference a un long int plutot qu'a un pointeur sur un
              int.

       o      Un  specificateur  de conversion qui specifie le type de conver-
              sion 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  corre-
       spondent,  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 is a decimal integer that specifies
       that  the  converted input should be placed in the location referred to
       by the n-ieme argument pointeur suivant format.

 

CONVERSIONS


       Les caracteres modificateurs de type suivant peuvent se apparaitre dans
       une specification 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 (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 diouxX 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  efg et que le pointeur suivant est un pointeur sur un dou-
              ble (plutot que sur un float).  Indiquer deux caracteres l  suc-
              cessifs  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 car-
              acteres 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 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 specificateurs 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, et aucune assigna-
              tion n'a lieu.

       d      Correspond a un entier decimal eventuellement signe, le pointeur
              correspondant doit etre du type 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  correspon-
              dant doit etre du type unsigned int *.

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

       x      Correspond a un entier hexadecimal non signe. Le pointeur  suiv-
              ant doit etre du type unsigned int *.

       X      Equivalent a x

       f      Correspond  a  un  nombre reel eventuellement signe. Le pointeur
              correspondant doit etre du type 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  carac-
              teres  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 car-
              acteres. 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 poin-
              teur 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  carac-
              teres 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 emplace-
              ment 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  carac-
              teres  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 cro-
              chet 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  void
              *.

       n      Aucune lecture n'est faite. Le nombre de caracteres deja lus est
              stocke dans le pointeur correspondant, qui doit etre de type 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'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  supposi-
              tions sur l'effet de la conversion %n sur la valeur renvoyee.

 

VALEUR RENVOYEE


       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 (voir ferror(3)) est positionne et
       errno est remplie en consequence

 

VOIR AUSSI


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

 

CONFORMITE


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

       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  nota-
       tions 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.

 

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, par exemple,
       utilisez q a la place de L avec les conversions diouxX 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  impor-
       tant dans un programme Set-UID ou Set-GID.

 

TRADUCTION


       Ce   document   est  une  traduction  realisee  par  Christophe  Blaess
        le 18 novembre 1996, mise a jour par
       Alain Portal  le 30 juin 2006 et revisee
       le 14 aot 2006.

       L'equipe de traduction a fait le maximum pour realiser  une  adaptation
       francaise de qualite. La version anglaise la plus a jour de ce document
       est  toujours  consultable  via  la  commande :    LANG=C man 3 scanf .
       N'hesitez  pas  a  signaler  a l'auteur ou au traducteur, selon le cas,
       toute erreur dans cette page de manuel.



LDP                            1er novembre 1995                      SCANF(3)