Función StackWalk (dbghelp.h)

Artículo
02/28/2024

Obtiene un seguimiento de pila.

Sintaxis

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

El tipo de arquitectura del equipo para el que se genera el seguimiento de la pila. Este parámetro puede ser uno de los valores siguientes.

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

[in] hProcess

Identificador del proceso para el que se genera el seguimiento de la pila. Si el autor de la llamada proporciona un puntero de devolución de llamada válido para el parámetro ReadMemoryRoutine , este valor no tiene que ser un identificador de proceso válido. Puede ser un token único y coherentemente igual para todas las llamadas a la función StackWalk64 . Si el controlador de símbolos se usa con StackWalk64, use los mismos identificadores de proceso para las llamadas a cada función.

[in] hThread

Identificador del subproceso para el que se genera el seguimiento de la pila. Si el autor de la llamada proporciona un puntero de devolución de llamada válido para el parámetro ReadMemoryRoutine , este valor no tiene que ser un identificador de subproceso válido. Puede ser un token único y coherentemente igual para todas las llamadas a la función StackWalk64 .

[in, out] StackFrame

Puntero a una estructura de STACKFRAME64 . Esta estructura recibe información para el siguiente marco, si la llamada de función se realiza correctamente.

[in, out] ContextRecord

Puntero a una estructura CONTEXT . Este parámetro solo es necesario cuando el parámetro MachineType no es IMAGE_FILE_MACHINE_I386. Sin embargo, se recomienda que este parámetro contenga un registro de contexto válido. Esto permite a StackWalk64 controlar una mayor variedad de situaciones.

Este contexto se puede modificar, por lo que no pase un registro de contexto que no se debe modificar.

[in, optional] ReadMemoryRoutine

Rutina de devolución de llamada que proporciona servicios de lectura de memoria. Cuando la función StackWalk64 necesita leer la memoria del espacio de direcciones del proceso, se usa la devolución de llamada ReadProcessMemoryProc64 .

Si este parámetro es NULL, la función usa una rutina predeterminada. En este caso, el parámetro hProcess debe ser un identificador de proceso válido.

Si este parámetro no es NULL, la aplicación debe implementar y registrar una función de devolución de llamada del controlador de símbolos que controla CBA_READ_MEMORY.

[in, optional] FunctionTableAccessRoutine

Rutina de devolución de llamada que proporciona acceso a la tabla de funciones en tiempo de ejecución para el proceso. Este parámetro es necesario porque la función StackWalk64 no tiene acceso a la tabla de funciones en tiempo de ejecución del proceso. Para obtener más información, vea FunctionTableAccessProc64.

El controlador de símbolos proporciona funciones que cargan y acceden a la tabla en tiempo de ejecución. Si se usan estas funciones, SymFunctionTableAccess64 se puede pasar como un parámetro válido.

[in, optional] GetModuleBaseRoutine

Rutina de devolución de llamada que proporciona una base de módulo para cualquier dirección virtual determinada. Este parámetro es obligatorio. Para obtener más información, vea GetModuleBaseProc64.

El controlador de símbolos proporciona funciones que cargan y mantienen la información del módulo. Si se usan estas funciones, SymGetModuleBase64 se puede pasar como un parámetro válido.

[in, optional] TranslateAddress

Rutina de devolución de llamada que proporciona traducción de direcciones para direcciones de 16 bits. Para obtener más información, vea TranslateAddressProc64.

La mayoría de los autores de llamadas de StackWalk64 pueden pasar de forma segura NULL para este parámetro.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es TRUE.

Si se produce un error en la función, el valor devuelto es FALSE. Tenga en cuenta que StackWalk64 generalmente no establece el último código de error.

Comentarios

La función StackWalk64 proporciona un método portátil para obtener un seguimiento de pila. El uso de la función StackWalk64 se recomienda sobre escribir su propia función debido a todas las complejidades asociadas con el recorrido de pila en plataformas. Además, hay opciones del compilador que hacen que la pila aparezca de forma diferente, en función de cómo se compile el módulo. Con esta función, la aplicación tiene un seguimiento de pila portátil que sigue funcionando como el compilador y el cambio del sistema operativo.

La primera llamada a esta función producirá un error si los miembros AddrPC, AddrFrame y AddrStack de la estructura de STACKFRAME64 pasadas en el parámetro StackFrame no se inicializan.

Todas las funciones DbgHelp, como esta, son un único subproceso. Por lo tanto, es probable que las llamadas desde más de un subproceso a esta función producirán un comportamiento inesperado o daños en la memoria. Para evitarlo, debe sincronizar todas las llamadas simultáneas de más de un subproceso a esta función.

Esta función sustituye a la función StackWalk . Para obtener más información, consulte Compatibilidad con la plataforma actualizada. StackWalk se define como se indica a continuación en 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