vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l

Escreva a saída formatada usando um ponteiro para uma lista de argumentos. Essas funções são versões de , vsnprintf, _vsnprintf, _vsnprintf_l, com aprimoramentos de segurança, _vsnwprintfconforme descrito em Recursos de_vsnwprintf_lsegurança no CRT.

Sintaxe

int vsnprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   va_list argptr
);

int _vsnprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   va_list argptr
);

int _vsnprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   _locale_t locale,
   va_list argptr
);

int _vsnwprintf_s(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format,
   va_list argptr
);

int _vsnwprintf_s_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format,
   _locale_t locale,
   va_list argptr
);

template <size_t size>
int _vsnprintf_s(
   char (&buffer)[size],
   size_t count,
   const char *format,
   va_list argptr
); // C++ only

template <size_t size>
int _vsnwprintf_s(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   va_list argptr
); // C++ only

Parâmetros

buffer
Local de armazenamento para saída.

sizeOfBuffer
O tamanho da buffer saída for. Tamanho em bytes para as funções que usam chare palavras para as que levam wchar_t.

count
Número máximo de caracteres para gravar, não incluindo a terminação NULL. Para as funções que levam wchar_t, é o número de caracteres largos para escrever. Ou _TRUNCATE.

format
Especificação do formato.

argptr
Ponteiro para a lista de argumentos.

locale
A localidade a ser usada ao formatar a saída.

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

Valor de retorno

O número de caracteres gravados, não incluindo a terminação NULL, ou um valor negativo se ocorrer um erro de saída.

Consulte Resumo do comportamento para obter detalhes.

Observações

Cada uma dessas funções leva um ponteiro para uma lista de argumentos, em seguida, formata e grava até count caracteres dos dados fornecidos para a memória apontada por buffer e acrescenta uma terminação NULL.

Em compilações de depuração, os bytes restantes sizeOfBuffer após a terminação NULL são preenchidos com 'xFE' conforme descrito em _CrtSetDebugFillThreshold.

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

vsnprintf_s é idêntica e _vsnprintf_s está incluída para conformidade com a norma ANSI. _vnsprintf é retido para compatibilidade com versões anteriores.

Resumo do comportamento

Para a tabela a seguir:

• Seja len o tamanho dos dados formatados. Se a função usa um char buffer, o tamanho é em bytes. Se a função usa um wchar_t buffer, o tamanho especifica o número de palavras de 16 bits.
• Caracteres referem-se a char caracteres para funções que usam um char buffer e a wchar_t caracteres para funções que usam um wchar_t buffer.
• Para obter mais informações sobre o manipulador de parâmetros inválido, consulte Validação de parâmetros.

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

Em C++, o uso dessas funções é simplificado por sobrecargas de modelo; As sobrecargas podem inferir o comprimento do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente funções mais antigas e não seguras por suas contrapartes mais novas e seguras. Para obter mais informações, consulte Sobrecargas de modelo seguro.

Mapeamentos de rotina de texto genérico

Requerimentos

* Necessário para compatibilidade com UNIX V.

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

Exemplo

// crt_vsnprintf_s.cpp
#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_s( buff, _countof(buff), _TRUNCATE, formatstring, args);
   printf("nSize: %d, buff: %s\n", nSize, buff);
   va_end(args);
}

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!

Ver também

de E/S de fluxo
vprintf funções
fprintf, _fprintf_l, fwprintf, _fwprintf_l
printf, _printf_l, wprintf, _wprintf_l
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
va_arg, va_copy, va_end, va_start