SymInitializeW-Funktion (dbghelp.h)

Artikel
11/20/2024

Initialisiert den Symbolhandler für einen Prozess.

Syntax

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

Parameter

[in] hProcess

Ein Handle, das den Aufrufer identifiziert. Dieser Wert sollte eindeutig und nicht zero sein, muss jedoch kein Prozesshandle sein. Wenn Sie jedoch ein Prozesshandle verwenden, stellen Sie sicher, dass Sie den richtigen Handle verwenden. Wenn es sich bei der Anwendung um einen Debugger handelt, verwenden Sie das Prozesshandle für den zu debuggenden Prozess. Verwenden Sie beim Debuggen eines anderen Prozesses nicht das von GetCurrentProcess zurückgegebene Handle, da das Aufrufen von Funktionen wie SymLoadModuleEx- unerwartete Ergebnisse haben kann.

Dieser Parameter kann nicht NULL-werden.

[in, optional] UserSearchPath

Der Pfad oder die Reihe von Pfaden, die durch ein Semikolon getrennt sind (;), der 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 TRUEist, werden die geladenen Module für den Prozess aufgezählt und die SymLoadModule64 Funktion für jedes Modul effektiv aufgerufen.

Rückgabewert

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

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

Bemerkungen

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 derselbe Wert sein, der an alle anderen vom Prozess aufgerufenen Symbolhandlerfunktionen übergeben wird. Es ist der Handle, mit dem die Funktionen den Aufrufer identifizieren und die richtigen Symbolinformationen suchen. Wenn Sie mit der Verwendung der Symbolinformationen fertig sind, rufen Sie die SymCleanup--Funktion auf, um alle Ressourcen zuzuordnen, 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 daher das Stammverzeichnis in einer Suche angeben, wird das gesamte Laufwerk durchsucht, was erhebliche 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 einzuschließen, rufen Sie die GetModuleFileNameEx--Funktion auf, und fügen Sie dann den Pfad hinzu, der an UserSearchPathzurückgegeben wird.

Ein Prozess, der SymInitialize- aufruft, sollte es nur dann erneut aufrufen, wenn er zuerst SymCleanup aufruft. Wenn der Aufruf von SymInitialize festlegen, fInvadeProcess auf "TRUE" 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 Aufrufe von mehr als einem Thread zu dieser Funktion wahrscheinlich zu unerwartetem Verhalten oder Speicherbeschädigung. Um dies zu vermeiden, rufen Sie SymInitialize nur dann auf, wenn der Prozess gestartet wird, und SymCleanup nur, wenn der Prozess endet. Für jeden Thread im Prozess ist es nicht erforderlich, diese Funktionen aufzurufen.

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

Beispiele

Ein Beispiel finden Sie unter Initialisieren des Symbolhandlers.

Anmerkung

Der dbghelp.h-Header definiert SymInitialize als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.