vsnprintf_s
, _vsnprintf_s
, _vsnprintf_s_l
, _vsnwprintf_s
_vsnwprintf_s_l
Scrivere l'output formattato mediante un puntatore a un elenco di argomenti. Queste funzioni sono versioni di , , , , , _vsnwprintf_l
con miglioramenti della sicurezza, come descritto in Funzionalità di sicurezza in CRT. _vsnwprintf
_vsnprintf_l
_vsnprintf
vsnprintf
Sintassi
int vsnprintf_s(
char *buffer,
size_t sizeOfBuffer,
size_t count,
const char *format,
va_list argptr
);
int _vsnprintf_s(
char *buffer,
size_t sizeOfBuffer,
size_t count,
const char *format,
va_list argptr
);
int _vsnprintf_s_l(
char *buffer,
size_t sizeOfBuffer,
size_t count,
const char *format,
_locale_t locale,
va_list argptr
);
int _vsnwprintf_s(
wchar_t *buffer,
size_t sizeOfBuffer,
size_t count,
const wchar_t *format,
va_list argptr
);
int _vsnwprintf_s_l(
wchar_t *buffer,
size_t sizeOfBuffer,
size_t count,
const wchar_t *format,
_locale_t locale,
va_list argptr
);
template <size_t size>
int _vsnprintf_s(
char (&buffer)[size],
size_t count,
const char *format,
va_list argptr
); // C++ only
template <size_t size>
int _vsnwprintf_s(
wchar_t (&buffer)[size],
size_t count,
const wchar_t *format,
va_list argptr
); // C++ only
Parametri
buffer
Percorso di archiviazione per l'output.
sizeOfBuffer
Dimensioni dell'oggetto per l'output buffer
. Dimensioni in byte per le funzioni che accettano char
le parole e per quelle che accettano wchar_t
.
count
Numero massimo di caratteri da scrivere senza includere l'oggetto di terminazione NULL
. Per le funzioni che accettano wchar_t
, è il numero di caratteri wide da scrivere. Oppure _TRUNCATE
.
format
Specifica di formato.
argptr
Puntatore a un elenco di argomenti.
locale
Impostazioni locali da utilizzare per la formattazione dell'output.
Per altre informazioni, vedere Specifiche di formato.
Valore restituito
Numero di caratteri scritti, senza includere l'terminazione NULL
o un valore negativo se si verifica un errore di output.
Per informazioni dettagliate, vedere Riepilogo del comportamento .
Osservazioni:
vsnprintf_s
è identico a _vsnprintf_s
e è incluso per la conformità allo standard ANSI. _vnsprintf
viene mantenuta per compatibilità con le versioni precedenti.
Ognuna di queste funzioni accetta un puntatore a un elenco di argomenti, quindi formatta scrive fino a count
caratteri nella memoria a cui punta buffer
e aggiunge un carattere Null di terminazione.
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.
Riepilogo del comportamento
Per la tabella seguente:
- Si supponga di
len
essere la dimensione dei dati formattati. Se la funzione accetta unchar
buffer, le dimensioni sono in byte. Se la funzione accetta unwchar_t
buffer, la dimensione specifica il numero di parole a 16 bit. - I caratteri fanno riferimento ai
char
caratteri per le funzioni che accettano unchar
buffer e aiwchar_t
caratteri per le funzioni che accettano unwchar_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 |
---|---|---|---|---|
Success | Scrive i caratteri nel buffer usando la stringa di formato specificata | Numero di caratteri scritti | 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 sizeOfBuffer == 0 e count == 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. Se l'esecuzione continua dopo l'esecuzione del gestore di parametri non validi, imposta errno e restituisce un valore negativo. |
-1 | EINVAL (22) |
Sì |
count == 0 |
Non scrive dati e restituisce il numero di caratteri che sarebbero stati scritti, senza includere l'oggetto di terminazione NULL . |
Numero di caratteri che sarebbero stati scritti senza includere l'oggetto di terminazione NULL . |
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. |
-1 | N/D | No |
count >= sizeOfBuffer e len < sizeOfBuffer |
Tutti i dati vengono scritti con un carattere di terminazione NULL . |
Numero di caratteri scritti, senza includere l'oggetto di terminazione NULL . |
N/D | No |
count >= sizeOfBuffer e len >= sizeOfBuffer e count != _TRUNCATE |
Se l'esecuzione continua dopo l'esecuzione del gestore di parametri non validi, imposta , imposta errno buffer[0] == NULL e restituisce un valore negativo. |
-1 | ERANGE (34) |
Sì |
count == _TRUNCATE e len >= sizeOfBuffer |
Scrive la maggior parte della stringa adatta a buffer , incluso l'oggetto di terminazione NULL . |
-1 | N/D | No |
count == _TRUNCATE e len < sizeOfBuffer |
Scrive l'intera stringa in buffer con terminazione NULL . |
Numero di caratteri scritti. | 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_errlist
e _sys_nerr
.
Importante
Assicurarsi che format
non sia una stringa definita dall'utente. Per altre informazioni, vedere Evitare sovraccarichi del buffer.
A partire da Windows 10 versione 2004 (build 19041), la printf
famiglia di funzioni stampa numeri a virgola mobile esattamente rappresentabili in base alle regole IEEE 754 per l'arrotondamento. Nelle versioni precedenti di Windows, i numeri a virgola mobile che terminano in '5' verrebbero sempre arrotondati. IEEE 754 indica che devono essere arrotondati 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".
Nota
Per assicurarsi che ci sia spazio per il carattere Null di terminazione, assicurarsi che il valore di count
sia rigorosamente minore della lunghezza del buffer oppure usare _TRUNCATE
.
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.
Suggerimento
Se viene visualizzato un errore esterno _vsnprintf_s
non definito e si usa Universal C Runtime, aggiungere legacy_stdio_definitions.lib
al set di librerie da collegare. Universal C Runtime non esporta direttamente questa funzione ed è invece definita inline in <stdio.h>
. Per altre informazioni, vedere Panoramica dei potenziali problemi di aggiornamento e modifiche della conformità di Visual Studio 2015.
Mapping di routine di testo generico
TCHAR.H routine |
_UNICODE e _MBCS non definito |
_MBCS definito |
_UNICODE definito |
---|---|---|---|
_vsntprintf_s |
_vsnprintf_s |
_vsnprintf_s |
_vsnwprintf_s |
_vsntprintf_s_l |
_vsnprintf_s_l |
_vsnprintf_s_l |
_vsnwprintf_s_l |
Requisiti
Ciclo | Intestazione obbligatoria | Intestazioni facoltative |
---|---|---|
vsnprintf_s |
<stdio.h> e <stdarg.h> |
<varargs.h> * |
_vsnprintf_s , _vsnprintf_s_l |
<stdio.h> e <stdarg.h> |
<varargs.h> * |
_vsnwprintf_s , _vsnwprintf_s_l |
<stdio.h> o <wchar.h> , e <stdarg.h> |
<varargs.h> * |
* Obbligatorio per la compatibilità di UNIX V.
Per altre informazioni sulla compatibilità, vedere Compatibility (Compatibilità).
Esempio
// crt_vsnprintf_s.cpp
#include <stdio.h>
#include <wtypes.h>
void FormatOutput(LPCSTR formatstring, ...)
{
int nSize = 0;
char buff[10];
memset(buff, 0, sizeof(buff));
va_list args;
va_start(args, formatstring);
nSize = vsnprintf_s( buff, _countof(buff), _TRUNCATE, formatstring, args);
printf("nSize: %d, buff: %s\n", nSize, buff);
va_end(args);
}
int main() {
FormatOutput("%s %s", "Hi", "there");
FormatOutput("%s %s", "Hi", "there!");
FormatOutput("%s %s", "Hi", "there!!");
}
nSize: 8, buff: Hi there
nSize: 9, buff: Hi there!
nSize: -1, buff: Hi there!
Vedi anche
I/O di flusso
Funzioni vprintf
fprintf
, _fprintf_l
, fwprintf
_fwprintf_l
printf
, _printf_l
, wprintf
_wprintf_l
sprintf
, _sprintf_l
, swprintf
, _swprintf_l
__swprintf_l
va_arg
, va_copy
, va_end
va_start