_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l

Статья
06/09/2015

Записывает форматированные данные в строку. Здесь представлены версии _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
Размер места хранения для выходных данных. Размер в bytes для _snprintf_s или размер в words для _snwprintf_s.
Count
Наибольшее число символов для хранения, или _TRUNCATE.
format
Строка управления форматом.
argument
Необязательные аргументы.
locale
Используемый языковой стандарт.

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

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

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

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

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

Заметки

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

Если count равно _TRUNCATE, тогда _snprintf_s записывает столько символов строки, сколько поместится в buffer, учитывая место для завершающего нуль-символа. Если вся строка (с завершающим нуль-символом) помещается в buffer, тогда _snprintf_s возвращает число записанных символов (не включая завершающий нуль-символ); в противном случае _snprintf_s возвращает -1 для указания того, что произошло усечение.

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

_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, int count )
{
   char dest[10];

   printf( "\n" );

   if ( count == _TRUNCATE )
      printf( "%d-byte buffer; truncation semantics\n",
               _countof(dest) );
   else
      printf( "count = %d; %d-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();
}