SCANF(3) Manuel du programmeur Linux SCANF(3)
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);
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 ana
logues 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 conver
sions sont introduites par le caractère % (symbole pour
cent). 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 correspon
dent à 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 car
actè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
Linux 9 Avril 1999 1
SCANF(3) Manuel du programmeur Linux SCANF(3)
é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 conver
sion 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 pro
gramme 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 option
nel 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 commen
cent, 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 cor
respond à 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 *.
Linux 9 Avril 1999 2
SCANF(3) Manuel du programmeur Linux SCANF(3)
D Equivalent à ld, utilisé uniquement pour compati
bilité avec des versions précédentes. (Et seule
ment 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 poin
teur 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 car
actè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 corre
spondant doit être du type char *, et il doit y
Linux 9 Avril 1999 3
SCANF(3) Manuel du programmeur Linux SCANF(3)
avoir suffisament de place dans le tableau de car
actères pour accueillir la chaîne ainsi qu'un car
actè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 cro
chet 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'ensem
ble, il faut le placer en dernière position avant
le crochet fermant.Par exemple, `[^]0-9-]' corre
spond à 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'ensem
ble, 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 con
version, mais le stockage peut quand même être sup
primé 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 con
tradictions 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
Linux 9 Avril 1999 4
SCANF(3) Manuel du programmeur Linux SCANF(3)
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)
STANDARDS
Les fonctions fscanf, scanf, et sscanf sont conformes à
ANSI C3.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 documenta
tion info de la libc GNU (glibc-1.08) pour une description
complète.
BUGS
Toutes ces fonctions sont totalement conformes à ANSI
C3.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 C3.159-1989.
Certaines combinaisons d'attributs n'ont pas de sens en C
ANSI (par exemple %Ld). Bien qu'elles aient un comporte
ment 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, 1997.
Linux 9 Avril 1999 5