_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l

Scrive dati formattati in una stringa.Writes formatted data to a string. Queste sono versioni di snprintf, _snprintf, _snprintf_l, _snwprintf, _snwprintf_l con miglioramenti per la sicurezza, come descritto in Funzionalità di sicurezza in CRT.These are versions of snprintf, _snprintf, _snprintf_l, _snwprintf, _snwprintf_l with security enhancements as described in Security Features in the CRT.

SintassiSyntax

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

ParametriParameters

bufferbuffer
Percorso di archiviazione per l'output.Storage location for the output.

sizeOfBuffersizeOfBuffer
Dimensioni dl percorso di archiviazione per l'output.The size of the storage location for output. Dimensioni byte per snprintf_s o dimensioni in parole per snwprintf_s.Size in bytes for _snprintf_s or size in words for _snwprintf_s.

countcount
Numero massimo di caratteri da archiviare o _TRUNCATE.Maximum number of characters to store, or _TRUNCATE.

formatformat
Stringa di controllo del formato.Format-control string.

Argomentoargument
Argomenti facoltativi.Optional arguments.

localelocale
Impostazioni locali da usare.The locale to use.

Valore restituitoReturn Value

snprintf_s restituisce il numero di caratteri archiviati in buffer, senza contare il carattere di terminazione null._snprintf_s returns the number of characters stored in buffer, not counting the terminating null character. snwprintf_s restituisce il numero di caratteri "wide" archiviati in buffer, senza contare il carattere "wide" null finale._snwprintf_s returns the number of wide characters stored in buffer, not counting the terminating null wide character.

Se lo spazio di archiviazione necessaria per archiviare i dati e un carattere di terminazione null supera sizeOfBuffer, viene richiamato il gestore di parametri non validi, come descritto in convalida dei parametri.If the storage required to store the data and a terminating null exceeds sizeOfBuffer, the invalid parameter handler is invoked, as described in Parameter Validation. Se l'esecuzione continua dopo il gestore di parametri non validi, queste funzioni impostano buffer su una stringa vuota, impostare errno al ERANGEe restituiscono -1.If execution continues after the invalid parameter handler, these functions set buffer to an empty string, set errno to ERANGE, and return -1.

Se buffer oppure formato è un NULL puntatore, o se conteggio è minore o uguale a zero, viene richiamato il gestore di parametri non validi.If buffer or format is a NULL pointer, or if count is less than or equal to zero, the invalid parameter handler is invoked. Se l'esecuzione può continuare, queste funzioni impostano errno alla EINVAL e restituiscono -1.If execution is allowed to continue, these functions set errno to EINVAL and return -1.

Per informazioni su questi e altri codici di errore, vedere _doserrno, errno, _sys_errlist e _sys_nerr.For information about these and other error codes, see _doserrno, errno, _sys_errlist, and _sys_nerr.

NoteRemarks

Il snprintf_s funzione formatta e Archivia conteggio o un numero inferiore di caratteri in buffer e aggiunge un carattere di terminazione null.The _snprintf_s function formats and stores count or fewer characters in buffer and appends a terminating null. Ogni argomento (se presente) viene convertita e restituita in base alla specifica del formato corrispondente in formato.Each argument (if any) is converted and output according to the corresponding format specification in format. La formattazione sia coerenza con il printf famiglia di funzioni; vedere sintassi specifica del formato: funzioni printf e wprintf.The formatting is consistent with the printf family of functions; see Format Specification Syntax: printf and wprintf Functions. Se la copia avviene tra stringhe che si sovrappongono, il comportamento non è definito.If copying occurs between strings that overlap, the behavior is undefined.

Se conteggio viene truncate, quindi snprintf_s scrive la maggior parte della stringa come adattare in buffer lasciando spazio a un terminazione null.If count is _TRUNCATE, then _snprintf_s writes as much of the string as will fit in buffer while leaving room for a terminating null. Se l'intera stringa (con terminazione null) rientra buffer, quindi snprintf_s restituisce il numero di caratteri scritti (senza includere il carattere di terminazione null); in caso contrario, snprintf_s restituisce -1 per indicare che il troncamento si è verificato.If the entire string (with terminating null) fits in buffer, then _snprintf_s returns the number of characters written (not including the terminating null); otherwise, _snprintf_s returns -1 to indicate that truncation occurred.

Importante

Assicurarsi che format non sia una stringa definita dall'utente.Ensure that format is not a user-defined string.

snwprintf_s è una versione a caratteri wide snprintf_s; gli argomenti puntatori per snwprintf_s sono stringhe a caratteri "wide"._snwprintf_s is a wide-character version of _snprintf_s; the pointer arguments to _snwprintf_s are wide-character strings. Rilevamento degli errori in di codifica snwprintf_s potrebbero essere diversi da quello in snprintf_s.Detection of encoding errors in _snwprintf_s might differ from that in _snprintf_s. snwprintf_s, ad esempio swprintf_s, scrive l'output in una stringa anziché a una destinazione di tipo FILE._snwprintf_s, like swprintf_s, writes output to a string rather than to a destination of type FILE.

Le versioni di queste funzioni con il l suffisso sono identiche ad eccezione del fatto che usano il parametro delle impostazioni locali passato al posto di quelle del thread corrente.The versions of these functions with the _l suffix are identical except that they use the locale parameter passed in instead of the current thread locale.

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.In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. Per altre informazioni, vedere Secure Template Overloads.For more information, see Secure Template Overloads.

Mapping di routine di testo genericoGeneric-Text Routine Mappings

Routine Tchar.hTchar.h routine _UNICODE e _MBCS non definiti_UNICODE and _MBCS not defined _MBCS definito_MBCS defined _UNICODE definito_UNICODE defined
sntprintf_s_sntprintf_s _snprintf_s_snprintf_s _snprintf_s_snprintf_s _snwprintf_s_snwprintf_s
sntprintf_s_l_sntprintf_s_l _snprintf_s_l_snprintf_s_l _snprintf_s_l_snprintf_s_l _snwprintf_s_l_snwprintf_s_l

RequisitiRequirements

RoutineRoutine Intestazione obbligatoriaRequired header
snprintf_s, snprintf_s_l_snprintf_s, _snprintf_s_l <stdio.h><stdio.h>
snwprintf_s, snwprintf_s_l_snwprintf_s, _snwprintf_s_l <stdio.h> o <wchar.h><stdio.h> or <wchar.h>

Per altre informazioni sulla compatibilità, vedere Compatibilità.For more compatibility information, see Compatibility.

EsempioExample

// 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: ''

Vedere ancheSee also

I/O di flussoStream I/O
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_lsprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
fprintf, _fprintf_l, fwprintf, _fwprintf_lfprintf, _fprintf_l, fwprintf, _fwprintf_l
printf, _printf_l, wprintf, _wprintf_lprintf, _printf_l, wprintf, _wprintf_l
scanf, _scanf_l, wscanf, _wscanf_lscanf, _scanf_l, wscanf, _wscanf_l
sscanf, _sscanf_l, swscanf, _swscanf_lsscanf, _sscanf_l, swscanf, _swscanf_l
Funzioni vprintfvprintf Functions