vsnprintf, _vsnprintf, _vsnprintf_l, , _vsnwprintf_vsnwprintf_l

Escreva a saída formatada usando um ponteiro para uma lista de argumentos. Versões mais seguras dessas funções estão disponíveis; veja 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 para 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 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 usa um ponteiro para uma lista de argumentos, formata os dados e grava em count caracteres na memória apontada por buffer. A vsnprintf função sempre grava um terminador nulo, mesmo que trunce 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 _l sufixo são idênticas, exceto que elas usam o parâmetro locale passado em vez da localidade do thread atual.

Em C++, essas funções têm sobrecargas de modelo que invocam as contrapartes mais recentes e seguras 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 _vsnprintffunções , _vsnprintf_l, _vsnwprintf e _vsnwprintf_l são específicas da Microsoft. Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo: use 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 muda se você usar vsnprintf, juntamente com parâmetros de cadeia de caracteres estreita. O count parâmetro pode ser o tamanho total do buffer e o valor retornado é o número de caracteres que teriam sido gravados se count fosse grande o suficiente:

Exemplo: use vsnprintf() com strings 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!

Consulte 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_endva_start