`vsnprintf`, , `_vsnprintf_vsnprintf_l`, `_vsnwprintf_vsnwprintf_l`

Статья
01/23/2024

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

Синтаксис

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 всегда записывает знак завершения NULL, даже если усекает выходные данные. При использовании _vsnprintf и _vsnwprintfбуфер завершается значением NULL, только если в конце есть комната (то есть, если число символов для записи меньше count).

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

Важно!

Чтобы предотвратить определенные риски безопасности, убедитесь, что format это не определяемая пользователем строка. Дополнительные сведения см. в разделе "Избегание переполнения буфера". Начиная с Windows 10 версии 2004 (сборка 19041), printf семейство функций выводит точно представленные числа с плавающей запятой в соответствии с правилами IEEE 754 для округления. В предыдущих версиях Windows точно представленные числа с плавающей запятой, заканчивающиеся на "5", всегда округлялись. IEEE 754 утверждает, что они должны округлиться до ближайшей даже цифры (также известной как "Округление банкира"). Например, оба printf("%1.0f", 1.5) и printf("%1.0f", 2.5) должны округлиться до 2. Ранее 1,5 округляет до 2 и 2,5 округления до 3. Это изменение влияет только на точно представленные числа. Например, 2.35 (который при представлении в памяти приближается к 2,3500000000000000008) продолжает округляется до 2,4. Округление, выполняемое этими функциями, теперь также учитывает режим округления с плавающей запятой, заданный fesetround. Ранее округление всегда выбрало FE_TONEAREST поведение. Это изменение влияет только на программы, созданные с помощью Visual Studio 2019 версии 16.2 и более поздних версий. Чтобы использовать устаревшее поведение округления с плавающей запятой, свяжите ссылку с "legacy_stdio_float_rounding.obj".

Примечание.

Чтобы убедиться, что при вызове вызываемого _vsnprintf_vsnwprintf_vsnprintf_lзначения null имеется место, и _vsnwprintf_lубедитесь, что count длина буфера не превышает длину буфера и инициализирует буфер до null до вызова функции.

Так как vsnprintf всегда записывает конечный null, count параметр может быть равен размеру буфера.

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

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

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

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

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

Condition	Поведение	Возвращаемое значение	`errno`	Вызывает обработчик недопустимого параметра
Удачное завершение	Записывает символы в буфер с помощью указанной строки формата.	Число записанных символов, а не подсчет конца символа NULL.	Н/П	No
Ошибка кодирования во время форматирования	Если описатель `s`строки обработки или `SZ`форматирование спецификации останавливается.	-1	`EILSEQ` (42)	No
Ошибка кодирования во время форматирования	Если описатель символов `c` обработки или `C`недопустимый символ пропускается. Число записанных символов не увеличивается для пропущенного символа, а также не записывается для него никакие данные. Обработка спецификации формата продолжается после пропуска описателя с ошибкой кодирования.	Число записанных символов, не включая завершение `NULL`.	`EILSEQ` (42)	No
`buffer == NULL` и `count != 0`.	Если выполнение продолжается после выполнения обработчика недопустимых параметров, задает `errno` и возвращает отрицательное значение.	-1	`EINVAL` (22)	Да
`count == 0`	Данные не записываются	Число символов, которые были бы написаны, не включая завершающийся `NULL`. Этот результат можно использовать для выделения достаточного пространства буфера для строки и конца `NULL`, а затем снова вызвать функцию для заполнения буфера.	Н/П	No
`count < 0`	Небезопасно: значение считается неподписанным, скорее всего, создает большое значение, которое приводит к перезаписи памяти, следующей за буфером.	Количество записанных символов.	Н/П	No
`count < sizeOfBuffer` и `len <= count`.	Все данные записываются, а завершение `NULL` добавляется.	Число записанных символов, не включая завершение `NULL`.	Н/П	No
`count < sizeOfBuffer` и `len > count`.	`count-1` Первые символы записываются после конца null.	Число символов, которые были бы записаны `count` , соответствовало количеству символов для выходных данных, не включая конечный элемент NULL.	Н/П	No
`count >= sizeOfBuffer` и `len < sizeOfBuffer`.	Все данные записываются с завершением `NULL`.	Число записанных символов, не включая завершение `NULL`.	Н/П	No
`count >= sizeOfBuffer` и `len >= sizeOfBuffer`.	Небезопасно: перезаписывает память, которая следует буферу.	Число записанных символов, не включая завершение `NULL`.	Н/П	No
`format == NULL`	Данные не записываются. Если выполнение продолжается после выполнения обработчика недопустимых параметров, задает `errno` и возвращает отрицательное значение.	-1	`EINVAL` (22)	Да

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

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

`TCHAR.H` Обычной	`_UNICODE` и `_MBCS` не определен	`_MBCS` Определенные	`_UNICODE` Определенные
`_vsntprintf`	`_vsnprintf`	`_vsnprintf`	`_vsnwprintf`
`_vsntprintf_l`	`_vsnprintf_l`	`_vsnprintf_l`	`_vsnwprintf_l`

Requirements

Маршрут	Обязательный заголовок (C)	Обязательный заголовок (C++)
`vsnprintf`, , `_vsnprintf``_vsnprintf_l`	`<stdio.h>`	`<stdio.h>` или `<cstdio>`
`_vsnwprintf`, `_vsnwprintf_l`	`<stdio.h>` или `<wchar.h>`	`<stdio.h>`, `<wchar.h>`, `<cstdio>` или `<cwchar>`

Функции _vsnprintfи _vsnwprintf_vsnwprintf_l функции _vsnprintf_lотносятся к корпорации Майкрософт. Дополнительные сведения о совместимости см. в разделе Совместимость.

Пример. Использование расширенных символов с `_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_lswprintf, _swprintf_l__swprintf_l
va_arg, , va_copyva_endva_start

`vsnprintf`, , `_vsnprintf_vsnprintf_l`, `_vsnwprintf_vsnwprintf_l`

Синтаксис

Параметры

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

Замечания

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

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

Requirements

Пример. Использование расширенных символов с `_vsnwprintf()`

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

См. также

Обратная связь

Обратная связь

Дополнительные ресурсы

vsnprintf, , _vsnprintf_vsnprintf_l, _vsnwprintf_vsnwprintf_l

Синтаксис

Параметры

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

Замечания

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

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

Requirements

Пример. Использование расширенных символов с _vsnwprintf()

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

См. также

Обратная связь

Обратная связь

Дополнительные ресурсы

`vsnprintf`, , `_vsnprintf_vsnprintf_l`, `_vsnwprintf_vsnwprintf_l`

Пример. Использование расширенных символов с `_vsnwprintf()`

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