scanf, fscanf, sscanf, scanf_s, fscanf_s, sscanf_s

Défini dans l'en-tête `<stdio.h>`
int scanf( const char* format, ... );	(1)	(jusqu'à C99)
int scanf( const char* restrict format, ... );	(1)		(depuis C99)
int fscanf( FILE* stream, const char* format, ... );	(2)	(jusqu'à C99)
int fscanf( FILE* restrict stream, const char* restrict format, ... );	(2)		(depuis C99)
int sscanf( const char* buffer, const char* format, ... );	(3)	(jusqu'à C99)
int sscanf( const char* restrict buffer, const char* restrict format, ... );	(3)		(depuis C99)
int scanf_s(const char* restrict format, ...);	(4)	(depuis C11)
int fscanf_s(FILE* restrict stream, const char* restrict format, ...);	(5)	(depuis C11)
int sscanf_s(const char* restrict buffer, const char* restrict format, ...);	(6)	(depuis C11)

Lit des données à partir de diverses sources, les interprète selon format et stocke les résultats dans des emplacements donnés.

1) lit les données depuis stdin

2) lit les données depuis le flux de fichier stream

3) lit les données depuis la chaîne de caractères terminée par un caractère nul buffer. Atteindre la fin de la chaîne est équivalent à atteindre la condition de fin de fichier pour fscanf

4-6) Identique à (1-3), sauf que les spécificateurs de conversion %c, %s et %[ attendent chacun deux arguments (le pointeur habituel et une valeur de type rsize_t indiquant la taille du tableau récepteur, qui peut être 1 lors de la lecture avec un %c dans un seul caractère) et sauf que les erreurs suivantes sont détectées à l'exécution et appellent la fonction gestionnaire de contrainte actuellement installée :

l'un des arguments de type pointeur est un pointeur nul
format, stream ou buffer est un pointeur nul
le nombre de caractères qui seraient écrits par %c, %s ou %[, plus le caractère nul de terminaison, dépasserait le deuxième argument (rsize_t) fourni pour chacun de ces spécificateurs de conversion
éventuellement, toute autre erreur détectable, comme un spécificateur de conversion inconnu

Comme pour toutes les fonctions avec vérification des limites, scanf_s, fscanf_s et sscanf_s ne sont garanties disponibles que si __STDC_LIB_EXT1__ est défini par l'implémentation et si l'utilisateur définit __STDC_WANT_LIB_EXT1__ comme la constante entière 1 avant d'inclure <stdio.h>.

Paramètres

stream	-	flux de fichier d'entrée à lire
buffer	-	pointeur vers une chaîne de caractères terminée par un caractère nul à lire
format	-	pointeur vers une chaîne de caractères terminée par un caractère nul spécifiant comment lire l'entrée
...	-	arguments récepteurs.

La chaîne format se compose de

caractères multi-octets non blancs sauf % : chaque caractère de ce type dans la chaîne de format consomme exactement un caractère identique du flux d'entrée, ou fait échouer la fonction si le caractère suivant du flux n'est pas égal.
caractères blancs : n'importe quel caractère blanc dans la chaîne de format consomme tous les caractères blancs consécutifs disponibles de l'entrée (déterminé comme en appelant isspace en boucle). Notez qu'il n'y a pas de différence entre "\n", " ", "\t\t" ou d'autres blancs dans la chaîne de format.
spécifications de conversion. Chaque spécification de conversion a le format suivant :

caractère d'introduction %.

(optionnel) caractère de suppression d'affectation *. Si cette option est présente, la fonction n'assigne le résultat de la conversion à aucun argument récepteur.

(optionnel) nombre entier (supérieur à zéro) qui spécifie la largeur de champ maximale, c'est-à-dire le nombre maximum de caractères que la fonction est autorisée à consommer lors de la conversion spécifiée par la spécification de conversion courante. Notez que %s et %[ peuvent entraîner un débordement de tampon si la largeur n'est pas fournie.

(optionnel) modificateur de longueur qui spécifie la taille de l'argument récepteur, c'est-à-dire le type de destination réel. Cela affecte la précision de conversion et les règles de débordement. Le type de destination par défaut est différent pour chaque type de conversion (voir tableau ci-dessous).

spécificateur de format de conversion.

Les spécificateurs de format suivants sont disponibles :

Spécificateur de conversion	Explication	Type d'argument attendu
Modificateur de longueur→		`hh`	`h`	aucun	`l`	`ll`	`j`	`z`	`t`	`L`
Disponible uniquement depuis C99→		Oui				Oui	Oui	Oui	Oui
`%`	Correspond au littéral `%`.	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A	N/A
`c`	Correspond à un caractère ou une séquence de caractères. Si un spécificateur de largeur est utilisé, correspond exactement à largeur caractères (l'argument doit être un pointeur vers un tableau avec suffisamment d'espace). Contrairement à %s et %[, n'ajoute pas le caractère nul au tableau.	N/A	N/A	`char*`	`wchar_t*`	N/A	N/A	N/A	N/A	N/A
`s`	Correspond à une séquence de caractères non blancs (une chaîne). Si un spécificateur de largeur est utilisé, correspond jusqu'à largeur ou jusqu'au premier caractère blanc, selon la première occurrence. Stocke toujours un caractère nul en plus des caractères correspondants (donc le tableau d'arguments doit avoir de la place pour au moins largeur+1 caractères).
`[`ensemble `]`	Correspond à une séquence non vide de caractères de l'ensemble de caractères. Si le premier caractère de l'ensemble est `^`, alors tous les caractères ne faisant pas partie de l'ensemble sont mis en correspondance. Si l'ensemble commence par `]` ou `^]` alors le caractère `]` est également inclus dans l'ensemble. La mise en œuvre définit si le caractère `-` en position non initiale dans le scanset peut indiquer une plage, comme dans `[0-9]`. Si un spécificateur de largeur est utilisé, correspond seulement jusqu'à largeur. Stocke toujours un caractère nul en plus des caractères correspondants (donc le tableau d'arguments doit avoir de la place pour au moins largeur+1 caractères).
`d`	Correspond à un entier décimal. Le format du nombre est le même que celui attendu par strtol avec la valeur `10` pour l'argument `base`.	`signed char` ou `unsigned char`	`signed short` ou `unsigned short`	`signed int` ou `unsigned int`	`signed long` ou `unsigned long`	`signed long long` ou `unsigned long long`	`intmax_t` ou `uintmax_t`	`size_t*`	`ptrdiff_t*`	N/A
`b` (C23)	Correspond à un entier binaire non signé. Le format du nombre est le même que celui attendu par strtoul avec la valeur `2` pour l'argument `base`.
`i`	Correspond à un entier. Le format du nombre est le même que celui attendu par strtol avec la valeur `0` pour l'argument `base` (la base est déterminée par les premiers caractères analysés).
`u`	Correspond à un entier décimal non signé. Le format du nombre est le même que celui attendu par strtoul avec la valeur `10` pour l'argument `base`.
`o`	Correspond à un entier octal non signé. Le format du nombre est le même que celui attendu par strtoul avec la valeur `8` pour l'argument `base`.
`x` `X`	Correspond à un entier hexadécimal non signé. Le format du nombre est le même que celui attendu par strtoul avec la valeur `16` pour l'argument `base`.
`n`	Retourne le nombre de caractères lus jusqu'à présent. Aucune entrée n'est consommée. N'incrémente pas le compteur d'affectation. Si le spécificateur a un opérateur de suppression d'affectation défini, le comportement est indéfini.
`a` (C99) `A` (C99) `e` `E` `f` `F` (C99) `g` `G`	Correspond à un nombre à virgule flottante. Le format du nombre est le même que celui attendu par strtof.	N/A	N/A	`float*`	`double*`	N/A	N/A	N/A	N/A	`long double*`
`p`	Correspond à une séquence de caractères définie par l'implémentation définissant un pointeur. `printf` La famille de fonctions devrait produire la même séquence en utilisant le spécificateur de format `%p`.	N/A	N/A	`void**`	N/A	N/A	N/A	N/A	N/A	N/A
Notes
Pour chaque spécificateur de conversion autre que `n`, la séquence la plus longue de caractères d'entrée qui ne dépasse aucune largeur de champ spécifiée et qui est soit exactement ce que le spécificateur de conversion attend, soit un préfixe d'une séquence qu'il attendrait, est consommée à partir du flux. Le premier caractère, s'il existe, après cette séquence consommée reste non lu. Si la séquence consommée a une longueur nulle ou si la séquence consommée ne peut pas être convertie comme spécifié ci-dessus, l'échec de correspondance se produit sauf si la fin du fichier, une erreur de codage ou une erreur de lecture a empêché l'entrée du flux, auquel cas il s'agit d'un échec d'entrée. Sauf pour le spécificateur `%`, l'élément d'entrée (ou, pour `%n`, le nombre de caractères d'entrée) est d'abord converti en un type approprié au spécificateur de conversion. Sauf si l'affectation a été supprimée avec `*`, le résultat de la conversion est écrit dans l'objet pointé par l'argument suivant qui n'a pas encore été écrit. Si cet objet n'a pas un type approprié, ou si le résultat de la conversion ne peut pas être représenté dans l'objet, le comportement est indéfini. Tous les spécificateurs de conversion autres que `[`, `c` et `n` consomment et suppriment tous les caractères blancs de début (déterminés comme en appelant isspace) avant de tenter d'analyser l'entrée. Ces caractères consommés ne comptent pas dans la largeur de champ maximale spécifiée. Les spécificateurs de conversion `lc`, `ls` et `l[` effectuent une conversion multi-octets en caractère large comme en appelant mbrtowc avec un objet mbstate_t initialisé à zéro avant la conversion du premier caractère. Les spécificateurs de conversion `s` et `[` stockent toujours le terminateur nul en plus des caractères correspondants. La taille du tableau de destination doit être au moins supérieure d'un à la largeur de champ spécifiée. L'utilisation de `%s` ou `%[` sans spécifier la taille du tableau de destination est aussi dangereuse que gets. Les spécifications de conversion correctes pour les types entiers à largeur fixe (int8_t, etc.) sont définies dans l'en-tête `<inttypes.h>` (bien que `SCNdMAX`, `SCNuMAX`, etc. soient synonymes de `%jd`, `%ju`, etc.). Il y a un point de séquence après l'action de chaque spécificateur de conversion ; cela permet de stocker plusieurs champs dans la même variable « réceptacle ». Lors de l'analyse d'une valeur à virgule flottante incomplète qui se termine par l'exposant sans chiffres, comme l'analyse de `"100er"` avec le spécificateur de conversion `%f`, la séquence `"100e"` (le préfixe le plus long d'un nombre à virgule flottante potentiellement valide) est consommée, ce qui entraîne une erreur de correspondance (la séquence consommée ne peut pas être convertie en un nombre à virgule flottante), avec `"r"` restant. Certaines implémentations existantes ne suivent pas cette règle et reviennent en arrière pour ne consommer que `"100"`, laissant `"er"`, par exemple bogue glibc 1765. Si une spécification de conversion est invalide, le comportement est indéfini.

Si une spécification de conversion est invalide, le comportement est indéfini.

Valeur de retour

1-3) Nombre d'arguments récepteurs assignés avec succès (qui peut être nul en cas d'échec de correspondance avant l'assignation du premier argument récepteur), ou EOF si un échec d'entrée survient avant l'assignation du premier argument récepteur.

4-6) Identique à (1-3), sauf que EOF est également retourné en cas de violation de contrainte à l'exécution.

Complexité

Non garantie. Notamment, certaines implémentations de sscanf sont en $O(N)$ , où N = strlen(buffer) [1].

Notes

Parce que la plupart des spécificateurs de conversion consomment d'abord tous les blancs consécutifs, du code comme

scanf("%d", &a);
scanf("%d", &b);

lira deux entiers saisis sur des lignes différentes (le deuxième %d consommera le saut de ligne laissé par le premier) ou sur la même ligne, séparés par des espaces ou des tabulations (le deuxième %d consommera les espaces ou les tabulations).

Les spécificateurs de conversion qui ne consomment pas les blancs de début, comme %c, peuvent être forcés à le faire en utilisant un caractère blanc dans la chaîne de format :

scanf("%d", &a);
scanf(" %c", &c); // consume all consecutive whitespace after %d, then read a char

Exemple

Exécuter ce code

#define __STDC_WANT_LIB_EXT1__ 1
#include <locale.h>
#include <stddef.h>
#include <stdio.h>

int main(void)
{
    int i, j;
    float x, y;
    char str1[10], str2[4];
    wchar_t warr[2];
    setlocale(LC_ALL, "en_US.utf8");

    char input[] = "25 54.32E-1 Thompson 56789 0123 56ß水";
    /* parse as follows:
       %d: an integer
       %f: a floating-point value
       %9s: a string of at most 9 non-whitespace characters
       %2d: two-digit integer (digits 5 and 6)
       %f:  a floating-point value (digits 7, 8, 9)
       %*d: an integer which isn't stored anywhere
       ' ': all consecutive whitespace
       %3[0-9]: a string of at most 3 decimal digits (digits 5 and 6)
       %2lc: two wide characters, using multibyte to wide conversion  */
    int ret = sscanf(input, "%d%f%9s%2d%f%*d %3[0-9]%2lc",
                     &i, &x, str1, &j, &y, str2, warr);

    printf("Converted %d fields:\n"
           "i = %d\n"
           "x = %f\n"
           "str1 = %s\n"
           "j = %d\n"
           "y = %f\n"
           "str2 = %s\n"
           "warr[0] = U+%x\n"
           "warr[1] = U+%x\n",
           ret, i, x, str1, j, y, str2, warr[0], warr[1]);

#ifdef __STDC_LIB_EXT1__
    int n = sscanf_s(input, "%d%f%s", &i, &x, str1, (rsize_t)sizeof str1);
    // writes 25 to i, 5.432 to x, the 9 bytes "Thompson\0" to str1, and 3 to n.
#endif
}

Sortie possible :

Converted 7 fields:
i = 25
x = 5.432000
str1 = Thompson
j = 56
y = 789.000000
str2 = 56
warr[0] = U+df
warr[1] = U+6c34

Références

Norme C23 (ISO/IEC 9899:2024) :

7.21.6.2 La fonction fscanf (p. : à déterminer)

7.21.6.4 La fonction scanf (p. : à déterminer)

7.21.6.7 La fonction sscanf (p. : à déterminer)

K.3.5.3.2 La fonction fscanf_s (p. : à déterminer)

K.3.5.3.4 La fonction scanf_s (p. : à déterminer)

K.3.5.3.7 La fonction sscanf_s (p. : à déterminer)

Norme C17 (ISO/IEC 9899:2018) :

7.21.6.2 La fonction fscanf (p. : 231-236)

7.21.6.4 La fonction scanf (p. : 236-237)

7.21.6.7 La fonction sscanf (p. : 238-239)

K.3.5.3.2 La fonction fscanf_s (p. : 430-431)

K.3.5.3.4 La fonction scanf_s (p. : 432)

K.3.5.3.7 La fonction sscanf_s (p. : 433)

Norme C11 (ISO/IEC 9899:2011) :

7.21.6.2 La fonction fscanf (p. : 317-324)

7.21.6.4 La fonction scanf (p. : 325)

7.21.6.7 La fonction sscanf (p. : 326)

K.3.5.3.2 La fonction fscanf_s (p. : 592-593)

K.3.5.3.4 La fonction scanf_s (p. : 594)

K.3.5.3.7 La fonction sscanf_s (p. : 596)

Norme C99 (ISO/IEC 9899:1999) :

7.19.6.2 La fonction fscanf (p. : 282-289)

7.19.6.4 La fonction scanf (p. : 290)

7.19.6.7 La fonction sscanf (p. : 291)

Norme C89/C90 (ISO/IEC 9899:1990) :

4.9.6.2 La fonction fscanf

4.9.6.4 La fonction scanf

4.9.6.6 La fonction sscanf

Voir aussi

vscanfvfscanfvsscanfvscanf_svfscanf_svsscanf_s (C99)(C99)(C99)(C11)(C11)(C11)	lit l'entrée formatée depuis stdin, un flux de fichier ou un tampon en utilisant une liste d'arguments variable (fonction)
fgets	obtient une chaîne de caractères depuis un flux de fichier (fonction)
printffprintfsprintfsnprintfprintf_sfprintf_ssprintf_ssnprintf_s (C99)(C11)(C11)(C11)(C11)	imprime la sortie formatée sur stdout, un flux de fichier ou un tampon (fonction)
Documentation C++ pour scanf, fscanf, sscanf

Support du compilateur
Langage
En-têtes
Support des types
Utilitaires de programme
Support des fonctions variadiques
Gestion des erreurs
Gestion dynamique de la mémoire
Bibliothèque de chaînes
Algorithmes
Numériques
Utilitaires de date et heure
Support d'entrée/sortie
Support de localisation
Support de la concurrence (C11)
Spécifications techniques
Index des symboles

fr.cppreference.net

Namespaces

Variants