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

- NAME
- SYNOPSIS
- DESCRIPTION

- EXPORTS
- CONSTANTS
- STRUCTURES
- FUNCTIONS

- AUTHOR
- COPYRIGHT
- SEE ALSO

# 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

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

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