sscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l

Article
06/09/2015

Lit les données mises en forme à partir d'une chaîne. Ces versions sscanf, _sscanf_l, swscanf, _swscanf_l présentent des améliorations de sécurité, comme décrit dans Fonctionnalités de sécurité dans le CRT.

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

buffer
Données stockées
format
Chaîne de contrôle de format. Pour plus d'informations, consultez Champs de spécification de format : fonctions scanf et wscanf.
argument
Arguments facultatifs
locale
Paramètres régionaux à utiliser

Valeur de retour

Chacune de ces fonctions retourne le nombre de champs qui sont correctement convertis et assigné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 la fin de la chaîne est atteinte avant la première conversion.

Si buffer ou 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, ces fonctions retournent -1 et attribuent à errno 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 sscanf_s lit les données dans buffer dans l'emplacement fourni par chaque argument. Les arguments après la chaîne de format spécifient des pointeurs vers des variables dont le type correspond à un spécificateur de type dans format. Contrairement à la version la moins sécurisée sscanf, un paramètre de taille de mémoire tampon est requis lorsque vous utilisez les caractères de champ de type c, C, s, S, ou des ensembles de contrôles de chaîne qui sont placés entre []. La taille de la mémoire tampon en caractères doit être fournie en tant que paramètre supplémentaire immédiatement après chaque paramètre de mémoire tampon qui la requiert. Par exemple, si vous lisez dans une chaîne, la taille de mémoire tampon pour cette chaîne est passée comme suit :

wchar_t ws[10];

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

La taille de la mémoire tampon inclut le caractère null de fin. Un champ de spécification de largeur peut être utilisé 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.

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

wchar_t wc;

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

Cet exemple lit un caractère unique de la chaîne d'entrée puis le stocke dans une mémoire tampon à caractères larges. Lorsque plusieurs caractères sont lus pour les chaînes complètes non null, les entiers non-signés sont utilisés comme spécification de largeur et comme taille de mémoire tampon.

char c[4];

sscanf_s(input, "%4c", &c, _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.

Notes

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

L'argument format contrôle l'interprétation des champs d'entrée et a la même forme et fonction que l'argument format pour la fonction scanf_s. Si la copie se produit entre des chaînes qui se chevauchent, le comportement est indéfini.

swscanf_s est une version à caractères larges de sscanf_s; les arguments vers swscanf_s sont des chaînes à caractères larges. sscanf_s ne gère pas les caractères hexadécimaux multioctets. swscanf_s ne gère pas les caractères pleine chasse hexadécimaux Unicode ou de « zone de compatibilité ». Sinon, swscanf_s et sscanf_s se comportent de la même façon.

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.

Mappages de routines de texte générique

Routine TCHAR.H	_UNICODE & _MBCS non définis	_MBCS défini	_UNICODE défini
_stscanf_s	sscanf_s	sscanf_s	swscanf_s
_stscanf_s_l	_sscanf_s_l	_sscanf_s_l	_swscanf_s_l

Configuration requise

Routine	En-tête requis
sscanf_s, _sscanf_s_l	<stdio.h>
swscanf_s, _swscanf_s_l	<stdio.h> ou <wchar.h>

Pour plus d'informations sur la compatibilité, consultez Compatibilité.

Exemple

// 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, _countof(s) );
   sscanf_s( tokenstring, "%c", &c, 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 );
}