Функция StackWalk (dbghelp.h)

Статья
08/23/2023

Получает трассировку стека.

Синтаксис

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

Параметры

[in] MachineType

Тип архитектуры компьютера, для которого создается трассировка стека. Этот параметр может принимать одно из указанных ниже значений.

Значение	Значение
IMAGE_FILE_MACHINE_I386 0x014c	Intel x86
IMAGE_FILE_MACHINE_IA64 0x0200	Intel Itanium
IMAGE_FILE_MACHINE_AMD64 0x8664	x64 (AMD64 или EM64T)

[in] hProcess

Дескриптор процесса, для которого создается трассировка стека. Если вызывающий объект предоставляет допустимый указатель обратного вызова для параметра ReadMemoryRoutine , это значение не обязательно должно быть допустимым дескриптором процесса. Это может быть маркер, который является уникальным и постоянно одинаковым для всех вызовов функции StackWalk64 . Если обработчик символов используется с StackWalk64, используйте те же дескрипторы процесса для вызовов каждой функции.

[in] hThread

Дескриптор потока, для которого создается трассировка стека. Если вызывающий объект предоставляет допустимый указатель обратного вызова для параметра ReadMemoryRoutine , это значение не обязательно должно быть допустимым дескриптором потока. Это может быть маркер, который является уникальным и постоянно одинаковым для всех вызовов функции StackWalk64 .

[in, out] StackFrame

Указатель на структуру STACKFRAME64 . Эта структура получает сведения для следующего кадра, если вызов функции выполнен успешно.

[in, out] ContextRecord

Указатель на структуру CONTEXT . Этот параметр является обязательным, только если параметр MachineType не IMAGE_FILE_MACHINE_I386. Однако рекомендуется, чтобы этот параметр содержал допустимую запись контекста. Это позволяет StackWalk64 обрабатывать более разнообразные ситуации.

Этот контекст может быть изменен, поэтому не следует передавать запись контекста, которую не следует изменять.

[in, optional] ReadMemoryRoutine

Подпрограмма обратного вызова, которая предоставляет службы чтения памяти. Если функции StackWalk64 необходимо считывать память из адресного пространства процесса, используется обратный вызов ReadProcessMemoryProc64 .

Если этот параметр имеет значение NULL, функция использует подпрограмму по умолчанию. В этом случае параметр hProcess должен быть допустимым дескриптором процесса.

Если этот параметр не равен NULL, приложение должно реализовать и зарегистрировать функцию обратного вызова обработчика символов, которая обрабатывает CBA_READ_MEMORY.

[in, optional] FunctionTableAccessRoutine

Подпрограмма обратного вызова, которая предоставляет доступ к таблице функций времени выполнения для процесса. Этот параметр является обязательным, так как функция StackWalk64 не имеет доступа к таблице функций времени выполнения процесса. Дополнительные сведения см. в разделе FunctionTableAccessProc64.

Обработчик символов предоставляет функции, которые загружают таблицу времени выполнения и получают доступ к ней. Если используются эти функции, то SymFunctionTableAccess64 можно передать в качестве допустимого параметра.

[in, optional] GetModuleBaseRoutine

Подпрограмма обратного вызова, которая предоставляет базу модуля для любого заданного виртуального адреса. Это обязательный параметр. Дополнительные сведения см. в разделе GetModuleBaseProc64.

Обработчик символов предоставляет функции, которые загружают и поддерживают сведения о модуле. Если используются эти функции, то SymGetModuleBase64 можно передать в качестве допустимого параметра.

[in, optional] TranslateAddress

Подпрограмма обратного вызова, которая обеспечивает преобразование адресов для 16-разрядных адресов. Дополнительные сведения см. в разделе TranslateAddressProc64.

Большинство вызывающих объектов StackWalk64 могут безопасно передавать значение NULL для этого параметра.

Возвращаемое значение

Если функция выполняется успешно, возвращается значение TRUE.

Если функция завершается сбоем, возвращается значение FALSE. Обратите внимание, что StackWalk64 обычно не задает последний код ошибки.

Функция StackWalk64 предоставляет переносимый метод для получения трассировки стека. Рекомендуется использовать функцию StackWalk64 вместо написания собственной функции из-за всех сложностей, связанных со стеком на платформах. Кроме того, существуют параметры компилятора, которые приводят к тому, что стек отображается по-разному в зависимости от того, как компилируется модуль. С помощью этой функции приложение имеет переносимую трассировку стека, которая продолжает работать в качестве компилятора и изменения операционной системы.

Первый вызов этой функции завершится ошибкой, если элементы AddrPC, AddrFrame и AddrStackструктуры STACKFRAME64 , переданной в параметре StackFrame , не инициализированы.

Все функции DbgHelp, такие как эта, являются однопоточными. Поэтому вызовы из нескольких потоков к этой функции, скорее всего, приведут к непредвиденному поведению или повреждению памяти. Чтобы избежать этого, необходимо синхронизировать все параллельные вызовы из нескольких потоков в эту функцию.

Эта функция заменяет функцию StackWalk . Дополнительные сведения см. в разделе Обновленная поддержка платформы. StackWalk определяется следующим образом в 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

Требования

Требование	Значение
Целевая платформа	Windows
Header	dbghelp.h
Библиотека	DbgHelp.lib
DLL	DbgHelp.dll
Распространяемые компоненты	DbgHelp.dll 5.1 или более поздней версии