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, _vsnwprintfcom aprimoramentos de_vsnwprintf_l segurança, conforme descrito em Recursos de seguranç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 levam char, e palavras para aquelas que levam wchar_t.

count
Número máximo de caracteres a serem gravados, não incluindo o .NULL Para as funções que usam wchar_t, é o número de caracteres largos a serem gravados. Ou _TRUNCATE.

format
Especificação de 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 o valor final , ou negativo se ocorrer um erro de NULLsaída.

Consulte Resumo do comportamento para obter detalhes.

Observações

Cada uma dessas funções recebe um ponteiro para uma lista de argumentos, formata e grava em count caracteres dos dados fornecidos na memória apontada por buffer e acrescenta um NULL.

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

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

vsnprintf_s é idêntico e _vsnprintf_s está incluído para conformidade com o padrão 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 usar um char buffer, o tamanho será em bytes. Se a função usar um wchar_t buffer, o tamanho especificará 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âmetro inválido, consulte Validação de parâmetro.

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 recentes e seguras. Para obter mais informações, consulte Sobrecargas de modelo seguras.

Mapeamentos de rotina de texto genérico

Requisitos

* Necessário para compatibilidade com UNIX V.

Para obter 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!

Consulte também

E/S de fluxo
Funções vprintf
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_endva_start