_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
输出存储位置的范围。 words 中的 bytes 的大小或 _snwprintf_s 中的 _snprintf_s 的大小。
Count
可存储的最多字符数，或 _TRUNCATE。
format
窗体控件字符串。
argument
可选参数。
locale
要使用的区域设置。

返回值

_snprintf_s 返回存储在 buffer 中的字符，不包括终止 null 字符。 _snwprintf_s 返回存储在 buffer 中的宽字符数，不包括中止 null 宽字符。

如果需要存储的数据存储和终止 null，超过 sizeOfBuffer的参数无效处理程序，如参数验证所述。如果对无效参数处理程序后继续执行，则这些功能将buffer 设置为空字符串，将 errno 设置为 ERANGE，并返回 -1。

如果 buffer 或 format 是 NULL 指针，或者如果 count 小于或等于零，则调用无效参数处理程序。如果允许执行继续，则这些功能将 EINVAL 设置为 errno 并返回 -1。

有关这些内容以及其他错误代码的详细信息，请参阅 _doserrno、errno、_sys_errlist 和 _sys_nerr。

备注

_snprintf_s 函数格式和存储 count 或 buffer 并追加一个字符终止符 null。每个参数（如果有）根据 format 中相应的格式规范进行转换和输出。格式的函数系列的 printf 一致；参见格式规范语法：printf 和 wprintf 函数。如果在重叠的字符串之间发生复制，则此行为不确定。

如果 count 为 _TRUNCATE，则 _snprintf_s 编写尽可能多字符串适合 buffer，当退出终止 null 时空间。如果整个字符串 (与终止空) 符合 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();
}