SCANF(3)

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 (consulter feature_test_macros(7)) :

vscanf(), vsscanf(), vfscanf() :
    _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L

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

•   For decimal conversions, an optional quote character ('). This specifies that the input number may include thousands' separators as defined by the LC_NUMERIC category of the current locale. (See setlocale(3).) The quote character may precede or follow the '*' assignment-suppression character.

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

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

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   Matches a sequence of non-white-space characters; the next pointer must be a pointer to the initial element of a character array that is long enough to hold the input sequence and the terminating null byte ('\0'), which is added automatically. The input string stops at white space or at the maximum field width, whichever occurs first.

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.

[   Matches a nonempty sequence of characters from the specified set of accepted characters; the next pointer must be a pointer to char, and there must be enough room for all the characters in the string, plus a terminating null byte. The usual skip of leading white space is suppressed. The string is to be made up of characters in (or not in) a particular set; the set is defined by the characters between the open bracket [ character and a close bracket ] character. The set excludes those characters if the first character after the open bracket is a circumflex (^). To include a close bracket in the set, make it the first character after the open bracket or the circumflex; any other position will end the set. The hyphen character - is also special; when placed between two other characters, it adds all intervening characters to the set. To include a hyphen, make it the last character before the final close bracket. For instance, [^]0-9-] means the set "everything except close bracket, zero through nine, and hyphen". The string ends with the appearance of a character not in the (or, with a circumflex, in) set or when the field width runs out.

p   Matches a pointer value (as printed by %p in printf(3)); the next pointer must be a pointer to a pointer to void.

n   Nothing is expected; instead, the number of characters consumed thus far from the input is stored through the next pointer, which must be a pointer to int. This is not a conversion and does not increase the count returned by the function. The assignment can be suppressed with the * assignment-suppression character, but the effect on the return value is undefined. Therefore %*n conversions should not be used.

VALEUR RENVOYÉE
On success, these functions return the number of input items successfully matched and assigned; this can be fewer than provided for, or even zero, in the event of an early matching failure.

The value EOF is returned if the end of input is reached before either the first successful conversion or a matching failure occurs. EOF is also returned if a read error occurs, in which case the error indicator for the stream (see ferror(3)) is set, and errno is set to indicate the error.

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

ATTRIBUTS
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

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.

EXEMPLES
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 5.08 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/.

TRADUCTION
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> et Frédéric Hantrais <fhantrais@gmail.com> 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>.