scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - Entrées
formatées
#include <stdio.h>
int scanf(const char *format, ...);
int fscanf(FILE *flux, const char *format, ...);
int sscanf(const char *chaîne, const char *format, ...);
#include <stdarg.h>
int vscanf(const char *format, va_list ap);
int vsscanf(const char *chaîne, const char *format, va_list ap);
int vfscanf(FILE *flux, const char *format, va_list ap);
vscanf(), vsscanf(), vfscanf() :
_ISOC99_SOURCE ||
_POSIX_C_SOURCE >= 200112L
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 flux, et
sscanf() lit ses entrées dans la chaîne de
caractères pointée par chaîne.
La fonction vfscanf() est analogue à
vfprintf(3) et lit ses arguments depuis le flux pointé par
flux 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 comment 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()
renvoie. 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 soit avec le caractère
« % », soit avec 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().
-
•
- Pour les conversions décimales, un caractère apostrophe
« ' ». Il indique que le nombre en
entrée peut comporter des séparateurs de milliers tels que
défini par la catégorie LC_NUMERIC de la locale
courante. Le caractère apostrophe peut précéder ou
suivre le caractère d'affectation-suppression
« * ».
-
•
- 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 lorsqu'on trouve un caractère qui ne
correspond pas, quelque soit la condition vérifiée en
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 NULL final
(« \0 ») pour marquer la fin de
l'entrée ; la largeur maximale du champ n'inclut pas ce
caractère de terminaison.
-
•
- An optional type modifier character. For example, the l type
modifier is used with integer conversions such as %d to specify
that the corresponding pointer argument refers to a long
rather than a pointer to an 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.
Les caractères modificateurs de type suivant peuvent
se apparaître dans une spécification de
conversion :
- h
- Indicates that the conversion will be one of d, i, o,
u, x, X, or n and the next pointer is a
pointer to a short or unsigned short (rather than
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
- Indicates either that the conversion will be one of d, i,
o, u, x, X, or n and the next pointer
is a pointer to a long or unsigned long (rather than
int), or that the conversion will be one of e, f, or
g and the next pointer is a pointer to double (rather than
float). Specifying two l characters is equivalent to
L. If used with %c or %s, the corresponding parameter
is considered as a pointer to a wide character or wide-character string
respectively.
- 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 affectation n'a lieu.
- d
- Correspond à un entier décimal éventuellement
signé, le pointeur correspondant doit être un pointeur vers
un int.
- 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é. Il peut
éventuellement commencer par le préfixe 0x ou
0X qui sera alors écarté. 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 suivant 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 NULL final
(« \0 ») qui est ajouté
automatiquement. La conversion s'arrête soit au premier
caractère blanc, soit à la longueur maximale du champ,
quelle que soit la condition vérifiée en premier.
- 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 caractère, et il doit y avoir suffisamment
de place dans la chaîne pour tous les caractères. Aucun
octet NULL 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 caractère 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 tous 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 a 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 suivant, qui
doit être un pointeur vers un int. Il ne s'agit pas
d'une conversion et le compteur d'assignations renvoyé à la
fin de l'exécution n'est pas incrémente. L'assignation peut
être supprimée par le caractère
d'assignation-suppression *, mais l'effet sur la valeur
renvoyée n'est alors pas définit. Par conséquent, les
conversions %*n ne devraient pas être utilisées.
En cas de succès, ces fonctions renvoient le nombre
d'éléments d'entrées correctement mis en correspondance
et affectés. Ce nombre peut être plus petit que le nombre
d'éléments attendus, et même être nul, dans le
cas d'une erreur précoce 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
- EAGAIN
- Le descripteur de fichier flux sous-jacent est non bloquant et
l'opération de lecture bloquerait.
- EBADF
- Le descripteur de fichier flux 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 assez de mémoire.
- ERANGE
- Le résultat de la conversion entière est plus grand que la
taille pouvant être stockée dans le type entier
correspondant.
Pour une explication des termes utilisés dans cette
section, consulter attributes(7).
| Interface |
Attribut |
Valeur |
| scanf(), fscanf(), sscanf(), vscanf(),
vsscanf(), vfscanf() |
Sécurité des threads |
MT-Safe locale |
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.
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 la 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 la 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.).
Toutes ces fonctions sont totalement conformes à C89, mais
lui ajoutent les spécificateurs q et a ainsi que les
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.
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.
Cette page fait partie de la publication 5.10 du projet
man-pages Linux. Une description du projet et des instructions pour
signaler des anomalies et la dernière version de cette page peuvent
être trouvées à l'adresse
https://www.kernel.org/doc/man-pages/.
La traduction française de cette page de manuel a
été créée par Christophe Blaess
<https://www.blaess.fr/christophe/>, Stéphan Rafin
<stephan.rafin@laposte.net>, Thierry Vignaud
<tvignaud@mandriva.com>, François Micaux, Alain Portal
<aportal@univ-montp2.fr>, Jean-Philippe Guérard
<fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh)
<jean-luc.coulon@wanadoo.fr>, Julien Cristau
<jcristau@debian.org>, Thomas Huriaux
<thomas.huriaux@gmail.com>, Nicolas François
<nicolas.francois@centraliens.net>, Florentin Duneau
<fduneau@gmail.com>, Simon Paillard
<simon.paillard@resel.enst-bretagne.fr>, Denis Barbier
<barbier@debian.org>, David Prévot <david@tilapin.org>,
Frédéric Hantrais <fhantrais@gmail.com> et
Grégoire Scano <gregoire.scano@malloc.fr>
Cette traduction est une documentation libre ; veuillez
vous reporter à la
GNU General
Public License version 3 concernant les conditions de copie et de
distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.
Si vous découvrez un bogue dans la traduction de cette page
de manuel, veuillez envoyer un message à
debian-l10n-french@lists.debian.org.