CreateToolhelp32Snapshot 函数 (tlhelp32.h)

项目
08/26/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
Library	Kernel32.lib
DLL	Kernel32.dll