Provided by:
manpages-fr_1.67.0-1_all 
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
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’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 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.
BOGUES
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.