vsnprintf, , _vsnprintf_vsnprintf_l, _vsnwprintf_vsnwprintf_l

Запишите отформатированный вывод с помощью указателя на список аргументов. Доступны более безопасные версии этих функций; см. vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, , _vsnwprintf_s. _vsnwprintf_s_l

Синтаксис

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

Параметры

buffer
Место хранения продукции.

count
Наибольшее количество символов для записи. Для функций, которые принимают wchar_t, это количество широких символов для записи.

format
Спецификация формата.

argptr
Указатель на список аргументов.

locale
Используемая региональная настройка.

Дополнительные сведения см. в разделе Синтаксис спецификации формата.

Возвращаемое значение

Количество записанных символов, не включая завершающий NULL, или отрицательное значение в случае возникновения ошибки вывода.

Дополнительные сведения см . в сводке по поведению.

Замечания

Каждая из этих функций принимает указатель на список аргументов, затем форматирует данные и записывает до count символов в память, на bufferкоторую указывает . Функция vsnprintf всегда записывает нулевой терминатор, даже если она обрезает вывод. При использовании _vsnprintf и , _vsnwprintfбуфер завершается нулем только в том случае, если в конце есть место (то есть, если количество записываемых символов меньше count).

Начиная с UCRT в Visual Studio 2015 и Windows 10, vsnprintf больше не идентичен _vsnprintf. Функция vsnprintf соответствует стандарту C99 и _vsnprintf сохранена для обеспечения обратной совместимости со старым кодом. Разница в том, vsnprintf что если у вас закончился буфер, он завершает конец буфера нулем и возвращает количество символов, которое было бы необходимо, но _vsnprintf не завершает буфер нулем и возвращает -1. Кроме того, включает еще один символ в выходные данные, _vsnprintf() так как он не завершает буфер без значения NULL.

Версии этих функций с _l суффиксом идентичны, за исключением того, что они используют переданный параметр locale вместо текущей локали потока.

В C++ эти функции имеют шаблонные перегрузки, которые вызывают более новые, безопасные аналоги этих функций. Дополнительные сведения см. в разделе "Безопасные перегрузки шаблонов".

Сводка по поведению

В следующей таблице:

• Пусть sizeOfBuffer будет размер buffer. Если функция принимает char буфер, размер находится в байтах. Если функция принимает wchar_t буфер, размер указывает количество 16-разрядных слов.
• Допустим len , размер отформатированных данных. Если функция принимает char буфер, размер находится в байтах. Если функция принимает wchar_t буфер, размер указывает количество 16-разрядных слов.
• Символы относятся к char символам функций, которые принимают char буфер, а также wchar_t к символам для функций, которые принимают wchar_t буфер.
• Дополнительные сведения о обработчике недопустимых параметров см. в разделе "Проверка параметров".

Сведения об этих и других кодах ошибок см. в разделе _doserrno, errno_sys_errlistи _sys_nerr.

Сопоставления подпрограмм универсального текста

Требования

Функции _vsnprintf, _vsnprintf_l_vsnwprintf и _vsnwprintf_l являются специфичными для Microsoft. Дополнительные сведения о совместимости см. в разделе Совместимость.

Пример: Используйте широкие символы с _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!

Поведение меняется, если вместо него используется vsnprintf вместе с узкостроковыми параметрами. Параметр count может быть всем размером буфера, а возвращаемое значение — это количество символов, которое было бы записано, если count бы было достаточно большим:

Пример: Использование vsnprintf() с узкими строками

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

См. также

Потоковый ввод-вывод
vprintf функции
Синтаксис спецификации формата: printf и wprintf функции
fprintf, , _fprintf_lfwprintf_fwprintf_l
printf, , _printf_lwprintf_wprintf_l
sprintf, _sprintf_l, , swprintf, _swprintf_l__swprintf_l
va_arg, , va_copyva_endva_start