vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l

Escreva a saída formatada usando um ponteiro para uma lista de argumentos. Estão disponíveis versões mais seguras destas funções; ver 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
Número máximo de caracteres para gravar. Para as funções que levam wchar_t, é o número de caracteres largos para escrever.

format
Especificação do formato.

argptr
Ponteiro para a lista de argumentos.

locale
A localidade a ser usada.

Para obter mais informações, consulte Sintaxe da especificação de formato.

Valor de retorno

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

Consulte Resumo do comportamento para obter detalhes.

Observações

Cada uma dessas funções leva 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 nulo somente se houver espaço no final (ou seja, se o número de caracteres para gravar for menor que count).

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

As versões dessas funções com o sufixo _l são idênticas, exceto que elas usam o parâmetro locale passado em vez da localidade 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 seguro.

Resumo do comportamento

Para a tabela a seguir:

• Seja sizeOfBuffer do tamanho de buffer. Se a função usa um char buffer, o tamanho é em bytes. Se a função usa um wchar_t buffer, o tamanho especifica o número de palavras de 16 bits.
• Seja len o tamanho dos dados formatados. Se a função usa um char buffer, o tamanho é em bytes. Se a função usa um wchar_t buffer, o tamanho especifica 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âmetros inválido, consulte Validação de parâmetros.

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

Mapeamentos de rotina de texto genérico

Requerimentos

O _vsnprintf, _vsnprintf_l_vsnwprintf e _vsnwprintf_l as funções são específicas da Microsoft. Para obter mais 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 em vez disso, juntamente com parâmetros de cadeia de caracteres estreita. O count parâmetro pode ser o tamanho inteiro do buffer, e o valor de retorno é 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!

Ver também

de E/S de fluxo
vprintf funções
Sintaxe da especificação do 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