_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l

Articolo
06/09/2015

Scrive dati formattati in una stringa. Queste sono versioni di _snprintf, _snprintf_l, _snwprintf, _snwprintf_l con i miglioramenti della sicurezza come descritto in Funzionalità di sicurezza in CRT.

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
La dimensione del percorso di archiviazione per l'output. Dimensioni in bytes per _snprintf_s o dimensioni in words per _snwprintf_s.
Count
Numero massimo di caratteri da archiviare, o _TRUNCATE.
format
Stringa di controllo del formato.
argument
Argomenti facoltativi.
locale
Impostazioni locali da utilizzare.

Valore restituito

_snprintf_s restituisce il numero di caratteri archiviato in buffer, senza contare il carattere Null di terminazione. _snwprintf_s restituisce il numero di caratteri "wide" archiviati in buffer, senza contare il carattere "wide" Null finale.

Se la memoria richiesta per archiviare i dati e un valore null di terminazione supera sizeOfBuffer, il gestore non valido di parametro viene richiamato, come descritto in Convalida dei parametri. Se l'esecuzione continua dopo il gestore di parametri non validi, queste funzioni impostano il buffer su una stringa vuota, impostano errno a ERANGEe restituiscono -1.

Se il buffer o format è un puntatore a NULL, o se count è minore o uguale a zero, il gestore di parametri non validi viene invocato. Se l'esecuzione può continuare, queste funzioni impostano errno su EINVAL e restituiscono -1.

Per ulteriori informazioni su questi e altri codici, vedere _doserrno, errno, _sys_errlist, e _sys_nerr.

Note

La funzione _snprintf_s formatta e memorizza count o meno caratteri in buffer e aggiunge un valore null di terminazione. Ogni argomento (se presente) viene convertito e restituito in base al formato specifico in format. La formattazione è coerente con la famiglia di funzioni printf; consultare Sintassi per la specifica del formato: funzioni printf wprintf. Se la copia avviene tra stringhe che si sovrappongono, il comportamento non è definito.

Se count è _TRUNCATE, quindi _snprintf_s scrive un numero di stringhe sufficiente affinché possano essere contenute in buffer lasciando spazio a un valore null di terminazione. Se l'intera stringa (con il carattere di terminazione null) ci sta in buffer, allora _snprintf_s restituisce il numero di caratteri scritto (escluso il carattere di terminazione null); in caso contrario, _snprintf_s restituisce -1 per indicare che il troncamento si è verificato.

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

_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 può essere diverso da quello di _snprintf_s. _snwprintf_s, come swprintf_s, scrive l'output in una stringa anziché a 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 ulteriori informazioni, vedere Overload di modelli sicuri.

Mapping di routine di testo generico

Routine Tchar.h	_UNICODE e _MBCS non definiti	_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

Routine	Intestazione obbligatoria
_snprintf_s, _snprintf_s_l	<stdio.h>
_snwprintf_s, _snwprintf_s_l	<stdio.h> o <wchar.h>

Per ulteriori informazioni sulla compatibilità, vedere Compatibilità nell'introduzione.

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, int count )
{
   char dest[10];

   printf( "\n" );

   if ( count == _TRUNCATE )
      printf( "%d-byte buffer; truncation semantics\n",
               _countof(dest) );
   else
      printf( "count = %d; %d-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();
}