`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`

Articolo
07/04/2023

Scrive dati formattati in una stringa. Sono disponibili versioni più sicure di queste funzioni; vedere _snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l.

Sintassi

int snprintf(
   char *buffer,
   size_t count,
   const char *format [,
   argument] ...
);

int _snprintf(
   char *buffer,
   size_t count,
   const char *format [,
   argument] ...
);

int _snprintf_l(
   char *buffer,
   size_t count,
   const char *format,
   _locale_t locale [,
   argument] ...
);

int _snwprintf(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format [,
   argument] ...
);

int _snwprintf_l(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format,
   _locale_t locale [,
   argument] ...
);

template <size_t size>
int _snprintf(
   char (&buffer)[size],
   size_t count,
   const char *format [,
   argument] ...
); // C++ only

template <size_t size>
int _snprintf_l(
   char (&buffer)[size],
   size_t count,
   const char *format,
   _locale_t locale [,
   argument] ...
); // C++ only

template <size_t size>
int _snwprintf(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format [,
   argument] ...
); // C++ only

template <size_t size>
int _snwprintf_l(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   _locale_t locale [,
   argument] ...
); // C++ only

Parametri

buffer
Percorso di archiviazione per l'output.

count
Numero massimo di caratteri da scrivere. Per le funzioni che accettano wchar_t, è il numero massimo di caratteri wide da scrivere.

format
Stringa di controllo del formato.

argument
Argomenti facoltativi.

locale
Impostazioni locali da utilizzare per formattare l'output.

Per altre informazioni, vedere Sintassi delle specifiche di formato: printf e wprintf funzioni.

Valore restituito

Numero di caratteri che sarebbero stati scritti nel buffer se count fosse stato ignorato. Il conteggio non include il carattere di terminazione NULL .

Si supponga di len essere la lunghezza della stringa di dati formattata, senza includere l'oggetto di terminazione NULL.
Per tutte le funzioni, se len < count, i len caratteri vengono archiviati in buffer, viene aggiunto un carattere di terminazione Null e viene restituito il numero di caratteri scritti, non incluso il carattere di terminazione NULL.

Le versioni di caratteri wide di queste funzioni restituiscono il numero di caratteri wide scritti, senza includere la terminazione NULL.

Per informazioni dettagliate, vedere Riepilogo del comportamento .

Osservazioni:

A partire da UCRT in Visual Studio 2015 e Windows 10, snprintf non è più identico a _snprintf. Il snprintf comportamento è ora conforme allo standard C99. La differenza è che se si esaurisce il buffer, snprintf null termina la fine del buffer e restituisce il numero di caratteri necessari, mentre _snprintf non termina il buffer e restituisce -1. snprintf() Include anche un altro carattere nell'output perché non termina il buffer.

snprintf e la _snprintf famiglia di funzioni formattano e archiviano count o meno caratteri in buffer.
snprintf archivia sempre un carattere di terminazione NULL , troncando l'output, se necessario.
Se snprintf restituisce un valore >count - 1, l'output è stato troncato.
La _snprintf famiglia di funzioni aggiunge solo un carattere di terminazione NULL se la lunghezza della stringa formattata è rigorosamente minore di count caratteri.
Eventuali argument vengono convertiti ed emessi in base alla specifica del formato corrispondente in format. Il formato è costituito da caratteri ordinari e ha lo stesso formato e la stessa funzione dell'argomento format per printf. Se la copia avviene tra stringhe che si sovrappongono, il comportamento non è definito.

Riepilogo del comportamento

Per la tabella seguente:

Si supponga di sizeOfBuffer essere la dimensione di buffer. Se la funzione accetta un char buffer, le dimensioni sono in byte. Se la funzione accetta un wchar_t buffer, la dimensione specifica il numero di parole a 16 bit.
Si supponga di len essere la dimensione dei dati formattati. Se la funzione accetta un char buffer, le dimensioni sono in byte. Se la funzione accetta un wchar_t buffer, la dimensione specifica il numero di parole a 16 bit.
I caratteri fanno riferimento ai char caratteri per le funzioni che accettano un char buffer e ai wchar_t caratteri per le funzioni che accettano un wchar_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
Riuscita	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'identificatore `s`di stringa di elaborazione , `S`o `Z`, l'elaborazione della specifica del formato viene arrestata, un `NULL` oggetto viene posizionato all'inizio del buffer.	-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 `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ì
`count == 0`	Numero di caratteri che sarebbero stati scritti, senza includere l'oggetto di terminazione `NULL`. È possibile usare questo risultato per allocare spazio del buffer sufficiente per la stringa e una terminazione `NULL`e quindi chiamare di nuovo la funzione per riempire il buffer.	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	N/D	No
`count < sizeOfBuffer` e `len <= count`	Tutti i dati vengono scritti e viene aggiunta una terminazione `NULL` .	Numero di caratteri scritti, senza includere l'oggetto di terminazione `NULL`.	N/D	No
`count < sizeOfBuffer` e `len > count`	I primi `count-1` caratteri vengono scritti seguiti da un carattere di terminazione Null.	Il numero di caratteri che sarebbero stati scritti corrispondeva `count` al numero di caratteri da restituire, senza includere il carattere di terminazione Null.	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`	Unsafe: sovrascrive la memoria che segue il buffer.	Numero di caratteri scritti, senza includere l'oggetto di terminazione `NULL`.	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_errliste _sys_nerr.

Importante

Assicurarsi che format non sia una stringa definita dall'utente. Poiché le funzioni non garantiscono la _snprintf terminazione Null, in particolare quando il valore restituito è count, assicurarsi che siano seguite dal codice che aggiunge il carattere di terminazione Null. Per altre informazioni, vedere Evitare sovraccarichi del buffer.

A partire da Windows 10 versione 2004 (build 19041), la printf famiglia di funzioni stampa esattamente numeri a virgola mobile rappresentabili in base alle regole I edizione Enterprise E 754 per l'arrotondamento. Nelle versioni precedenti di Windows, i numeri a virgola mobile che terminano in '5' verrebbero sempre arrotondati. I edizione Enterprise E 754 indica che devono arrotondare 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.

_snwprintf è una versione a caratteri "wide" di _snprintf. Gli argomenti puntatori per _snwprintf sono stringhe a caratteri "wide". Il rilevamento degli errori di codifica in _snwprintf potrebbe differire dal rilevamento in _snprintf. _snwprintf, proprio come swprintf, scrive l'output in una stringa anziché in una destinazione di tipo FILE.

Le versioni di queste funzioni con il suffisso _l sono identiche, ad eccezione del fatto che utilizzano il parametro delle impostazioni locali passato al posto delle impostazioni locali del thread corrente.

In C++, queste funzioni hanno overload di modelli che richiamano le controparti più recenti e più sicure. Per altre informazioni, vedere Proteggere gli overload dei modelli.

Mapping di routine di testo generico

`Tchar.h` Routine	`_UNICODE` e `_MBCS` non definito	`_MBCS` Definito	`_UNICODE` Definito
`_sntprintf`	`_snprintf`	`_snprintf`	`_snwprintf`
`_sntprintf_l`	`_snprintf_l`	`_snprintf_l`	`_snwprintf_l`

Requisiti

Ciclo	Intestazione obbligatoria
`snprintf`, `_snprintf`, `_snprintf_l`	`<stdio.h>`
`_snwprintf`, `_snwprintf_l`	`<stdio.h>` oppure `<wchar.h>`

Per altre informazioni sulla compatibilità, vedere Compatibility (Compatibilità).

Esempio

// crt_snprintf.c
// compile with: /W3
#include <stdio.h>
#include <stdlib.h>

#if !defined(__cplusplus)
typedef int bool;
const bool true = 1;
const bool false = 0;
#endif

#define FAIL 0 // change to 1 and see what happens

int main(void)
{
   char buffer[200];
   const static char s[] = "computer"
#if FAIL
"computercomputercomputercomputercomputercomputercomputercomputer"
"computercomputercomputercomputercomputercomputercomputercomputer"
"computercomputercomputercomputercomputercomputercomputercomputer"
"computercomputercomputercomputercomputercomputercomputercomputer"
#endif
   ;
   const char c = 'l';
   const int i = 35;
#if FAIL
   const double fp = 1e300; // doesn't fit in the buffer
#else
   const double fp = 1.7320534;
#endif
   /* !subtract one to prevent "squeezing out" the terminal null! */
   const int bufferSize = sizeof(buffer)/sizeof(buffer[0]) - 1;
   int bufferUsed = 0;
   int bufferLeft = bufferSize - bufferUsed;
   bool bSuccess = true;
   buffer[0] = 0;

   /* Format and print various data: */

   if (bufferLeft > 0)
   {
      int perElementBufferUsed = _snprintf(&buffer[bufferUsed],
      bufferLeft, "   String: %s\n", s ); // C4996
      // Note: _snprintf is deprecated; consider _snprintf_s instead
      if (bSuccess = (perElementBufferUsed >= 0))
      {
         bufferUsed += perElementBufferUsed;
         bufferLeft -= perElementBufferUsed;
         if (bufferLeft > 0)
         {
            int perElementBufferUsed = _snprintf(&buffer[bufferUsed],
            bufferLeft, "   Character: %c\n", c ); // C4996
            if (bSuccess = (perElementBufferUsed >= 0))
            {
               bufferUsed += perElementBufferUsed;
               bufferLeft -= perElementBufferUsed;
               if (bufferLeft > 0)
               {
                  int perElementBufferUsed = _snprintf(&buffer
                  [bufferUsed], bufferLeft, "   Integer: %d\n", i ); // C4996
                  if (bSuccess = (perElementBufferUsed >= 0))
                  {
                     bufferUsed += perElementBufferUsed;
                     bufferLeft -= perElementBufferUsed;
                     if (bufferLeft > 0)
                     {
                        int perElementBufferUsed = _snprintf(&buffer
                        [bufferUsed], bufferLeft, "   Real: %f\n", fp ); // C4996
                        if (bSuccess = (perElementBufferUsed >= 0))
                        {
                           bufferUsed += perElementBufferUsed;
                        }
                     }
                  }
               }
            }
         }
      }
   }

   if (!bSuccess)
   {
      printf("%s\n", "failure");
   }
   else
   {
      /* !store null because _snprintf doesn't necessarily (if the string
       * fits without the terminal null, but not with it)!
       * bufferUsed might be as large as bufferSize, which normally is
       * like going one element beyond a buffer, but in this case
       * subtracted one from bufferSize, so we're ok.
       */
      buffer[bufferUsed] = 0;
      printf( "Output:\n%s\ncharacter count = %d\n", buffer, bufferUsed );
   }
   return EXIT_SUCCESS;
}

Output:
   String: computer
   Character: l
   Integer: 35
   Real: 1.732053

character count = 69

Vedi anche

I/O di flusso
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
fprintf, _fprintf_l, fwprintf, _fwprintf_l
printf, _printf_l, wprintf, _wprintf_l
scanf, _scanf_l, wscanf, _wscanf_l
sscanf, _sscanf_l, swscanf, _swscanf_l
Funzioni vprintf

`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`

Sintassi

Parametri

Valore restituito

Osservazioni:

Riepilogo del comportamento

Mapping di routine di testo generico

Requisiti

Esempio

Vedi anche

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive

snprintf, _snprintf, _snprintf_l, _snwprintf, _snwprintf_l

Sintassi

Parametri

Valore restituito

Osservazioni:

Riepilogo del comportamento

Mapping di routine di testo generico

Requisiti

Esempio

Vedi anche

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive

`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`