SCANF(3) Manuel du programmeur Linux SCANF(3)
scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - Entrées formatées
#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 (voir fea‐
ture_test_macros(7)) :
vscanf(), vsscanf(), vfscanf() : _XOPEN_SOURCE >= 600 ||
_ISOC99_SOURCE ; ou cc -std=c99
Les fonctions de la famille scanf() analysent leurs entrées con‐
formé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 conver‐
sion 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 nom‐
bre d’arguments pointeur excède le nombre de spécifications de con‐
version, 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, voir stdarg(3). La fonction vscanf() examine
l’entrée standard en utilisant une liste variable d’arguments poin‐
teurs et la fonction vsscanf() examine une chaîne. Elles sont respec‐
tivement 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, nou‐
velle ligne, etc.; voir 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 exacte‐
ment 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 conver‐
sion, 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 « a » optionnel. Il est utilisé dans les con‐
versions de chaînes 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. Ceci est une extension GNU ; C99
emploie le caractère « a » comme un spécificateur de conver‐
sion (il peut également être utilisé en tant que tel dans
l’implémentation GNU).
· Un entier décimal optionnel qui indique la taille maximum du
champ. La lecture des caractères s’arrête soit lorsque ce max‐
imum est atteint, soit lorsque on trouve un caractère qui ne
correspond pas, celui qui arrive le premier. La plupart des con‐
versions abandonnent les caractères blancs de tête (les excep‐
tions 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 de terminaison
nul (« \0 ») 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 conver‐
sion 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 succes‐
sifs. 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 poin‐
teur 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 con‐
sidé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 poin‐
teur suivant est un pointeur sur un long double ou que la con‐
version 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 poin‐
teur 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 suiv‐
ant 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 car‐
actères correspondants à la base concernée sont utilisés.
o Correspond à un entier octal non signé. Le pointeur correspon‐
dant 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 car‐
actères blancs. Le pointeur correspondant doit être un poin‐
teur 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 conver‐
sion 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 car‐
actères. Aucun octet nul final n’est ajouté. Les caractères
blancs de début ne sont pas supprimés. Si on veut les élim‐
iner, 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’ensem‐
ble 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 car‐
actè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 prob‐
ablement sage de ne pas faire de suppositions sur l’effet de la
conversion %n sur la 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 (voir fer‐
ror(3)) est positionné et errno est remplie en conséquence
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 ; voir signal(7).
EINVAL Pas suffisamment de paramètres ; ou bien format est NULL.
ENOMEM Pas suffisamment 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.
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 nota‐
tions 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.
Pour utiliser cette fonctionnalité, indiquez a comme modificateur de
longueur (par conséquent %as ou %a[range]). L’appelant doit libérer
(free(3)) l’espace occupé par la chaîne renvoyée, comme dans l’exem‐
ple 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 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.
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).
Depuis la version 2.7, la glibc fournit aussi le modificateur m pour
faire la même chose que le modificateur a. Le modificateur m a les
avantages suivants :
* 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.)
* Il est spécifié dans la version POSIX.1 à venir.
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.
getc(3), printf(3), setlocale(3), strtod(3), strtol(3), strtoul(3)
Cette page fait partie de la publication 3.07 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent être trouvées à l’adresse http://www.ker‐
nel.org/doc/man-pages/.
Cette page de manuel a été traduite et mise à jour par Christophe
Blaess <http://www.blaess.fr/christophe/>; entre 1996 et 2003, puis par
Alain Portal <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et mise Ã
disposition sur http://manpagesfr.free.fr/.
Les mises à jour et corrections de la version présente dans Debian
sont directement gérées par Nicolas François <nicolas.francois@cen‐
traliens.net> et l’équipe francophone de traduction de Debian.
Veuillez signaler toute erreur de traduction en écrivant Ã
<debian-l10n-french [AT] lists.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> ».
GNU 12 juillet 2007 SCANF(3)