Provided by: manpages-fr-dev_3.57d1p1-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);
Exigences de macros de test de fonctionnalités 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 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 endroits pointés par des arguments
pointeurs qui suivent le format. Chaque argument pointeur doit être du type approprié pour
la valeur retournée par la spécification de conversion correspondante.
Si le nombre de spécifications de conversion dans format excède le nombre d'arguments
pointeur, le résultat est indéterminé. Si le nombre d'arguments pointeur excède le nombre
de spécifications de conversion, les arguments pointeur en excès sont évalués mais
ignorés.
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, consultez
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(3) et vsprintf(3).
La chaîne format consiste en une séquence de directives qui décrit comme traiter la
séquence des caractères d'entrée. Si le traitement des directives échoue, aucune autre
entrée n'est lue et scanf() revient. Un « échec » peut être soit un échec d'entrée
signifiant que les caractères d'entrée ne sont pas disponibles, soit un échec de
correspondance signifiant que l'entrée n'est pas appropriée (voir plus loin)
Une directive peut être :
• Une séquence de caractères blancs (espace, tabulation, nouvelle ligne, etc. ;
consultez isspace(3)). Cette directive correspond à un nombre quelconque de
caractères blancs, y compris aucun, dans l'entrée.
• Un caractère ordinaire (c'est-à-dire autre qu'un caractère blanc et que le
caractère « % ». Ce caractère doit exactement correspondre au caractère suivant de
l'entrée.
• Une spécification de conversion qui débute avec le caractère « % ». Une séquence de
caractères de l'entrée est convertie conformément à la spécification et le résultat
est placé dans l'argument pointeur correspondant. Si l'élément suivant de l'entrée
ne correspond pas à la spécification de conversion, la conversion échoue — c'est un
échec de correspondance.
Chaque spécification de conversion dans format commence avec soit le caractère « % », soit
la séquence de caractères « %n$ » (voir plus loin pour la distinction) suivie par :
• Un caractère d'affectation-suppression optionnel « * » : scanf() lit l'entrée comme
indiqué par la spécification de conversion mais ne tient pas compte de l'entrée.
Aucun argument pointeur n'est nécessaire et cette spécification n'est pas
comptabilisée dans le nombre d'affectations réussies renvoyé par scanf().
• Un caractère « m » optionnel. Il est utilisé dans les conversions de chaînes (%s,
%c, %[) et soulage l'appelant du besoin d'allouer un tampon correspondant pour
conserver l'entrée : à la place, scanf() alloue un tampon de taille suffisante et
affecte l'adresse de ce tampon à l'argument pointeur correspondant qui doit être un
pointeur vers une variable char * (il n'est pas nécessaire que cette variable soit
initialisée avant l'appel). L'appelant doit par la suite libérer (free(3)) ce
tampon lorsqu'il devient inutile.
• Un entier décimal optionnel qui indique la taille maximum du champ. La lecture des
caractères s'arrête soit lorsque ce maximum est atteint, soit lorsque on trouve un
caractère qui ne correspond pas, celui qui arrive le premier. La plupart des
conversions abandonnent les caractères blancs de tête (les exceptions sont notées
plus loin), et ces caractère abandonnés n'entrent pas en compte dans la taille
maximale du champ. Les conversions d'entrée de chaînes stocke un octet nul (« \0 »)
final pour marquer la fin de l'entrée ; la largeur maximale du champ n'inclut pas
ce caractère de terminaison.
• Un caractère modificateur de type optionnel. Par exemple, le modificateur de type l
est utilisé avec les conversions d'entrée telles que %d pour spécifier que
l'argument pointeur correspondant fait référence à un long int plutôt qu'à un
pointeur sur un int.
• Un spécificateur de conversion qui spécifie le type de conversion d'entrée à
effectuer.
Les spécifications de conversion dans format sont de deux formes : soit elles commencent
par « % », soit elles commencent par « %n$ ». Les deux formes ne doivent pas être
mélangées dans la même chaîne format, excepté qu'une chaîne contenant les spécifications
« %n$ » peut inclure %% et %*. Si format contient des spécifications « % », celles-ci
correspondent, dans l'ordre, aux arguments pointeur successifs. Dans la forme « %n$ » (qui
est spécifiée par POSIX.1-2001 mais pas par C99), n est un entier décimal qui spécifie que
l'entrée convertie devrait être placée à l'endroit référencé par le n-ième argument
pointeur suivant format.
Conversions
Les caractères modificateurs de type suivant peuvent se apparaître dans une spécification
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 (plutôt 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 été 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 (plutôt 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 (plutôt que sur un float). Indiquer deux caractères l
successifs est équivalent à indiquer L. Si c'est utilisé avec %c ou %s, le
paramètre correspondant est considéré, respectivement, comme un pointeur vers un
caractère large ou une chaîne de caractères 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 équivalent à L. Ce spécificateur n'existe pas en C ANSI.
t Comme pour h, mais le pointeur suivant est un pointeur vers un ptrdiff_t. Ce
modificateur a été introduit dans C99.
z Comme pour h, mais le pointeur suivant est un pointeur vers un size_t. Ce
modificateur a été introduit dans C99.
Les spécificateurs de conversion suivant sont disponibles :
% Correspond à un caractère « % ». Ceci signifie qu'un spécificateur %% dans la
chaîne de format correspond à un seul caractère « % » dans la chaîne d'entrée.
Aucune conversion (mais les caractères blancs de début sont ignorés), et aucune
assignation n'a lieu.
d Correspond à un entier décimal éventuellement signé, le pointeur correspondant doit
être un pointeur vers un int.
D Équivalent à 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 (hexadé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 un
pointeur vers un unsigned int.
u Correspond à un entier décimal non signé. Le pointeur suivant doit être un pointeur
vers un unsigned int.
x Correspond à un entier hexadécimal non signé. Le pointeur suivant doit être un
pointeur vers un unsigned int.
X Équivalent à x
f Correspond à un nombre réel éventuellement signé. Le pointeur correspondant doit
être un pointeur vers un float.
e Équivalent à f.
g Équivalent à f.
E Équivalent à f.
a (C99) Équivalent à f.
s Correspond à une séquence de caractères différents des caractères blancs. Le
pointeur correspondant doit être un pointeur sur un tableau de caractères qui doit
être assez large pour accueillir toute la séquence d'entrée, ainsi que l'octet nul
final (« \0 ») qui est ajouté automatiquement. La conversion s'arrête au premier
caractère blanc, ou à la longueur maximale du champ.
c Correspond à une séquence de caractères dont la longueur est spécifiée par la
largeur maximum de champ (par défaut 1). Le pointeur suivant doit être un pointeur
vers un char, et il doit y avoir suffisamment de place dans la chaîne pour tous les
caractères. Aucun octet 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 une espace dans le
format.
[ Correspond à une séquence non vide de caractères appartenant à un ensemble donné.
Le pointeur correspondant doit être un pointeur vers un char et il doit y avoir
suffisamment de place dans le tableau de caractères pour accueillir la chaîne ainsi
qu'un octet 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 chaîne 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 suivant doit être un pointeur sur un pointeur sur void.
n Aucune lecture n'est faite. Le nombre de caractères déjà lus est stocké dans le
pointeur correspondant, qui doit être un pointeur vers un int. Ce n'est pas une
conversion, mais le stockage peut quand même être supprimé avec le caractère
d'affectation-suppression *. 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 mis en correspondance
et assignés. Ce nombre peut être plus petit que le nombre d'éléments attendus, et même
être nul, s'il y a une erreur de mise en correspondance.
La valeur EOF est renvoyée si la fin de l'entrée est atteinte avant la première conversion
réussie ou si un échec de correspondance survient. EOF est également renvoyé si une erreur
de lecture survient, auquel cas l'indicateur d'erreur pour le flux (consultez ferror(3))
est positionné et errno est remplie en conséquence
ERREURS
EAGAIN Le descripteur de fichier stream sous-jacent est non bloquant et l'opération 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 séquence d'octet en entrée ne constitue pas un caractère valable.
EINTR La lecture a été interrompue par un signal ; consultez signal(7).
EINVAL Pas suffisamment de paramètres ; ou bien format est NULL.
ENOMEM Plus de mémoire disponible.
ERANGE Le résultat de la conversion entière est plus grand que la taille pouvant être
stockée dans le type entier correspondant.
CONFORMITÉ
Les fonctions fscanf(), scanf(), et sscanf() sont conformes à C89, C99 et POSIX.1-2001.
Ces normes ne spécifient pas l'erreur ERANGE.
Le spécificateur 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
œil sur la documentation info de la libc GNU (glibc-1.08) pour une description complète.
NOTES
Le modificateur d'affectation-allocation « a »
Initialement, la bibliothèque C de GNU prenait en charge l'allocation dynamique des
chaînes de caractères en entrée (comme une extension non standard) au moyen du caractère a
(cette fonctionnalité remonte au moins à la version 2.0 de glibc). Ainsi, il était
possible, grâce au code suivant, de faire que scanf() alloue un tampon pour une chaîne en
entrée, et renvoie un pointeur vers ce tampon dans *buf:
char *buf;
scanf("%as", &buf);
L'utilisation de la lettre a dans ce but posait problème étant donné que a est également
synonyme de f dans le standard ISO C (entrée de nombre à virgule flottante). POSIX.1-2008
spécifie en revanche que le modificateur m doit être utilisée pour l'affectation
allocation (comme indiqué dans la DESCRIPTION plus haut).
Notez que le modificateur a n'est pas disponible si le programme a été compilé avec gcc
-std=c99 ou gcc -D_ISOC99_SOURCE (à moins que _GNU_SOURCE n'ait également été indiqué),
auquel cas a est interprété comme un spécificateur de nombres en virgule flottante (voir
plus haut).
Le modificateur m est pris en charge depuis la version 2.7 de glibc et les nouveaux
programmes doivent utiliser ce modificateur plutôt que a.
En plus d'être un standard de POSIX, le modificateur m présente les avantages suivants par
rapport au modificateur a:
* Il peut être appliqué aux spécificateurs de conversion %c (par exemple %3mc).
* Il lève toute ambiguité avec le spécificateur de conversion en virgule flottante %a (et
n'est pas affecté par gcc -std=c99 etc.).
BOGUES
Toutes ces fonctions sont totalement conformes à C89, mais lui ajoutent les spécificateurs
q et a ainsi que des comportements supplémentaires des spécificateurs L et l. Ce derniers
doivent être considérés comme des bogues, car ils modifient le comportement de
spécificateurs définis dans C89.
Certaines combinaisons de modificateurs de type et de spécificateurs de conversion définis
par le C ANSI n'ont pas de sens (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 modificateurs définis en C ANSI, c'est-à-dire, utilisez q à
la place de L avec les conversions d, i, o, u, x et X 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 tampon, qui peut conduire à un trou de sécurité important dans un
programme setuid ou setgid.
EXEMPLE
Pour utiliser l'indicateur de conversion d'allocation dynamique, indiquez m comme
modificateur de longueur (par conséquent %ms ou %m[range]). L'appelant doit libérer
(free(3)) l'espace occupé par la chaîne renvoyée, comme dans l'exemple suivant :
char *p;
int n;
errno = 0;
n = scanf("%m[a-z]", &p);
if (n == 1) {
printf("read: %s\n", p);
free(p);
} else if (errno != 0) {
perror("scanf");
} else {
fprintf(stderr, "Pas de caractères correspondants\n");
}
Comme montré dans cet exemple, il n'est nécessaire d'appeler free(3) que si l'appel à
scanf() a réussi à lire une chaîne.
VOIR AUSSI
getc(3), printf(3), setlocale(3), strtod(3), strtol(3), strtoul(3)
COLOPHON
Cette page fait partie de la publication 3.57 du projet man-pages Linux. Une description
du projet et des instructions pour signaler des anomalies peuvent être trouvées à
l'adresse http://www.kernel.org/doc/man-pages/.
TRADUCTION
Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a
<http://po4a.alioth.debian.org/> par l'équipe de traduction francophone au sein du projet
perkamon <http://perkamon.alioth.debian.org/>.
Christophe Blaess <http://www.blaess.fr/christophe/> (1996-2003), Alain Portal
<http://manpagesfr.free.fr/> (2003-2006). Nicolas François et l'équipe francophone de
traduction de Debian (2006-2009).
Veuillez signaler toute erreur de traduction en écrivant à
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le paquet
manpages-fr.
Vous pouvez toujours avoir accès à la version anglaise de ce document en utilisant la
commande « man -L C <section> <page_de_man> ».