sscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l

Articolo
06/09/2015

Legge i dati formattati da una stringa. Queste versioni di sscanf, _sscanf_l, swscanf, _swscanf_l contengono i miglioramenti della sicurezza come descritto in Funzionalità di sicurezza in 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 ] ...
);

Parametri

buffer
Dati archiviati
format
Stringa di controllo del formato. Per ulteriori informazioni, vedere Campi per la specifica di formato: funzioni scanf e wscanf.
argument
Argomenti facoltativi
locale
Impostazioni locali da utilizzare.

Valore restituito

Ognuna di queste funzioni restituisce il numero di campi che vengono convertiti correttamente e assegnati; il valore restituito non include i campi che sono stati letti ma non assegnati. Un valore restituito pari a 0 indica che nessun campo è stato assegnato. Il valore restituito è EOF per un errore, o se la fine della stringa viene raggiunta prima della prima conversione.

Se buffer o format è un NULL puntatore null, viene richiamato il gestore di parametro non valido, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, la funzione restituisce -1 e imposta errno su EINVAL

Per informazioni su questi e altri codici di errore, vedere errno, _doserrno, _sys_errlist, and _sys_nerr.

Note

La funzione sscanf_s legge i dati da buffer alla posizione fornita da ogni argument. I parametri dopo la stringa format specificano i puntatori a variabili che hanno un tipo che corrisponde a un tipo identificatore in format. A differenza della versione meno sicura sscanf, un parametro della dimensione del buffer è obbligatorio quando si utilizzano i caratteri di campo di tipo c, C, s, S o set di controllo di stringa racchiusi in []. La dimensione del buffer nei caratteri deve essere fornita come parametro aggiuntivo subito dopo ogni parametro del buffer che lo richiede. Ad esempio, se si sta leggendo una stringa, la dimensione del buffer per tale stringa viene passata come segue:

wchar_t ws[10];

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

La dimensione del buffer include il carattere di terminazione null. Un campo di specifica della larghezza può essere utilizzato per assicurarsi che il token che viene letto verrà inserito nel buffer. Se non viene utilizzato alcun campo di specifica della larghezza e il token letto è troppo grande per adattarsi al buffer, in quest'ultimo non vengono scritti dati.

In caso di caratteri, un singolo carattere può essere letto come segue:

wchar_t wc;

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

In questo esempio viene letto un singolo carattere nella stringa di input e quindi memorizzato in un buffer a caratteri estesi. Quando si leggono più caratteri di stringe senza caratteri di terminazione, viene usato un valore unsigned integer che specifica la sua lunghezza e la dimensione del buffer.

char c[4];

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

Per ulteriori informazioni, vedere scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l e Caratteri di campo di tipo per scanf.

Nota

Il parametro di dimensione è di tipo unsigned, non size_t.

L'argomento format controlla l'interpretazione dei campi di input e ha gli stessi form e funzione dell'argomento format per la funzione scanf_s. Se la copia avviene tra stringhe che si sovrappongono, il comportamento non è definito.

swscanf_s è una versione a caratteri estesi di sscanf_s; quindi gli argomenti di swscanf_s sono stringhe a caratteri estesi. sscanf_s non gestisce caratteri esadecimali multibyte. swscanf_s non gestisce i caratteri esadecimali o dell'"area di compatibilità" a larghezza intera Unicode. Altrimenti swscanf_s e sscanf_s si comportano in modo identico.

Le versioni di queste funzioni che hanno il suffisso _l sono identiche ad eccezione del fatto che utilizzano il parametro delle impostazioni locali che viene passato al posto di quelle della thread corrente.

Mapping di routine su testo generico

Routine TCHAR.H	_UNICODE & _MBCS non definiti	_MBCS definito	_UNICODE definito
_stscanf_s	sscanf_s	sscanf_s	swscanf_s
_stscanf_s_l	_sscanf_s_l	_sscanf_s_l	_swscanf_s_l

Requisiti

Routine	Intestazione obbligatoria
sscanf_s, _sscanf_s_l	<stdio.h>
swscanf_s, _swscanf_s_l	<stdio.h> o <wchar.h>

Per ulteriori informazioni sulla compatibilità, vedere Compatibilità.

Esempio

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