scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l

Article
06/09/2015

Lit les données mises en forme à partir du flux d'entrée standard. Ces versions scanf, _scanf_l, wscanf, _wscanf_l présentent des améliorations de sécurité, comme décrit dans Fonctionnalités de sécurité dans le 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 contrôle du format.
argument
Arguments facultatifs.
locale
Paramètres régionaux à utiliser.

Valeur de retour

Retourne le nombre de champs convertis et assignés avec succès ; la valeur de retour n'inclut pas les champs qui ont été lus mais non assignés. La valeur de retour 0 indique qu'aucun champ n'a été assigné. 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 rencontré lors de la première tentative de lecture d'un caractère. Si format est un pointeur NULL, le gestionnaire de paramètres non valides est appelé, comme décrit dans Validation de paramètre. Si l'exécution est autorisée à se poursuivre, scanf_s et wscanf_s retournent EOF et définissent errno avec la valeur EINVAL.

Pour plus d'informations sur ces codes de retour et autres, consultez errno, _doserrno, _sys_errlist et _sys_nerr.

Notes

La fonction scanf_s lit les données à partir du flux d'entrée standard stdin et les écrit dans l'emplacement fourni par la liste d'arguments argument. Chaque argument doit être un pointeur vers une variable dont le type correspond à un spécificateur de type dans format. Si la copie se produit entre des chaînes qui se chevauchent, le comportement est indéfini.

wscanf_s est une version à caractères larges de scanf_s; l'argument format vers wscanf_s est une chaîne à caractères larges. wscanf_s et scanf_s se comportent de la même façon si le flux est ouvert en mode ANSI. scanf_s ne prend actuellement pas en charge la saisie à partir d'un flux d'UNICODE.

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

Contrairement à scanf et wscanf, scanf_s et wscanf_s requièrent que la taille de la mémoire tampon soit spécifiée pour tous les paramètres d'entrée de type c, C, s, S, ou les ensembles de contrôles de chaîne placés entre []. La taille de la mémoire tampon en caractères est passée en tant que paramètre supplémentaire immédiatement après le pointeur vers la mémoire tampon ou la variable. Par exemple, si vous lisez 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 la mémoire tampon inclut le caractère null de fin. Utilisez un champ de spécification de largeur pour garantir que le jeton qui est lu pourra être contenu dans la mémoire tampon. Si aucun champ de spécification de largeur n'est utilisé, et le jeton lu dans est trop grand pour tenir dans la mémoire tampon, rien ne sera écrit dans cette mémoire tampon.

Notes

Le paramètre size est de type unsigned, et non du type size_t.

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

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

Le spécificateur de format S indique comment utiliser la largeur des caractères qui est «opposée» à la largeur par défaut prise en charge par la fonction. La largeur des caractères est codée sur un octet, mais la fonction prend en charge les caractères codés sur deux octets. Cet exemple lit dans une chaîne de 9 caractères maximum d'une taille d'un octet et les place dans une mémoire tampon de caractères d'une taille de deux octets. 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 suivants sont stockés dans ws[1], et ainsi de suite.

Dans le cas de caractères, un caractère unique peut être lu comme suit :

char c;

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

Lorsque plusieurs caractères sont lus pour les chaînes complètes non null, les entiers sont utilisés comme spécification de largeur et comme 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 largeur scanf.

Mappages de routines de texte générique

Routine TCHAR.H	_UNICODE & _MBCS non définis	_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 Champs de spécification de format : fonctions scanf et wscanf.

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 Windows Store . Les handles de flux standard associés à la console, stdin, stdout et stderr doivent être redirigés pour que les fonctions runtime C puissent les utiliser dans les applications Windows Store . Pour plus d'informations sur la compatibilité, consultez Compatibilité.

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);
}

Ce programme génère la sortie suivante quand cette entrée lui est donnée:

71 98.6 h z Byte characters

36 92.3 y n Wide characters