vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l

Artigo
06/09/2015

A saída formatada de gravação usando um ponteiro para uma lista de argumentos. Versões mais seguras dessas funções estão disponíveis; 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 a serem gravados.
format
Especificação de formato.
argptr
Ponteiro para a lista de argumentos.
locale
A localidade a ser usada.

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

Valor de retorno

vsnprintf,_vsnprintf, e retorno de _vsnwprintf o número de caracteres gravados se o número de caracteres a escrita de é menor ou igual a count; se o número de caracteres a serem gravados é maior que count, essas funções retornam -1 indicando que a saída foram truncados. O valor de retorno não inclui o terminador nulo, se é gravado.

Se buffer ou format são NULL, ou se a contagem é menor ou igual a zero, essas funções invoca o manipulador inválido do parâmetro, conforme descrito em Validação do parâmetro. Se a execução puder continuar, essas funções retornarão -1 e definirão errno a EINVAL.

Comentários

Cada uma dessas funções usa um ponteiro para uma lista de argumentos, ele formata os dados, e prepara à memória count caracteres apontada por buffer. Se houver uma sala na extremidade (ou seja, se o número de caracteres a serem gravados é menor que count), o buffer nulo será encerrado.

Observação de segurança
Verifique se format não é uma cadeia de caracteres definida pelo usuário.Para obter mais informações, consulte Evitando saturações de buffer.

Dica

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

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

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

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

Mapeamentos da rotina de texto genérico

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 a compatibilidade de UNIX V.

Para informações adicionais de 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!!");
}