Nom

scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - Entrées formatées.

Résumé

.nf #include <stdio.h> .na 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 ); .ad

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

Conversions

A 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

(GlibC) 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 .

a

(C99) Équivalent à f.

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ée

Ces 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 aussi

strtol (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.

Bugs

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

Traduction

Christophe Blaess, 1996-2003.