SymInitialize 関数 (dbghelp.h)

[アーティクル]
03/11/2023

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

構文

BOOL IMAGEAPI SymInitialize(
  [in]           HANDLE hProcess,
  [in, optional] PCSTR  UserSearchPath,
  [in]           BOOL   fInvadeProcess
);

パラメーター

[in] hProcess

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

このパラメーターを 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を定義します。

例

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

要件


対象プラットフォーム	Windows
ヘッダー	dbghelp.h
Library	Dbghelp.lib
[DLL]	Dbghelp.dll
再頒布可能パッケージ	DbgHelp.dll 5.1 以降

SymInitialize 関数 (dbghelp.h)

構文

パラメーター

戻り値

解説

例

要件

関連項目

フィードバック

フィードバック

その他のリソース