scanf

Nom

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);DescriptionLes
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 arguments
pointeurs. 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 et
vsprintf. 
Les arguments pointeurs successifs doivent correspondre correctement
aux indicateurs de conversion fournis (voir néanmoins l'attribut '*' plus
bas). Toutes les conversions sont introduites par le caractère % (symbole
pourcent). La chaîne format peut également contenir d'autres caractères. Les
blancs (comme les espaces, les tabulations ou les retours chariots) dans
la chaîne format correspondent à un nombre quelconque de blancs (et même
aucun) dans la chaine d'entrée. Tous les autres caractères ne peuvent correspondre
qu'a eux-même. L'examen de l'entrée s'arrête dès qu'un caractère d'entrée ne correspond
pas à un caractère du format. L'examen s'arrête également quand une conversion
d'entrée est impossible (voir ci-dessous). 
ConversionsA la suite du caractère
% introduisant une conversion, il peut y avoir un nombre quelconque de
caractères attributs de la liste suivante : * Ne pas stocker le résultat.
La conversion est bien effectuée comme d'habitude, mais le resultat est
éliminé au lieu d'être memorisé dans un pointeur. a  Indique que la conversion
sera de type s, la mémoire nécessaire pour la chaine sera allouée avec
malloc(3) et le pointeur sera assigné à la variable de type char qui n'a
pas besoin d'être initialisée auparavant. Cet attribut n'existe pas en C ANSI.
h Indique que la conversion sera de type dioux ou n et que le pointeur
suivant est un pointeur sur un short  int (plutôt que sur un int). l Indique
que la conversion sera de type dioux ou n et que le pointeur suivant est
un pointeur sur un 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 attributs l successifs est équivalent
à indiquer l'attribut L. 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. (ce type n'existe pas en C ANSI. Un programme l'utilisant ne sera pas
portable sur toutes  les machines). q est équivalent à L. Cet attribut n'existe
pas en C ANSI. En plus de ces attributs peut se trouver un champ optionnel
de longueur maximale, exprimée sous forme d'entier, entre le caractère %
et l'indicateur de conversion. Si aucune longueur n'est donnée, une valeur
infinie est utilisée par défaut (avec une exception, voir plus bas). Autrement,
la conversion examinera au plus le nombre de caractères indiqués. Avant
que les conversions ne commencent, la plupart d'entre elles éliminent les
blancs. Ces espaces blancs ne sont pas comptés dans le champ de largeur
maximale. 
Les conversions suivantes sont disponibles : 
% Correspond à un
caractère  `%'.  Ceci signifie qu'un indicateur `%%'  dans la chaîne de format
correspond à un seul caractere `%' dans la chaine 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 Equivalent à
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 (héxadé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 héxadécimal non signé.
Le pointeur suivant doit être du type unsigned int *. X Equivalent à x 
f Correspond à un nombre réel éventuellement signé. Le pointeur correspondant
doit être du type float *. e Equivalent à f. g Equivalent à f. E Equivalent
à f s Correspond à une séquence de caractères différents des caractères
blancs. Le pointeur correspondant doit être du type char *, et la chaine
doit être assez large pour accueillir toute la séquence, ainsi que le caractère
NUL final. La conversion s'arrête au premier caractère blanc, ou à la longueur
maximale du champ. c Correspond à une séquence de width caractères (par
défaut 1). Le pointeur associé doit être du type char *, et il doit y avoir
suffisament de place dans la chaîne pour tous les caracteres. Aucun caractère
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 un espace dans le format. [ Correspond
à une séquence non vide de caractères appartenant à un ensemble donné. Le
pointeur correspondant doit être du type char *, et il doit y avoir suffisament
de place dans le tableau de caractères pour accueillir la chaîne ainsi
qu'un caractère 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 chaine se termine dès l'occurence d'un caractère exclus (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 correspondant doit être du type 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 un
attribut *. 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éeCes fonctions renvoient le nombre d'éléments d'entrées
correctement assignés. Ce nombre peut être plus petit que le nombre d'élements
attendus, et même être nul, s'il y a une erreur de mise en correspondance.
La valeur zéro indique qu'aucune conversion n'a été faite bien que des caractères
étaient disponibles en entrée. Typiquement c'est un caractère d'entrée invalide
qui en est la cause, par exemple un caractère alphabétique dans une conversion
`%d'. La valeur EOF est renvoyée si une erreur d'entrée a eu lieu avant toute
conversion, par exemple une fin de fichier. Si une erreur fin-de-fichier se
produit après que les conversions aient commencé, le nombre de conversions
réussies sera renvoyé. Voir Aussistrtol(3), strtoul(3), strtod(3), getc(3),
printf(3) ConformitéLes fonctions fscanf, scanf, et sscanf sont conformes
à ANSI X3.159-1989 (``C ANSI''). L'attribut 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.  
BoguesToutes ces fonctions
sont totalement conformes à ANSI X3.159-1989, mais lui ajoutent les attributs
q et a ainsi que des comportements supplémentaires des attributs L et l.
Ce derniers doivent être considérés comme des bugs, car ils modifient le
comportement d'attributs définis dans ANSI X3.159-1989. Certaines combinaisons
d'attributs  n'ont pas de sens en C ANSI (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 attributs définis
en C ANSI, par exemple, 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
buffer, qui peut conduire à un trou de sécurité important dans un programme
Set-UID ou Set-GID.   
TraductionChristophe Blaess, 1997.