sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l

  • 發行項

將格式化資料寫入字串。 這些函式是 、 _sprintf_l 、 swprintf 、 _swprintf_l 的版本 sprintf ， __swprintf_l 具有 CRT 中安全性功能中所述 的安全性增強功能。

語法

int sprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   const char *format,
   ...
);
int _sprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   const char *format,
   _locale_t locale,
   ...
);
int swprintf_s(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   const wchar_t *format,
   ...
);
int _swprintf_s_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   const wchar_t *format,
   _locale_t locale,
   ...
);
template <size_t size>
int sprintf_s(
   char (&buffer)[size],
   const char *format,
   ...
); // C++ only
template <size_t size>
int swprintf_s(
   wchar_t (&buffer)[size],
   const wchar_t *format,
   ...
); // C++ only

參數

buffer
輸出的儲存位置

sizeOfBuffer
要儲存的最大字元數。

format
格式控制字串

...
要進行格式化的選擇性引數

locale
要使用的地區設定。

如需詳細資訊，請參閱 格式規格語法 。

傳回值

寫入的字元數，如果發生錯誤，則為 -1。 如果 buffer 或 format 為 null 指標、則 sprintf_s 和 swprintf_s 會傳回 -1，並將 errno 設定為 EINVAL。

sprintf_s 會傳回儲存在 buffer中的位元組數目，不計結束的 null 字元。 swprintf_s 會傳回儲存在 buffer 中的寬字元數目，不計結束的 null 寬字元。

備註

sprintf_s 函式會在 buffer 中格式化並儲存一連串字元和值。 每個 argument (如果有的話) 是根據 format中的對應格式規格進行轉換和輸出。 此格式包含一般字元，與 printf 的 format 引數具有相同的形式和功能。 null 字元會附加至最後一個寫入的字元之後。 如果在重疊的字串之間進行複製，則行為是未定義的。

sprintf_s 和 sprintf 之間有一個主要差異，即在於 sprintf_s 會檢查格式字串中的格式化字元是否有效，而 sprintf 只檢查格式字串或緩衝區是否為 NULL 指標。 如果任一檢查失敗，則會叫用不正確參數處理常式，如參數驗證 中所述 。 如果允許繼續執行，則函式會傳回 -1 並將 errno 設定為 EINVAL。

sprintf_s 和 sprintf 之間的另一個主要差異在於 sprintf_s 接受指定輸出緩衝區大小 (以字元為單位) 的長度參數。 若緩衝區對格式化文字而言太小 (包括結尾的 null)，就會藉由 null 字元放在 buffer[0]，將緩衝區設為空字串，並叫用無效的參數處理常式。 與 _snprintf不同的是， sprintf_s 保證緩衝區會以 null 結尾 (除非緩衝區大小為零)。

swprintf_s 是 sprintf_s的寬字元版本， swprintf_s 的指標引數是寬字元字串。 中的 swprintf_s 編碼錯誤偵測可能與 中的 sprintf_s 偵測不同。 這些有 _l 尾碼的函式版本是一樣的，不同之處在於會使用傳入的地區設定，而不使用目前的執行緒地區設定。

在 C++ 中，範本多載可簡化這些函式的使用。 多載可以自動推斷緩衝區長度，而不需要指定 size 引數。 而且，它們可以使用較新的、更安全的對應專案來自動取代較舊的非安全函式。 如需詳細資訊，請參閱 保護範本多載 。

有一些版本 sprintf_s 可更充分控制緩衝區太小時會發生什麼情況。 如需詳細資訊，請參閱 、 、 _snprintf_s_l_snwprintf_s_snwprintf_s_l 。 _snprintf_s

重要

從 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' 。

泛型文字常式對應

TCHAR.H 常式 _UNICODE 和 _MBCS 未定義 _MBCS 定義 _UNICODE 定義
_stprintf_s sprintf_s sprintf_s swprintf_s
_stprintf_s_l _sprintf_s_l _sprintf_s_l _swprintf_s_l

需求

常式 必要的標頭
sprintf_s, _sprintf_s_l C： < stdio.h>

C++： < cstdio > 或 < stdio.h>
swprintf_s, _swprintf_s_l C： < stdio.h > 或 < wchar.h>

C++： < cstdio > 、 < cwchar > 、 < stdio.h > 或 < wchar.h>

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

範例：使用sprintf_s格式化資料

// crt_sprintf_s.c
// This program uses sprintf_s to format various
// data and place them in the string named buffer.
//

#include <stdio.h>

int main( void )
{
   char  buffer[200], s[] = "computer", c = 'l';
   int   i = 35, j;
   float fp = 1.7320534f;

   // Format and print various data:
   j  = sprintf_s( buffer, 200,     "   String:    %s\n", s );
   j += sprintf_s( buffer + j, 200 - j, "   Character: %c\n", c );
   j += sprintf_s( buffer + j, 200 - j, "   Integer:   %d\n", i );
   j += sprintf_s( buffer + j, 200 - j, "   Real:      %f\n", fp );

   printf_s( "Output:\n%s\ncharacter count = %d\n", buffer, j );
}

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

character count = 79

範例：錯誤碼處理

// crt_swprintf_s.c
// wide character example
// also demonstrates swprintf_s returning error code
#include <stdio.h>

int main( void )
{
   wchar_t buf[100];
   int len = swprintf_s( buf, 100, L"%s", L"Hello world" );
   printf( "wrote %d characters\n", len );
   len = swprintf_s( buf, 100, L"%s", L"Hello\xffff world" );
   // swprintf_s fails because string contains WEOF (\xffff)
   printf( "wrote %d characters\n", len );
}

wrote 11 characters
wrote -1 characters

另請參閱

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