SymInitializeW 函式（dbghelp.h）

發行項
11/20/2024

初始化進程的符號處理程式。

語法

BOOL IMAGEAPI SymInitializeW(
  [in]           HANDLE hProcess,
  [in, optional] PCWSTR UserSearchPath,
  [in]           BOOL   fInvadeProcess
);

參數

[in] hProcess

識別呼叫端的句柄。此值應該是唯一和非零值，但不需要是進程句柄。不過，如果您使用進程句柄，請務必使用正確的句柄。如果應用程式是調試程式，請使用正在偵錯之進程的進程句柄。偵錯另一個進程時，請勿使用由 getCurrentProcess 傳回的句柄，因為呼叫 SymLoadModuleEx 等函式可能會產生非預期的結果。

這個參數不能 NULL。

[in, optional] UserSearchPath

路徑或以分號分隔的路徑系列（;)，用來搜尋符號檔。如果此參數 NULL，連結庫會嘗試從下列來源形成符號路徑：

應用程式的目前工作目錄
_NT_SYMBOL_PATH環境變數
_NT_ALTERNATE_SYMBOL_PATH環境變數

請注意，您也可以使用 SymSetSearchPath 函式來設定搜尋路徑。

[in] fInvadeProcess

如果此值 TRUE，請列舉進程的載入模組，並有效地為每個模組呼叫 SymLoadModule64 函式。

傳回值

如果函式成功，則傳回值 TRUE。

如果函式失敗，則傳回值 FALSE。若要擷取擴充的錯誤資訊，請呼叫 GetLastError。

言論

SymInitialize 函式可用來初始化進程的符號處理程式。在符號處理程式的內容中，程式是收集符號資訊時要使用的便利物件。通常，調試程式和其他工具會使用符號處理程式，這些工具需要載入要偵錯的進程符號。

傳遞至 SymInitialize 的句柄必須是傳遞至進程所呼叫之所有其他符號處理程式函式的相同值。函式用來識別呼叫端並找出正確符號資訊的句柄。當您使用符號資訊完成時，請呼叫 SymCleanup 函式，以解除分配與載入符號之進程相關聯的所有資源。

搜尋符號檔案會以遞歸方式針對 UserSearchPath 參數中指定的所有路徑執行。因此，如果您在搜尋中指定根目錄，則會搜尋整個磁碟驅動器，這可能需要相當長的時間。請注意，包含進程可執行文件的目錄不會自動屬於搜尋路徑的一部分。若要在搜尋路徑中包含此目錄，請呼叫 GetModuleFileNameEx 函式，然後將傳回的路徑新增至 UserSearchPath。

呼叫 symInitialize 的程式，除非先呼叫 symCleanup ，否則不應該再次呼叫它。如果呼叫 SymInitializefInvadeProcess 設定為 TRUE，而您只需要重載模組清單，請使用 SymRefreshModuleList 函式。

所有 DbgHelp 函式，例如此函式，都是單個線程。因此，從一個以上的線程呼叫此函式可能會導致非預期的行為或記憶體損毀。若要避免這種情況，請只在進程啟動時呼叫 SymInitialize，只有當進程結束時，才會 SymCleanup。進程中的每個線程都不需要呼叫這些函式。

若要呼叫此函式的 Unicode 版本，請定義DBGHELP_TRANSLATE_TCHAR。