Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function takes a snapshot of the processes, heaps, modules, and threads used by the processes.

Syntax 

HANDLE WINAPI CreateToolhelp32Snapshot(
  DWORD
 dwFlags,
  DWORD
 th32ProcessID
);

Parameters

dwFlags

[in] Portions of the system to include in the snapshot. The following table shows possible values.

Value Description

TH32CS_GETALLMODS

Includes all modules in the snapshot. Must be used with the OR operator in combination with TH32CS_SNAPMODULE.

TH32CS_SNAPALL

Equivalent to specifying TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE, TH32CS_SNAPPROCESS, and TH32CS_SNAPTHREAD.

TH32CS_SNAPHEAPLIST

Includes the heap list of the specified process in the snapshot.

TH32CS_SNAPMODULE

Includes the module list of the specified process in the snapshot.

TH32CS_SNAPNOHEAPS

By default, the process heap information is included when creating PROCESS snapshot.

For a more efficient way of receiving the basic information of the process, use this flag with TH32CS_SNAPPROCESS.

TH32CS_SNAPPROCESS

Includes the process list in the snapshot.

TH32CS_SNAPTHREAD

Includes the thread list in the snapshot.
th32ProcessID

[in] Process identifier. This parameter can be zero to indicate the current process. This parameter is used when TH32CS_SNAPHEAPLIST or TH32CS_SNAPMODULE is specified. Otherwise, it is ignored.

Return Value

An open handle to the specified snapshot indicates success. INVALID_HANDLE_VALUE indicates failure.

Remarks

The snapshot returned is a copy of the current state of the system. To close a snapshot, call the CloseToolhelp32Snapshotfunction. Do not call the CloseHandlefunction to close the snapshot call. That generates a memory leak. The snapshot taken by this function is examined by other tool help functions to provide their results. Access to the snapshot is read-only.

The snapshot handle acts like an object handle and is subject to the same rules regarding the processes and threads where it is valid. To retrieve an extended error status code generated by this function, use the GetLastErrorfunction. Because the data captured by CreateToolhelp32Snapshotis static and the system is dynamic, use try-excepts around the APIs that access this data.

Requirements

Header tlhelp32.h, toolhelp.h
Library toolhelp.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also