|
Win32API::ToolHelp - Perl extension for obtaining information about currently executing applications using the plain Win32 ToolHelp API |
Win32API::ToolHelp - Perl extension for obtaining information about currently executing applications using the plain Win32 ToolHelp API
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);
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.)
Nothing is exported by default. The following tags can be used to have sets of symbols exported:
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.
LF32_ constants are used as flags in the heap entry describing structure
HEAPENTRY32.
TH32CS_ constants are used by the CreateToolhelp32Snapshot function
to specify portions of the system to include in the snapshot.
TH32CS_SNAPHEAPLIST, TH32CS_SNAPMODULE,
TH32CS_SNAPPROCESS, and TH32CS_SNAPTHREAD.
THREAD_ constants are used as flags in the thread entry describing
structure THREADENTRY32.
IDLE_PRIORITY_CLASS,
NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base
priority level of 16 for REALTIME_PRIORITY_CLASS processes.
IDLE_PRIORITY_CLASS,
NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base
priority level of 31 for REALTIME_PRIORITY_CLASS processes.
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.)
LF32_ constants.
GlobalLock or LocalLock function is called on the block either
by the application or the DLL that the heap belongs to.
HF32_
constants.
Note: The modBaseAddr and hModule members are valid only
in the context of the process specified by th32ProcessID.
CreateProcess function.
THREAD_ constants.
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)CreateToolhelp32Snapshot function.
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.
TH32CS_ constants.
TH32CS_SNAPHEAPLIST
or TH32CS_SNAPMODULE value is specified. Otherwise, it is ignored.
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()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.
HEAPENTRY32 structure to be filled if the function
succeedes.
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.
CreateToolhelp32Snapshot function.
HEAPLIST32 structure to be filled if the function succeedes.
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.
CreateToolhelp32Snapshot function.
HEAPLIST32 structure to be filled if the function succeedes.
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)HEAPENTRY32 structure to be filled if the function
succeedes.
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.
CreateToolhelp32Snapshot function.
MODULEENTRY32 structure to be filled if the function
succeedes.
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.
CreateToolhelp32Snapshot function.
MODULEENTRY32 structure to be filled if the function
succeedes.
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.
CreateToolhelp32Snapshot function.
PROCESSENTRY32 structure to be filled if the function
succeedes.
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.
CreateToolhelp32Snapshot function.
PROCESSENTRY32 structure to be filled if the function
succeedes.
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)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.
CreateToolhelp32Snapshot function.
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.
CreateToolhelp32Snapshot function.
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.
Ferdinand Prantl <prantl@host.sk>
See http://prantl.host.sk/perl/modules/Win32API/ToolHelp for the most recent version.
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.
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 |