_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 中從 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 小於或等於零，無效參數處理常式將被叫用。如果允許繼續執行，這些函式會將 errno 設為 EINVAL，並傳回 -1。

如需有關這些錯誤碼和其他錯誤碼的詳細資訊，請參閱 _doserrno、errno、_sys_errlist 和 _sys_nerr。

備註

_snprintf_s 函式。 buffer 格式化並儲存 count 或更少字元並附加一個結尾的 NULL。每個引數(如果有的話) 是根據 format 中的對應格式規格進行轉換和輸出。格式化 printf 函式家族一致;請參閱格式規格語法：printf 和 wprintf 函式。如果在重疊的字串之間進行複製，則行為是未定義的。

如果 count 是 _TRUNCATE，則 _snprintf_s 寫入相同的多個字串與符合 buffer ，當離開的結尾的 NULL 時的空間。如果整個字串 (加上結尾 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 and _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>

如需更多關於相容性的資訊，請參閱入門介紹中的相容性 (Compatibility) 。

範例

// 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();
}