_snprintf_s， _snprintf_s_l， _snwprintf_s， _snwprintf_s_l

项目
02/21/2013

向字符串写入设置数据格式。这些是 _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 中 words 的大小 _snprintf_s 的或范围 _snwprintf_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 函数在 buffer 设置格式并存储 count 或少量字符并追加终止 null。每个参数 (如果有) 基于在 format相应的格式规范转换和输出。格式与函数 printf 系列一致的; 格式规范语法：printf 和 wprintf 函数参见。如果复制出现在重叠的字符串之间，该行为不确定。

如果 count 是 _TRUNCATE，则 _snprintf_s 编写尽可能多地字符串与将适合 buffer ，当出终止 null 时空间。如果整个字符串 (与终止空) 适合 buffer， _snprintf_s 然后返回编写的字符数 (不包括终止 null);否则， _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();
}