SymLoadModuleEx-Funktion (dbghelp.h)

Artikel
02/26/2024

Lädt die Symboltabelle für das angegebene Modul.

Syntax

DWORD64 IMAGEAPI SymLoadModuleEx(
  [in] HANDLE        hProcess,
  [in] HANDLE        hFile,
  [in] PCSTR         ImageName,
  [in] PCSTR         ModuleName,
  [in] DWORD64       BaseOfDll,
  [in] DWORD         DllSize,
  [in] PMODLOAD_DATA Data,
  [in] DWORD         Flags
);

Parameter

[in] hProcess

Ein Handle für den Prozess, der ursprünglich an die SymInitialize-Funktion übergeben wurde.

[in] hFile

Ein Handle für die Datei für das ausführbare Image. Dieses Argument wird hauptsächlich von Debuggern verwendet, bei denen der Debugger das Dateihandle übergibt, das aus einem Debugereignis abgerufen wurde. Der Wert NULL gibt an, dass hFile nicht verwendet wird.

[in] ImageName

Der Name des ausführbaren Images. Dieser Name kann einen partiellen Pfad, einen vollständigen Pfad oder überhaupt keinen Pfad enthalten. Wenn die Datei nicht mit dem angegebenen Namen gefunden werden kann, wird der Symbolsuchpfad verwendet.

[in] ModuleName

Ein Tastenkombinationsname für das Modul. Wenn der Zeigerwert NULL ist, erstellt die Bibliothek einen Namen unter Verwendung des Basisnamens der Symboldatei.

[in] BaseOfDll

Die Ladeadresse des Moduls. Wenn der Wert 0 ist, ruft die Bibliothek die Ladeadresse aus der Symboldatei ab. Die in der Symboldatei enthaltene Ladeadresse ist nicht unbedingt die tatsächliche Ladeadresse. Debugger und andere Anwendungen mit einer tatsächlichen Ladeadresse sollten beim Aufrufen dieser Funktion die tatsächliche Ladeadresse verwenden.

Wenn es sich bei dem Bild um eine PDB-Datei handelt, darf dieser Parameter nicht 0 sein.

[in] DllSize

Die Größe des Moduls in Bytes. Wenn der Wert 0 ist, ruft die Bibliothek die Größe aus der Symboldatei ab. Die in der Symboldatei enthaltene Größe entspricht nicht unbedingt der tatsächlichen Größe. Debugger und andere Anwendungen mit einer tatsächlichen Größe sollten beim Aufrufen dieser Funktion die reale Größe verwenden.

Wenn es sich bei dem Bild um eine PDB-Datei handelt, darf dieser Parameter nicht 0 sein.

[in] Data

Ein Zeiger auf eine MODLOAD_DATA-Struktur , die andere Header als den PE-Standardheader darstellt. Dieser Parameter ist optional und kann NULL sein.

[in] Flags

Dieser Parameter kann null oder mindestens einer der folgenden Werte sein. Wenn dieser Parameter 0 ist, lädt die Funktion die Module und die Symbole für das Modul.

Wert	Bedeutung
SLMFLAG_NO_SYMBOLS 0x4	Lädt das Modul, aber nicht die Symbole für das Modul.
SLMFLAG_VIRTUAL 0x1	Erstellt ein virtuelles Modul mit dem Namen ModuleName an der adresse, die in BaseOfDll angegeben ist. Um diesem Modul Symbole hinzuzufügen, rufen Sie die SymAddSymbol-Funktion auf.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Basisadresse des geladenen Moduls.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen abzurufen.

Wenn das Modul bereits geladen ist, ist der Rückgabewert 0, und GetLastError gibt ERROR_SUCCESS zurück.

Hinweise

Der Symbolhandler erstellt einen Eintrag für das Modul, und wenn die Option zum verzögerten Laden von Symbolen deaktiviert ist, wird versucht, die Symbole zu laden. Wenn das verzögerte Laden von Symbolen aktiviert ist, wird das Modul als verzögert markiert, und die Symbole werden erst geladen, wenn ein Verweis auf ein Symbol im Modul erfolgt. Daher sollten Sie immer die SymGetModuleInfo64-Funktion aufrufen, nachdem Sie SymLoadModuleEx aufgerufen haben.

Verwenden Sie zum Entladen der Symboltabelle die Funktion SymUnloadModule64 .

Alle DbgHelp-Funktionen, z. B. diese, sind single threaded. Daher führen an diese Funktion gerichtete Aufrufe mehrerer Threads wahrscheinlich zu unerwartetem Verhalten oder einer Beschädigung des Speichers. Um dies zu vermeiden, müssen Sie alle an diese Funktion gerichteten gleichzeitigen Aufrufe mehrerer Threads synchronisieren.

Um die Unicode-Version dieser Funktion aufzurufen, definieren Sie DBGHELP_TRANSLATE_TCHAR.