vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l

Articolo
06/09/2015

Scrivere l'output formattato utilizzando un puntatore a un elenco di argomenti. Queste sono versioni di vsprintf, _vsprintf_l, vswprintf, _vswprintf_l, __vswprintf_l con i miglioramenti della sicurezza come descritto in Funzionalità di sicurezza in CRT.

int vsprintf_s(
   char *buffer,
   size_t numberOfElements,
   const char *format,
   va_list argptr 
); 
int _vsprintf_s_l(
   char *buffer,
   size_t numberOfElements,
   const char *format,
   locale_t locale,
   va_list argptr 
); 
int vswprintf_s(
   wchar_t *buffer,
   size_t numberOfElements,
   const wchar_t *format,
   va_list argptr 
);
int _vswprintf_s_l(
   wchar_t *buffer,
   size_t numberOfElements,
   const wchar_t *format,
   locale_t locale,
   va_list argptr 
);
template <size_t size>
int vsprintf_s(
   char (&buffer)[size],
   const char *format,
   va_list argptr 
); // C++ only
template <size_t size>
int vswprintf_s(
   wchar_t (&buffer)[size],
   const wchar_t *format,
   va_list argptr 
); // C++ only

Parametri

buffer
Percorso di archiviazione per l'output.
numberOfElements
Dimensione del buffer in caratteri.
format
Specifica di formato,
argptr
Puntatore all'elenco di argomenti.
locale
Impostazioni locali da utilizzare.

Valore restituito

vsprintf_s e vswprintf_s restituiscono il numero di caratteri scritti, escluso il carattere di terminazione null, o un valore negativo se un errore di output viene visualizzato. Se buffer o format sono un puntatore null, se count è zero, o se la stringa di formato contiene caratteri di formattazione non validi, viene richiamato il gestore di parametro non valido, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, la funzione restituisce -1 e imposta errno a EINVAL.

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

Note

Ognuna di queste funzioni accetta un puntatore ad un elenco di argomenti, quindi formatta e scrive i dati specificati nella locazione di memoria indicata da buffer.

vswprintf_s è conforme allo standard ISO C per vswprintf, che richiede il secondo parametro, count, di tipo size_t.

Queste funzioni differiscono dalle versioni non sicure in quanto le versioni sicure supportano i parametri posizionali. Per ulteriori informazioni, vedere Parametri posizionali printf_p.

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 & _MBCS non definiti	_MBCS definito	_UNICODE definito
_vstprintf_s	vsprintf_s	vsprintf_s	vswprintf_s
_vstprintf_s_l	_vsprintf_s_l	_vsprintf_s_l	_vswprintf_s_l

Requisiti

Routine	Intestazione obbligatoria	Intestazioni facoltative
vsprintf_s, _vsprintf_s_l	<stdio.h> e <stdarg.h>	<varargs.h>*
vswprintf_s, _vswprintf_s_l	<stdio.h> o <wchar.h>, e <stdarg.h>	<varargs.h>*

* Necessario per la compatibilità con UNIX V.

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

Esempio

// crt_vsprintf_s.c
// This program uses vsprintf_s to write to a buffer.
// The size of the buffer is determined by _vscprintf.

#include <stdlib.h>
#include <stdarg.h>

void test( char * format, ... )
{
   va_list args;
   int len;
   char * buffer;

   va_start( args, format );
   len = _vscprintf( format, args ) // _vscprintf doesn't count
                               + 1; // terminating '\0'
   buffer = malloc( len * sizeof(char) );
   vsprintf_s( buffer, len, format, args );
   puts( buffer );
   free( buffer );
}

int main( void )
{
   test( "%d %c %d", 123, '<', 456 );
   test( "%s", "This is a string" );
}