_snprintf_s、 _snprintf_s_l、 _snwprintf_s、 _snwprintf_s_l

發行項
02/28/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
輸出的儲存位置大小。 Size in bytes for _snprintf_s or size in words for _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函式的格式與儲存區count或更少的字元buffer ，並將結尾的 null。每個引數 (如果有的話) 是轉換並輸出傳送至對應的格式規格，以根據format。格式是一致的printf系列的函式。 see 格式規格語法：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++ 中，使用這些函式已經過簡化的樣板的多載；多載可以自動推斷緩衝區長度 (而不必指定 size 引數)，它們可以自動取代較舊的、不安全的函式與其較新的、安全的對應項目。如需詳細資訊，請參閱安全範本多載。

泛用文字常式對應

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