_snprintf, _snprintf_l, _snwprintf, _snwprintf_l

Artigo
02/25/2013

Dados para uma seqüência de caracteres formatada de gravações.Versões mais seguras dessas funções estão disponíveis; see _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
Número máximo de caracteres para armazenar.
format
Seqüência de caracteres de controle de formato.
argument
Argumentos opcionais.
locale
A localidade para usar.

Para obter mais informações, consulte Especificações de formato.

Valor de retorno

Permitir que len ter o comprimento da seqüência de dados formatados (não incluindo a terminação nula).lene count estão em bytes para _snprintf, caracteres largos em _snwprintf.

If len < count, em seguida, len caracteres são armazenados em buffer, é acrescentado um terminador de null, e len é retornado.

Se len = count, em seguida, len caracteres são armazenados em buffer, nenhum terminador de null é acrescentado, e len é retornado.

If len > count, em seguida, count caracteres são armazenados em buffer, nenhum terminador de null é acrescentado e um valor negativo é retornado.

Se buffer é um ponteiro nulo e count é diferente de zero, ou format é um ponteiro nulo, o manipulador de parâmetro inválido é invocado, conforme descrito em Validação de parâmetro.Se a execução terá permissão para continuar, essas funções retornam -1 e defina errno para EINVAL.

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

Comentários

O _snprintf armazenamentos e formatos de função count caracteres ou menos em buffere o acrescenta um caractere nulo de terminação, se o comprimento da seqüência de caracteres formatada é estritamente menos de count caracteres.Cada argument (se houver) são convertidos e saída de acordo com a especificação de formato correspondente em format.O formato consiste em caracteres comuns e tenha o mesmo formulário e funcionar como o format argumento para printf.Se copiar ocorrer entre cadeias de caracteres que se sobrepõem, o comportamento é indefinido.

Observação de segurança
Certifique-se de que format não é uma seqüência definida pelo usuário.Porque esta função não garante a terminação nula (em particular, quando o valor de retorno é count), certifique-se de que ele é seguido 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 seqüências de caracteres largos.Detecção de erros de codificação _snwprintf podem diferir do que em _snprintf._snwprintf, como swprintf, grava a saída para uma seqüência de caracteres em vez de um destino do tipo FILE.

As versões dessas funções com o _l sufixo são idênticas exceto que eles usam o parâmetro de localidade passado em vez da localidade do thread atual.

No C++, essas funções têm sobrecargas de modelo que invocam as suas similares do mais recentes, seguras dessas funções.Para obter mais informações, consulte Proteger Overloads de modelo.

Mapeamentos de rotina de texto genérico

Rotina de TCHAR.h	_ Unicode e _ MBCS do arquivo não definido	_ MBCS do arquivo 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 na introdução.

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