SymInitializeW 関数 (dbghelp.h)

[アーティクル]
11/20/2024

プロセスのシンボルハンドラーを初期化します。

構文

BOOL IMAGEAPI SymInitializeW(
  [in]           HANDLE hProcess,
  [in, optional] PCWSTR UserSearchPath,
  [in]           BOOL   fInvadeProcess
);

パラメーター

[in] hProcess

呼び出し元を識別するハンドル。この値は一意で 0 以外にする必要がありますが、プロセスハンドルである必要はありません。ただし、プロセスハンドルを使用する場合は、必ず正しいハンドルを使用してください。アプリケーションがデバッガーの場合は、デバッグ対象のプロセスのプロセスハンドルを使用します。 SymLoadModuleEx などの関数を呼び出すと予期しない結果が発生する可能性があるため、別のプロセスをデバッグするときに、GetCurrentProcess によって返されるハンドルを使用しないでください。

このパラメーターは NULLできません。

[in, optional] UserSearchPath

シンボルファイルの検索に使用される、セミコロン (;)) で区切られたパスまたは一連のパス。このパラメーターが NULL場合、ライブラリは次のソースからのシンボルパスの形成を試みます。

アプリケーションの現在の作業ディレクトリ
_NT_SYMBOL_PATH環境変数
_NT_ALTERNATE_SYMBOL_PATH環境変数

検索パスは、SymSetSearchPath 関数を使用して設定することもできます。

[in] fInvadeProcess

この値が TRUE場合は、プロセスの読み込まれたモジュールを列挙し、実質的に各モジュールの SymLoadModule64 関数を呼び出します。

戻り値

関数が成功した場合、戻り値は TRUE。

関数が失敗した場合、戻り値は FALSE。拡張エラー情報を取得するには、GetLastError呼び出します。

備考

SymInitialize 関数は、プロセスのシンボルハンドラーを初期化するために使用されます。シンボルハンドラーのコンテキストでは、プロセスはシンボル情報を収集するときに使用する便利なオブジェクトです。通常、シンボルハンドラーは、デバッグ中のプロセスのシンボルを読み込む必要があるデバッガーやその他のツールによって使用されます。

SymInitialize に渡されるハンドルは、プロセスによって呼び出される他のすべてのシンボルハンドラー関数に渡されるのと同じ値である必要があります。呼び出し元を識別し、正しいシンボル情報を見つけるために関数が使用するハンドルです。シンボル情報の使用が完了したら、SymCleanup 関数を呼び出して、シンボルが読み込まれるプロセスに関連付けられているすべてのリソースの割り当てを解除します。

シンボルファイルの検索は、UserSearchPath パラメーターで指定されたすべてのパスに対して再帰的に実行されます。そのため、検索でルートディレクトリを指定すると、ドライブ全体が検索され、時間がかかる可能性があります。プロセスの実行可能ファイルを含むディレクトリは、自動的には検索パスの一部ではないことに注意してください。このディレクトリを検索パスに含めるには、GetModuleFileNameEx 関数を呼び出し、UserSearchPathに返されるパスを追加します。

SymInitialize 呼び出すプロセスは、SymCleanup を最初呼び出さない限り、再度呼び出さないでください。 SymInitialize 呼び出し fInvadeProcess を TRUE 設定し、モジュールリストを再読み込みするだけで済む場合は、SymRefreshModuleList 関数を使用します。

この関数など、すべての DbgHelp 関数はシングルスレッドです。そのため、複数のスレッドからこの関数を呼び出すと、予期しない動作やメモリ破損が発生する可能性があります。これを回避するには、プロセス開始時にのみ SymInitialize を呼び出し、プロセスが終了したときにのみ SymCleanup をします。プロセス内の各スレッドがこれらの関数を呼び出す必要はありません。

この関数の Unicode バージョンを呼び出すには、DBGHELP_TRANSLATE_TCHARを定義します。

例

例については、「シンボルハンドラーの初期化」を参照してください。

手記

dbghelp.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして SymInitialize を定義します。エンコードに依存しないエイリアスをエンコードに依存しないコードと組み合わせて使用すると、コンパイルエラーやランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

必要条件

要件	価値
ターゲットプラットフォームの	ウィンドウズ
ヘッダー	dbghelp.h
ライブラリ	Dbghelp.lib
DLL	Dbghelp.dll
再頒布可能パッケージの	DbgHelp.dll 5.1 以降

次の方法で共有

SymInitializeW 関数 (dbghelp.h)

構文

パラメーター

戻り値

備考

例

必要条件

関連項目

フィードバック

その他のリソース