vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l

Статья
06/09/2015

Записывают форматированные выходные данные с помощью указателя на список аргументов. Существуют более безопасные версии этих функций; см. раздел 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
Наибольшее число символов для записи.
format
Спецификация формата.
argptr
Указатель на список аргументов.
locale
Используемый языковой стандарт.

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

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

vsnprintf,_vsnprintf и _vsnwprintf возвращают число записанных символов, если число символов для записи меньше или равно count; если число символов для записи превосходит count, эти функции возвращают значение -1, указывающее на усечение результата. Возвращаемое значение не включает завершающий нулевой символ, если он был записан.

Если buffer или format — NULL или если число меньше или равно нулю, эти функции вызывают обработчик недопустимого параметра, как описано в разделе Проверка параметров. Если выполнение может быть продолжено, эти функции возвращают -1 и устанавливают errno в значение EINVAL.

Заметки

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

Примечание по безопасности
Убедитесь, что format не является строкой, определяемой пользователем.Дополнительные сведения см. в разделе Как избежать переполнения буфера.

Примечание

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

vsnprintf идентична _vsnprintf. vsnprintf включается для соответствия со стандартом ANSI; _vnsprintf сохраняется для обеспечения обратной совместимости.

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

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

Универсальное текстовое сопоставление функций

Подпрограмма TCHAR.H	_UNICODE & _MBCS не определены	_MBCS определено	_UNICODE определено
_vsntprintf	_vsnprintf	_vsnprintf	_vsnwprintf
_vsntprintf_l	_vsnprintf_l	_vsnprintf_l	_vsnwprintf_l

Требования

Подпрограмма	Обязательный заголовок	Необязательные заголовки
vsnprintf	<stdio.h> и <stdarg.h>	<varargs.h>*
_vsnprintf, _vsnprintf_l	<stdio.h> и <stdarg.h>	<varargs.h>*
_vsnwprintf, _vsnwprintf_l	<stdio.h> или <wchar.h> и <stdarg.h>	<varargs.h>*

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

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

Пример

// crt_vsnprintf.cpp
// compile with: /W3
#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( buff, sizeof(buff) - 1, formatstring, args); // C4996
// Note: vsnprintf is deprecated; consider vsnprintf_s instead
   printf("nSize: %d, buff: %s\n", nSize, buff);
}

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