scanf(3) Library Functions Manual scanf(3)

scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf - Entrées formatées

Bibliothèque C standard (libc, -lc)

#include <stdio.h>
int scanf(const char *restrict format, ...);
int fscanf(FILE *restrict flux,
           const char *restrict format, ...);
int sscanf(const char *restrict chaîne,
           const char *restrict format, ...);
#include <stdarg.h>
int vscanf(const char *restrict format, va_list ap);
int vfscanf(FILE *restrict flux,
           const char *restrict format, va_list ap);
int vsscanf(const char *restrict chaîne,
           const char *restrict format, va_list ap);
Exigences de macros de test de fonctionnalités pour la glibc (consulter feature_test_macros(7)) :

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.
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 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.

Les caractères modificateurs de type suivant peuvent se apparaître dans une spécification de conversion :

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 ou un unsigned short (plutôt que sur un int).
Comme pour h, sauf que le pointeur suivant est un pointeur sur un signed char ou un unsigned char.
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.
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). If used with %c or %s, the corresponding parameter is considered as a pointer to a wide character or wide-character string respectively.
(ell-ell) Indicates that the conversion will be one of b, d, i, o, u, x, X, or n and the next pointer is a pointer to a long long or unsigned long long (rather than int).
Indicates that the conversion will be either e, f, or g and the next pointer is a pointer to long double or (as a GNU extension) the conversion will be d, i, o, u, or x and the next pointer is a pointer to long long.
Est équivalent à L. Ce spécificateur n'existe pas en C ANSI.
Comme pour h, mais le pointeur suivant est un pointeur vers un ptrdiff_t. Ce modificateur a été introduit dans C99.
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.
Deprecated. Matches an optionally signed decimal integer; the next pointer must be a pointer to int.
Deprecated. Matches an optionally signed integer; the next pointer must be a pointer to int. The integer is read in base 16 if it begins with 0x or 0X, in base 8 if it begins with 0, and in base 10 otherwise. Only characters that correspond to the base are used.
Deprecated. Matches an unsigned octal integer; the next pointer must be a pointer to unsigned int.
Deprecated. Matches an unsigned decimal integer; the next pointer must be a pointer to unsigned int.
Deprecated. Matches an unsigned hexadecimal integer (that may optionally begin with a prefix of 0x or 0X, which is discarded); the next pointer must be a pointer to unsigned int.
Deprecated. Equivalent to x.
Deprecated. Matches an optionally signed floating-point number; the next pointer must be a pointer to float.
Deprecated. Equivalent to f.
Deprecated. Equivalent to f.
Deprecated. Equivalent to f.
Deprecated. (C99) Equivalent to f.
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.
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.
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.
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

Le descripteur de fichier flux sous-jacent est non bloquant et l'opération de lecture bloquerait.
Le descripteur de fichier flux sous-jacent n'est pas valide ou bien n'est pas ouvert en lecture.
La séquence d'octet en entrée ne constitue pas un caractère valable.
La lecture a été interrompue par un signal ; consultez signal(7).
Pas suffisamment de paramètres ; ou bien format est NULL.
Plus assez de mémoire.

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

The functions fscanf(), scanf(), and sscanf() conform to C89 and C99 and POSIX.1-2001.

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).

Note that the a modifier is not available if the program is compiled with gcc -std=c99 or gcc -D_ISOC99_SOURCE (unless _GNU_SOURCE is also specified), in which case the a is interpreted as a specifier for floating-point numbers (see above).

Support for the m modifier was added to glibc 2.7, and new programs should use that modifier instead of a.

As well as being standardized by POSIX, the m modifier has the following further advantages over the use of a:

  • Il peut être appliqué aux spécificateurs de conversion %c (par exemple %3mc).
  • It avoids ambiguity with respect to the %a floating-point conversion specifier (and is unaffected by gcc -std=c99 etc.).

All functions are fully C89 conformant, but provide the additional modifiers q and a as well as an additional behavior of the L and ll modifiers. The latter may be considered to be a bug, as it changes the behavior of modifiers defined in 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.

getc(3), printf(3), setlocale(3), strtod(3), strtol(3), strtoul(3)

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.

15 décembre 2022 Pages du manuel de Linux 6.02