_snprintf、_snprintf_l、_snwprintf、_snwprintf_l

發行項
06/09/2015

將格式化資料寫入字串。這些函式已有更安全的版本可用，請參閱 _snprintf_s、_snprintf_s_l、_snwprintf_s、_snwprintf_s_l。

int _snprintf(
   char *buffer,
   size_t count,
   const char *format [,
   argument] ... 
);
int _snprintf_l(
   char *buffer,
   size_t count,
   const char *format,
   locale_t locale [,
   argument] ... 
);
int _snwprintf(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format [,
   argument] ... 
);
int _snwprintf_l(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format,
   locale_t locale [,
   argument] ... 
);
template <size_t size>
int _snprintf(
   char (&buffer)[size],
   size_t count,
   const char *format [,
   argument] ... 
); // C++ only
template <size_t size>
int _snprintf_l(
   char (&buffer)[size],
   size_t count,
   const char *format,
   locale_t locale [,
   argument] ... 
); // C++ only
template <size_t size>
int _snwprintf(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format [,
   argument] ... 
); // C++ only
template <size_t size>
int _snwprintf_l(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   locale_t locale [,
   argument] ... 
); // C++ only

參數

buffer
輸出的儲存位置。
count
要儲存的最大字元數。
format
格式控制字串。
argument
選擇性引數。
locale
要使用的地區設定。

如需詳細資訊，請參閱格式規格語法：printf 和 wprintf 函式。

傳回值

使 len 成為格式化資料字串的長度，不含結束的 null。 len 和 count 對 _snprintf 以位元組為單位，對 _snwprintf 則為寬字元。

如果 len < count，len 字元會儲存於 buffer 中，並會附加 null 結束字元，傳回 len。

如果 len = count，則len 字元會儲存於 buffer 中，不會附加 null 結束字元，並且傳回 len。

如果 len > count，count 字元會儲存於 buffer 中，不會附加 null 結束字元，並且傳回負值。

如果 buffer 為 null 指標，而 count 為零，則會傳回 len 作為格式化輸出所需字元數 (不含結束 null) 計數。若要使用相同的 argument 和 locale 參數成功呼叫，請至少配置保存 len + 1 個字元的緩衝區。

如果 buffer 為 null 指標，而 count 為非零，或者 format 為 null 指標，則叫用的參數處理常式無效，如參數驗證中所述。如果允許繼續執行，這些函式會傳回 -1，並將 errno 設為 EINVAL。

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

備註

如果格式化的字串長度少於 count 個字元，則 _snprintf 函式會在 buffer 中格式化並儲存 count 或更少的字元數，並且會附加結束 null 字元。每個 argument (如果有) 皆根據 format 中的對應格式規格進行轉換和輸出。此格式包含一般字元，與 printf 的 format 引數具有相同的形式和功能。如果在重疊的字串之間進行複製，則行為是未定義的。

安全性提示
確認 format 不是使用者定義的字串。由於此函式並不保證 NULL 結束，尤其是當傳回值為 count 時，請務必在後方附上加入 null 結束字元的程式碼。如需詳細資訊，請參閱避免緩衝區滿溢。

_snwprintf 是 _snprintf 的寬字元版本，_snwprintf 的指標引數是寬字元字串。 _snwprintf 中的編碼錯誤偵測可能不同於 _snprintf。 _snwprintf 與 swprintf 類似，會將輸出寫入輸出字串，而不是 FILE 類型的目的地。

這些有 _l 尾碼的函式版本都相同，不同之處在於會使用傳入的地區設定參數，而不使用目前的執行緒地區設定。

在 C++ 中，這些函式具有多載樣板，可以叫用更新、更安全的相對版本。如需詳細資訊，請參閱安全範本多載。

一般文字常式對應

Tchar.h 常式	未定義 _UNICODE 和 _MBCS	_MBCS 已定義	_UNICODE 已定義
_sntprintf	_snprintf	_snprintf	_snwprintf
_sntprintf_l	_snprintf_l	_snprintf_l	_snwprintf_l

需求

常式	必要的標頭
_snprintf, _snprintf_l	<stdio.h>
_snwprintf, _snwprintf_l	<stdio.h> 或 <wchar.h>

如需詳細的相容性資訊，請參閱相容性。

範例

// crt_snprintf.c
// compile with: /W3
#include <stdio.h>
#include <stdlib.h>

#if !defined(__cplusplus)
typedef int bool;
const bool true = 1;
const bool false = 0;
#endif

#define FAIL 0 // change to 1 and see what happens

int main(void)
{
   char buffer[200];
   const static char s[] = "computer"
#if FAIL
"computercomputercomputercomputercomputercomputercomputercomputer"
"computercomputercomputercomputercomputercomputercomputercomputer"
"computercomputercomputercomputercomputercomputercomputercomputer"
"computercomputercomputercomputercomputercomputercomputercomputer"
#endif
   ;
   const char c = 'l'; 
   const int i = 35;
#if FAIL
   const double fp = 1e300; // doesn't fit in the buffer
#else
   const double fp = 1.7320534;
#endif
   /* !subtract one to prevent "squeezing out" the terminal nul! */
   const int bufferSize = sizeof(buffer)/sizeof(buffer[0]) - 1;
   int bufferUsed = 0;
   int bufferLeft = bufferSize - bufferUsed;
   bool bSuccess = true;
   buffer[0] = 0;

   /* Format and print various data: */

   if (bufferLeft > 0)
   {
      int perElementBufferUsed = _snprintf(&buffer[bufferUsed], 
      bufferLeft, "   String: %s\n", s ); // C4996
      // Note: _snprintf is deprecated; consider _snprintf_s instead
      if (bSuccess = (perElementBufferUsed >= 0))
      {
         bufferUsed += perElementBufferUsed;
         bufferLeft -= perElementBufferUsed;
         if (bufferLeft > 0)
         {
            int perElementBufferUsed = _snprintf(&buffer[bufferUsed], 
            bufferLeft, "   Character: %c\n", c ); // C4996
            if (bSuccess = (perElementBufferUsed >= 0))
            {
               bufferUsed += perElementBufferUsed;
               bufferLeft -= perElementBufferUsed;
               if (bufferLeft > 0)
               {
                  int perElementBufferUsed = _snprintf(&buffer
                  [bufferUsed], bufferLeft, "   Integer: %d\n", i ); // C4996
                  if (bSuccess = (perElementBufferUsed >= 0))
                  {
                     bufferUsed += perElementBufferUsed;
                     bufferLeft -= perElementBufferUsed;
                     if (bufferLeft > 0)
                     {
                        int perElementBufferUsed = _snprintf(&buffer
                        [bufferUsed], bufferLeft, "   Real: %f\n", fp ); // C4996
                        if (bSuccess = (perElementBufferUsed >= 0))
                        {
                           bufferUsed += perElementBufferUsed;
                        }
                     }
                  }
               }
            }
         }
      }
   }

   if (!bSuccess)
   {
      printf("%s\n", "failure");
   }
   else
   {
      /* !store nul because _snprintf doesn't necessarily (if the string 
       * fits without the terminal nul, but not with it)!
       * bufferUsed might be as large as bufferSize, which normally is 
       * like going one element beyond a buffer, but in this case 
       * subtracted one from bufferSize, so we're ok.
       */
      buffer[bufferUsed] = 0;
      printf( "Output:\n%s\ncharacter count = %d\n", buffer, bufferUsed );
   }
   return EXIT_SUCCESS;
}