vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l

Grave saída formatada usando um ponteiro para uma lista de argumentos. Essas funções são versões do , , , , com aprimoramentos de segurança, _vsnprintf_vsnprintf_lconforme descrito em Recursos de vsnprintfsegurança na CRT._vsnwprintf_l_vsnwprintf

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 de saída.

sizeOfBuffer
O tamanho da buffer saída for. Tamanho em bytes para as funções que tomam , e palavras para aquelas que tomam charwchar_t.

count
Número máximo de caracteres a serem gravados não incluindo o .NULL Para as funções que tomam wchar_t, é o número de caracteres largos para escrever. 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, confira Especificações de formato.

Retornar valor

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

Consulte Resumo do comportamento para obter detalhes.

Comentários

vsnprintf_s é idêntico e _vsnprintf_s está incluído para conformidade com o padrão ANSI. _vnsprintf é mantido para compatibilidade com versões anteriores.

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

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

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 usar um wchar_t buffer, o tamanho especificará o número de palavras de 16 bits.
• Caracteres referem-se a caracteres para funções que usam um buffer e a charwchar_t caracteres para funções que usam um charwchar_t buffer.
• Para obter mais informações sobre o manipulador de parâmetros inválidos, consulte Validação de parâmetro.

Condição	Comportamento	Retornar valor	errno	Invoca um manipulador de parâmetro inválido
Sucesso	Grava os caracteres no buffer usando a cadeia de caracteres de formato especificada	O número de caracteres escritos	N/D	Não
Erro de codificação durante a formatação	Se o processamento do especificador sde cadeia de caracteres , ou Z, So processamento de especificação de formato for interrompido.	-1	EILSEQ (42)	Não
Erro de codificação durante a formatação	Se o especificador c de caracteres de processamento ou C, o caractere inválido será ignorado. O número de caracteres gravados não é incrementado para o caractere ignorado, nem os dados são gravados para ele. O processamento da especificação de formato continua depois de ignorar o especificador com o erro de codificação.	O número de caracteres escritos, não incluindo o término NULL.	EILSEQ (42)	Não
buffer == NULL e sizeOfBuffer == 0 e count == 0	Nenhum dado é gravado.	0	N/D	Não
buffer == NULLe ou sizeOfBuffer != 0count != 0	Se a execução continuar após a execução do manipulador de parâmetros inválido, definirá errno e retornará um valor negativo.	-1	EINVAL (22)	Sim
buffer != NULL e sizeOfBuffer == 0	Nenhum dado é gravado. Se a execução continuar após a execução do manipulador de parâmetros inválido, definirá errno e retornará um valor negativo.	-1	EINVAL (22)	Sim
count == 0	Não grava nenhum dado e retorna o número de caracteres que teriam sido gravados, não incluindo o encerramento NULL.	O número de caracteres que teriam sido gravados não incluindo o término NULL.	N/D	Não
count < 0	Não seguro: o valor é tratado como não assinado, provavelmente criando um valor grande que resulta na substituição da memória que segue o buffer.	O número de caracteres escritos, não incluindo o término NULL.	N/D	Não
count < sizeOfBuffer e len <= count	Todos os dados são gravados e uma rescisão NULL é anexada.	O número de caracteres gravados.	N/D	Não
count < sizeOfBuffer e len > count	Os primeiros count caracteres são escritos.	-1	N/D	Não
count >= sizeOfBuffer e len < sizeOfBuffer	Todos os dados são gravados com um arquivo NULL.	O número de caracteres escritos, não incluindo o término NULL.	N/D	Não
count >= sizeOfBuffer e len >= sizeOfBuffer e count != _TRUNCATE	Se a execução continuar após a execução do manipulador de parâmetros inválido, define errno, define buffer[0] == NULLe retorna um valor negativo.	-1	ERANGE (34)	Sim
count == _TRUNCATE e len >= sizeOfBuffer	Grava o máximo de sequência de caracteres que couber no buffer, incluindo o encerramento NULL.	-1	N/D	Não
count == _TRUNCATE e len < sizeOfBuffer	Grava toda a cadeia de caracteres em buffer com terminating NULL.	Número de caracteres escritos.	N/D	Não
format == NULL	Nenhum dado é gravado. Se a execução continuar após a execução do manipulador de parâmetros inválido, definirá errno e retornará um valor negativo.	-1	EINVAL (22)	Sim

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

Importante

Verifique se format não é uma cadeia de caracteres definida pelo usuário. Para obter mais informações, consulte Evitando saturações de buffer. Começando pelo Windows 10 versão 2004 (build 19041), a família de funções printf imprime números de ponto flutuante exatamente representáveis de acordo com as regras do IEEE 754 para arredondamento. Em versões anteriores do Windows, números de ponto flutuante que pudessem ser representados com exatidão e que terminassem em '5' eram sempre arredondados para cima. O IEEE 754 afirma que eles precisam arredondar para o dígito par mais próximo (também conhecido como "arredondamento bancário"). Por exemplo, ambos printf("%1.0f", 1.5) e printf("%1.0f", 2.5) devem ser arredondados para 2. Anteriormente, 1,5 seria arredondado para 2 e 2,5 para 3. Essa alteração afeta apenas números que possam ser representados com exatidão. Por exemplo, 2,35 (que, quando representado na memória, está mais próximo de 2,35000000000000008) continua arredondando para 2,4. O arredondamento feito por essas funções agora também respeita o modo de arredondamento de ponto flutuante definido por fesetround. Anteriormente, o arredondamento sempre escolhia o comportamento FE_TONEAREST. Essa alteração afeta apenas os programas criados usando o Visual Studio 2019 versão 16.2 e posteriores. Para usar o comportamento de arredondamento de ponto flutuante herdado, vincule-o a 'legacy_stdio_float_rounding.obj'.

Observação

Para garantir espaço para o nulo de terminação, certifique-se de que count seja estritamente menor do que o comprimento do buffer ou use _TRUNCATE.

Em C++, o uso dessas funções é simplificado pelas sobrecargas de modelo; as sobrecargas podem inferir o tamanho 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 equivalentes mais recentes e seguras. Para obter mais informações, consulte Sobrecargas de modelo seguras.

Dica

Se você receber um erro externo _vsnprintf_s indefinido e estiver usando o Universal C Runtime, adicione legacy_stdio_definitions.lib ao conjunto de bibliotecas a serem vinculadas. O Universal C Runtime não exporta essa função diretamente, em vez disso, ele é definido em linha no <stdio.h>. Para obter mais informações, consulte Visão geral de possíveis problemas de atualização e alterações de conformidade do Visual Studio 2015.

Mapeamentos de rotina de texto genérico

Rotina TCHAR.H	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_vsntprintf_s	_vsnprintf_s	_vsnprintf_s	_vsnwprintf_s
_vsntprintf_s_l	_vsnprintf_s_l	_vsnprintf_s_l	_vsnwprintf_s_l

Requisitos

Rotina	Cabeçalho necessário	Cabeçalhos opcionais
vsnprintf_s	<stdio.h> e <stdarg.h>	<varargs.h>*
_vsnprintf_s, _vsnprintf_s_l	<stdio.h> e <stdarg.h>	<varargs.h>*
_vsnwprintf_s, _vsnwprintf_s_l	<stdio.h> ou <wchar.h>, e <stdarg.h>	<varargs.h>*

* 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!

Confira 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_end, va_start