CreateToolhelp32Snapshot 函式 (tlhelp32.h)

發行項
03/08/2023

擷取指定進程的快照集，以及這些進程所使用的堆積、模組和執行緒。

語法

HANDLE CreateToolhelp32Snapshot(
  [in] DWORD dwFlags,
  [in] DWORD th32ProcessID
);

參數

[in] dwFlags

要包含在快照集的系統部分。此參數可以是下列一或多個值。

值	意義
TH32CS_INHERIT 0x80000000	表示快照集控制碼是可繼承的。
TH32CS_SNAPALL	包含系統中的所有進程和執行緒，以及 th32ProcessID中所指定進程的堆積和模組。相當於使用 OR 作業 ('\|' 來指定TH32CS_SNAPHEAPLIST、TH32CS_SNAPMODULE、TH32CS_SNAPPROCESS和TH32CS_SNAPTHREAD值) 。
TH32CS_SNAPHEAPLIST 0x00000001	包含快照集中 th32ProcessID 中指定的進程的所有堆積。若要列舉堆積，請參閱 Heap32ListFirst。
TH32CS_SNAPMODULE 0x00000008	包含快照集中 th32ProcessID 中指定的進程的所有模組。若要列舉模組，請參閱 Module32First。如果函式因 ERROR_BAD_LENGTH而失敗，請重試函式，直到函式成功為止。 64 位 Windows：在 32 位進程中使用此旗標包含 th32ProcessID中所指定進程的 32 位模組，而在 64 位進程中使用它則包含 64 位模組。若要從 64 位進程包含 th32ProcessID 中指定的進程 32 位模組，請使用 TH32CS_SNAPMODULE32 旗標。
TH32CS_SNAPMODULE32 0x00000010	從 64 位進程呼叫時，在快照集中包含 th32ProcessID 中指定的所有 32 位模組。此旗標可以與 TH32CS_SNAPMODULE 或 TH32CS_SNAPALL結合。如果函式因 ERROR_BAD_LENGTH而失敗，請重試函式，直到函式成功為止。
TH32CS_SNAPPROCESS 0x00000002	在快照集中包含系統中的所有進程。若要列舉進程，請參閱 Process32First。
TH32CS_SNAPTHREAD 0x00000004	在快照集中包含系統中的所有線程。若要列舉執行緒，請參閱 Thread32First。若要識別屬於特定進程的執行緒，請在列舉執行緒時，將其進程識別碼與THREADENTRY32結構的th32OwnerProcessID成員進行比較。

[in] th32ProcessID

要包含在快照集之進程的進程識別碼。此參數可以是零，表示目前的進程。指定 TH32CS_SNAPHEAPLIST、 TH32CS_SNAPMODULE、 TH32CS_SNAPMODULE32或 TH32CS_SNAPALL 值時，會使用此參數。否則會忽略它，而且所有進程都會包含在快照集內。

如果指定的進程是閒置進程或其中一個 CSRSS 進程，則此函式會失敗，而且最後一個錯誤碼 會ERROR_ACCESS_DENIED ，因為其存取限制會防止使用者層級的程式碼開啟它們。

如果指定的進程是 64 位進程，而呼叫端是 32 位進程，則此函式會失敗，而且最後一個錯誤碼 會ERROR_PARTIAL_COPY ( 299) 。

傳回值

如果函式成功，它會傳回指定快照集的開啟控制碼。

如果函式失敗，它會傳回 INVALID_HANDLE_VALUE。若要取得擴充的錯誤資訊，請呼叫 GetLastError。可能的錯誤碼包括 ERROR_BAD_LENGTH。

備註

此函式所擷取的快照集會由其他工具說明函式檢查，以提供其結果。快照集的存取權是唯讀的。快照集控制碼可作為物件控制碼，而且受限於與它有效的進程和執行緒相同的規則。

若要列舉所有進程的堆積或模組狀態，請指定 TH32CS_SNAPALL 並將 th32ProcessID 設定為零。然後，針對快照集中的每個額外進程，再次呼叫 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 位進程擷取 32 位和 64 位進程的可執行檔映射完整名稱。

範例

如需範例，請參閱擷取快照集和檢視程式。

規格需求


最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平台	Windows
標頭	tlhelp32.h
程式庫	Kernel32.lib
DLL	Kernel32.dll