`_snprintf_s`, `_snprintf_s_l`, `_snwprintf_s`, `_snwprintf_s_l`

Articolo
10/12/2023

Scrive dati formattati in una stringa. Queste funzioni sono versioni di snprintf, _snprintf, _snprintf_l, _snwprintf_snwprintf_l con miglioramenti della sicurezza descritti in Funzionalità di sicurezza in CRT.

Sintassi

int _snprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format [,
   argument] ...
);

int _snprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   _locale_t locale [,
   argument] ...
);

int _snwprintf_s(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format [,
   argument] ...
);

int _snwprintf_s_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format,
   _locale_t locale [,
   argument] ...
);

template <size_t size>
int _snprintf_s(
   char (&buffer)[size],
   size_t count,
   const char *format [,
   argument] ...
); // C++ only

template <size_t size>
int _snwprintf_s(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format [,
   argument] ...
); // C++ only

Parametri

buffer
Percorso di archiviazione per l'output.

sizeOfBuffer
Dimensioni dl percorso di archiviazione per l'output. Dimensioni in byte per le funzioni che accettano charle parole e per quelle che accettano wchar_t.

count
Numero massimo di caratteri da scrivere. Per le funzioni che accettano wchar_t, è il numero massimo di caratteri wide da scrivere. Oppure _TRUNCATE.

format
Stringa di controllo del formato.

argument
Argomenti facoltativi.

locale
Impostazioni locali da usare.

Valore restituito

Numero di caratteri scritti, senza includere l'oggetto di terminazione NULL. Se si verifica un errore di output, viene restituito un valore negativo. Per informazioni dettagliate, vedere Riepilogo del comportamento .

Osservazioni:

La _snprintf_s funzione formatta e archivia count o meno caratteri in buffer e aggiunge una terminazione NULL. Ogni argomento (se presente) viene convertito e restituito in base alla specifica di formato corrispondente in format. La formattazione è coerente con la printf famiglia di funzioni. Vedere sintassi delle specifiche di formato: printf e wprintf funzioni. Se la copia avviene tra stringhe che si sovrappongono, il comportamento non è definito.

Riepilogo del comportamento

Per la tabella seguente:

-Consente di len specificare le dimensioni dei dati formattati. Se la funzione accetta un char buffer, le dimensioni sono in byte. Se la funzione accetta un wchar_t buffer, la dimensione specifica il numero di parole a 16 bit.

I caratteri fanno riferimento ai char caratteri per le funzioni che accettano un char buffer e ai wchar_t caratteri per le funzioni che accettano un wchar_t buffer.
Per altre informazioni sul gestore di parametri non validi, vedere Convalida dei parametri.

Condizione	Comportamento	Valore restituito	`errno`	Richiama il gestore di parametri non validi
Riuscita	Scrive i caratteri nel buffer usando la stringa di formato specificata.	Numero di caratteri scritti, senza includere l'oggetto di terminazione `NULL`.	N/D	No
Errore di codifica durante la formattazione	Se l'elaborazione dell'identificatore `s`di stringa , `S`o `Z`, viene arrestata l'elaborazione della specifica del formato.	-1	`EILSEQ` (42)	No
Errore di codifica durante la formattazione	Se l'identificatore `c` di carattere di elaborazione o `C`, il carattere non valido viene ignorato. Il numero di caratteri scritti non viene incrementato per il carattere ignorato, né per i dati scritti. L'elaborazione della specifica del formato continua dopo aver ignorato l'identificatore con l'errore di codifica.	Numero di caratteri scritti, senza includere l'oggetto di terminazione `NULL`.	`EILSEQ` (42)	No
`buffer == NULL`e e `sizeOfBuffer == 0count == 0`	Non viene scritto alcun dato.	0	N/D	No
`buffer == NULL` e o `sizeOfBuffer != 0` o `count != 0`	Se l'esecuzione continua dopo l'esecuzione del gestore di parametri non validi, imposta `errno` e restituisce un valore negativo.	-1	`EINVAL` (22)	Sì
`buffer != NULL` e `sizeOfBuffer == 0`	Non viene scritto alcun dato.	-1	`EINVAL` (22)	Sì
`count == 0`	Un `NULL` oggetto viene posizionato all'inizio del buffer.	-1	N/D	No
`count < 0`	Unsafe: il valore viene considerato senza segno, creando probabilmente un valore di grandi dimensioni che comporta la sovrascrittura della memoria che segue il buffer.	Numero di caratteri scritti, senza includere l'oggetto di terminazione `NULL`.	N/D	No
`count < sizeOfBuffer` e `len <= count`	Tutti i dati vengono scritti e viene aggiunta una terminazione `NULL` .	Numero di caratteri scritti.	N/D	No
`count < sizeOfBuffer` e `len > count`	I primi `count` caratteri vengono scritti e viene aggiunta una terminazione `NULL` .	-1	N/D	No
`count >= sizeOfBuffer` e `len < sizeOfBuffer`	Tutti i dati vengono scritti con un carattere di terminazione `NULL`.	Numero di caratteri scritti.	N/D	No
`count >= sizeOfBuffer`e e `len >= sizeOfBuffercount != _TRUNCATE`	Se l'esecuzione continua dopo l'esecuzione del gestore di parametri non validi, imposta , imposta `errnobuffer[0] == NULL`e restituisce un valore negativo.	-1	`ERANGE` (34)	Sì
`count == _TRUNCATE` e `len >= sizeOfBuffer`	Scrive la maggior parte della stringa come si adatta `buffer` a e una terminazione `NULL`.	-1	N/D	No
`count == _TRUNCATE` e `len < sizeOfBuffer`	Scrive l'intera stringa in `buffer` con un oggetto di terminazione `NULL`.	Numero di caratteri scritti, senza includere l'oggetto di terminazione `NULL`.	N/D	No
`format == NULL`	Non viene scritto alcun dato. Se l'esecuzione continua dopo l'esecuzione del gestore di parametri non validi, imposta `errno` e restituisce un valore negativo.	-1	`EINVAL` (22)	Sì

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

Importante

Assicurarsi che format non sia una stringa definita dall'utente.

A partire da Windows 10 versione 2004 (build 19041), la printf famiglia di funzioni stampa esattamente numeri a virgola mobile rappresentabili in base alle regole I edizione Enterprise E 754 per l'arrotondamento. Nelle versioni precedenti di Windows, i numeri a virgola mobile che terminano in '5' verrebbero sempre arrotondati. I edizione Enterprise E 754 indica che devono arrotondare alla cifra pari più vicina (nota anche come "Arrotondamento del banchiere"). Ad esempio, sia printf("%1.0f", 1.5) che printf("%1.0f", 2.5) devono essere arrotondati a 2. In precedenza, 1,5 arrotonderebbe a 2 e 2,5 arrotonderebbe a 3. Questa modifica influisce solo sui numeri rappresentabili esattamente. Ad esempio, 2.35 (che, se rappresentato in memoria, è più vicino a 2,350000000000000008) continua a arrotondare fino a 2,4. L'arrotondamento eseguito da queste funzioni ora rispetta anche la modalità di arrotondamento a virgola mobile impostata da fesetround. In precedenza, l'arrotondamento ha sempre scelto FE_TONEAREST il comportamento. Questa modifica interessa solo i programmi compilati con Visual Studio 2019 versione 16.2 e successive. Per usare il comportamento di arrotondamento a virgola mobile legacy, collegarsi a "legacy_stdio_float_rounding.obj".

_snwprintf_s è una versione a caratteri "wide" di _snprintf_s. Gli argomenti puntatori per _snwprintf_s sono stringhe a caratteri "wide". Il rilevamento degli errori di codifica in _snwprintf_s potrebbe essere diverso da quello in _snprintf_s. _snwprintf_s, proprio come swprintf_s, scrive l'output in una stringa anziché in una destinazione di tipo FILE.

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

In C++ l'utilizzo di queste funzioni è semplificato dagli overload dei modelli. Gli overload possono dedurre la lunghezza del buffer automaticamente (eliminando la necessità di specificare un argomento di dimensione) e possono sostituire automaticamente le funzioni precedenti e non sicure con le controparti più recenti e sicure. Per altre informazioni, vedere Proteggere gli overload dei modelli.

Mapping di routine di testo generico

`Tchar.h` Routine	`_UNICODE` e `_MBCS` non definito	`_MBCS` Definito	`_UNICODE` Definito
`_sntprintf_s`	`_snprintf_s`	`_snprintf_s`	`_snwprintf_s`
`_sntprintf_s_l`	`_snprintf_s_l`	`_snprintf_s_l`	`_snwprintf_s_l`

Requisiti

Ciclo	Intestazione obbligatoria
`_snprintf_s`, `_snprintf_s_l`	`<stdio.h>`
`_snwprintf_s`, `_snwprintf_s_l`	`<stdio.h>` oppure `<wchar.h>`

Per altre informazioni sulla compatibilità, vedere Compatibility (Compatibilità).

Esempio

// crt_snprintf_s.cpp
// compile with: /MTd

// These #defines enable secure template overloads
// (see last part of Examples() below)
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES 1
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT 1

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <crtdbg.h>  // For _CrtSetReportMode
#include <errno.h>

// This example uses a 10-byte destination buffer.

int snprintf_s_tester( const char * fmt, int x, size_t count )
{
   char dest[10];

   printf( "\n" );

   if ( count == _TRUNCATE )
      printf( "%zd-byte buffer; truncation semantics\n",
               _countof(dest) );
   else
      printf( "count = %zd; %zd-byte buffer\n",
               count, _countof(dest) );

   int ret = _snprintf_s( dest, _countof(dest), count, fmt, x );

   printf( "    new contents of dest: '%s'\n", dest );

   return ret;
}

void Examples()
{
   // formatted output string is 9 characters long: "<<<123>>>"
   snprintf_s_tester( "<<<%d>>>", 121, 8 );
   snprintf_s_tester( "<<<%d>>>", 121, 9 );
   snprintf_s_tester( "<<<%d>>>", 121, 10 );

   printf( "\nDestination buffer too small:\n" );

   snprintf_s_tester( "<<<%d>>>", 1221, 10 );

   printf( "\nTruncation examples:\n" );

   int ret = snprintf_s_tester( "<<<%d>>>", 1221, _TRUNCATE );
   printf( "    truncation %s occur\n", ret == -1 ? "did"
                                                  : "did not" );

   ret = snprintf_s_tester( "<<<%d>>>", 121, _TRUNCATE );
   printf( "    truncation %s occur\n", ret == -1 ? "did"
                                                  : "did not" );
   printf( "\nSecure template overload example:\n" );

   char dest[10];
   _snprintf( dest, 10, "<<<%d>>>", 12321 );
   // With secure template overloads enabled (see #defines
   // at top of file), the preceding line is replaced by
   //    _snprintf_s( dest, _countof(dest), 10, "<<<%d>>>", 12345 );
   // Instead of causing a buffer overrun, _snprintf_s invokes
   // the invalid parameter handler.
   // If secure template overloads were disabled, _snprintf would
   // write 10 characters and overrun the dest buffer.
   printf( "    new contents of dest: '%s'\n", dest );
}

void myInvalidParameterHandler(
   const wchar_t* expression,
   const wchar_t* function,
   const wchar_t* file,
   unsigned int line,
   uintptr_t pReserved)
{
   wprintf(L"Invalid parameter handler invoked: %s\n", expression);
}

int main( void )
{
   _invalid_parameter_handler oldHandler, newHandler;

   newHandler = myInvalidParameterHandler;
   oldHandler = _set_invalid_parameter_handler(newHandler);
   // Disable the message box for assertions.
   _CrtSetReportMode(_CRT_ASSERT, 0);

   Examples();
}


count = 8; 10-byte buffer
    new contents of dest: '<<<121>>'

count = 9; 10-byte buffer
    new contents of dest: '<<<121>>>'

count = 10; 10-byte buffer
    new contents of dest: '<<<121>>>'

Destination buffer too small:

count = 10; 10-byte buffer
Invalid parameter handler invoked: ("Buffer too small", 0)
    new contents of dest: ''

Truncation examples:

10-byte buffer; truncation semantics
    new contents of dest: '<<<1221>>'
    truncation did occur

10-byte buffer; truncation semantics
    new contents of dest: '<<<121>>>'
    truncation did not occur

Secure template overload example:
Invalid parameter handler invoked: ("Buffer too small", 0)
    new contents of dest: ''

Vedi anche

I/O di flusso
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
fprintf, _fprintf_l, fwprintf, _fwprintf_l
printf, _printf_l, wprintf, _wprintf_l
scanf, _scanf_l, wscanf, _wscanf_l
sscanf, _sscanf_l, swscanf, _swscanf_l
Funzioni vprintf

`_snprintf_s`, `_snprintf_s_l`, `_snwprintf_s`, `_snwprintf_s_l`

Sintassi

Parametri

Valore restituito

Osservazioni:

Riepilogo del comportamento

Mapping di routine di testo generico

Requisiti

Esempio

Vedi anche

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive

_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l

Sintassi

Parametri

Valore restituito

Osservazioni:

Riepilogo del comportamento

Mapping di routine di testo generico

Requisiti

Esempio

Vedi anche

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive

`_snprintf_s`, `_snprintf_s_l`, `_snwprintf_s`, `_snwprintf_s_l`