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

Статья
08/23/2023

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

Синтаксис

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

Параметры

[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 , это значение не обязательно должно быть допустимым дескриптором процесса. Это может быть токен, который является уникальным и постоянно одинаковым для всех вызовов функции StackWalkEx . Если обработчик символов используется с StackWalkEx, используйте те же дескрипторы процесса для вызовов каждой функции.

[in] hThread

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

[in, out] StackFrame

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

[in, out] ContextRecord

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

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

[in, optional] ReadMemoryRoutine

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

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

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

[in, optional] FunctionTableAccessRoutine

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

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

[in, optional] GetModuleBaseRoutine

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

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

[in, optional] TranslateAddress

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

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

[in] Flags

Сочетание 0 или более флагов.

SYM_STKWALK_DEFAULT (0)

SYM_STKWALK_FORCE_FRAMEPTR (1)

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

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

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

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

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

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

Требования

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