vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l

Статья
06/09/2015

Записывают форматированные выходные данные с помощью указателя на список аргументов. Здесь представлены версии vsprintf, _vsprintf_l, vswprintf, _vswprintf_l, __vswprintf_l с усовершенствованной безопасностью, как описано в разделе Функции безопасности в CRT.

int vsprintf_s(
   char *buffer,
   size_t numberOfElements,
   const char *format,
   va_list argptr 
); 
int _vsprintf_s_l(
   char *buffer,
   size_t numberOfElements,
   const char *format,
   locale_t locale,
   va_list argptr 
); 
int vswprintf_s(
   wchar_t *buffer,
   size_t numberOfElements,
   const wchar_t *format,
   va_list argptr 
);
int _vswprintf_s_l(
   wchar_t *buffer,
   size_t numberOfElements,
   const wchar_t *format,
   locale_t locale,
   va_list argptr 
);
template <size_t size>
int vsprintf_s(
   char (&buffer)[size],
   const char *format,
   va_list argptr 
); // C++ only
template <size_t size>
int vswprintf_s(
   wchar_t (&buffer)[size],
   const wchar_t *format,
   va_list argptr 
); // C++ only

Параметры

buffer
Место хранения выходных данных.
numberOfElements
Размер buffer в символах.
format
Спецификация формата.
argptr
Указатель на список аргументов.
locale
Используемый языковой стандарт.

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

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

Дополнительные сведения об этих и других кодах ошибок см. в разделе _doserrno, errno, _sys_errlist и _sys_nerr.

Заметки

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

vswprintf_s соответствует стандарту ISO языка C для vswprintf, который требует второго параметра count типа size_t.

Эти функции отличаются от их небезопасных версий тем, что безопасные версии поддерживают позиционные параметры. Для получения дополнительной информации см. Позиционные параметры printf_p.

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

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

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

Подпрограмма TCHAR.H	_UNICODE & _MBCS не определены	_MBCS определено	_UNICODE определено
_vstprintf_s	vsprintf_s	vsprintf_s	vswprintf_s
_vstprintf_s_l	_vsprintf_s_l	_vsprintf_s_l	_vswprintf_s_l

Требования

Подпрограмма	Обязательный заголовок	Необязательные заголовки
vsprintf_s, _vsprintf_s_l	<stdio.h> и <stdarg.h>	<varargs.h>*
vswprintf_s, _vswprintf_s_l	<stdio.h> или <wchar.h> и <stdarg.h>	<varargs.h>*

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

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

Пример

// crt_vsprintf_s.c
// This program uses vsprintf_s to write to a buffer.
// The size of the buffer is determined by _vscprintf.

#include <stdlib.h>
#include <stdarg.h>

void test( char * format, ... )
{
   va_list args;
   int len;
   char * buffer;

   va_start( args, format );
   len = _vscprintf( format, args ) // _vscprintf doesn't count
                               + 1; // terminating '\0'
   buffer = malloc( len * sizeof(char) );
   vsprintf_s( buffer, len, format, args );
   puts( buffer );
   free( buffer );
}

int main( void )
{
   test( "%d %c %d", 123, '<', 456 );
   test( "%s", "This is a string" );
}