SCANF
Section : Manuel du programmeur Linux (
3)
Mise à jour de la version anglaise : 23 juin 2008
Index
Menu principal
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 (voir
feature_test_macros(7)) :
vscanf(),
vsscanf(),
vfscanf() :
_XOPEN_SOURCE >= 600 || _ISOC99_SOURCE ; 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, 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(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. ;
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 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 « a » optionnel.
Il est utilisé dans les conversions 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 conversion (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 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 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 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
diouxX
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
diouxX
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
efg
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
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.
- 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, et aucune assignation n'a lieu.
- d
-
Correspond à un entier décimal éventuellement signé,
le pointeur correspondant être un pointeur vers un
int.
- D
-
Équivalent à
ld,
utilisé uniquement pour compatibilité avec des versions antérieures.
(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 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ée de caractères inclus
ou exclus d'un ensemble donné.
L'ensembleest 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 (voir
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 valide.
- EINTR
-
La lecture a été interrompue par un signal ; voir
signal(7).
- EINVAL
-
Pas suffisamment d'arguments ; 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.
CONFORMITÉ
Les fonctions
fscanf(),
scanf(),
et
sscanf()
sont conformes à C89, C99 et POSIX.1-2001.
Ces normes n'indiquent pas d'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 oeil sur la documentation
info
de la
libc GNU (glibc-1.08)
pour une description complète.
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,
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 tampon, qui peut conduire
à un trou de sécurité important dans un programme Set-UID ou Set-GID.
NOTES
La glibc gère une extension non standard qui fait que la bibliothèque
alloue dynamiquement une chaîne de taille suffisante pour les chaînes d'entrée
ayant les spécificateurs de conversion
%s
et
%a[range].
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'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 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 indiqué dans la version POSIX.1 à venir.
VOIR AUSSI
getc(3),
printf(3),
setlocale(3),
strtod(3),
strtol(3),
strtoul(3)
TRADUCTION
Ce document est une traduction réalisée par Christophe Blaess
<http://www.blaess.fr/christophe/> le 18 novembre 1996, mise à jour par
Alain Portal <aportal AT univ-montp2 DOT fr> le 30 juin 2006
et révisée le 17 juillet 2008.
L'équipe de traduction a fait le maximum pour réaliser une adaptation
française de qualité. La version anglaise la plus à jour de ce document est
toujours consultable via la commande : « LANG=C man 3 scanf ».
N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute
erreur dans cette page de manuel.
Index
- NOM
-
- SYNOPSIS
-
- DESCRIPTION
-
- Conversions
-
- VALEUR RENVOYÉE
-
- ERREURS
-
- CONFORMITÉ
-
- BOGUES
-
- NOTES
-
- VOIR AUSSI
-
- TRADUCTION
-
Dernière mise à jour : 17 juillet 2008