scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l

 

Date de publication : novembre 2016

Pour obtenir la dernière documentation sur Visual Studio 2017, consultez Documentation Visual Studio 2017.

Lit les données mises en forme du flux d'entrée standard. Ces versions de scanf, _scanf_l, wscanf, _wscanf_l ont des améliorations de sécurité, comme décrit dans fonctionnalités de sécurité de la bibliothèque 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
Format de la chaîne de contrôle.

argument
Arguments facultatifs.

locale
Paramètres régionaux à utiliser.

Retourne le nombre de champs correctement convertis et assignés. La valeur de retour n'inclut pas les champs qui ont été lus mais pas assignés. La valeur de retour 0 indique qu'aucun champ n'a été assigné. La valeur de retour est EOF si une erreur est détectée, ou si le caractère de fin de fichier ou le caractère de fin de chaîne est rencontré durant la première tentative de lecture d'un caractère. Si format est un NULL pointeur, le Gestionnaire de paramètre non valide est appelé, comme décrit dans Validation de paramètre. Si l'exécution est autorisée à continuer, scanf_s et wscanf_s retournent EOF et définissent errno à EINVAL.

Pour plus d’informations sur les autres codes d’erreur, consultez errno, _doserrno, _sys_errlist et _sys_nerr.

La fonction scanf_s lit les données du flux d'entrée standard stdin et les écrit dans l'emplacement indiqué par argument. Chaque argument doit être un pointeur vers une variable d'un type qui correspond à un spécificateur de type dans format. Si une 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 de 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 pas en charge actuellement les entrées à partir d'un flux UNICODE.

Les versions de ces fonctions avec 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 nécessitent 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 pour les jeux de contrôles de chaîne 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 la mémoire tampon pour cette chaîne est passée comme suit :

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 inclut le caractère Null de fin. Vous pouvez utiliser un champ de spécification de largeur pour vous assurer que le jeton lu sera contenu sans problème en mémoire tampon. Si aucun champ de spécification de largeur n'est utilisé, et si le jeton lu est trop grand pour la mémoire tampon, aucune valeur n'est écrite dans cette mémoire tampon.

System_CAPS_ICON_note.jpg Remarque

Le paramètre relatif à la taille est de type unsigned, et non size_t. Utilisez un cast statique pour convertir un size_t valeur unsigned 64 bits des configurations de build.

L'exemple suivant montre que le paramètre relatif à la taille de la mémoire tampon décrit le nombre maximal de caractères, et non 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(L"%9S", ws, (unsigned)_countof(ws));  

Le spécificateur de format S indique l'utilisation de la largeur des caractères « inverse » à la largeur par défaut prise en charge par la fonction. La largeur des caractères est basée sur les caractères codés sur un octet, mais la fonction prend en charge les caractères codés sur deux octets. Cet exemple lit une chaîne d'une largeur maximale de 9 caractères codés sur un octet, et les place dans une mémoire tampon dont la largeur est basée sur des caractères codés sur deux octets. 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.

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

char c;

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

Durant la lecture de plusieurs caractères pour les chaînes qui ne se terminent pas par une valeur Null, des entiers sont utilisés pour la spécification de la largeur et la taille de la mémoire tampon.

char c[4];

scanf_s("%4c", &c, (unsigned)_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 et _MBCS non définis_MBCS défini_UNICODE défini
_tscanf_sscanf_sscanf_swscanf_s
_tscanf_s_l_scanf_s_l_scanf_s_l_wscanf_s_l

Pour plus d’informations, consultez des champs de spécification de Format : fonctions scanf et wscanf.

RoutineEn-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 8.x 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 du Windows 8.x Store. Pour plus d'informations sur la compatibilité, voir Compatibilité.

// 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é :

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  

Prise en charge de virgule flottante
Flux d’e/s
Paramètres régionaux
fscanf, _fscanf_l, fwscanf, _fwscanf_l
printf, _printf_l, wprintf, _wprintf_l
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
sscanf, _sscanf_l, swscanf, _swscanf_l

Afficher: