NAME

Win32API::ToolHelp - Perl extension for obtaining information about currently executing applications using the plain Win32 ToolHelp API

SYNOPSIS

  use Win32API::ToolHelp ':All';

  # --- prints names of all processes
  my $handle = CreateToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0);
  my $pe;
  Process32First($handle, $pe);
  do {
    print "$pe->{th32ProcessID}\t$pe->{szExeFile}\n";
  } while (Process32Next($handle, $pe));
  CloseToolhelp32Snapshot($handle);

  # --- prints names of the modules used by the current process
  my $handle = CreateToolhelp32Snapshot(TH32CS_SNAPMODULE, $$);
  my $me;
  Module32First($handle, $me);
  do {
    print "$me->{th32ModuleID}\t$me->{szModule}\n";
  } while (Module32Next($handle, $me));
  CloseToolhelp32Snapshot($handle);

DESCRIPTION

The functions provided by the ToolHelp library make it easier for you to obtain information about currently executing applications. These functions are designed to streamline the creation of tools, specifically debuggers.

It covers enumerating the currently running processes and their modules, traversing heaps, listing threads and taking snapshots of memory of the currently running processes. The results are return in a form as close as possible to the original Win32 API (simple types are returned as scalars of the same type and structures are returned as references to hashes with keys of the same names as the members in the original structures have). There are all functions of the ToolHelp library implemented in this module.

The support for the ToolHelp library API is included in Windows 95 or higher or in Windows 2000 or higher. It is not included in Windows NT. See the module Win32API::ProcessStatus for the similar functionality for Windows NT.

(Note that much of the following documentation refers to the behavior of the underlying Win32 ToolHelp API calls which may vary in its current and future versions without any changes to this module. Therefore you should check the Win32 ToolHelp API documentation in MSDN directly when needed.)

EXPORTS

Nothing is exported by default. The following tags can be used to have sets of symbols exported:

:Func

The basic function names: CloseToolhelp32Snapshot CreateToolhelp32Snapshot GetLastToolHelpError Heap32First Heap32ListFirst Heap32ListNext Heap32Next Module32First Module32Next Process32First Process32Next SetLastToolHelpError Thread32First Thread32Next Toolhelp32ReadProcessMemory.

:FuncA

The ANSI function names: Module32FirstA Module32NextA Process32FirstA Process32NextA.

:FuncW

The Unicode function names: Module32FirstW Module32NextW Process32FirstW Process32NextW.

:HF32_

The constants for identifying a heap type: HF32_DEFAULT HF32_SHARED.

:LF32_

The constants for finding a type of an allocated memory block: LF32_FIXED LF32_FREE LF32_MOVEABLE.

:TH32CS_

The constants for creating snapshots of a running system: TH32CS_INHERIT TH32CS_SNAPALL TH32CS_SNAPHEAPLIST TH32CS_SNAPMODULE TH32CS_SNAPMODULE32 TH32CS_SNAPPROCESS TH32CS_SNAPTHREAD.

:THREAD_

The constants defining the thread priority: THREAD_PRIORITY_LOWEST THREAD_PRIORITY_BELOW_NORMAL THREAD_PRIORITY_NORMAL THREAD_PRIORITY_HIGHEST THREAD_PRIORITY_ABOVE_NORMAL THREAD_PRIORITY_ERROR_RETURN THREAD_PRIORITY_TIME_CRITICAL THREAD_PRIORITY_IDLE.

CONSTANTS

The constants described here and exported by this module are used only in its structures and functions. See the module Win32API::Const for the common Win32 constants.

HF32_ constants are used as flags in the heap list describing structure HEAPLIST32.

HF32_DEFAULT

Process's default heap.

HF32_SHARED

Heap shared among processes.

LF32_ constants are used as flags in the heap entry describing structure HEAPENTRY32.

LF32_FIXED

The memory block has a fixed (unmovable) location.

LF32_FREE

The memory block is not used.

LF32_MOVEABLE

The memory block location can be moved.

TH32CS_ constants are used by the CreateToolhelp32Snapshot function to specify portions of the system to include in the snapshot.

TH32CS_INHERIT

Indicates that the snapshot handle is to be inheritable.

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_SNAPPROCESS

Includes the process list in the snapshot.

TH32CS_SNAPTHREAD

Includes the thread list in the snapshot.

THREAD_ constants are used as flags in the thread entry describing structure THREADENTRY32.

THREAD_PRIORITY_IDLE

Indicates a base priority level of 1 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base priority level of 16 for REALTIME_PRIORITY_CLASS processes.

THREAD_PRIORITY_LOWEST

Indicates 2 points below normal priority for the priority class.

THREAD_PRIORITY_BELOW_NORMAL

Indicates one point below normal priority for the priority class.

THREAD_PRIORITY_NORMAL

Indicates normal priority for the priority class.

THREAD_PRIORITY_ABOVE_NORMAL

Indicates one point above normal priority for the priority class.

THREAD_PRIORITY_HIGHEST

Indicates two points above normal priority for the priority class.

THREAD_PRIORITY_TIME_CRITICAL

Indicates a base priority level of 15 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base priority level of 31 for REALTIME_PRIORITY_CLASS processes.

STRUCTURES

The structures that act as input and ouput parameters are handled as hashes with keys of the same names as the members in the original structures have. It allows those already familiar with the Win32 API to get off to a quick start and occasionally use the original MSDN documentation to the API.

(Obviously the member dwSize is omitted as there is no need to pre-allocate the actual size for the output hash in Perl.)

HEAPENTRY32

Describes one entry (block) of a heap that is being examined.

hHandle

Handle to the heap block.

dwAddress

Linear address of the start of the block.

dwBlockSize

Size, in bytes, of the heap block.

dwFlags

Flags. The values available are listed in the description of LF32_ constants.

dwLockCount

Lock count on the memory block. The lock count is incremented each time the GlobalLock or LocalLock function is called on the block either by the application or the DLL that the heap belongs to.

dwResvd

Reserved; do not use.

th32ProcessID

Identifier of the process to examine.

th32HeapID

Heap identifier in the owning process context. The contents of this member has meaning only to the tool help functions. It is not a handle, nor is it usable by functions other than the ToolHelp functions.

HEAPLIST32

Describes one entry (block) of a heap that is being examined.

dwProcessID

Identifier of the process to examine.

th32HeapID

Heap identifier in the owning process context. The contents of this member has meaning only to the tool help functions. It is not a handle, nor is it usable by functions other than the ToolHelp functions.

dwFlags

Flags. The values available are listed in the description of HF32_ constants.

MODULEENTRY32

Describes an entry from a list that enumerates the modules used by a specified process.

th32ModuleID

Module identifier in the context of the owning process. The contents of this member has meaning only to the tool help functions. It is not a handle, nor is it usable by functions other than the ToolHelp functions.

th32ProcessID

Identifier of the process being examined.

GlblcntUsage

Global usage count on the module.

ProccntUsage

Module usage count in the context of the owning process.

modBaseAddr

Base address of the module in the context of the owning process.

modBaseSize

Size, in bytes, of the module.

hModule

Handle to the module in the context of the owning process.

szModule

String containing the module name.

szExePath

String containing the location (path) of the module.

Note: The modBaseAddr and hModule members are valid only in the context of the process specified by th32ProcessID.

PROCESSENTRY32

Describes an entry from a list that enumerates the processes residing in the system address space when a snapshot was taken.

cntUsage

Number of references to the process. A process exists as long as its usage count is nonzero. As soon as its usage count becomes zero, a process terminates.

th32ProcessID

Identifier of the process.

th32DefaultHeapID

Identifier of the default heap for the process. The contents of this member has meaning only to the tool help functions. It is not a handle, nor is it usable by functions other than the ToolHelp functions.

th32ModuleID

Module identifier of the process. The contents of this member has meaning only to the tool help functions. It is not a handle, nor is it usable by functions other than the ToolHelp functions.

cntThreads

Number of execution threads started by the process.

th32ParentProcessID

Identifier of the process that created the process being examined.

pcPriClassBase

Base priority of any threads created by this process.

dwFlags

Reserved; do not use.

szExeFile

Path and filename of the executable file for the process.

THREADENTRY32

Describes an entry from a list that enumerates the threads executing in the system when a snapshot was taken.

cntUsage

Number of references to the thread. A thread exists as long as its usage count is nonzero. As soon as its usage count becomes zero, a thread terminates.

th32ThreadID

Identifier of the thread. This identifier is compatible with the thread identifier returned by the CreateProcess function.

th32OwnerProcessID

Identifier of the process that created the thread.

tpBasePri

Initial priority level assigned to a thread. The values available are listed in the description of THREAD_ constants.

tpDeltaPri

Change in the priority level of a thread. This value is a signed delta from the base priority level assigned to the thread.

dwFlags

Reserved; do not use.

FUNCTIONS

ToolHelp functions return either a handle to access its structures or a boolean status of the function's result. To retrieve an extended information about the error if it occurs use the GetLastToolHelpError function. If no error happens GetLastToolHelpError still returns the last occured error code (successful calls do not modify the last stored error code). You can set or reset the internally stored error code explicitely by the function SetLastToolHelpError.

To use something more convenient than numbers for comparisons of return values and error codes see the module Win32API::Const.

There are couple of functions that are implemented as ANSI versions on Windows 95 or higher and as both ANSI and Unicode versions on Windows 2000 or higher. ANSI versions are named XxxA and Unicode versions XxxW just like the Win32 ToolHelp originals. If you omit the last A/W letter the ANSI version is used as strings are ANSI in Perl's internals. Results of Unicode functions are converted into ANSI before returned.

CloseToolhelp32Snapshot($hSnapshot)

Closes an open system snapshot handle.

hSnapshot [IN]

Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.

[RETVAL]

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastToolHelpError.

Windows NT/2000/XP: Closing an invalid handle raises an exception when the application is running under a debugger. This includes closing a handle twice, for example.

It invalidates the specified system snapshot handle, decrements the object's handle count, and performs object retention checks. After the last handle to an object is closed, the object is removed from the system.

CreateToolhelp32Snapshot($dwFlags, $th32ProcessID)

Takes a snapshot of the processes and the heaps, modules, and threads used by the processes.

dwFlags [IN]

Specifies portions of the system to include in the snapshot. The values available are listed in the description of TH32CS_ constants.

th32ProcessID [IN]

Specifies the process identifier. This parameter can be zero to indicate the current process. This parameter is used when the TH32CS_SNAPHEAPLIST or TH32CS_SNAPMODULE value is specified. Otherwise, it is ignored.

[RETVAL]

Returns an open handle to the specified snapshot if successful or 0xffffffff (INVALID_HANDLE_VALUE) otherwise.

The snapshot taken by this function is examined by the other ToolHelp 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 which processes and threads it is valid in.

To retrieve an extended error status code generated by this function, use the GetLastToolHelpError function.

To destroy the snapshot, use the CloseToolhelp32Snapshot function. Alternatively you can use the general CloseHandle function.

GetLastToolHelpError()

Retrieves the last-error code value of the ToolHelp functions. The last-error code is stored if a function fails and remembered until another function calls when it is overwritten by the new error code. Successful calls do not modify this internally stored last-error code value.

[RETVAL]

The return value is the last-error code value. Functions set this value by calling the SetLastToolHelpError function if they fail.

To obtain an error string for system error codes, use the FormatMessage function. For a complete list of error codes, see the System Error Codes section in MSDN. There are pre-defined constants for the Win32 system error codes in the module <Win32API::Const>.

You should call the GetLastToolHelpError function immediately when a function's return value indicates that such a call will return useful data. A subsequent call to another ToolHelp function could fail as well and GetLastToolHelpError would return its error code instead of the former one.

Function failure is typically indicated by a return value such as zero, undefined, or –1 (0xffffffff).

Error codes returned are 32-bit values with the most significant bit set to 1 (bit 31 is the most significant bit). Zero code is ERROR_SUCCESS.

Heap32First($lphe, $th32ProcessID, $th32HeapID)

Retrieves information about the first block of a heap that has been allocated by a process.

lphe [OUT]

Reference to a HEAPENTRY32 structure to be filled if the function succeedes.

th32ProcessID [IN]

Identifier of the process context that owns the heap.

th32HeapID [IN]

Identifier of the heap to enumerate.

[RETVAL]

Returns TRUE if information for the first heap block has been copied to the buffer or FALSE otherwise. The 18 (ERROR_NO_MORE_FILES) error value is returned by the GetLastToolHelpError function if the heap is invalid or empty.

To access subsequent blocks of the same heap, use the Heap32Next function.

Heap32ListFirst($hSnapshot, $lphl)

Retrieves information about the first heap that has been allocated by a specified process.

hSnapshot [IN]

Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.

lphl [OUT]

Reference to a HEAPLIST32 structure to be filled if the function succeedes.

[RETVAL]

Returns TRUE if the first entry of the heap list has been copied to the buffer or FALSE otherwise. The 18 (ERROR_NO_MORE_FILES) error value is returned by the GetLastToolHelpError function when no heap list exists or the snapshot does not contain heap list information.

To retrieve information about other heaps in the heap list, use the Heap32ListNext function.

Heap32ListNext($hSnapshot, $lphl)

Retrieves information about the next heap that has been allocated by a process.

hSnapshot [IN]

Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.

lphl [OUT]

Reference to a HEAPLIST32 structure to be filled if the function succeedes.

[RETVAL]

Returns TRUE if the next entry of the heap list has been copied to the buffer or FALSE otherwise. The 18 (ERROR_NO_MORE_FILES) error value is returned by the GetLastToolHelpError function when no more entries in the heap list exist.

To retrieve information about the first heap in a heap list, use the Heap32ListFirst function.

Heap32Next($lphe)

Retrieves information about the next block of a heap that has been allocated by a process.

lphe [IN/OUT]

Reference to a HEAPENTRY32 structure to be filled if the function succeedes.

[RETVAL]

Returns TRUE if information about the next block in the heap has been copied to the buffer or FALSE otherwise. The GetLastToolHelpError function returns 18 (ERROR_NO_MORE_FILES) when no more objects in the heap exist and 13 (ERROR_INVALID_DATA) if the heap appears to be corrupt or is modified during the walk in such a way that Heap32Next cannot continue.

To retrieve information for the first block of a heap, use the Heap32First function.

Module32First($hSnapshot, $lpme)

Retrieves information about the first module associated with a process.

hSnapshot [IN]

Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.

lpme [OUT]

Reference to a MODULEENTRY32 structure to be filled if the function succeedes.

[RETVAL]

Returns TRUE if the first entry of the module list has been copied to the buffer or FALSE otherwise. The 18 (ERROR_NO_MORE_FILES) error value is returned by the GetLastToolHelpError function if no modules exist or the snapshot does not contain module information.

This method actually calls the ANSI version Module32FirstA, use Module32FirstW to call the Unicode version instead. To retrieve information about other modules associated with the specified process, use the Module32Next function.

Module32Next($hSnapshot, $lpme)

Retrieves information about the next module associated with a process or thread.

hSnapshot [IN]

Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.

lpme [OUT]

Reference to a MODULEENTRY32 structure to be filled if the function succeedes.

[RETVAL]

Returns TRUE if the next entry of the module list has been copied to the buffer or FALSE otherwise. The 18 (ERROR_NO_MORE_FILES) error value is returned by the GetLastToolHelpError function if no more modules exist.

This method actually calls the ANSI version Module32NextA, use Module32NextW to call the Unicode version instead. To retrieve information about first module associated with a process, usethe Module32First function.

Process32First($hSnapshot, $lppe)

Retrieves information about the first process encountered in a system snapshot.

hSnapshot [IN]

Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.

lppe [OUT]

Reference to a PROCESSENTRY32 structure to be filled if the function succeedes.

[RETVAL]

Returns TRUE if the first entry of the process list has been copied to the buffer or FALSE otherwise. The 18 (ERROR_NO_MORE_FILES) error value is returned by the GetLastToolHelpError function if no processes exist or the snapshot does not contain process information.

This method actually calls the ANSI version Process32FirstA, use Process32FirstW to call the Unicode version instead. To retrieve information about other processes recorded in the same snapshot, use the Process32Next function.

Process32Next($hSnapshot, $lppe)

Retrieves information about the next process recorded in a system snapshot.

hSnapshot [IN]

Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.

lppe [OUT]

Reference to a PROCESSENTRY32 structure to be filled if the function succeedes.

[RETVAL]

Returns TRUE if the next entry of the process list has been copied to the buffer or FALSE otherwise. The 18 (ERROR_NO_MORE_FILES) error value is returned by the GetLastToolHelpError function if no processes exist or the snapshot does not contain process information.

This method actually calls the ANSI version Process32NextA, use Process32NextW to call the Unicode version instead. To retrieve information about the first process recorded in a snapshot, use the Process32First function.

SetLastToolHelpError($dwError)

Sets the last-error code value of the ToolHelp functions.

dwError [IN]

Specifies the last-error code.

Error codes returned are 32-bit values with the most significant bit set to 1 (bit 31 is the most significant bit). Zero code is ERROR_SUCCESS.

Applications can retrieve the value saved by this function by using the GetLastToolHelpError function. The use of GetLastToolHelpError is optional; an application can call it to find out the specific reason for a function failure.

Thread32First($hSnapshot, $lpte)

Retrieves information about the first thread of any process encountered in a system snapshot.

hSnapshot [IN]

Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.

lpte [OUT]

Reference to a THREADENTRY32 structure to be filled if the function succeedes.

[RETVAL]

Returns TRUE if the first entry of the thread list has been copied to the buffer or FALSE otherwise. The 18 (ERROR_NO_MORE_FILES) error value is returned by the GetLastToolHelpError function if no threads exist or the snapshot does not contain thread information.

To retrieve information about other threads recorded in the same snapshot, use the Thread32Next function.

Thread32Next($hSnapshot, $lpte)

Retrieves information about the next thread of any process encountered in the system memory snapshot.

hSnapshot [IN]

Handle to the snapshot returned from a previous call to the CreateToolhelp32Snapshot function.

lpte [OUT]

Reference to a THREADENTRY32 structure to be filled if the function succeedes.

[RETVAL]

Returns TRUE if the next entry of the thread list has been copied to the buffer or FALSE otherwise. The 18 (ERROR_NO_MORE_FILES) error value is returned by the GetLastToolHelpError function if no threads exist or the snapshot does not contain thread information.

To retrieve information about the first thread recorded in a snapshot, use the Thread32First function.

Toolhelp32ReadProcessMemory($th32ProcessID, $lpBaseAddress, $lpBuffer, $cbRead, $lpNumberOfBytesRead)

Copies memory allocated to another process into an application-supplied buffer.

th32ProcessID [IN]

Identifier of the process whose memory is being copied. This parameter can be zero to copy the memory of the current process.

lpBaseAddress [IN]

Base address in the specified process to read. Before transferring any data, the system verifies that all data in the base address and memory of the specified size is accessible for read access. If this is the case, the function proceeds. Otherwise, the function fails.

lpBuffer [OUT]

Reference to a scalar string that receives the contents of the address space of the specified process.

bcRead [IN]

Number of bytes to read from the specified process.

lpNumberOfBytesRead [OUT]

Number of bytes copied to the specified buffer. This parameter can be omitted if it is not needed.

[RETVAL]

Returns TRUE if successful.

AUTHOR

Ferdinand Prantl <prantl@host.sk>

See http://prantl.host.sk/perl/modules/Win32API/ToolHelp for the most recent version.

COPYRIGHT

Copyright (c) 2002, Ferdinand Prantl. All rights reserved.

Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Author makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

SEE ALSO

Win32API::ProcessStatus, Win32::Process, Win32::Job and Win32API::Const.

cpanm Win32API::ToolHelp

perl -MCPAN -e shell
install Win32API::ToolHelp