`snprintf`、、 `_snprintf`、 `_snprintf_l`、 `_snwprintf`、 `_snwprintf_l`

發行項
08/03/2024

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

語法

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 終止符的程式代碼。如需詳細資訊，請參閱 Avoiding Buffer Overruns (避免緩衝區滿溢)。

從 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.35000000000000008) 會繼續四捨五入至 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`