`_snprintf_s`, , `_snprintf_s_l_snwprintf_s_snwprintf_s_l`

Статья
10/12/2023

Записывает форматированные данные в строку. Эти функции — это версии snprintf, _snprintf_snprintf_l_snwprintfс улучшениями безопасности, _snwprintf_lописанными в функциях безопасности в CRT.

Синтаксис

int _snprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format [,
   argument] ...
);

int _snprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   _locale_t locale [,
   argument] ...
);

int _snwprintf_s(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format [,
   argument] ...
);

int _snwprintf_s_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format,
   _locale_t locale [,
   argument] ...
);

template <size_t size>
int _snprintf_s(
   char (&buffer)[size],
   size_t count,
   const char *format [,
   argument] ...
); // C++ only

template <size_t size>
int _snwprintf_s(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format [,
   argument] ...
); // C++ only

Параметры

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

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

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

format
Строка управления форматом.

argument
Необязательные аргументы.

locale
Используемый языковой стандарт.

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

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

Замечания

Форматы _snprintf_s функций и сохранение count или меньше символов в buffer и добавление конца NULL. Каждый аргумент (если он есть) преобразуется и выводится согласно соответствующей спецификации формата в format. Форматирование соответствует семейству printf функций; см . синтаксис спецификации формата: printf и wprintf функции. Если копирование производится между перекрывающимися строками, поведение не определено.

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

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

-Дайте 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`и `sizeOfBuffer == 0count == 0`	Данные не записываются.	0	Н/П	No
`buffer == NULLsizeOfBuffer != 0` или`count != 0`	Если выполнение продолжается после выполнения обработчика недопустимых параметров, задает `errno` и возвращает отрицательное значение.	-1	`EINVAL` (22)	Да
`buffer != NULL` и `sizeOfBuffer == 0`.	Данные не записываются.	-1	`EINVAL` (22)	Да
`count == 0`	A `NULL` помещается в начало буфера.	-1	Н/П	No
`count < 0`	Небезопасно: значение считается неподписанным, скорее всего, создает большое значение, которое приводит к перезаписи памяти, следующей за буфером.	Число записанных символов, не включая завершение `NULL`.	Н/П	No
`count < sizeOfBuffer` и `len <= count`.	Все данные записываются, а завершение `NULL` добавляется.	Количество записанных символов.	Н/П	No
`count < sizeOfBuffer` и `len > count`.	Первые `count` символы записываются, а завершение `NULL` добавляется.	-1	Н/П	No
`count >= sizeOfBuffer` и `len < sizeOfBuffer`.	Все данные записываются с завершением `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`.	Число записанных символов, не включая завершение `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".

_snwprintf_s — это двухбайтовая версия _snprintf_s; аргументы указателя для _snwprintf_s представляют собой двухбайтовые строки. Обнаружение ошибок кодировки в _snwprintf_s может отличаться от обнаружения ошибок в _snprintf_s. _snwprintf_s так же, как swprintf_s, записывает выходные данные в строку вместо назначения типа FILE.

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

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

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

`Tchar.h` рутина	`_UNICODE` и `_MBCS` не определен	`_MBCS` Определенные	`_UNICODE` Определенные
`_sntprintf_s`	`_snprintf_s`	`_snprintf_s`	`_snwprintf_s`
`_sntprintf_s_l`	`_snprintf_s_l`	`_snprintf_s_l`	`_snwprintf_s_l`

Требования

Маршрут	Обязательный заголовок
`_snprintf_s`, `_snprintf_s_l`	`<stdio.h>`
`_snwprintf_s`, `_snwprintf_s_l`	`<stdio.h>` или `<wchar.h>`

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

Пример

// crt_snprintf_s.cpp
// compile with: /MTd

// These #defines enable secure template overloads
// (see last part of Examples() below)
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES 1
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT 1

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <crtdbg.h>  // For _CrtSetReportMode
#include <errno.h>

// This example uses a 10-byte destination buffer.

int snprintf_s_tester( const char * fmt, int x, size_t count )
{
   char dest[10];

   printf( "\n" );

   if ( count == _TRUNCATE )
      printf( "%zd-byte buffer; truncation semantics\n",
               _countof(dest) );
   else
      printf( "count = %zd; %zd-byte buffer\n",
               count, _countof(dest) );

   int ret = _snprintf_s( dest, _countof(dest), count, fmt, x );

   printf( "    new contents of dest: '%s'\n", dest );

   return ret;
}

void Examples()
{
   // formatted output string is 9 characters long: "<<<123>>>"
   snprintf_s_tester( "<<<%d>>>", 121, 8 );
   snprintf_s_tester( "<<<%d>>>", 121, 9 );
   snprintf_s_tester( "<<<%d>>>", 121, 10 );

   printf( "\nDestination buffer too small:\n" );

   snprintf_s_tester( "<<<%d>>>", 1221, 10 );

   printf( "\nTruncation examples:\n" );

   int ret = snprintf_s_tester( "<<<%d>>>", 1221, _TRUNCATE );
   printf( "    truncation %s occur\n", ret == -1 ? "did"
                                                  : "did not" );

   ret = snprintf_s_tester( "<<<%d>>>", 121, _TRUNCATE );
   printf( "    truncation %s occur\n", ret == -1 ? "did"
                                                  : "did not" );
   printf( "\nSecure template overload example:\n" );

   char dest[10];
   _snprintf( dest, 10, "<<<%d>>>", 12321 );
   // With secure template overloads enabled (see #defines
   // at top of file), the preceding line is replaced by
   //    _snprintf_s( dest, _countof(dest), 10, "<<<%d>>>", 12345 );
   // Instead of causing a buffer overrun, _snprintf_s invokes
   // the invalid parameter handler.
   // If secure template overloads were disabled, _snprintf would
   // write 10 characters and overrun the dest buffer.
   printf( "    new contents of dest: '%s'\n", dest );
}

void myInvalidParameterHandler(
   const wchar_t* expression,
   const wchar_t* function,
   const wchar_t* file,
   unsigned int line,
   uintptr_t pReserved)
{
   wprintf(L"Invalid parameter handler invoked: %s\n", expression);
}

int main( void )
{
   _invalid_parameter_handler oldHandler, newHandler;

   newHandler = myInvalidParameterHandler;
   oldHandler = _set_invalid_parameter_handler(newHandler);
   // Disable the message box for assertions.
   _CrtSetReportMode(_CRT_ASSERT, 0);

   Examples();
}


count = 8; 10-byte buffer
    new contents of dest: '<<<121>>'

count = 9; 10-byte buffer
    new contents of dest: '<<<121>>>'

count = 10; 10-byte buffer
    new contents of dest: '<<<121>>>'

Destination buffer too small:

count = 10; 10-byte buffer
Invalid parameter handler invoked: ("Buffer too small", 0)
    new contents of dest: ''

Truncation examples:

10-byte buffer; truncation semantics
    new contents of dest: '<<<1221>>'
    truncation did occur

10-byte buffer; truncation semantics
    new contents of dest: '<<<121>>>'
    truncation did not occur

Secure template overload example:
Invalid parameter handler invoked: ("Buffer too small", 0)
    new contents of dest: ''

См. также

Потоковый ввод-вывод
sprintf, , _sprintf_lswprintf, _swprintf_l__swprintf_l
fprintf, , _fprintf_lfwprintf_fwprintf_l
printf, , _printf_lwprintf_wprintf_l
scanf, , _scanf_lwscanf_wscanf_l
sscanf, , _sscanf_lswscanf_swscanf_l
Функции vprintf

Поделиться через

`_snprintf_s`, , `_snprintf_s_l_snwprintf_s_snwprintf_s_l`

Синтаксис

Параметры

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

Замечания

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

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

Требования

Пример

См. также

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

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

Поделиться через

_snprintf_s, , _snprintf_s_l_snwprintf_s_snwprintf_s_l

Синтаксис

Параметры

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

Замечания

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

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

Требования

Пример

См. также

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

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

`_snprintf_s`, , `_snprintf_s_l_snwprintf_s_snwprintf_s_l`