StackWalk 関数 (dbghelp.h)

スタック トレースを取得します。

構文

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

スタック トレースが生成されるコンピューターのアーキテクチャの種類。 このパラメーターには、次の値のいずれかを指定できます。

[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 関数を使用することをお勧めします。 さらに、モジュールのコンパイル方法に応じて、スタックの表示方法が異なるコンパイラ オプションがあります。 この関数を使用すると、アプリケーションには、コンパイラとオペレーティング システムの変更時に引き続き機能する移植可能なスタック トレースがあります。

StackFrame パラメーターで渡されるSTACKFRAME64構造体の AddrPC、AddrFrame、AddrStack メンバーが初期化されていない場合、この関数の最初の呼び出しは失敗します。

この関数など、すべての 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

要件

こちらもご覧ください

CONTEXT

DbgHelp 関数

FunctionTableAccessProc64

GetModuleBaseProc64

ReadProcessMemoryProc64

STACKFRAME64

TranslateAddressProc64