scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_lscanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l

Lit les données mises en forme du flux d'entrée standard.Reads formatted data from the standard input stream. Ces versions de scanf, _scanf_l, wscanf, _wscanf_l intègrent les améliorations de sécurité décrites dans Fonctionnalités de sécurité dans le CRT.These versions of scanf, _scanf_l, wscanf, _wscanf_l have security enhancements, as described in Security Features in the CRT.

SyntaxeSyntax

int scanf_s(
   const char *format [,
   argument]...
);
int _scanf_s_l(
   const char *format,
   locale_t locale [,
   argument]...
);
int wscanf_s(
   const wchar_t *format [,
   argument]...
);
int _wscanf_s_l(
   const wchar_t *format,
   locale_t locale [,
   argument]...
);

ParamètresParameters

formatformat
Format de la chaîne de contrôle.Format control string.

argumentargument
Arguments facultatifs.Optional arguments.

localelocale
Paramètres régionaux à utiliser.The locale to use.

Valeur de retourReturn Value

Retourne le nombre de champs correctement convertis et assignés.Returns the number of fields successfully converted and assigned. La valeur de retour n’inclut pas les champs qui ont été lus mais qui n’ont pas été assignés.The return value doesn't include fields that were read but not assigned. Une valeur de retour de 0 indique qu’aucun champ n’a été assigné.A return value of 0 indicates no fields were assigned. La valeur de retour est EOF pour une erreur, ou si le caractère de fin de fichier ou le caractère de fin de chaîne est trouvé lors de la première tentative de lecture d’un caractère.The return value is EOF for an error, or if the end-of-file character or the end-of-string character is found in the first attempt to read a character. Si format est un pointeur null , le gestionnaire de paramètres non valides est appelé, comme décrit dans validation de paramètre.If format is a NULL pointer, the invalid parameter handler is invoked, as described in Parameter Validation. Si l’exécution est autorisée à se poursuivre, scanf_s et wscanf_s retournent EOF et attribuent à errno la valeur EINVAL.If execution is allowed to continue, scanf_s and wscanf_s return EOF and set errno to EINVAL.

Pour obtenir des informations sur ces codes d’erreur et les autres, consultez errno, _doserrno, _sys_errlist et _sys_nerr.For information about these and other error codes, see errno, _doserrno, _sys_errlist, and _sys_nerr.

NotesRemarks

La fonction scanf_s lit les données du flux d’entrée standard, stdin, et les écrit dans un argument.The scanf_s function reads data from the standard input stream, stdin, and writes it into argument. Chaque argument doit être un pointeur vers un type de variable qui correspond au spécificateur de type dans le format.Each argument must be a pointer to a variable type that corresponds to the type specifier in format. Si une copie se produit entre des chaînes qui se chevauchent, le comportement est indéfini.If copying occurs between strings that overlap, the behavior is undefined.

wscanf_s est une version à caractères larges de scanf_s; l’argument format de wscanf_s est une chaîne de caractères larges.wscanf_s is a wide-character version of scanf_s; the format argument to wscanf_s is a wide-character string. wscanf_s et scanf_s se comportent de la même manière si le flux est ouvert en mode ANSI.wscanf_s and scanf_s behave identically if the stream is opened in ANSI mode. scanf_s ne prend pas actuellement en charge l’entrée d’un flux Unicode.scanf_s doesn't currently support input from a UNICODE stream.

Les versions de ces fonctions qui ont le suffixe _L sont identiques, sauf qu’elles utilisent les paramètres régionaux à la place des paramètres régionaux du thread actuel.The versions of these functions that have the _l suffix are identical, except they use the locale parameter instead of the current thread locale.

Contrairement à scanf et wscanf, scanf_s et wscanf_s nécessitent que vous spécifiiez des tailles de mémoire tampon pour certains paramètres.Unlike scanf and wscanf, scanf_s and wscanf_s require you to specify buffer sizes for some parameters. Spécifiez les tailles pour tous les paramètres c, c, s , oujeu de contrôle de chaîne [] .Specify the sizes for all c, C, s, S, or string control set [] parameters. La taille de la mémoire tampon en caractères est passée en tant que paramètre supplémentaire.The buffer size in characters is passed as an additional parameter. Il suit immédiatement le pointeur vers la mémoire tampon ou la variable.It immediately follows the pointer to the buffer or variable. Par exemple, si vous lisez une chaîne, la taille de la mémoire tampon pour cette chaîne est passée comme suit :For example, if you're reading a string, the buffer size for that string is passed as follows:

char s[10];
scanf_s("%9s", s, (unsigned)_countof(s)); // buffer size is 10, width specification is 9

La taille de la mémoire tampon comprend le terminal null.The buffer size includes the terminal null. Vous pouvez utiliser un champ de spécification de largeur pour vous assurer que le jeton lu s’intègre dans la mémoire tampon.You can use a width specification field to ensure the token that's read in fits into the buffer. Lorsqu’un jeton est trop grand pour tenir, rien n’est écrit dans la mémoire tampon, sauf s’il existe une spécification de largeur.When a token is too large to fit, nothing is written to the buffer unless there's a width specification.

Notes

Le paramètre size est de type unsigned, et non size_t.The size parameter is of type unsigned, not size_t. Utilisez un cast statique pour convertir une valeur size_t en non signée pour les configurations de build 64 bits.Use a static cast to convert a size_t value to unsigned for 64-bit build configurations.

Le paramètre taille de la mémoire tampon décrit le nombre maximal de caractères, pas les octets.The buffer size parameter describes the maximum number of characters, not bytes. Dans cet exemple, la largeur du type de mémoire tampon ne correspond pas à la largeur du spécificateur de format.In this example, the width of the buffer type doesn't match the width of the format specifier.

wchar_t ws[10];
wscanf_s(L"%9S", ws, (unsigned)_countof(ws));

Le spécificateur de format S signifie utiliser la largeur de caractère « opposé » à la largeur par défaut prise en charge par la fonction.The S format specifier means use the character width that's "opposite" the default width supported by the function. La largeur des caractères est un octet unique, mais la fonction prend en charge les caractères codés sur deux octets.The character width is single byte, but the function supports double-byte characters. Cet exemple lit une chaîne allant jusqu’à neuf caractères codés sur un octet, et les place dans une mémoire tampon de caractères codés sur deux octets.This example reads in a string of up to nine single-byte-wide characters and puts them in a double-byte-wide character buffer. Les caractères sont traités comme des valeurs codées sur un octet. Les deux premiers caractères sont stockés dans ws[0], alors que les deux derniers sont stockés dans ws[1], et ainsi de suite.The characters are treated as single-byte values; the first two characters are stored in ws[0], the second two are stored in ws[1], and so on.

Cet exemple lit un caractère unique :This example reads a single character:

char c;
scanf_s("%c", &c, 1);

Lorsque plusieurs caractères pour les chaînes qui se terminent par un caractère NULL sont lus, des entiers sont utilisés pour la spécification de largeur et la taille de la mémoire tampon.When multiple characters for non-null-terminated strings are read, integers are used for both the width specification and the buffer size.

char c[4];
scanf_s("%4c", c, (unsigned)_countof(c)); // not null terminated

Pour plus d’informations, consultez Spécification de largeur scanf.For more information, see scanf Width Specification.

Mappages de routines de texte génériqueGeneric-Text Routine Mappings

Routine TCHAR.HTCHAR.H routine _UNICODE et _MBCS non définis_UNICODE & _MBCS not defined _MBCS défini_MBCS defined _UNICODE défini_UNICODE defined
_tscanf_s_tscanf_s scanf_sscanf_s scanf_sscanf_s wscanf_swscanf_s
_tscanf_s_l_tscanf_s_l _scanf_s_l_scanf_s_l _scanf_s_l_scanf_s_l _wscanf_s_l_wscanf_s_l

Pour plus d’informations, consultez Champs de spécification de format : fonctions scanf et wscanf.For more information, see Format Specification Fields: scanf and wscanf Functions.

Configuration requiseRequirements

RoutineRoutine En-tête requisRequired header
scanf_s, _scanf_s_lscanf_s, _scanf_s_l <stdio.h><stdio.h>
wscanf_s, _wscanf_s_lwscanf_s, _wscanf_s_l <stdio.h> ou <wchar.h><stdio.h> or <wchar.h>

La console n’est pas prise en charge dans les applications de plateforme Windows universelle (UWP).The console isn't supported in Universal Windows Platform (UWP) apps. Les handles de flux standard stdin, stdoutet stderr doivent être redirigés pour que les fonctions runtime C puissent les utiliser dans les applications UWP.The standard stream handles stdin, stdout, and stderr must be redirected before C run-time functions can use them in UWP apps. Pour plus d'informations sur la compatibilité, voir Compatibilité.For additional compatibility information, see Compatibility.

ExempleExample

// crt_scanf_s.c
// This program uses the scanf_s and wscanf_s functions
// to read formatted input.

#include <stdio.h>
#include <stdlib.h>

int main( void )
{
   int      i,
            result;
   float    fp;
   char     c,
            s[80];
   wchar_t  wc,
            ws[80];

   result = scanf_s( "%d %f %c %C %s %S", &i, &fp, &c, 1,
                     &wc, 1, s, (unsigned)_countof(s), ws, (unsigned)_countof(ws) );
   printf( "The number of fields input is %d\n", result );
   printf( "The contents are: %d %f %c %C %s %S\n", i, fp, c,
           wc, s, ws);
   result = wscanf_s( L"%d %f %hc %lc %S %ls", &i, &fp, &c, 2,
                      &wc, 1, s, (unsigned)_countof(s), ws, (unsigned)_countof(ws) );
   wprintf( L"The number of fields input is %d\n", result );
   wprintf( L"The contents are: %d %f %C %c %hs %s\n", i, fp,
            c, wc, s, ws);
}

Ce programme génère la sortie suivante en fonction de ce qui est entré :This program produces the following output when given this input:

71 98.6 h z Byte characters
36 92.3 y n Wide characters
The number of fields input is 6
The contents are: 71 98.599998 h z Byte characters
The number of fields input is 6
The contents are: 36 92.300003 y n Wide characters

Voir aussiSee also

Prise en charge de la virgule flottanteFloating-Point Support
E/S de fluxStream I/O
Paramètres régionauxLocale
fscanf, _fscanf_l, fwscanf, _fwscanf_lfscanf, _fscanf_l, fwscanf, _fwscanf_l
printf, _printf_l, wprintf, _wprintf_lprintf, _printf_l, wprintf, _wprintf_l
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_lsprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
sscanf, _sscanf_l, swscanf, _swscanf_lsscanf, _sscanf_l, swscanf, _swscanf_l