Provided by:
manpages-fr-dev_3.27fr1.4-1_all 
NOM
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - Entrees formatees
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);
Exigences de macros de test de fonctionnalites pour la glibc (consultez
feature_test_macros(7)) :
vscanf(), vsscanf(), vfscanf() :
_XOPEN_SOURCE >= 600 || _ISOC99_SOURCE ||
_POSIX_C_SOURCE >= 200112L
ou cc -std=c99
DESCRIPTION
Les fonctions de la famille scanf() analysent leurs entrees
conformement 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
suivent le format. Chaque argument pointeur doit etre du type approprie
pour la valeur retournee par la specification de conversion
correspondante.
Si le nombre de specifications de conversion dans format excede le
nombre 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, consultez 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(3) et vsprintf(3).
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'entr'ee signifiant que les
caracteres d'entree ne sont pas disponibles, soit un 'echec de
correspondance 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. ; consultez 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
correspondre 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
conformement 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 sp'ecification 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
lorsqu'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 lorsque ce
maximum est atteint, soit lorsque on trouve un caractere qui ne
correspond pas, celui qui arrive le premier. La plupart des
conversions 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 caract`ere 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
correspondant fait reference a un long int plutot qu'a un
pointeur sur un int.
o Un sp'ecificateur de conversion qui specifie le type de
conversion 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 correspondent, 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 n-ieme
argument pointeur suivant format.
Conversions
Les caract`eres modificateurs de type suivant peuvent se apparaitre dans
une specification de conversion :
h Indique que la conversion sera de type d, i, o, u, x, X 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 d, i, o, u, x, X 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 e, f ou g et que le pointeur suivant est un
pointeur sur un double (plutot que sur un float). Indiquer deux
caracteres l successifs 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 caracteres larges.
L Indique que la conversion sera de type e, f ou g et que le
pointeur suivant est un pointeur sur un long double ou que la
conversion sera de type d, i, o, u, ou x 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 sp'ecificateurs 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
(mais les caracteres blancs de debut sont ignores), et aucune
assignation n'a lieu.
d Correspond a un entier decimal eventuellement signe, le pointeur
correspondant doit etre un pointeur vers un 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
correspondant doit etre un pointeur vers un unsigned int.
u Correspond a un entier decimal non signe. Le pointeur suivant
doit etre un pointeur vers un unsigned int.
x Correspond a un entier hexadecimal non signe. Le pointeur
suivant doit etre un pointeur vers un unsigned int.
X Equivalent a x
f Correspond a un nombre reel eventuellement signe. Le pointeur
correspondant doit etre un pointeur vers un 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
caracteres 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
caracteres. 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
pointeur 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
caracteres 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
emplacement 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
caracteres 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 crochet 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 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 un pointeur
vers un 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 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 suppositions sur l'effet de
la conversion %n sur la valeur renvoyee.
VALEUR RENVOY'EE
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 (consultez ferror(3)) est positionne
et errno est remplie en consequence
ERREURS
EAGAIN Le descripteur de fichier stream sous-jacent est non bloquant et
l'operation de lecture bloquerait.
EBADF Le descripteur de fichier stream sous-jacent n'est pas valide ou
bien n'est pas ouvert en lecture.
EILSEQ La sequence d'octet en entree ne constitue pas un caractere
valable.
EINTR La lecture a ete interrompue par un signal ; consultez
signal(7).
EINVAL Pas suffisamment de parametres ; ou bien format est NULL.
ENOMEM Plus de memoire disponible.
ERANGE Le resultat de la conversion entiere est plus grand que la
taille pouvant etre stockee dans le type entier correspondant.
CONFORMIT'E
Les fonctions fscanf(), scanf(), et sscanf() sont conformes a C89, C99
et POSIX.1-2001. Ces normes ne specifient pas l'erreur ERANGE.
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
notations 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.
NOTES
Pour utiliser cette fonctionnalite, indiquez a comme modificateur de
longueur (par consequent %as ou %a[range]). L'appelant doit liberer
(free(3)) l'espace occupe par la chaine renvoyee, comme dans l'exemple
suivant :
char *p;
int n;
errno = 0;
n = scanf("%a[a-z]", &p);
if (n == 1) {
printf("read: %s\n", p);
free(p);
} else if (errno != 0) {
perror("scanf");
} else {
fprintf(stderr, "No matching characters\n"):
}
Comme montre dans cet exemple, il n'est necessaire d'appeler free(3)
que si l'appel a scanf() a reussi a lire une chaine.
Le modificateur a n'est pas disponible si le programme a ete compile
avec gcc -std=c99 ou gcc -D_ISOC99_SOURCE (a moins que _GNU_SOURCE
n'ait egalement ete indique), auquel cas a est interprete comme un
specificateur de nombres en virgule flottante (voir plus haut).
Depuis la version 2.7, la glibc fournit aussi le modificateur m pour
faire la meme chose que le modificateur a. Le modificateur m a les
avantages suivants :
* Il peut etre applique aux specificateurs de conversion %c (par
exemple %3mc).
* Il leve toute ambiguite avec le specificateur de conversion en
virgule flottante %a (et n'est pas affecte par gcc -std=c99 etc.)
* Il est specifie dans la version POSIX.1 a venir.
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, c'est-a-dire,
utilisez q a la place de L avec les conversions d, i, o, u, x et X 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
important dans un programme setuid ou setgid.
VOIR AUSSI
getc(3), printf(3), setlocale(3), strtod(3), strtol(3), strtoul(3)
COLOPHON
Cette page fait partie de la publication 3.27 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent etre trouvees a l'adresse
<URL:http://www.kernel.org/doc/man-pages/>.
TRADUCTION
Depuis 2010, cette traduction est maintenue a l'aide de l'outil po4a
<URL:http://po4a.alioth.debian.org/> par l'equipe de traduction
francophone au sein du projet perkamon
<URL:http://perkamon.alioth.debian.org/>.
Christophe Blaess <URL:http://www.blaess.fr/christophe/> (1996-2003),
Alain Portal <URL:http://manpagesfr.free.fr/> (2003-2006). Nicolas
Francois et l'equipe francophone de traduction de Debian (2006-2009).
Veuillez signaler toute erreur de traduction en ecrivant a
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir acces a la version anglaise de ce document
en utilisant la commande << man -L C <section> <page_de_man> >>.