Funzione SymInitialize (dbghelp.h)
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
[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 |