`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`

發行項
10/12/2023

將格式化資料寫入字串。這些函式有更安全的版本可供使用;請參閱、、 _snwprintf_s_snprintf_s_l 、 _snwprintf_s_l 。 _snprintf_s

語法

int snprintf(
   char *buffer,
   size_t count,
   const char *format [,
   argument] ...
);

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
要寫入的最大字元數。對於採用 wchar_t 的函式，這是要寫入的最大寬字元數。

format
格式控制字串。

argument
選擇性引數。

locale
用來格式化輸出的地區設定。

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

傳回值

如果 count 忽略，則會寫入緩衝區的字元數。計數不包含終止 NULL 字元。

讓我們 len 成為格式化資料字串的長度，不包括終止 NULL 的。
針對所有函式，如果 len < count 為，則會 len 將字元儲存在 buffer 中，則會附加 null 結束字元，而且會傳回寫入的字元數，不包括終止 NULL 的。

這些函式的寬字元版本會傳回寫入的寬字元數，不包括終止 NULL 的。

如需詳細資訊，請參閱行為摘要。

備註

自 Visual Studio 2015 及 Windows 10 的 UCRT 起， snprintf 即不再等同於 _snprintf。行為 snprintf 現在是 C99 標準一致性。差別在於，如果您用完緩衝區， snprintf Null 會終止緩衝區的結尾，並傳回所需的字元數，而 _snprintf 不會以 Null 結束緩衝區並傳回 -1。此外， snprintf() 在輸出中再包含一個字元，因為它不會以 Null 結束緩衝區。

snprintf和函 _snprintf 式系列會格式化和儲存 count 或較少的字元。 buffer
snprintf 一律會儲存終止 NULL 字元，並視需要截斷輸出。
如果 snprintf 傳回值 >count - 1，則輸出已經截斷。
如果格式化字串長度嚴格小於 count 字元，則函 _snprintf 式系列只會附加終止 NULL 字元。
每個 argument (如果有) 皆根據 format中的對應格式規格進行轉換和輸出。此格式包含一般字元，與 printf 的 format 引數具有相同的形式和功能。如果在重疊的字串之間進行複製，則行為是未定義的。

行為摘要

下表：

讓 sizeOfBuffer 做為的大小 buffer 。如果函式接受 char 緩衝區，大小會以位元組為單位。如果函式接受 wchar_t 緩衝區，大小會指定 16 位單字的數目。
讓我們 len 成為格式化資料的大小。如果函式接受 char 緩衝區，大小會以位元組為單位。如果函式接受 wchar_t 緩衝區，大小會指定 16 位單字的數目。
字元是指 char 採用 char 緩衝區的函式字元，以及 wchar_t 採用 wchar_t 緩衝區之函式的字元。
如需無效參數處理常式的詳細資訊，請參閱參數驗證。

Condition	行為	傳回值	`errno`	叫用無效的參數處理常式
成功	使用指定的格式字串，將字元寫入緩衝區。	寫入的字元數。	N/A	No
格式設定期間的編碼錯誤	如果處理字串規範 `s` 、 `S` 或 `Z` 格式規格處理停止， `NULL` 則會將放在緩衝區的開頭。	-1	`EILSEQ` (42)	No
格式設定期間的編碼錯誤	如果處理字元規範 `c` 或 `C` ，則會略過不正確字元。寫入的字元數目不會針對略過的字元遞增，也不會為它寫入任何資料。在略過規範並出現編碼錯誤之後，處理格式規格會繼續進行。	寫入的字元數，不包括終止 `NULL` 的。	`EILSEQ` (42)	No
`buffer == NULL` 和 `count != 0`	如果在不正確參數處理常式執行之後繼續執行，請設定 `errno` 並傳回負值。	-1	`EINVAL` (22)	Yes
`count == 0`	已寫入的字元數，不包括終止 `NULL` 的。您可以使用此結果，為字串和終止 `NULL` 配置足夠的緩衝區空間，然後再次呼叫函式以填滿緩衝區。	N/A	No
`count < 0`	Unsafe：此值會被視為不帶正負號，因此可能會建立大型值，以覆寫緩衝區後面的記憶體。	寫入的字元數	N/A	No
`count < sizeOfBuffer` 和 `len <= count`	所有資料都會寫入，並附加終止 `NULL` 。	寫入的字元數，不包括終止 `NULL` 的。	N/A	No
`count < sizeOfBuffer` 和 `len > count`	第一 `count-1` 個字元的寫入後面接著 Null 結束字元。	已寫入的字元數已 `count` 符合輸出的字元數，不包括 Null 結束字元。	N/A	No
`count >= sizeOfBuffer` 和 `len < sizeOfBuffer`	所有資料都會以終止 `NULL` 來寫入。	寫入的字元數，不包括終止 `NULL` 的。	N/A	No
`count >= sizeOfBuffer` 和 `len >= sizeOfBuffer`	Unsafe：覆寫緩衝區後面的記憶體。	寫入的字元數，不包括終止 `NULL` 的。	N/A	No
`format == NULL`	未寫入任何資料。如果在不正確參數處理常式執行之後繼續執行，請設定 `errno` 並傳回負值。	-1	`EINVAL` (22)	Yes

如需這些錯誤碼和其他錯誤碼的相關資訊，請參閱 _doserrno 、 errno_sys_errlist 和 _sys_nerr 。

重要

確認 format 不是使用者定義的字串。因為函式 _snprintf 不保證 Null 終止，特別是當傳回值是 count 時，請確定它們後面接著加入 Null 結束字元的程式碼。如需詳細資訊，請參閱避免緩衝區滿溢。

從 Windows 10 版本 2004（組建 19041）開始，函 printf 式系列會根據 IEEE 754 規則來列印完全可代表的浮點數以進行四捨五入。在舊版的 Windows 中，完全代表以 '5' 結尾的浮點數一律會四捨五入。 IEEE 754 指出，他們必須四捨五入到最接近的偶數數位（也稱為「銀行家的四捨五入」）。例如， printf("%1.0f", 1.5) 和應該 printf("%1.0f", 2.5) 四捨五入為 2。先前，1.5 會四捨五入為 2，而 2.5 會四捨五入為 3。這項變更只會影響確切可表示的數位。例如，2.35 （在記憶體中表示時，其接近 2.3500000000000000008）會繼續四捨五入至 2.4。這些函式完成的四捨五入現在也會遵守所 fesetround 設定的浮點舍入模式。之前，舍入一律選擇 FE_TONEAREST 行為。這項變更只會影響使用 Visual Studio 2019 16.2 版和更新版本所建置的程式。若要使用舊版浮點舍入行為，請與 legacy_stdio_float_rounding.obj 連結。

_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`, `_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 null! */
   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 null because _snprintf doesn't necessarily (if the string
       * fits without the terminal null, 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;
}

Output:
   String: computer
   Character: l
   Integer: 35
   Real: 1.732053

character count = 69

另請參閱

資料流 I/O
sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l
fprintf, _fprintf_l, fwprintf, _fwprintf_l
printf, _printf_l, wprintf, _wprintf_l
scanf, _scanf_l, wscanf, _wscanf_l
sscanf, _sscanf_l, swscanf, _swscanf_l
vprintf 函數

`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`

語法

參數

傳回值

備註

行為摘要

泛型文字常式對應

需求

範例

另請參閱

意見反應

意見反應

其他資源

snprintf, _snprintf, _snprintf_l, _snwprintf, _snwprintf_l

語法

參數

傳回值

備註

行為摘要

泛型文字常式對應

需求

範例

另請參閱

意見反應

意見反應

其他資源

`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`