Win32API::ProcessStatus - Perl extension for obtaining information about processes using the plain Win32 PSAPI
use Win32API::ProcessStatus ':All'; # --- prints IDs of all processes my $IDs; EnumerateProceses($IDs); foreach my $ID (@$IDs) { print "$ID "; }
The ProcessStatus helper functions make it easier for you to obtain information about processes.
It covers enumerating the currently running processes and their modules. 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, arrays as references to arrays and structures as references to hashes with keys of the same names as the members of the original structures have). There are only process and module handling functions of the ProcessStatus helper implemented in this module (in the meanwhile).
These functions are available in Psapi.dll, which is included in Windows 2000 or higher. To use these functions on Windows NT, you must obtain the redistributable version of this DLL. It is not included in Windows 95 or higher. See the module Win32API::ToolHelp for the similar functionality for Windows 95 or higher.
(Note that much of the following documentation refers to the behavior of the underlying Win32 ProcessStatus API calls which may vary in its current and future versions without any changes to this module. Therefore you should check the Win32 ProcessStatus 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 basic function names: EnumProcesses EnumProcessModules GetLastProcessStatusError GetModuleBaseName GetModuleFileNameEx GetModuleInformation SetLastProcessStatusError.
The ANSI function names: GetModuleBaseNameA GetModuleFileNameExA.
The Unicode function names: GetModuleBaseNameW GetModuleFileNameExW.
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.
Contains the module load address, size, and entry point.
The load address of the module.
The size, in bytes, of the linear space that the module occupies.
The entry point of the module.
The load address of a module is the same as the HMODULE value. The information returned in the SizeOfImage and EntryPoint members comes from the module's Portable Executable (PE) header. The module entry point is the location called during process startup, thread startup, process shutdown, and thread shutdown. While this is not the address of the DllMain function, it should be close enough for most purposes.
HMODULE
SizeOfImage
EntryPoint
DllMain
ProcessStatus functions return either a boolean status of the function's result or a number of characters filled into the output buffer. To retrieve an extended information about the error if it occurs use the GetLastProcessStatusError function. If no error happens GetLastProcessStatusError 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 SetLastProcessStatusError.
GetLastProcessStatusError
SetLastProcessStatusError
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 ProcessStatus 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.
Retrieves the process identifier for each process object in the system.
Reference to an array that receives the list of process identifiers.
Specifies the size, in bytes, of the lpidProcess array. It defaults to 4096 (1024 * sizeof(DWORD)) if omitted.
4096 (1024 * sizeof(DWORD))
Receives the number of bytes returned in the lpidProcess array. It can be omitted if not needed.
lpidProcess
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastProcessStatusError.
It is a good idea to give EnumProcesses a large array of DWORD values, because it is hard to predict how many processes there will be at the time you call EnumProcesses. To determine how many processes were enumerated by the call to EnumProcesses, divide the resulting value in the cbNeeded parameter by sizeof(DWORD). There is no indication given when the buffer is too small to store all process identifiers.
EnumProcesses
DWORD
cbNeeded
sizeof(DWORD)
To obtain process handles for the processes whose identifiers you have just obtained, call the OpenProcess function.
OpenProcess
Retrieves a handle for each module in the specified process.
Handle to the process.
Reference to the array that receives the list of module handles.
Specifies the size, in bytes, of the lphModule array. It defaults to 4096 (1024 * sizeof(DWORD)) if omitted.
lphModule
Receives the number of bytes required to store all module handles in the lphModule array. It can be omitted if not needed.
It is a good idea to give EnumProcessModules a large array of HMODULE values, because it is hard to predict how many modules there will be in the process at the time you call EnumProcessModules. To determine if the lphModule array is too small to hold all module handles for the process, compare the value returned in lpcbNeeded with the value specified in cb. If lpcbNeeded is greater than cb, increase the size of the array and call EnumProcessModules again.
EnumProcessModules
lpcbNeeded
cb
To determine how many modules were enumerated by the call to EnumProcessModules, divide the resulting value in the lpcbNeeded parameter by sizeof(HMODULE).
sizeof(HMODULE)
Retrieves the last-error code value of the ProcessStatus 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.
The return value is the last-error code value. Functions set this value by calling the SetLastProcessStatusError 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.
FormatMessage
You should call the GetLastProcessStatusError function immediately when a function's return value indicates that such a call will return useful data. A subsequent call to another ProcessStatus function could fail as well and GetLastProcessStatusError 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.
ERROR_SUCCESS
Retrieves the base name of the specified module.
Handle to the process that contains the module.
Handle to the module.
Reference to the buffer that receives the base name of the module. If the base name is longer than maximum number of characters specified by the nSize parameter, the base name is truncated.
nSize
Specifies the maximum number of characters to copy to the lpBaseName buffer. It defaults to MAX_PATH if omitted.
lpBaseName
MAX_PATH
If the function succeeds, the return value specifies the length of the string copied to the buffer. If the function fails, the return value is zero. To get extended error information, call GetLastProcessStatusError.
Retrieves the fully qualified path for the specified module.
Reference to the buffer that receives the fully qualified path to the module. If the file name is longer than maximum number of characters specified by the nSize parameter, the file name is truncated.
Specifies the maximum number of characters to copy to the lpFilename buffer. It defaults to MAX_PATH if omitted.
lpFilename
Retrieves information about the specified module in the MODULEINFO structure.
MODULEINFO
Reference to the MODULEINFO structure that receives information about the module.
(Obviously the parameter cbSize from the original Win32 function is omitted as there is no need to specify the size of the MODULEINFO structure returned as a hash in Perl.)
cbSize
Sets the last-error code value of the ProcessStatus functions.
Specifies the last-error code.
Applications can retrieve the value saved by this function by using the GetLastProcessStatusError function. The use of GetLastProcessStatusError is optional; an application can call it to find out the specific reason for a function failure.
Original Author: Ferdinand Prantl <prantl@host.sk>
Current Maintainer: Graham Ollis <plicease@cpan.org>
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.
Win32API::ToolHelp, Win32::Process, Win32::Job and Win32API::Const.
To install Win32API::ProcessStatus, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Win32API::ProcessStatus
CPAN shell
perl -MCPAN -e shell install Win32API::ProcessStatus
For more information on module installation, please visit the detailed CPAN module installation guide.