SymInitialize-Funktion (dbghelp.h)

Artikel
08/23/2023

Initialisiert den Symbolhandler für einen Prozess.

Syntax

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

Parameter

[in] hProcess

Ein Handle, das den Aufrufer identifiziert. Dieser Wert sollte eindeutig und nichtzero sein, muss aber kein Prozesshandle sein. Wenn Sie jedoch ein Prozesshandle verwenden, achten Sie darauf, das richtige Handle zu verwenden. Wenn es sich bei der Anwendung um einen Debugger handelt, verwenden Sie das Prozesshandle für den zu debuggenden Prozess. Verwenden Sie nicht das von GetCurrentProcess zurückgegebene Handle. Das verwendete Handle muss eindeutig sein, um die Freigabe einer Sitzung mit einer anderen Komponente zu vermeiden. Die Verwendung von GetCurrentProcess kann unerwartete Ergebnisse haben, wenn mehrere Komponenten versuchen, dbghelp zum Überprüfen des aktuellen Prozesses zu verwenden. Die Verwendung von GetCurrentProcess beim Debuggen eines anderen Prozesses führt auch zu unerwarteten Ergebnissen bei Funktionen wie SymLoadModuleEx .

Dieser Parameter darf nicht NULL sein.

[in, optional] UserSearchPath

Der Pfad oder die Reihe von Pfaden, die durch ein Semikolon (;) getrennt sind, das zum Suchen nach Symboldateien verwendet wird. Wenn dieser Parameter NULL ist, versucht die Bibliothek, einen Symbolpfad aus den folgenden Quellen zu bilden:

Das aktuelle Arbeitsverzeichnis der Anwendung
Die umgebungsvariable _NT_SYMBOL_PATH
Die umgebungsvariable _NT_ALTERNATE_SYMBOL_PATH

Beachten Sie, dass der Suchpfad auch mithilfe der SymSetSearchPath-Funktion festgelegt werden kann.

[in] fInvadeProcess

Wenn dieser Wert TRUE ist, listet die geladenen Module für den Prozess auf und ruft effektiv die SymLoadModule64-Funktion für jedes Modul auf.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert TRUE.

Wenn die Funktion fehlschlägt, ist der Rückgabewert FALSE. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen abzurufen.

Hinweise

Die SymInitialize-Funktion wird verwendet, um den Symbolhandler für einen Prozess zu initialisieren. Im Kontext des Symbolhandlers ist ein Prozess ein praktisches Objekt, das beim Sammeln von Symbolinformationen verwendet werden kann. In der Regel werden Symbolhandler von Debuggern und anderen Tools verwendet, die Symbole für einen zu debuggenden Prozess laden müssen.

Der an SymInitialize übergebene Handle muss der gleiche Wert sein, der an alle anderen vom Prozess aufgerufenen Symbolhandlerfunktionen übergeben wird. Es ist der Handle, den die Funktionen verwenden, um den Aufrufer zu identifizieren und die richtigen Symbolinformationen zu suchen. Wenn Sie die Symbolinformationen verwendet haben, rufen Sie die SymCleanup-Funktion auf, um alle Ressourcen zu behandeln, die dem Prozess zugeordnet sind, für den Symbole geladen werden.

Die Suche nach Symboldateien wird rekursiv für alle Pfade ausgeführt, die im UserSearchPath-Parameter angegeben sind. Wenn Sie also das Stammverzeichnis in einer Suche angeben, wird das gesamte Laufwerk durchsucht, was viel Zeit in Anspruch nehmen kann. Beachten Sie, dass das Verzeichnis, das die ausführbare Datei für den Prozess enthält, nicht automatisch Teil des Suchpfads ist. Um dieses Verzeichnis in den Suchpfad aufzunehmen, rufen Sie die GetModuleFileNameEx-Funktion auf, und fügen Sie dann den pfad hinzu, der zu UserSearchPath zurückgegeben wird.

Ein Prozess, der SymInitialize aufruft, sollte ihn nicht erneut aufrufen, es sei denn, er ruft zuerst SymCleanup auf. Wenn der Aufruf von SymInitializefInvadeProcess auf TRUE festgelegt hat und Sie einfach die Modulliste neu laden müssen, verwenden Sie die SymRefreshModuleList-Funktion .

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, rufen Sie SymInitialize nur auf, wenn Ihr Prozess gestartet wird, und SymCleanup nur, wenn Ihr Prozess endet. Es ist nicht erforderlich, dass jeder Thread im Prozess diese Funktionen aufruft.

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