Strsafe.h 完全指南：Windows 平台更安全的 C 字串處理 API

編輯：關於C語言

背景：傳統 CRT 字串函式的缺陷

緩衝區溢位：strcpy/strcat/sprintf 不檢查目的緩衝區大小。
截斷無通知：strncpy/strncat 截斷時不保證以 NULL 結尾，且不回報是否發生截斷。
返回值不一致：有的回傳目的指標，有的回傳字元數，有的回傳錯誤碼，易誤用。
參數語意混淆：strncat(dest, src, n) 的 n 是「最大附加字元數」而非「目的緩衝區剩餘空間」。

Strsafe.h 設計目標

所有函式強制要求目的緩衝區大小（字元數）作為參數。
保證結果以 NULL 結尾（除非緩衝區大小為 0）。
統一回傳 HRESULT，SUCCEEDED(hr)/FAILED(hr) 判斷成敗。
支援 32/64 位元、Unicode/ANSI 同源碼（TCHAR 模型）。
提供 Ex 版本取得剩餘空間、當前指標、失敗時填充模式等進階資訊。

快速上手

#include <strsafe.h>
// 連結庫：strsafe.lib（Visual Studio 專案屬性 → Linker → Input → Additional Dependencies）
// 或僅包含頭文件（函式為 inline/靜態庫自動解析）

核心 API 對照表

傳統 CRT	Strsafe 替代	關鍵差異
`strcpy(dst, src)`	`StringCchCopy(dst, cchDst, src)`	檢查 `cchDst`，保證 NULL 結尾
`strncpy(dst, src, n)`	`StringCchCopyN(dst, cchDst, src, cchSrc)`	明確指定來源字元數 `cchSrc`
`strcat(dst, src)`	`StringCchCat(dst, cchDst, src)`	自動計算剩餘空間
`strncat(dst, src, n)`	`StringCchCatN(dst, cchDst, src, cchSrc)`	同左
`sprintf(buf, fmt, ...)`	`StringCchPrintf(buf, cchBuf, fmt, ...)`	格式化並檢查長度
`vsprintf`	`StringCchVPrintf`	va_list 版本
`strlen`	`StringCchLength(str, cchMax, &len)`	限制最大掃描長度，避免掃描未結尾字串

實戰對比：不安全 vs 安全

不安全版本（隱含 Bug）

void UnsafeFunc(LPTSTR szPath, DWORD cchPath) {
    TCHAR szCWD[MAX_PATH];
    GetCurrentDirectory(ARRAYSIZE(szCWD), szCWD);  // 未檢查返回值
    strncpy(szPath, szCWD, cchPath);               // 可能不以 NULL 結尾
    strncat(szPath, TEXT("\\"), cchPath);          // cchPath 語意錯誤：應傳剩餘空間
    strncat(szPath, TEXT("desktop.ini"), cchPath); // 同左
}

安全版本（Strsafe）

bool SaferFunc(LPTSTR szPath, DWORD cchPath) {
    TCHAR szCWD[MAX_PATH];
    return GetCurrentDirectory(ARRAYSIZE(szCWD), szCWD) &&
           SUCCEEDED(StringCchCopy(szPath, cchPath, szCWD)) &&
           SUCCEEDED(StringCchCat(szPath, cchPath, TEXT("\\"))) &&
           SUCCEEDED(StringCchCat(szPath, cchPath, TEXT("desktop.ini")));
}

每一步皆檢查 HRESULT，任一失敗即短路返回 false，目的緩衝區始終保持有效狀態。

Ex 版本進階功能

HRESULT StringCchCopyEx(
    LPTSTR  pszDest,
    size_t  cchDest,
    LPCTSTR pszSrc,
    LPTSTR  *ppszDestEnd,     // 輸出：複製後字串結尾指標
    size_t  *pcchRemaining,   // 輸出：剩餘字元數（含 NULL）
    DWORD   dwFlags           // 行為旗標
);

常用旗標

STRSAFE_FILL_BEHIND_NULL：複製後以指定字元填充剩餘空間（預設 0）。
STRSAFE_IGNORE_NULLS：視 NULL 為普通字元繼續複製（罕用）。
STRSAFE_FILL_ON_FAILURE：失敗時以指定字元填充整個緩衝區。
STRSAFE_NULL_ON_FAILURE：失敗時將緩衝區設為空字串（pszDest[0]=0）。
STRSAFE_NO_TRUNCATION：視截斷為失敗（回傳 STRSAFE_E_INSUFFICIENT_BUFFER）。

效能實測（1.8 GHz，1000 萬次迴圈）

版本	耗時	相對基準
傳統 CRT (`strcpy/strcat`)	7.3 秒	1.00x
Strsafe 標準版	8.3 秒	1.14x
Strsafe Ex 版（含填充 0xFE）	11.1 秒	1.52x
Strsafe Ex 版（僅 NULL_ON_FAILURE）	8.3 秒	1.14x

結論：標準版效能損失 <15%，完全可接受；Ex 版填充操作較費時，按需啟用。

自動取代機制

包含 strsafe.h 後，編譯器會 #undef 傳統字串函式（strcpy 等），若舊碼仍呼叫會產生編譯錯誤，強制遷移。若需保留舊函式，可在包含前定義 STRSAFE_NO_DEPRECATE。

最佳實踐清單

專案層級強制 #include <strsafe.h>（預編譯頭或強制包含）。
啟用 /DSTRSAFE_NO_DEPRECATE=0 確保舊 API 被禁用。
所有字串操作統一用 StringCchCopy/Cat/Printf 族。
傳遞緩衝區大小以 字元數（而非位元組數），Unicode 版 sizeof(buf)/sizeof(TCHAR)。
檢查每個 HRESULT，失敗路徑記錄日誌並安全降級。
需額外資訊（剩餘空間、結尾指標）時改用 Ex 版。

跨平台替代方案

平台	推薦庫/函式	特色
Linux/Unix	`strlcpy/strlcat` (BSD)	保證 NULL 結尾，回傳來源長度
C11 Annex K	`strcpy_s/strcat_s/sprintf_s`	標準化 bounds-checking 介面
C++	`std::string`, `std::format` (C++20)	RAII、型別安全、無緩衝區管理負擔
Glib	`g_strlcpy/g_strlcat/g_strdup_printf`	GLib 生態通用