SymInitialize 函式 (dbghelp.h)

發行項
03/11/2023

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

語法

BOOL IMAGEAPI SymInitialize(
  [in]           HANDLE hProcess,
  [in, optional] PCSTR  UserSearchPath,
  [in]           BOOL   fInvadeProcess
);

參數

[in] hProcess

識別呼叫端的控制碼。此值應該是唯一且非零的，但不需要是進程控制碼。不過，如果您使用進程控制碼，請務必使用正確的控制碼。如果應用程式是偵錯工具，請使用正在偵錯之進程的進程控制碼。請勿使用 GetCurrentProcess傳回的控制碼。使用的控制碼必須是唯一的，以避免與其他元件共用會話，而且當多個元件嘗試使用 dbghelp 檢查目前的進程時，使用 GetCurrentProcess 可能會有非預期的結果。偵錯另一個進程時，使用 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。

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

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

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