scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l

Article
03/26/2013

Données mises en forme lues dans le flux d'entrée standard.Ce sont des versions de scanf, _scanf_l, wscanf, _wscanf_l avec des améliorations de sécurité comme décrit dans Fonctionnalités de sécurité du CRT.

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ètres

format
Chaîne de format.
argument
Arguments facultatifs.
locale
Les paramètres régionaux à utiliser.

Valeur de retour

Retourne le nombre de champs avec succès convertis et assignés ; la valeur de retour n'inclut pas les champs qui ont été lus mais non assigné.Une valeur de retour de 0 indique qu'un champ n'a été assigné.La valeur de retour est EOFpour une erreur ou si le caractère de fin de fichier ou le caractère de fin de chaîne est produit dans le premier test de la lecture d'un caractère.Si format est un pointeur d' NULL, le gestionnaire de paramètre non valide est appelé, comme décrit dans Validation des paramètres.Si est autorisé à l'exécution pour continuer, scanf_s et wscanf_s retournent EOF et le positionnement errno à EINVAL.

Pour plus d'informations sur ces derniers et d'autres codes d'erreur, consultez l' _doserrno, errno, _sys_errlist, et _sys_nerr.

Notes

La fonction d' scanf_slit les données du flux d'entrée standard stdinet écrit les données dans l'emplacement spécifié par argument.Chaque argument doit être un pointeur vers une variable d'un type qui correspond à un spécificateur de type dans format.Si copier nécessaire entre les chaînes qui se chevauchent, le comportement est pas défini.

wscanf_sest une version à caractère élargi d' scanf_s; l'argument d' format à wscanf_sest une chaîne à caractères larges.wscanf_set scanf_sse comportent de la même manière identique si le flux est ouvert en mode ANSI.scanf_s ne prend pas en charge actuellement l'entrée d'un flux d'UNICODE.

Les versions de ces fonctions avec le suffixe d' _l sont identiques sauf qu'elles utilisent le paramètre de paramètres régionaux passé au lieu des paramètres régionaux du thread actuel.

Contrairement à scanfet d' wscanf, scanf_set wscanf_srequièrent la taille de la mémoire tampon d'être spécifiée pour tous les paramètres d'entrée de type c, C, s, S, ou [.La taille de la mémoire tampon de caractères est passée comme paramètre supplémentaire qui suit immédiatement le pointeur dans la mémoire tampon ou la variable.Par exemple, si la lecture d'une chaîne, la taille de mémoire tampon pour cette chaîne est passée comme suit :

char s[10];

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

La taille de mémoire tampon inclut null de fin.Un champ de spécification de largeur peut être utilisé pour garantir que le jeton lu dans le insérera dans la mémoire tampon.Si un champ de spécification de largeur n'est utilisé, et le jeton lu est trop grand pour recevoir dans la mémoire tampon, rien ne sera écrit dans cette mémoire tampon.

[!REMARQUE]

Le paramètre de taille est de type unsigned, pas size_t.

L'exemple suivant montre que le paramètre de taille de mémoire tampon décrit le nombre maximal de caractères, et non des octets.Dans l'appel à wscanf_s, la largeur de caractère qui est indiquée par le type de mémoire tampon ne correspond pas à la largeur de caractère qui est indiquée par le spécificateur de format.

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

Le spécificateur de format d' S indique l'utilisation de la largeur de caractère qui est « contraire » de la largeur par défaut qui est prise en charge par la fonction.La largeur de caractère est codé sur un octet, mais les caractères codés sur deux octets de charge de fonction.Cet exemple lit dans une chaîne de jusqu'à 9 caractères unique-octet- larges et les place dans une mémoire tampon de caractères double-octet- large.Les caractères sont traités comme valeurs codées sur un octet ; les deux premiers caractères sont stockés dans ws[0], les deux deuxième sont stockés dans ws[1], et ainsi de suite.

Dans le cas de caractères, il peut lire un caractère unique comme suit :

char c;

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

Lors de la lecture de plusieurs caractères pour les chaînes terminées non null, les entiers sont utilisés comme spécification de largeur et de taille de mémoire tampon.

char c[4];

scanf_s("%4c", &c, _countof(c)); // not null terminated

Pour plus d'informations, consultez spécification de la largeur de scanf.

Mappages de routines de texte générique

Routine de TCHAR.H	_UNICODE et non définis _MBCS	_MBCS défini	_UNICODE défini
_tscanf_s	scanf_s	scanf_s	wscanf_s
_tscanf_s_l	_scanf_s_l	_scanf_s_l	_wscanf_s_l

Pour plus d'informations, consultez l' Champs de spécification de format — le scanf s'exécute et le wscanf s'exécute.

Configuration requise

Routine	En-tête requis
scanf_s, _scanf_s_l	<stdio.h>
wscanf_s, _wscanf_s_l	<stdio.h> ou <wchar.h>

La console n'est pas prise en charge dans les applications d' Windows Store .Les handles standard de flux de données associés à la console, stdin, stdout, et stderr, doivent être redirigés pour que les fonctions runtime C peuvent les utiliser dans des applications d' Windows Store .Pour des informations de compatibilité supplémentaires, consultez l' Compatibilité dans l'introduction.

Exemple

// 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, _countof(s), ws, _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, _countof(s), ws, _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);
}