vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l

Artigo
08/25/2010

gravar formatado usando um ponteiro para uma lista de argumentos de saída.Versões mais seguras dessas funções estão disponível; consulte vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l.

int vsnprintf(
   char *buffer,
   size_t count,
   const char *format,
   va_list argptr 
);
int _vsnprintf(
   char *buffer,
   size_t count,
   const char *format,
   va_list argptr 
);
int _vsnprintf_l(
   char *buffer,
   size_t count,
   const char *format,
   locale_t locale,
   va_list argptr 
);
int _vsnwprintf(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format,
   va_list argptr 
);
int _vsnwprintf_l(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format,
   locale_t locale,
   va_list argptr 
);
template <size_t size>
int vsnprintf(
   char (&buffer)[size],
   size_t count,
   const char *format,
   va_list argptr 
); // C++ only
template <size_t size>
int _vsnprintf(
   char (&buffer)[size],
   size_t count,
   const char *format,
   va_list argptr 
); // C++ only
template <size_t size>
int _vsnprintf_l(
   char (&buffer)[size],
   size_t count,
   const char *format,
   locale_t locale,
   va_list argptr 
); // C++ only
template <size_t size>
int _vsnwprintf(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   va_list argptr 
); // C++ only
template <size_t size>
int _vsnwprintf_l(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   locale_t locale,
   va_list argptr 
); // C++ only

Parâmetros

buffer
Local de armazenamento para saída.
count
Número máximo de caracteres para gravar.
format
Especificação de formato.
argptr
Ponteiro para a lista de argumentos.
locale
A localidade para usar.

Valor de retorno

vsnprintf,_vsnprintf, and _vsnwprintf return the number of characters written if the number of characters to write is less than or equal to count; if the number of characters to write is greater than count, these functions return -1 indicating that output has been truncated.O valor retornado não inclui terminação nula, se um for gravado.

If buffer ou format é NULL, ou se contagem for menor ou igual a zero, essas funções chamar o manipulador de parâmetro inválido, conforme descrito em Validação de parâmetro. Se a execução for permitida para continuar, essas funções retornam -1 e conjunto errno para EINVAL.

Comentários

Cada uma dessas funções leva um ponteiro para uma lista de argumentos, em seguida, formata os dados e grava count caracteres para a memória apontado por buffer. Se houver espaço no participante (ou seja, se o número de caracteres para escrever for menor que count), o buffer será terminada com caractere nulo.

Observação de segurança:
Certifique-se de que format não é uma seqüência de caracteres definida pelo usuário. Para obter mais informações, consulte Evitar saturações de buffer.

Observação:
Para garantir que haja espaço para a terminação nula, certifique-se de que count é estritamente menor do que o comprimento do buffer e inicializar o buffer nulo antes para chamar a função.

vsnprintf é idêntico ao _vsnprintf. vsnprintf é incluído para conformidade com o ANSI padrão; _vnsprintf é mantido para compatibilidade com versões anteriores.

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

No C++, essas funções têm sobrecargas de modelo que invocam as suas similares do mais recentes, seguras dessas funções.For more information, see Proteger overloads de modelo.

Mapeamentos de rotina de texto genérica

Rotina TCHAR.H	_UNICODE & _MBCS não definido	_MBCS definido	_UNICODE definido
_vsntprintf	_vsnprintf	_vsnprintf	_vsnwprintf
_vsntprintf_l	_vsnprintf_l	_vsnprintf_l	_vsnwprintf_l

Requisitos

Rotina	Cabeçalho necessário	Cabeçalhos opcionais
vsnprintf	<stdio.h> e <stdarg.h>	<varargs.h> *
_vsnprintf, vsnprintf_l	<stdio.h> e <stdarg.h>	<varargs.h> *
_vsnwprintf, _vsnwprintf_l	<stdio.h> ou <wchar.h> e <stdarg.h>	<varargs.h> *

* Necessário para compatibilidade UNIX V.

Para obter informações adicionais compatibilidade, consulte Compatibilidade na introdução.

Exemplo

// crt_vsnprintf.cpp
// compile with: /W3
#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( buff, sizeof(buff) - 1, formatstring, args); // C4996
// Note: vsnprintf is deprecated; consider vsnprintf_s instead
   printf("nSize: %d, buff: %s\n", nSize, buff);
}

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!