Edit

Snapshots of the System

  • Article

Snapshots are at the core of the tool help functions. A snapshot is a read-only copy of the current state of one or more of the following lists that reside in system memory: processes, threads, modules, and heaps.

Processes that use tool help functions access these lists from snapshots instead of directly from the operating system. The lists in system memory change when processes are started and ended, threads are created and destroyed, executable modules are loaded and unloaded from system memory, and heaps are created and destroyed. The use of information from a snapshot prevents inconsistencies. Otherwise, changes to a list could possibly cause a thread to incorrectly traverse the list or cause an access violation (a GP fault). For example, if an application traverses the thread list while other threads are created or terminated, information that the application is using to traverse the thread list might become outdated and could cause an error for the application traversing the list.

To take a snapshot of the system memory, use the CreateToolhelp32Snapshot function. You can control the content of a snapshot by specifying one or more of the following values when calling this function:

  • TH32CS_SNAPHEAPLIST
  • TH32CS_SNAPMODULE
  • TH32CS_SNAPPROCESS
  • TH32CS_SNAPTHREAD

The TH32CS_SNAPHEAPLIST and TH32CS_SNAPMODULE values are process specific. When these values are specified, the heap and module lists of the specified process are included in the snapshot. If you specify zero as the process identifier, the current process is used. The TH32CS_SNAPTHREAD value always creates a system-wide snapshot even if a process identifier is passed to CreateToolhelp32Snapshot.

To enumerate the heap or module state for all processes, specify the TH32CS_SNAPALL value and the process identifier of the current process. Then, for each additional process in the snapshot, call CreateToolhelp32Snapshot again, specifying its process identifier and the TH32CS_SNAPHEAPLIST or TH32CS_SNAPMODULE value.

You can retrieve an extended error status code for CreateToolhelp32Snapshot by using the GetLastError function.

When your process finishes using a snapshot, destroy it using the CloseHandle function. If you do not destroy a snapshot, the process will leak memory until the it exits, at which time the system reclaims the memory.

Note

The snapshot handle acts like a file handle and is subject to the same rules regarding the processes and threads in which it can be used. To specify that the handle is inheritable, create the snapshot using the TH32CS_INHERIT value.

 

Taking a Snapshot and Viewing Processes