Compartilhar via


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 de , _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l com aprimoramentos devsnprintf 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 de 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, confira Especificações de formato.

Valor retornado

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.

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 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.
Condição Comportamento Valor retornado errno Invoca um manipulador de parâmetro inválido
Êxito Grava os caracteres no buffer usando a cadeia de caracteres de formato especificada O número de caracteres gravados N/D Não
Erro de codificação durante a formatação Se o especificador sde cadeia de caracteres de processamento , S, ou Z, o processamento da especificação de formato for interrompido. -1 EILSEQ (42) Não
Erro de codificação durante a formatação Se estiver processando especificador c de caracteres ou C, o caractere inválido será ignorado. O número de caracteres gravados não é incrementado para o caractere ignorado, nem nenhum dado é gravado 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, sem incluir o .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álidos, 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álidos, 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, sem incluir o .NULL O número de caracteres que teriam sido gravados não incluindo o .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, sem incluir o .NULL N/D Não
count < sizeOfBuffer e len <= count Todos os dados são gravados e uma terminaçã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 .NULL O número de caracteres escritos, sem incluir o .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álidos, definirá errno, definirá buffer[0] == NULLe retornará um valor negativo. -1 ERANGE (34) Sim
count == _TRUNCATE e len >= sizeOfBuffer Grava o máximo da string que couber em buffer, incluindo a terminação NULL. -1 N/D Não
count == _TRUNCATE e len < sizeOfBuffer Grava a string inteira em buffer com terminação NULL. Número de caracteres gravados. 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álidos, 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, confira Como evitar sobrecargas 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