_snprintf, _snprintf_l, _snwprintf, _snwprintf_l

Articolo
06/09/2015

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.

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 archiviare.
format
Stringa di controllo del formato.
argument
Argomenti facoltativi.
locale
Impostazioni locali da utilizzare.

Per ulteriori informazioni, vedere Sintassi per la specifica del formato: funzioni printf wprintf.

Valore restituito

Lasciare che len sia la lunghezza della stringa di dati formattata, escluso il carattere di terminazione Null. len e count sono in byte per _snprintf, caratteri wide per _snwprintf.

Se len < count, i caratteri len sono archiviati in buffer, viene aggiunto un carattere di terminazione Null e viene restituito len.

Se len = count, i caratteri len sono archiviati in buffer, non viene aggiunto alcun carattere di terminazione Null e viene restituito len.

Se len > count, i caratteri count sono archiviati in buffer, non viene aggiunto alcun carattere di terminazione Null e viene restituito un valore negativo.

Se buffer è un puntatore Null e count è pari a zero, len viene restituito come numero di caratteri necessari per formattare l'output, escluso il carattere di terminazione Null. Per eseguire correttamente una chiamata con gli stessi parametri argument e locale, allocare un buffer contenente almeno len + 1 carattere.

Se buffer è un puntatore Null e count è diverso da zero o se format è un puntatore Null, viene richiamato il gestore di parametro non valido, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, queste funzioni restituiscono -1 e impostano errno su EINVAL.

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

Note

La funzione _snprintf formatta e archivia count o un numero inferiore di caratteri in buffer e aggiunge un carattere di terminazione Null se la lunghezza della stringa formattata è rigorosamente minore dei caratteri count. 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 la funzione printf. Se la copia avviene tra stringhe che si sovrappongono, il comportamento non è definito.

Nota sulla sicurezza
Assicurarsi che format non sia una stringa definita dall'utente.Poiché questa funzione non garantisce una terminazione NULL, in particolare quando il valore restituito è count, assicurarsi che sia seguita da codice che aggiunge il carattere di terminazione Null.Per ulteriori informazioni, vedere Evitare sovraccarichi del buffer.

_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 essere diverso da quello 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 presentano overload dei modelli che richiamano le relative controparti più sicure e recenti. Per ulteriori informazioni, vedere Overload di modelli sicuri.

Mapping di routine di testo generico

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

Requisiti

Routine	Intestazione obbligatoria
_snprintf, _snprintf_l	<stdio.h>
_snwprintf, _snwprintf_l	<stdio.h> o <wchar.h>

Per ulteriori informazioni sulla compatibilità, vedere 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 nul! */
   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 nul because _snprintf doesn't necessarily (if the string 
       * fits without the terminal nul, 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;
}