vsnprintf_s, , _vsnprintf_s_vsnprintf_s_l, _vsnwprintf_s_vsnwprintf_s_l

Записывают форматированные выходные данные с помощью указателя на список аргументов. Эти функции — это версии vsnprintf, _vsnwprintf_l_vsnwprintf_vsnprintf_l _vsnprintfс улучшениями безопасности, как описано в функциях безопасности в CRT.

Синтаксис

int vsnprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   va_list argptr
);

int _vsnprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   va_list argptr
);

int _vsnprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   _locale_t locale,
   va_list argptr
);

int _vsnwprintf_s(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format,
   va_list argptr
);

int _vsnwprintf_s_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format,
   _locale_t locale,
   va_list argptr
);

template <size_t size>
int _vsnprintf_s(
   char (&buffer)[size],
   size_t count,
   const char *format,
   va_list argptr
); // C++ only

template <size_t size>
int _vsnwprintf_s(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   va_list argptr
); // C++ only

Параметры

buffer
Место хранения выходных данных.

sizeOfBuffer
Размер выходных buffer данных. Размер в байтах для функций, которые принимают, и слова для тех, которые принимаютcharwchar_t.

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

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

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

locale
Языковой стандарт, используемый при форматировании выходных данных.

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

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

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

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

Замечания

vsnprintf_s_vsnprintf_s идентичен и включен для соответствия стандарту ANSI. Функция _vnsprintf поддерживается для совместимости с предыдущими версиями.

Каждая из этих функций принимает указатель на список аргументов, затем форматирует и записывает до count символов заданных данных в область памяти, на которую указывает buffer, затем добавляет завершающий нуль-символ.

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

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

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

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

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

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

Внимание

Убедитесь, что 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".

Примечание.

Чтобы было достаточно места для завершающего нуль-символа, убедитесь, что значение параметра count строго меньше размера буфера, или используйте _TRUNCATE.

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

Совет

Если вы получаете неопределенную внешнюю _vsnprintf_s ошибку и используете универсальную среду выполнения C, добавьте legacy_stdio_definitions.lib в набор библиотек для ссылки. Универсальная среда выполнения C не экспортирует эту функцию напрямую и вместо этого определяется встроенным в <stdio.h>. Дополнительные сведения см. в разделе "Общие сведения о потенциальных проблемах обновления" и изменениях соответствия Visual Studio 2015.

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

TCHAR.H рутина	_UNICODE и _MBCS не определен	_MBCS Определенные	_UNICODE Определенные
_vsntprintf_s	_vsnprintf_s	_vsnprintf_s	_vsnwprintf_s
_vsntprintf_s_l	_vsnprintf_s_l	_vsnprintf_s_l	_vsnwprintf_s_l

Требования

Маршрут	Обязательный заголовок	Необязательные заголовки
vsnprintf_s	<stdio.h> и <stdarg.h>.	<varargs.h>*
_vsnprintf_s, _vsnprintf_s_l	<stdio.h> и <stdarg.h>.	<varargs.h>*
_vsnwprintf_s, _vsnwprintf_s_l	<stdio.h>или , и <wchar.h><stdarg.h>	<varargs.h>*

* Требуется для совместимости UNIX V.

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

Пример

// crt_vsnprintf_s.cpp
#include <stdio.h>
#include <wtypes.h>

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

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

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

См. также

Потоковый ввод-вывод
Функции vprintf
fprintf, , _fprintf_lfwprintf_fwprintf_l
printf, , _printf_lwprintf_wprintf_l
sprintf, , _sprintf_lswprintf, _swprintf_l__swprintf_l
va_arg, , va_copyva_endva_start