sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l

Articolo
06/09/2015

Scrivere dati formattati in una stringa. Queste sono versioni di sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l con i miglioramenti della sicurezza come descritto in Funzionalità di sicurezza in CRT.

int sprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   const char *format [,
   argument] ... 
);
int _sprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   const char *format,
   locale_t locale [,
   argument] ... 
);
int swprintf_s(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   const wchar_t *format [,
   argument]...
);
int _swprintf_s_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   const wchar_t *format,
   locale_t locale [,
   argument]…
);
template <size_t size>
int sprintf_s(
   char (&buffer)[size],
   const char *format [,
   argument] ... 
); // C++ only
template <size_t size>
int swprintf_s(
   wchar_t (&buffer)[size],
   const wchar_t *format [,
   argument]...
); // C++ only

Parametri

buffer
Percorso di archiviazione per l'output
sizeOfBuffer
Numero massimo di caratteri da archiviare.
format
Stringa di controllo del formato
argument
Argomenti facoltativi
locale
Impostazioni locali da utilizzare.

Per ulteriori informazioni, vedere Specifiche di formato.

Valore restituito

Numero di caratteri scritti o –1 se si è verificato un errore. Se buffer o format è un puntatore Null, sprintf_s e swprintf_s restituiscono -1 e impostano errno su EINVAL.

sprintf_s restituisce il numero di byte archiviato in buffer, senza contare il carattere Null terminale. swprintf_s restituisce il numero di caratteri "wide" archiviati in buffer, senza contare il carattere "wide" Null finale.

Note

La funzione sprintf_s formatta e archivia una serie di caratteri e di valori in buffer. Ogni funzione argument (se presente) viene convertita e restituita in base al formato specificato in format. Il formato è costituito da caratteri ordinari e ha lo stesso formato e la stessa funzione dell'argomento format per la funzione printf. Un carattere Null viene aggiunto dopo l'ultimo carattere scritto. Se la copia avviene tra stringhe che si sovrappongono, il comportamento non è definito.

La differenza principale tra sprintf_s e sprintf è che sprintf_s controlla la stringa di formato per i caratteri di formattazione validi, mentre sprintf controlla solo se la stringa di formato o il buffer è un puntatore NULL. Se il controllo non riesce, il gestore di parametro non valido viene richiamato, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, la funzione restituisce -1 e imposta errno su EINVAL.

Un'altra differenza principale tra sprintf_s e sprintf è che sprintf_s accetta un parametro di lunghezza che specifica la dimensione del buffer di output in caratteri. Se il buffer è troppo piccolo per il testo che viene stampato, il buffer viene impostato su una stringa vuota e il gestore di parametro non valido viene richiamato. A differenza di snprintf, sprintf_s garantisce che il buffer avrà terminazione Null (a meno che la dimensione del buffer sia zero).

swprintf_s è una versione a caratteri "wide" di sprintf_s. Gli argomenti puntatori per swprintf_s sono stringhe a caratteri "wide". Il rilevamento degli errori di codifica in swprintf_s può essere diverso da quello di sprintf_s. 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.

Sono disponibili versioni sprintf_s che offrono un controllo maggiore su ciò che accade se il buffer è troppo piccolo. Per ulteriori informazioni, vedere _snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l.

Mapping di routine di testo generico

Routine TCHAR.H	_UNICODE & _MBCS non definiti	_MBCS definito	_UNICODE definito
_stprintf_s	sprintf_s	sprintf_s	swprintf_s
_stprintf_s_l	_sprintf_s_l	_sprintf_s_l	_swprintf_s_l

Requisiti

Routine	Intestazione obbligatoria
sprintf_s, _sprintf_s_l	<stdio.h>
swprintf_s, _swprintf_s_l	<stdio.h> o <wchar.h>

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

Esempio

// crt_sprintf_s.c
// This program uses sprintf_s to format various
// data and place them in the string named buffer.
//

#include <stdio.h>

int main( void )
{
   char  buffer[200], s[] = "computer", c = 'l';
   int   i = 35, j;
   float fp = 1.7320534f;

   // Format and print various data: 
   j  = sprintf_s( buffer, 200,     "   String:    %s\n", s );
   j += sprintf_s( buffer + j, 200 - j, "   Character: %c\n", c );
   j += sprintf_s( buffer + j, 200 - j, "   Integer:   %d\n", i );
   j += sprintf_s( buffer + j, 200 - j, "   Real:      %f\n", fp );

   printf_s( "Output:\n%s\ncharacter count = %d\n", buffer, j );
}

// crt_swprintf_s.c
// wide character example
// also demonstrates swprintf_s returning error code
#include <stdio.h>

int main( void )
{
   wchar_t buf[100];
   int len = swprintf_s( buf, 100, L"%s", L"Hello world" );
   printf( "wrote %d characters\n", len );
   len = swprintf_s( buf, 100, L"%s", L"Hello\xffff world" );
   // swprintf_s fails because string contains WEOF (\xffff)
   printf( "wrote %d characters\n", len );
}