|
Win32API::Process - Perl extension for handling the processes using the plain Win32 API |
Win32API::Process - Perl extension for handling the processes using the plain Win32 API
use Win32API::Process ':All';
# --- opens handle to the current process my $handle = OpenProcess(PROCESS_ALL_ACCESS, 0, $$); CloseProcess($handle);
The Process functions exposes the part of Win32 API handling the processes.
It contains just process opening an terminating functionality
in the meanwhile. It is supposed to be used
with the Win32API::ProcessStatus module or modules that need handles
to processes on their interfaces.
(Note that much of the following documentation refers to the behavior of the underlying Win32 API calls which may vary in its current and future versions without any changes to this module. Therefore you should check the Win32 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.
PROCESS_ constants are used as flags in the process handlingopening functions.
CreateRemoteThread function
to create a thread in the process.
DuplicateHandle function to duplicate a handle.
GetExitCodeProcess
and GetPriorityClass functions to read information from the process object.
AssignProcessToJobObject
and SetProcessWorkingSetSize functions to set memory limits.
SetPriorityClass function
to set the priority class of the process.
TerminateProcess function
to terminate the process.
VirtualProtectEx
and WriteProcessMemory functions to modify the virtual memory
of the process.
ReadProcessMemory function
to read from the virtual memory of the process.
WriteProcessMemory function
to write to the virtual memory of the process.
DELETE, READ_CONTROL, WRITE_DAC, and WRITE_OWNER access.
Process functions return either a boolean status of the function's
result or a handle to a process. To retrieve an extended information
about the error if it occurs use the GetLastProcessError function.
If no error happens GetLastProcessError 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 SetLastProcessError.
To use something more convenient than numbers for comparisons of return
values and error codes see the module Win32API::Const.
CloseProcess($hProcess)GetLastProcessError.
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 process 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.
GetLastProcessError()SetLastProcessError 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 GetLastProcessError function immediately when
a function's return value indicates that such a call will return useful data.
A subsequent call to another Process function could fail as well
and GetLastProcessError 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.
PROCESS__ constants.
GetLastProcessError.
The handle returned by the OpenProcess function can be used in any function
that requires a handle to a process, such as the wait functions, provided
the appropriate access rights were requested.
When you are finished with the handle, be sure to close it using
the CloseProcess or CloseHandle function.
SetLastProcessError($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 GetLastProcessError function. The use of GetLastProcessError
is optional; an application can call it to find out the specific reason
for a function failure.
GetExitCodeProcess function to retrieve
the process's exit value. Use the GetExitCodeThread function to retrieve
a thread's exit value.
GetLastProcessError.
The TerminateProcess function is used to unconditionally cause a process
to exit. Use it only in extreme circumstances. The state of global data
maintained by dynamic-link libraries (DLLs) may be compromised if
TerminateProcess is used rather than ExitProcess.
TerminateProcess causes all threads within a process to terminate,
and causes a process to exit, but DLLs attached to the process are
not notified that the process is terminating.
Terminating a process causes the following:
All of the object handles opened by the process are closed.
All of the threads in the process terminate their execution.
The state of the process object becomes signaled, satisfying any threads that had been waiting for the process to terminate.
The states of all threads of the process become signaled, satisfying any threads that had been waiting for the threads to terminate.
The termination status of the process changes from STILL_ACTIVE to the exit
value of the process.
Terminating a process does not cause child processes to be terminated.
Terminating a process does not necessarily remove the process object from the system. A process object is deleted when the last handle to the process is closed.
Terminating a process does not generate notifications for WH_CBT hook
procedures.
Ferdinand Prantl <prantl@host.sk>
See http://prantl.host.sk/perl/modules/Win32API/Process 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::Process - Perl extension for handling the processes using the plain Win32 API |