sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l

Статья
06/09/2015

Запись форматированных данных в строку. Здесь представлены версии sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l с усовершенствованной безопасностью, как описано в разделе Функции безопасности в CRT.

int sprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   const char *format [,
   argument] ... 
);
int _sprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   const char *format,
   locale_t locale [,
   argument] ... 
);
int swprintf_s(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   const wchar_t *format [,
   argument]...
);
int _swprintf_s_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   const wchar_t *format,
   locale_t locale [,
   argument]…
);
template <size_t size>
int sprintf_s(
   char (&buffer)[size],
   const char *format [,
   argument] ... 
); // C++ only
template <size_t size>
int swprintf_s(
   wchar_t (&buffer)[size],
   const wchar_t *format [,
   argument]...
); // C++ only

Параметры

buffer
Место хранения выходных данных
sizeOfBuffer
Наибольшее число символов для хранения.
format
Строка управления форматом
argument
Необязательные аргументы
locale
Используемый языковой стандарт.

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

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

Записанное число символов или –1 в случае возникновения ошибки. Если buffer или format является пустым указателем, sprintf_s и swprintf_s возвращают значение -1 и задают errno равным EINVAL.

sprintf_s возвращает число байтов, сохраненных в buffer без учета завершающего символа null. swprintf_s возвращает число расширенных символов, сохраненных в buffer, без учета завершающего расширенного символа null.

Заметки

Функция sprintf_s форматирует и сохраняет набор символов и значений в buffer. Каждый argument (если он есть) преобразуется и выводится согласно соответствующей спецификацией формата в format. Формат состоит из обычных символов и имеет те же форму и функциональные возможности, что и аргумент format для printf. После последнего написанного символа добавляется символ null. Если копирование производится между перекрывающимися строками, поведение не определено.

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

Другое основное различие между sprintf_s и sprintf в том, что sprintf_s принимает параметр длины, определяющий размер буфера вывода в символах. Если буфер слишком мал для печатаемого текста, буфер задается равным пустой строке, вызывается обработчик недопустимого параметра. В отличие от snprintf, sprintf_s гарантирует, что буфер будет завершен символом null (если размер буфера не равен нулю).

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

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

Существуют версии sprintf_s, которые обеспечивают дополнительный контроль над происходящим, если буфер слишком мал. Дополнительные сведения см. в разделе _snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l.

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

Подпрограмма TCHAR.H	_UNICODE & _MBCS не определены	_MBCS определено	_UNICODE определено
_stprintf_s	sprintf_s	sprintf_s	swprintf_s
_stprintf_s_l	_sprintf_s_l	_sprintf_s_l	_swprintf_s_l

Требования

Подпрограмма	Обязательный заголовок
sprintf_s, _sprintf_s_l	<stdio.h>
swprintf_s, _swprintf_s_l	<stdio.h> или <wchar.h>

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

Пример

// crt_sprintf_s.c
// This program uses sprintf_s to format various
// data and place them in the string named buffer.
//

#include <stdio.h>

int main( void )
{
   char  buffer[200], s[] = "computer", c = 'l';
   int   i = 35, j;
   float fp = 1.7320534f;

   // Format and print various data: 
   j  = sprintf_s( buffer, 200,     "   String:    %s\n", s );
   j += sprintf_s( buffer + j, 200 - j, "   Character: %c\n", c );
   j += sprintf_s( buffer + j, 200 - j, "   Integer:   %d\n", i );
   j += sprintf_s( buffer + j, 200 - j, "   Real:      %f\n", fp );

   printf_s( "Output:\n%s\ncharacter count = %d\n", buffer, j );
}

// crt_swprintf_s.c
// wide character example
// also demonstrates swprintf_s returning error code
#include <stdio.h>

int main( void )
{
   wchar_t buf[100];
   int len = swprintf_s( buf, 100, L"%s", L"Hello world" );
   printf( "wrote %d characters\n", len );
   len = swprintf_s( buf, 100, L"%s", L"Hello\xffff world" );
   // swprintf_s fails because string contains WEOF (\xffff)
   printf( "wrote %d characters\n", len );
}