_snprintf, _snprintf_l, _snwprintf, _snwprintf_l

Artigo
06/09/2015

Grava dados formatados em uma cadeia de caracteres. Versões mais seguras dessas funções estão disponíveis; consulte _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

Parâmetros

buffer
Local de armazenamento para a saída.
count
O número máximo de caracteres a ser armazenado.
format
Cadeia de caracteres de controle de formato.
argument
Argumentos opcionais.
locale
A localidade a ser usada.

Para obter mais informações, consulte Sintaxe de especificação de formato: funções printf e and wprintf.

Valor de retorno

Deixe len ser o comprimento da cadeia de caracteres de dados formatada, não incluindo a terminação nula. len e count estão em bytes para _snprintf, caracteres largos para _snwprintf.

Se caracteres len < count, len forem armazenados em buffer, um terminador nulo será anexado, e len será retornado.

Se caracteres len = count, len forem armazenados em buffer, nenhum terminador nulo será anexado, e len será retornado.

Se caracteres len > count, count forem armazenados em buffer, nenhum terminador nulo será anexado, e um valor negativo será retornado.

Se buffer for um ponteiro nulo e count for zero, len será retornado como a contagem de caracteres necessária para formatar a saída, não incluindo a terminação nula. Para fazer uma chamada bem-sucedida com os mesmos parâmetros argument e locale, atribua um buffer que contém pelo menos len + 1 caracteres.

Se buffer for um ponteiro nulo e count for diferente de zero, ou se format for um ponteiro nulo, o manipulador de parâmetro inválido será chamado, conforme descrito em Validação do parâmetro. Se a execução puder continuar, essas funções retornarão -1 e definirão errno como EINVAL.

Para obter informações sobre esses e outros códigos de erro, consulte errno, _doserrno, _sys_errlist e _sys_nerr.

Comentários

A função _snprintf formata e armazena count ou menos caracteres em buffer, e anexa um caractere de terminação nula quando o comprimento da cadeia de caracteres formatada tem estritamente menos de count caracteres. Cada argument (se houver) é convertido e gerado de acordo com a especificação de formato correspondente em format. O formato consiste em caracteres comuns e tem o mesmo formato e função que o argumento format para printf. Se ocorrer cópia entre cadeias de caracteres que se sobrepõem, o comportamento será indefinido.

Observação de segurança
Verifique se format não é uma cadeia de caracteres definida pelo usuário.Como essa função não garante a terminação NULL – especificamente, quando o valor de retorno é count– certifique-se de que ela seja seguida pelo código que adiciona o terminador nulo.Para obter mais informações, consulte Evitando saturações de buffer.

_snwprintf é uma versão de caractere largo de _snprintf; os argumentos de ponteiro para _snwprintf são cadeias de caracteres largos. A detecção de erros de codificação em _snwprintf pode ser diferente da detecção em _snprintf. _snwprintf, assim como swprintf, grava o resultado em uma cadeia de caracteres em vez de um destino do tipo FILE.

As versões dessas funções que têm o sufixo _l são idênticas, exceto que elas usam o parâmetro de localidade informado em vez da localidade do thread atual.

No C++, essas funções têm as sobrecargas de modelo que invocam suas correspondentes mais seguras e mais recentes. Para obter mais informações, consulte Sobrecargas de modelo seguras.

Mapeamentos da rotina de texto genérico

Rotina Tchar.h	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_sntprintf	_snprintf	_snprintf	_snwprintf
_sntprintf_l	_snprintf_l	_snprintf_l	_snwprintf_l

Requisitos

Rotina	Cabeçalho necessário
_snprintf, _snprintf_l	<stdio.h>
_snwprintf, _snwprintf_l	<stdio.h> ou <wchar.h>

Para obter mais informações de compatibilidade, consulte Compatibilidade.

Exemplo

// 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;
}