vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l

Artigo
02/25/2013

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

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

Valor de retorno

vsnprintf,_vsnprintf, e _vsnwprintf retornar o número de caracteres gravados se o número de caracteres para escrever é menor ou igual a count; Se o número de caracteres para escrever for maior que count, essas funções -1 de retorno indicando que a saída foi truncada.O valor de retorno não inclui o nulo de terminação, se um for gravado.

Se buffer ou format é NULL, ou se count 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 terá permissão para continuar, essas funções retornam -1 e defina 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 até count caracteres à memória apontado por buffer.Se houver espaço no final (isto é, se o número de caracteres para escrever é menor do que count), o buffer será terminada por caractere nulo.

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

Observação
Para garantir que não há espaço para a terminação nula, ter certeza de que count é estritamente menores do que o comprimento do buffer e inicializar o buffer null antes para chamar a função.

vsnprintfé idêntico ao _vsnprintf.vsnprintfestá incluído para fins de conformidade para 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 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

TCHAR.Rotina H	_ Unicode & _ MBCS do arquivo não definido	_ MBCS do arquivo 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 de UNIX V.

Para obter 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!!");
}