Função StackWalk (dbghelp.h)

Artigo
08/23/2023

Obtém um rastreamento de pilha.

Sintaxe

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
);

Parâmetros

[in] MachineType

O tipo de arquitetura do computador para o qual o rastreamento de pilha é gerado. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
IMAGE_FILE_MACHINE_I386 0x014c	Intel x86
IMAGE_FILE_MACHINE_IA64 0x0200	Intel Itanium
IMAGE_FILE_MACHINE_AMD64 0x8664	x64 (AMD64 ou EM64T)

[in] hProcess

Um identificador para o processo para o qual o rastreamento de pilha é gerado. Se o chamador fornecer um ponteiro de retorno de chamada válido para o parâmetro ReadMemoryRoutine , esse valor não precisará ser um identificador de processo válido. Pode ser um token exclusivo e consistentemente o mesmo para todas as chamadas para a função StackWalk64 . Se o manipulador de símbolos for usado com StackWalk64, use os mesmos identificadores de processo para as chamadas para cada função.

[in] hThread

Um identificador para o thread para o qual o rastreamento de pilha é gerado. Se o chamador fornecer um ponteiro de retorno de chamada válido para o parâmetro ReadMemoryRoutine , esse valor não precisará ser um identificador de thread válido. Pode ser um token exclusivo e consistentemente o mesmo para todas as chamadas para a função StackWalk64 .

[in, out] StackFrame

Um ponteiro para uma estrutura STACKFRAME64 . Essa estrutura receberá informações para o próximo quadro, se a chamada de função for bem-sucedida.

[in, out] ContextRecord

Um ponteiro para uma estrutura CONTEXT . Esse parâmetro é necessário somente quando o parâmetro MachineType não é IMAGE_FILE_MACHINE_I386. No entanto, é recomendável que esse parâmetro contenha um registro de contexto válido. Isso permite que o StackWalk64 lide com uma maior variedade de situações.

Esse contexto pode ser modificado, portanto, não passe um registro de contexto que não deve ser modificado.

[in, optional] ReadMemoryRoutine

Uma rotina de retorno de chamada que fornece serviços de leitura de memória. Quando a função StackWalk64 precisa ler a memória do espaço de endereço do processo, o retorno de chamada ReadProcessMemoryProc64 é usado.

Se esse parâmetro for NULL, a função usará uma rotina padrão. Nesse caso, o parâmetro hProcess deve ser um identificador de processo válido.

Se esse parâmetro não for NULL, o aplicativo deverá implementar e registrar uma função de retorno de chamada do manipulador de símbolos que manipula CBA_READ_MEMORY.

[in, optional] FunctionTableAccessRoutine

Uma rotina de retorno de chamada que fornece acesso à tabela de funções em tempo de execução para o processo. Esse parâmetro é necessário porque a função StackWalk64 não tem acesso à tabela de funções em tempo de execução do processo. Para obter mais informações, consulte FunctionTableAccessProc64.

O manipulador de símbolos fornece funções que carregam e acessam a tabela em tempo de execução. Se essas funções forem usadas, SymFunctionTableAccess64 poderá ser passado como um parâmetro válido.

[in, optional] GetModuleBaseRoutine

Uma rotina de retorno de chamada que fornece uma base de módulo para qualquer endereço virtual especificado. Este parâmetro é necessário. Para obter mais informações, consulte GetModuleBaseProc64.

O manipulador de símbolos fornece funções que carregam e mantêm informações de módulo. Se essas funções forem usadas, SymGetModuleBase64 poderá ser passado como um parâmetro válido.

[in, optional] TranslateAddress

Uma rotina de retorno de chamada que fornece tradução de endereço para endereços de 16 bits. Para obter mais informações, consulte TranslateAddressProc64.

A maioria dos chamadores do StackWalk64 pode passar NULL com segurança para esse parâmetro.

Retornar valor

Se a função for bem-sucedida, o valor retornado será TRUE.

Se a função falhar, o valor retornado será FALSE. Observe que o StackWalk64 geralmente não define o último código de erro.

Comentários

A função StackWalk64 fornece um método portátil para obter um rastreamento de pilha. O uso da função StackWalk64 é recomendado ao escrever sua própria função devido a todas as complexidades associadas à movimentação de pilha em plataformas. Além disso, há opções do compilador que fazem com que a pilha apareça de forma diferente, dependendo de como o módulo é compilado. Usando essa função, seu aplicativo tem um rastreamento de pilha portátil que continua funcionando à medida que o compilador e o sistema operacional mudam.

A primeira chamada para essa função falhará se os membros AddrPC, AddrFrame e AddrStack da estrutura STACKFRAME64 passada no parâmetro StackFrame não forem inicializados.

Todas as funções DbgHelp, como esta, são threaded único. Portanto, chamadas de mais de um thread para essa função provavelmente resultarão em comportamento inesperado ou corrupção de memória. Para evitar isso, você deve sincronizar todas as chamadas simultâneas de mais de um thread para essa função.

Essa função substitui a função StackWalk . Para obter mais informações, consulte Suporte de plataforma atualizado. StackWalk é definido da seguinte maneira em 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