sscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_lsscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l

Lit les données mises en forme d’une chaîne.Reads formatted data from a string. Ces versions de sscanf, _sscanf_l, swscanf, _swscanf_l intègrent les améliorations de sécurité décrites dans Fonctionnalités de sécurité dans le CRT.These versions of sscanf, _sscanf_l, swscanf, _swscanf_l have security enhancements, as described in Security Features in the CRT.

SyntaxeSyntax

int sscanf_s(
   const char *buffer,
   const char *format [,
   argument ] ...
);
int _sscanf_s_l(
   const char *buffer,
   const char *format,
   locale_t locale [,
   argument ] ...
);
int swscanf_s(
   const wchar_t *buffer,
   const wchar_t *format [,
   argument ] ...
);
int _swscanf_s_l(
   const wchar_t *buffer,
   const wchar_t *format,
   locale_t locale [,
   argument ] ...
);

ParamètresParameters

bufferbuffer
Données stockéesStored data

formatformat
Chaîne de contrôle de format.Format-control string. 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.

argumentargument
Arguments facultatifsOptional arguments

localelocale
Paramètres régionaux à utiliserThe locale to use

Valeur de retourReturn Value

Chacune de ces fonctions 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.Each of these functions returns the number of fields that are successfully converted and assigned; the return value does not include fields that were read but not assigned. La valeur de retour 0 indique qu'aucun champ n'a été assigné.A return value of 0 indicates that no fields were assigned. La valeur de retour est EOF pour une erreur ou si la fin de la chaîne est atteinte avant la première conversion.The return value is EOF for an error or if the end of the string is reached before the first conversion.

Si la mémoire tampon ou le format est un pointeur null , le gestionnaire de paramètres non valides est appelé, comme décrit dans validation de paramètre.If buffer or 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, ces fonctions retournent-1 et attribuent à errno la valeur EINVALIf execution is allowed to continue, these functions return -1 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 sscanf_s lit les données de la mémoire tampon dans l’emplacement donné par chaque argument.The sscanf_s function reads data from buffer into the location that's given by each argument. Les arguments qui suivent la chaîne de format spécifient des pointeurs vers des variables dont le type correspond à un spécificateur de type au format.The arguments after the format string specify pointers to variables that have a type that corresponds to a type specifier in format. Contrairement à la version moins sécurisée sscanf, un paramètre de taille de mémoire tampon est requis lorsque vous utilisez les jeux de contrôles de type c, c, s, sou String placés dans [] .Unlike the less secure version sscanf, a buffer size parameter is required when you use the type field characters c, C, s, S, or string control sets that are enclosed in []. La taille de mémoire tampon en caractères doit être fournie comme paramètre supplémentaire de suite après chaque paramètre de mémoire tampon qui le nécessite.The buffer size in characters must be supplied as an additional parameter immediately after each buffer parameter that requires it. 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 are reading into a string, the buffer size for that string is passed as follows:

wchar_t ws[10];
swscanf_s(in_str, L"%9s", ws, (unsigned)_countof(ws)); // buffer size is 10, width specification is 9

La taille de la mémoire tampon inclut le caractère Null de fin.The buffer size includes the terminating null. Un champ de spécification de largeur peut être utilisé pour faire en sorte que le jeton lu tiendra dans la mémoire tampon.A width specification field may be used to ensure that the token that's read in will fit into the buffer. 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.If no width specification field is used, and the token read in is too big to fit in the buffer, nothing is written to that buffer.

Dans le cas des caractères, un caractère unique peut être lu comme suit :In the case of characters, a single character may be read as follows:

wchar_t wc;
swscanf_s(in_str, L"%c", &wc, 1);

Cet exemple lit un caractère unique dans la chaîne d’entrée et le stocke dans une mémoire tampon à caractères larges.This example reads a single character from the input string and then stores it in a wide-character buffer. Quand vous lisez plusieurs caractères pour des chaînes qui ne se terminent pas par un caractère Null, des entiers non signés sont utilisés pour spécifier la largeur et la taille de la mémoire tampon.When you read multiple characters for non-null terminated strings, unsigned integers are used as the width specification and the buffer size.

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

Pour plus d’informations, consultez scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l et Caractères du champ de type scanf.For more information, see scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l and scanf Type Field Characters.

Notes

Le paramètre size est de type unsigned, et non size_t.The size parameter is of type unsigned, not size_t. Lors de la compilation pour les cibles 64 bits, utilisez un cast statique pour convertir les résultats _countof ou sizeof à la taille correcte.When compiling for 64-bit targets, use a static cast to convert _countof or sizeof results to the correct size.

L’argument format contrôle l’interprétation des champs d’entrée et a les mêmes forme et fonction que l’argument format pour la fonction scanf_s .The format argument controls the interpretation of the input fields and has the same form and function as the format argument for the scanf_s function. 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.

swscanf_s est une version à caractères larges de sscanf_s; les arguments de swscanf_s sont des chaînes à caractères larges.swscanf_s is a wide-character version of sscanf_s; the arguments to swscanf_s are wide-character strings. sscanf_s ne gère pas les caractères hexadécimaux multioctets.sscanf_s does not handle multibyte hexadecimal characters. swscanf_s ne gère pas les caractères hexadécimaux ou « zone de compatibilité » Unicode à pleine chasse.swscanf_s does not handle Unicode full-width hexadecimal or "compatibility zone" characters. Sinon, swscanf_s et sscanf_s se comportent de la même façon.Otherwise, swscanf_s and sscanf_s behave identically.

Les versions de ces fonctions qui ont 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.The versions of these functions that have the _l suffix are identical except that they use the locale parameter that's passed in instead of the current thread locale.

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
_stscanf_s_stscanf_s sscanf_ssscanf_s sscanf_ssscanf_s swscanf_sswscanf_s
_stscanf_s_l_stscanf_s_l _sscanf_s_l_sscanf_s_l _sscanf_s_l_sscanf_s_l _swscanf_s_l_swscanf_s_l

Configuration requiseRequirements

RoutineRoutine En-tête requisRequired header
sscanf_s, _sscanf_s_lsscanf_s, _sscanf_s_l <stdio.h><stdio.h>
swscanf_s, _swscanf_s_lswscanf_s, _swscanf_s_l <stdio.h> ou <wchar.h><stdio.h> or <wchar.h>

Pour plus d'informations sur la compatibilité, voir Compatibilité.For additional compatibility information, see Compatibility.

ExemplesExample

// crt_sscanf_s.c
// This program uses sscanf_s to read data items
// from a string named tokenstring, then displays them.

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

int main( void )
{
   char  tokenstring[] = "15 12 14...";
   char  s[81];
   char  c;
   int   i;
   float fp;

   // Input various data from tokenstring:
   // max 80 character string plus null terminator
   sscanf_s( tokenstring, "%s", s, (unsigned)_countof(s) );
   sscanf_s( tokenstring, "%c", &c, (unsigned)sizeof(char) );
   sscanf_s( tokenstring, "%d", &i );
   sscanf_s( tokenstring, "%f", &fp );

   // Output the data read
   printf_s( "String    = %s\n", s );
   printf_s( "Character = %c\n", c );
   printf_s( "Integer:  = %d\n", i );
   printf_s( "Real:     = %f\n", fp );
}
String    = 15
Character = 1
Integer:  = 15
Real:     = 15.000000

Voir aussiSee also

E/S de fluxStream I/O
fscanf, _fscanf_l, fwscanf, _fwscanf_lfscanf, _fscanf_l, fwscanf, _fwscanf_l
scanf, _scanf_l, wscanf, _wscanf_lscanf, _scanf_l, wscanf, _wscanf_l
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_lsprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
snprintf, _snprintf, _snprintf_l, _snwprintf, _snwprintf_lsnprintf, _snprintf, _snprintf_l, _snwprintf, _snwprintf_l