SymLoadModule 函式 (dbghelp.h)

發行項
08/23/2023

載入符號表。

SymLoadModuleEx函式已取代此函式。

語法

DWORD IMAGEAPI SymLoadModule(
  [in]           HANDLE hProcess,
  [in, optional] HANDLE hFile,
  [in, optional] PCSTR  ImageName,
  [in, optional] PCSTR  ModuleName,
  [in]           DWORD  BaseOfDll,
  [in]           DWORD  SizeOfDll
);

參數

[in] hProcess

進程的控制碼。此控制碼之前必須傳遞至 SymInitialize 函式。

[in, optional] hFile

可執行檔映射之檔案的控制碼。這個引數主要是由偵錯工具使用，其中偵錯工具會傳遞從偵錯事件取得的檔案控制碼。 Null的值表示未使用hFile。

[in, optional] ImageName

可執行檔映射的名稱。此名稱可以包含部分路徑、完整路徑或完全沒有路徑。如果檔案無法依提供的名稱找到，則會使用符號搜尋路徑。

[in, optional] ModuleName

模組的快捷方式名稱。如果指標值為 Null，程式庫會使用符號檔的基底名稱來建立名稱。

[in] BaseOfDll

模組的載入位址。如果值為零，程式庫會從符號檔取得載入位址。符號檔中包含的載入位址不一定是實際的載入位址。呼叫此函式時，具有實際負載位址的偵錯工具和其他應用程式應該使用實際的負載位址。

如果映射是 .pdb 檔案，則此參數不可為零。

[in] SizeOfDll

模組的大小，以位元組為單位。如果值為零，程式庫會從符號檔取得大小。符號檔中包含的大小不一定是實際的大小。呼叫此函式時，具有實際大小的偵錯工具和其他應用程式應該使用實際大小。

如果映射是 .pdb 檔案，則此參數不可為零。

傳回值

如果函式成功，傳回值就是載入模組的基底位址。

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

如果模組已經載入，則傳回值為零，而 GetLastError 會 傳回ERROR_SUCCESS。

備註

符號處理常式會建立模組的專案，如果關閉延後符號載入選項，則會嘗試載入符號。如果已啟用延後符號載入，模組會標示為延後，而且在對模組中的符號進行參考之前，不會載入符號。

若要卸載符號表，請使用 SymUnloadModule64 函式。

所有 DbgHelp 函式，例如此函式都是單一執行緒。因此，從一個以上的執行緒呼叫此函式可能會導致非預期的行為或記憶體損毀。若要避免這種情況，您必須將所有並行呼叫從一個以上的執行緒同步至此函式。

此函式會取代 SymLoadModule 函式。如需詳細資訊，請參閱更新的平臺支援。 SymLoadModule 在 DbgHelp.h 中定義如下。

#if !defined(_IMAGEHLP_SOURCE_) && defined(_IMAGEHLP64)
#define SymLoadModule SymLoadModule64
#else
DWORD
IMAGEAPI
SymLoadModule(
    __in HANDLE hProcess,
    __in_opt HANDLE hFile,
    __in_opt PCSTR ImageName,
    __in_opt PCSTR ModuleName,
    __in DWORD BaseOfDll,
    __in DWORD SizeOfDll
    );
#endif