Funzione StackWalk (dbghelp.h)

Ottiene un'analisi dello stack.

Sintassi

BOOL IMAGEAPI StackWalk(
  [in]           DWORD                          MachineType,
  [in]           HANDLE                         hProcess,
  [in]           HANDLE                         hThread,
  [in, out]      LPSTACKFRAME                   StackFrame,
  [in, out]      PVOID                          ContextRecord,
  [in, optional] PREAD_PROCESS_MEMORY_ROUTINE   ReadMemoryRoutine,
  [in, optional] PFUNCTION_TABLE_ACCESS_ROUTINE FunctionTableAccessRoutine,
  [in, optional] PGET_MODULE_BASE_ROUTINE       GetModuleBaseRoutine,
  [in, optional] PTRANSLATE_ADDRESS_ROUTINE     TranslateAddress
);

Parametri

[in] MachineType

Tipo di architettura del computer per cui viene generata l'analisi dello stack. Questo parametro può avere uno dei valori seguenti.

[in] hProcess

Handle per il processo per il quale viene generata l'analisi dello stack. Se il chiamante fornisce un puntatore di callback valido per il parametro ReadMemoryRoutine , questo valore non deve essere un handle di processo valido. Può essere un token univoco e coerente per tutte le chiamate alla funzione StackWalk64 . Se il gestore dei simboli viene usato con StackWalk64, usare gli stessi handle di processo per le chiamate a ogni funzione.

[in] hThread

Handle per il thread per cui viene generata l'analisi dello stack. Se il chiamante fornisce un puntatore di callback valido per il parametro ReadMemoryRoutine , questo valore non deve essere un handle di thread valido. Può essere un token univoco e coerente per tutte le chiamate alla funzione StackWalk64 .

[in, out] StackFrame

Puntatore a una struttura STACKFRAME64 . Questa struttura riceve informazioni per il frame successivo, se la chiamata di funzione ha esito positivo.

[in, out] ContextRecord

Puntatore a una struttura CONTEXT . Questo parametro è obbligatorio solo quando il parametro MachineType non è IMAGE_FILE_MACHINE_I386. È tuttavia consigliabile che questo parametro contenga un record di contesto valido. In questo modo StackWalk64 può gestire un'ampia gamma di situazioni.

Questo contesto può essere modificato, pertanto non passare un record di contesto che non deve essere modificato.

[in, optional] ReadMemoryRoutine

Routine di callback che fornisce servizi di lettura della memoria. Quando la funzione StackWalk64 deve leggere la memoria dallo spazio indirizzi del processo, viene usato il callback ReadProcessMemoryProc64 .

Se questo parametro è NULL, la funzione usa una routine predefinita. In questo caso, il parametro hProcess deve essere un handle di processo valido.

Se questo parametro non è NULL, l'applicazione deve implementare e registrare una funzione di callback del gestore di simboli che gestisce CBA_READ_MEMORY.

[in, optional] FunctionTableAccessRoutine

Routine di callback che fornisce l'accesso alla tabella delle funzioni di runtime per il processo. Questo parametro è obbligatorio perché la funzione StackWalk64 non ha accesso alla tabella delle funzioni di runtime del processo. Per altre informazioni, vedere FunctionTableAccessProc64.

Il gestore dei simboli fornisce funzioni che caricano e accedono alla tabella di runtime. Se vengono usate queste funzioni, SymFunctionTableAccess64 può essere passato come parametro valido.

[in, optional] GetModuleBaseRoutine

Routine di callback che fornisce una base di moduli per qualsiasi indirizzo virtuale specificato. Questo parametro è obbligatorio. Per altre informazioni, vedere GetModuleBaseProc64.

Il gestore dei simboli fornisce funzioni che caricano e gestiscono le informazioni sui moduli. Se queste funzioni vengono usate, SymGetModuleBase64 può essere passato come parametro valido.

[in, optional] TranslateAddress

Routine di callback che fornisce la conversione degli indirizzi per indirizzi a 16 bit. Per altre informazioni, vedere TranslateAddressProc64.

La maggior parte dei chiamanti di StackWalk64 può passare in modo sicuro NULL per questo parametro.

Valore restituito

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

Se la funzione ha esito negativo, il valore restituito è FALSE. Si noti che StackWalk64 in genere non imposta l'ultimo codice di errore.

Commenti

La funzione StackWalk64 fornisce un metodo portabile per ottenere un'analisi dello stack. L'uso della funzione StackWalk64 è consigliato per scrivere una funzione personalizzata a causa di tutte le complessità associate allo stack walking sulle piattaforme. Inoltre, sono disponibili opzioni del compilatore che causano la visualizzazione dello stack in modo diverso, a seconda della modalità di compilazione del modulo. Usando questa funzione, l'applicazione dispone di un'analisi dello stack portabile che continua a funzionare man mano che il compilatore e il sistema operativo cambiano.

La prima chiamata a questa funzione avrà esito negativo se i membri AddrPC, AddrFrame e AddrStack della struttura STACKFRAME64 passata nel parametro StackFrame non vengono inizializzati.

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, è necessario sincronizzare tutte le chiamate simultanee da più thread a questa funzione.

Questa funzione sostituisce la funzione StackWalk . Per altre informazioni, vedere Aggiornamento del supporto della piattaforma. StackWalk è definito come segue in DbgHelp.h.

#if !defined(_IMAGEHLP_SOURCE_) && defined(_IMAGEHLP64)
#define StackWalk StackWalk64
#else
BOOL
IMAGEAPI
StackWalk(
    DWORD MachineType,
    __in HANDLE hProcess,
    __in HANDLE hThread,
    __inout LPSTACKFRAME StackFrame,
    __inout PVOID ContextRecord,
    __in_opt PREAD_PROCESS_MEMORY_ROUTINE ReadMemoryRoutine,
    __in_opt PFUNCTION_TABLE_ACCESS_ROUTINE FunctionTableAccessRoutine,
    __in_opt PGET_MODULE_BASE_ROUTINE GetModuleBaseRoutine,
    __in_opt PTRANSLATE_ADDRESS_ROUTINE TranslateAddress
    );

#endif

Requisiti

Vedi anche

CONTESTO

Funzioni DbgHelp

FunctionTableAccessProc64

GetModuleBaseProc64

ReadProcessMemoryProc64

STACKFRAME64

TranslateAddressProc64