CreateToolhelp32Snapshot 関数 (tlhelp32.h)
指定したプロセスのスナップショットと、これらのプロセスで使用されるヒープ、モジュール、スレッドを受け取ります。
構文
HANDLE CreateToolhelp32Snapshot(
[in] DWORD dwFlags,
[in] DWORD th32ProcessID
);
パラメーター
[in] dwFlags
スナップショットに含めるシステムの部分。 このパラメーターには、次の 1 つ以上の値を指定できます。
| 値 | 説明 |
|---|---|
|
スナップショット ハンドルが継承可能であることを示します。 |
|
システム内のすべてのプロセスとスレッドに加えて、 th32ProcessID で指定されたプロセスのヒープとモジュールが含まれます。 OR 演算 ('|') を使用して結合された TH32CS_SNAPHEAPLIST、 TH32CS_SNAPMODULE、 TH32CS_SNAPPROCESS、 およびTH32CS_SNAPTHREAD の値を指定することと同じです。 |
|
スナップショットの th32ProcessID で指定されたプロセスのすべてのヒープが含まれます。 ヒープを列挙するには、「 Heap32ListFirst」を参照してください。 |
|
スナップショットの th32ProcessID で指定されたプロセスのすべてのモジュールが含まれます。 モジュールを列挙するには、「 Module32First」を参照してください。 関数が ERROR_BAD_LENGTH で失敗した場合は、成功するまで関数を再試行してください。
64 ビット Windows: 32 ビット プロセスでこのフラグを使用すると、 th32ProcessID で指定されたプロセスの 32 ビット モジュールが含まれますが、64 ビット プロセスで使用する場合は 64 ビット モジュールが含まれます。 64 ビット プロセスから th32ProcessID で指定されたプロセスの 32 ビット モジュールを含めるには、 TH32CS_SNAPMODULE32 フラグを使用します。 |
|
64 ビット プロセスから呼び出されたときに、スナップショットの th32ProcessID で指定されたプロセスのすべての 32 ビット モジュールが含まれます。 このフラグは、 TH32CS_SNAPMODULE または TH32CS_SNAPALLと組み合わせることができます。 関数が ERROR_BAD_LENGTH で失敗した場合は、成功するまで関数を再試行してください。 |
|
システム内のすべてのプロセスをスナップショットに含みます。 プロセスを列挙するには、「 Process32First」を参照してください。 |
|
システム内のすべてのスレッドをスナップショットに含みます。 スレッドを列挙するには、「 Thread32First」を参照してください。
特定のプロセスに属するスレッドを識別するには、スレッドを列挙するときに、そのプロセス識別子をTHREADENTRY32構造体の th32OwnerProcessID メンバーと比較します。 |
[in] th32ProcessID
スナップショットに含めるプロセスのプロセス識別子。 このパラメーターには、現在のプロセスを示す 0 を指定できます。 このパラメーターは、TH32CS_SNAPHEAPLIST、 TH32CS_SNAPMODULE、 TH32CS_SNAPMODULE32、または TH32CS_SNAPALLの値が指定されている場合 に 使用されます。 それ以外の場合は無視され、すべてのプロセスがスナップショットに含まれます。
指定したプロセスがアイドル プロセスまたは CSRSS プロセスの 1 つである場合、この関数は失敗し、最後のエラー コードはアクセス制限によってユーザー レベルのコードで開くことができないため 、ERROR_ACCESS_DENIED されます。
指定したプロセスが 64 ビット プロセスで、呼び出し元が 32 ビット プロセスの場合、この関数は失敗し、最後のエラー コードは ERROR_PARTIAL_COPY (299) になります。
戻り値
関数が成功すると、指定したスナップショットに対して開いているハンドルが返されます。
関数が失敗した場合は、 INVALID_HANDLE_VALUEを返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。 考えられるエラー コードには 、ERROR_BAD_LENGTHが含まれます。
解説
この関数によって取得されたスナップショットは、その結果を提供するために他のツール ヘルプ関数によって調べられます。 スナップショットへのアクセスは読み取り専用です。 スナップショット ハンドルはオブジェクト ハンドルとして機能し、有効なプロセスとスレッドに関する同じ規則に従います。
すべてのプロセスのヒープまたはモジュールの状態を列挙するには、 TH32CS_SNAPALL を指定し、 th32ProcessID を 0 に設定します。 次に、スナップショット内の追加のプロセスごとに、CreateToolhelp32Snapshot をもう一度呼び出し、そのプロセス識別子とTH32CS_SNAPHEAPLISTまたはTH32_SNAPMODULE値を指定します。
現在のプロセス以外のプロセスのヒープとモジュールを含むスナップショットを作成する場合、 CreateToolhelp32Snapshot 関数は失敗したり、さまざまな理由で正しくない情報を返したりする可能性があります。 たとえば、ターゲット プロセスのローダー データ テーブルが破損しているか初期化されていない場合、または DLL の読み込みまたはアンロードの結果として関数呼び出し中にモジュール リストが変更された場合、関数は ERROR_BAD_LENGTH またはその他のエラー コードで失敗する可能性があります。 ターゲット プロセスが中断状態で開始されていないことを確認し、関数を再度呼び出してみてください。 TH32CS_SNAPMODULE または TH32CS_SNAPMODULE32 で呼び出されたときに関数が ERROR_BAD_LENGTH で失敗した場合は、成功するまで関数をもう一度呼び出します。
TH32CS_SNAPMODULEフラグとTH32CS_SNAPMODULE32 フラグは、LOAD_LIBRARY_AS_DATAFILEまたは同様のフラグと共に読み込まれたモジュールのハンドルを取得しません。 詳細については、「 LoadLibraryEx」を参照してください。
スナップショットを破棄するには、CloseHandle 関数を使用します。
QueryFullProcessImageName 関数を使用して、32 ビット プロセスと 64 ビット プロセスの両方の実行可能イメージの完全な名前を 32 ビット プロセスから取得できることに注意してください。
例
例については、「 スナップショットの作成」と「プロセスの表示」を参照してください。
要件
| サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
| サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
| 対象プラットフォーム | Windows |
| ヘッダー | tlhelp32.h |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |