scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l

Articolo
06/09/2015

Legge i dati formattatati dal flusso di input standard. Queste versioni di scanf, _scanf_l, wscanf, _wscanf_l contengono i miglioramenti della sicurezza come descritto in Funzionalità di sicurezza in 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]... 
);

Parametri

format
Stringa di controllo del formato.
argument
Argomenti facoltativi.
locale
Impostazioni locali da utilizzare.

Valore restituito

Restituisce il numero di campi che vengono convertiti correttamente e assegnati; nel valore restituito non sono inclusi 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 il carattere della fine del file o della stringa viene rilevato nel primo tentativo di leggere un carattere. Se format è un NULL puntatore null, viene richiamato il gestore di parametro non valido, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, scanf_s e wscanf_s restituiscono EOF e impostano errno su EINVAL.

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

Note

La funzione scanf_s legge i dati dal flusso di input standard stdin e scrive i dati nella locazione che è data da argument. Ogni argument deve essere un puntatore alla variabile di un tipo che corrisponde ad un tipo specificato in format. Se la copia avviene tra stringhe che si sovrappongono, il comportamento non è definito.

wscanf_s è una versione a caratteri estesi di scanf_s; l'argomento format in wscanf_s è una stringa di caratteri estesi. wscanf_s e scanf_s si comportano in modo identico se il flusso viene aperto in modalità ANSI. scanf_s attualmente non supporta l'input da un flusso di UNICODE.

Le versioni di queste funzioni che hanno il suffisso _l sono identiche ad eccezione del fatto che utilizzano il parametro delle impostazioni locali che è passato in ingresso anziché utilizzare quello della thread corrente.

A differenza di scanf e wscanf, scanf_s e wscanf_s richiedono che sia specificata la dimensione del buffer per tutti i parametri di input di tipo c, C, s, S, o set di controlli della stringa racchiusi in []. La dimensione del buffer nei caratteri viene passata come parametro aggiuntivo immediatamente dopo il puntatore al buffer o variabile. Ad esempio, se si sta leggendo una stringa, la dimensione del buffer per tale stringa viene passata nel modo seguente:

char s[10];

scanf_s("%9s", s, _countof(s)); // buffer size is 10, width specification is 9

La dimensione del buffer include il carattere di terminazione null. È possibile utilizzare un campo che specifica la lunghezza per assicurarsi che il token venga letto ed 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.

Nota

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

L'esempio seguente mostra che il parametro di dimensione del buffer indica il numero massimo di caratteri, non di byte. Nella chiamata a wscanf_s, la larghezza del carattere indicata dal tipo di buffer non corrisponde alla larghezza del carattere che è indicata nell'identificatore di formato.

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

L'identificatore di formato S indica l'utilizzo della larghezza del carattere che è "opposta" alla larghezza predefinita supportata dalla funzione. La larghezza del carattere è a singolo byte, ma la funziona supporta caratteri con doppio byte. In questo esempio viene letta una stringa con al più 9 caratteri estesi a singolo byte e li inserisce in un buffer con caratteri estesi a doppio byte. I caratteri vengono trattati come valori a singolo byte; i primi due caratteri vengono archiviati in ws[0], i due secondi vengono archiviati in ws[1], e così via.

Nel caso dei caratteri, un singolo carattere può essere letto come segue:

char c;

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

Quando vengono letti più caratteri di stringhe terminanti non null, vengono utilizzati valori integer per specificare la larghezza e la dimensione del buffer.

char c[4];

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

Per ulteriori informazioni, vedere Specifica della larghezza per scanf.

Mapping di routine su testo generico

Routine TCHAR.H	_UNICODE & e _MBCS non definiti	_MBCS definito	_UNICODE definito
_tscanf_s	scanf_s	scanf_s	wscanf_s
_tscanf_s_l	_scanf_s_l	_scanf_s_l	_wscanf_s_l

Per ulteriori informazioni, vedere Campi per la specifica di formato: funzioni scanf e wscanf.

Requisiti

Routine	Intestazione obbligatoria
scanf_s, _scanf_s_l	<stdio.h>
wscanf_s, _wscanf_s_l	<stdio.h> o <wchar.h>

La console non è supportata nelle applicazioni Windows Store. Gli handle del flusso standard associati alla console,stdin, stdout e stderr, devono essere reindirizzati prima di poter utilizzare le funzioni di runtime del linguaggio C nelle applicazioni Windows Store. Per ulteriori informazioni sulla compatibilità, vedere Compatibilità.

Esempio

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

Questo programma produce l'output seguente quando viene fornito questo input:

71 98.6 h z Byte characters

36 92.3 y n Wide characters