vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l

Grave saída formatada usando um ponteiro para uma lista de argumentos. Estão disponíveis versões mais seguras dessas funções; confira vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l.

Sintaxe

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

count
O número máximo de caracteres a serem gravados. Para as funções que usam wchar_t, é o número de caracteres largos a serem gravados.

format
Especificação de formato.

argptr
Ponteiro para a lista de argumentos.

locale
A localidade a ser usada.

Para obter mais informações, consulte Sintaxe de especificação 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

Cada uma dessas funções usa um ponteiro para uma lista de argumentos, em seguida, formata os dados e grava até count caracteres na memória apontada por buffer. A função vsnprintf sempre grava um terminador nulo, mesmo que ele trunque a saída. Quando você usa _vsnprintf e _vsnwprintf, o buffer é terminado em nulo somente se houver espaço no final (ou seja, se o número de caracteres a serem gravados for menor que count).

Começando com o UCRT no Visual Studio 2015 e Windows 10, vsnprintf não é mais idêntico a _vsnprintf. A vsnprintf função está em conformidade com o padrão C99; _vsnprintf é mantida para compatibilidade com versões anteriores com código mais antigo. A diferença é que, se você ficar sem buffer, vsnprintf o terminará em nulo o final do buffer e retornará o número de caracteres que seriam necessários, enquanto _vsnprintf não encerrará o buffer em nulo e retornará -1. Além disso, _vsnprintf() inclui mais um caractere na saída porque ele não termina o buffer em nulidade.

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.

No C++, essas funções têm sobrecargas de modelo que invocam os equivalentes mais novos e seguros dessas funções. Para obter mais informações, consulte Sobrecargas de modelo seguras.

Resumo do comportamento

Para a tabela a seguir:

• Seja sizeOfBuffer do tamanho de buffer. 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.
• 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, confira _doserrno, errno, _sys_errlist e _sys_nerr.

Mapeamentos de rotina de texto genérico

Requisitos

As funções _vsnprintf, _vsnprintf_l, _vsnwprintf e _vsnwprintf_l são específicas da Microsoft. Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo: usar caracteres largos com _vsnwprintf()

// crt_vsnwprintf.c
// compile by using: cl /W3 crt_vsnwprintf.c

// To turn off error C4996, define this symbol:
#define _CRT_SECURE_NO_WARNINGS

#include <stdio.h>
#include <wtypes.h>

#define BUFFCOUNT (10)

void FormatOutput(LPCWSTR formatstring, ...)
{
    int nSize = 0;
    wchar_t buff[BUFFCOUNT];
    memset(buff, 0, sizeof(buff));
    va_list args;
    va_start(args, formatstring);
    // Note: _vsnwprintf is deprecated; consider vsnwprintf_s instead
    nSize = _vsnwprintf(buff, BUFFCOUNT - 1, formatstring, args); // C4996
    wprintf(L"nSize: %d, buff: %ls\n", nSize, buff);
    va_end(args);
}

int main() {
    FormatOutput(L"%ls %ls", L"Hi", L"there");
    FormatOutput(L"%ls %ls", L"Hi", L"there!");
    FormatOutput(L"%ls %ls", L"Hi", L"there!!");
}

nSize: 8, buff: Hi there
nSize: 9, buff: Hi there!
nSize: -1, buff: Hi there!

O comportamento será alterado se você usar vsnprintf em vez disso, juntamente com parâmetros de cadeia estreita. O parâmetro count pode ser o tamanho inteiro do buffer e o valor retornado é o número de caracteres que teriam sido gravados se count fosse grande o suficiente:

Exemplo: usar vsnprintf() com cadeias de caracteres estreitas

// crt_vsnprintf.c
// compile by using: cl /W4 crt_vsnprintf.c
#include <stdio.h>
#include <stdarg.h> // for va_list, va_start
#include <string.h> // for memset

#define BUFFCOUNT (10)

void FormatOutput(char* formatstring, ...)
{
    int nSize = 0;
    char buff[BUFFCOUNT];
    memset(buff, 0, sizeof(buff));
    va_list args;
    va_start(args, formatstring);
    nSize = vsnprintf(buff, sizeof(buff), formatstring, args);
    printf("nSize: %d, buff: %s\n", nSize, buff);
    va_end(args);
}

int main() {
    FormatOutput("%s %s", "Hi", "there");   //  8 chars + null
    FormatOutput("%s %s", "Hi", "there!");  //  9 chars + null
    FormatOutput("%s %s", "Hi", "there!!"); // 10 chars + null
}

nSize: 8, buff: Hi there
nSize: 9, buff: Hi there!
nSize: 10, buff: Hi there!

Confira também

E/S de fluxo
Funções vprintf
Sintaxe de especificação de formato: printf e wprintf 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