Função StackWalkEx (dbghelp.h)

Artigo
02/29/2024

Obtém um rastreamento de pilha.

Sintaxe

BOOL IMAGEAPI StackWalkEx(
  [in]           DWORD                            MachineType,
  [in]           HANDLE                           hProcess,
  [in]           HANDLE                           hThread,
  [in, out]      LPSTACKFRAME_EX                  StackFrame,
  [in, out]      PVOID                            ContextRecord,
  [in, optional] PREAD_PROCESS_MEMORY_ROUTINE64   ReadMemoryRoutine,
  [in, optional] PFUNCTION_TABLE_ACCESS_ROUTINE64 FunctionTableAccessRoutine,
  [in, optional] PGET_MODULE_BASE_ROUTINE64       GetModuleBaseRoutine,
  [in, optional] PTRANSLATE_ADDRESS_ROUTINE64     TranslateAddress,
  [in]           DWORD                            Flags
);

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 StackWalkEx . Se o manipulador de símbolos for usado com StackWalkEx, 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 StackWalkEx .

[in, out] StackFrame

Um ponteiro para uma estrutura STACKFRAME_EX . 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 StackWalkEx 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 StackWalkEx 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 StackWalkEx 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 de 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 do 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ços para endereços de 16 bits. Para obter mais informações, consulte TranslateAddressProc64.

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

[in] Flags

Uma combinação de zero ou mais sinalizadores.

SYM_STKWALK_DEFAULT (0)

SYM_STKWALK_FORCE_FRAMEPTR (1)

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 StackWalkEx geralmente não define o último código de erro.

Comentários

A função StackWalkEx fornece um método portátil para obter um rastreamento de pilha. O uso da função StackWalkEx é recomendado ao gravar sua própria função devido a todas as complexidades associadas ao andar de pilha em plataformas. Além disso, há opções de 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 o AddrPC,
Os membros AddrFrame e AddrStack da estrutura STACKFRAME64 passada no parâmetro StackFrame não são 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.