Funzione SymInitialize (dbghelp.h)

Articolo
03/11/2023

Inizializza il gestore di simboli per un processo.

Sintassi

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

Parametri

[in] hProcess

Handle che identifica il chiamante. Questo valore deve essere univoco e diverso da zero, ma non deve essere un handle di processo. Tuttavia, se si usa un handle di processo, assicurarsi di usare l'handle corretto. Se l'applicazione è un debugger, usare l'handle di processo per il processo di cui viene eseguito il debug. Non usare l'handle restituito da GetCurrentProcess. L'handle usato deve essere univoco per evitare la condivisione di una sessione con un altro componente e l'uso di GetCurrentProcess può avere risultati imprevisti quando più componenti tentano di usare dbghelp per esaminare il processo corrente. L'uso di GetCurrentProcess quando si esegue il debug di un altro processo causerà anche risultati imprevisti come SymLoadModuleEx .

Questo parametro non può essere NULL.

[in, optional] UserSearchPath

Percorso o serie di percorsi separati da un punto e virgola (;), usato per cercare i file di simboli. Se questo parametro è NULL, la libreria tenta di formare un percorso di simbolo dalle origini seguenti:

Directory di lavoro corrente dell'applicazione
Variabile di ambiente _NT_SYMBOL_PATH
Variabile di ambiente _NT_ALTERNATE_SYMBOL_PATH

Si noti che il percorso di ricerca può essere impostato anche usando la funzione SymSetSearchPath .

[in] fInvadeProcess

Se questo valore è TRUE, enumera i moduli caricati per il processo e chiama in modo efficace la funzione SymLoadModule64 per ogni modulo.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è TRUE.

Se la funzione ha esito negativo, il valore restituito è FALSE. Per recuperare informazioni sull'errore estese, chiamare GetLastError.

Commenti

La funzione SymInitialize viene usata per inizializzare il gestore di simboli per un processo. Nel contesto del gestore dei simboli, un processo è un oggetto pratico da usare per la raccolta di informazioni sui simboli. In genere, i gestori di simboli vengono usati dai debugger e da altri strumenti che devono caricare i simboli per un processo di cui viene eseguito il debug.

L'handle passato a SymInitialize deve essere lo stesso valore passato a tutte le altre funzioni del gestore di simboli chiamate dal processo. È l'handle usato dalle funzioni per identificare il chiamante e individuare le informazioni corrette sul simbolo. Al termine dell'uso delle informazioni sui simboli, chiamare la funzione SymCleanup per deallocare tutte le risorse associate al processo per cui vengono caricati i simboli.

La ricerca dei file di simboli viene eseguita in modo ricorsivo per tutti i percorsi specificati nel parametro UserSearchPath . Pertanto, se si specifica la directory radice in una ricerca, viene eseguita la ricerca dell'intera unità, che può richiedere tempo significativo. Si noti che la directory che contiene il file eseguibile per il processo non fa automaticamente parte del percorso di ricerca. Per includere questa directory nel percorso di ricerca, chiamare la funzione GetModuleFileNameEx e quindi aggiungere il percorso restituito a UserSearchPath.

Un processo che chiama SymInitialize non deve chiamarlo di nuovo, a meno che non chiami SymCleanup per primo. Se la chiamata a SymInitialize imposta fInvadeProcess su TRUE ed è sufficiente ricaricare l'elenco di moduli, usare la funzione SymRefreshModuleList .

Tutte le funzioni DbgHelp, ad esempio questa, sono a thread singolo. Di conseguenza, le chiamate da più thread a questa funzione genereranno un comportamento imprevisto o un danneggiamento della memoria. Per evitare questo problema, chiama SymInitialize solo all'avvio del processo e SymCleanup solo al termine del processo. Non è necessario che ogni thread nel processo chiami queste funzioni.

Per chiamare la versione Unicode di questa funzione, definire DBGHELP_TRANSLATE_TCHAR.

Esempio

Per un esempio, vedere Inizializzazione del gestore dei simboli.

Requisiti


Piattaforma di destinazione	Windows
Intestazione	dbghelp.h
Libreria	Dbghelp.lib
DLL	Dbghelp.dll
Componente ridistribuibile	DbgHelp.dll 5.1 o versione successiva