NAME
Win32::Process - Create and manipulate processes.
SYNOPSIS
my
$ProcessObj
;
sub
ErrorReport{
Win32::FormatMessage( Win32::GetLastError() );
}
Win32::Process::Create(
$ProcessObj
,
"C:\\winnt\\system32\\notepad.exe"
,
"notepad temp.txt"
,
0,
NORMAL_PRIORITY_CLASS,
"."
)||
die
ErrorReport();
$ProcessObj
->Suspend();
$ProcessObj
->Resume();
$ProcessObj
->Wait(INFINITE);
DESCRIPTION
This module provides access to the process control functions in the Win32 API.
METHODS
- Win32::Process::Create($obj,$appname,$cmdline,$iflags,$cflags,$curdir)
-
Creates a new process.
Args:
$obj
container
for
process object
$appname
full path name of executable module (can be
'undef'
)
$cmdline
command line args (can be
'undef'
)
$iflags
flag: inherit calling processes handles or not
$cflags
flags
for
creation (see exported vars below)
$curdir
working dir of new process
Returns non-zero on success, 0 on failure.
$appname can be 'undef' to allow $cmdline to specify the command without an absolute path; $ENV{PATH} will be searched to find the executable. eg:
Win32::Process::Create(
$ProcessObj
,
undef
,
"netstat -an"
,
# finds "netstat.exe" from $ENV{PATH}
0,
NORMAL_PRIORITY_CLASS,
"."
);
See Microsoft's CreateProcess() docs for details. For instance, only .exe's will be searched; if you are trying to run a .com or .bat, you'll have to specify the extension, eg:
Win32::Process::Create(
$ProcessObj
,
undef
,
"tree.com /A /F"
,
[..]
- Win32::Process::Open($obj,$pid,$iflags)
-
Creates a handle Perl can use to an existing process as identified by $pid. The $iflags is the inherit flag that is passed to OpenProcess. Currently Win32::Process objects created using Win32::Process::Open cannot Suspend or Resume the process. All other calls should work.
Win32::Process::Open returns non-zero on success, 0 on failure.
- Win32::Process::KillProcess($pid, $exitcode)
-
Terminates any process identified by $pid. $exitcode will be set to the exit code of the process.
- $ProcessObj->Suspend()
-
Suspend the process associated with the $ProcessObj.
- $ProcessObj->Resume()
-
Resume a suspended process.
- $ProcessObj->Kill($exitcode)
-
Kill the associated process, have it terminate with exit code $ExitCode.
- $ProcessObj->GetPriorityClass($class)
-
Get the priority class of the process.
- $ProcessObj->SetPriorityClass($class)
-
Set the priority class of the process (see exported values below for options). Note that the ABOVE_NORMAL_PRIORITY_CLASS and BELOW_NORMAL_PRIORITY_CLASS classes only work on Windows 2000 and later.
- $ProcessObj->GetProcessAffinityMask($processAffinityMask, $systemAffinityMask)
-
Get the process affinity mask. This is a bitvector in which each bit represents the processors that a process is allowed to run on.
- $ProcessObj->SetProcessAffinityMask($processAffinityMask)
-
Set the process affinity mask. Only available on Windows NT.
- $ProcessObj->GetExitCode($exitcode)
-
Retrieve the exitcode of the process. Will return STILL_ACTIVE if the process is still running. The STILL_ACTIVE constant is only exported by explicit request.
- $ProcessObj->Wait($timeout)
-
Wait for the process to die. $timeout should be specified in milliseconds. To wait forever, specify the constant
INFINITE
.Returns a false value if the process is still alive by the time timeout expires:
if
(
$process
->Wait(1) ) {
print
"Process is done\n"
;
}
else
{
print
"Process is still running\n"
;
}
- $ProcessObj->GetProcessID()
-
Returns the Process ID.
- Win32::Process::GetCurrentProcessID()
-
Returns the current process ID, which is the same as $$. But not on cygwin, where $$ is the cygwin-internal PID and not the windows PID. On cygwin GetCurrentProcessID() returns the windows PID as needed for all the Win32::Process functions.
EXPORTS
The following constants are exported by default:
CREATE_DEFAULT_ERROR_MODE
CREATE_NEW_CONSOLE
CREATE_NEW_PROCESS_GROUP
CREATE_NO_WINDOW
CREATE_SEPARATE_WOW_VDM
CREATE_SUSPENDED
CREATE_UNICODE_ENVIRONMENT
DEBUG_ONLY_THIS_PROCESS
DEBUG_PROCESS
DETACHED_PROCESS
HIGH_PRIORITY_CLASS
IDLE_PRIORITY_CLASS
INFINITE
NORMAL_PRIORITY_CLASS
REALTIME_PRIORITY_CLASS
THREAD_PRIORITY_ABOVE_NORMAL
THREAD_PRIORITY_BELOW_NORMAL
THREAD_PRIORITY_ERROR_RETURN
THREAD_PRIORITY_HIGHEST
THREAD_PRIORITY_IDLE
THREAD_PRIORITY_LOWEST
THREAD_PRIORITY_NORMAL
THREAD_PRIORITY_TIME_CRITICAL
The following additional constants are exported by request only:
ABOVE_NORMAL_PRIORITY_CLASS
BELOW_NORMAL_PRIORITY_CLASS
STILL_ACTIVE
LICENSE
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.