summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/site/lib/Win32/Process.pm
blob: 0f2a681d51b672767ceb6692546f3b733652bb6b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
package Win32::Process;

require Exporter;
require DynaLoader;
@ISA = qw(Exporter DynaLoader);

$VERSION = '0.16';

# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.
@EXPORT = qw(
	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
);

@EXPORT_OK = qw(
	STILL_ACTIVE
	ABOVE_NORMAL_PRIORITY_CLASS
	BELOW_NORMAL_PRIORITY_CLASS
);

sub AUTOLOAD {
    # This AUTOLOAD is used to 'autoload' constants from the constant()
    # XS function.
    my($constname);
    ($constname = $AUTOLOAD) =~ s/.*:://;
    local $! = 0;
    my $val = constant($constname);
    if ($! != 0) {
        my ($pack,$file,$line) = caller;
        die "Your vendor has not defined Win32::Process macro $constname, used at $file line $line.";
    }
    eval "sub $AUTOLOAD { $val }";
    goto &$AUTOLOAD;
} # end AUTOLOAD

bootstrap Win32::Process;

# Win32::IPC > 1.02 uses the get_Win32_IPC_HANDLE method:
*get_Win32_IPC_HANDLE = \&get_process_handle;

1;
__END__

=head1 NAME

Win32::Process - Create and manipulate processes.

=head1 SYNOPSIS

    use Win32::Process;
    use Win32;

    sub ErrorReport{
	print 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);

=head1  DESCRIPTION

This module provides access to the process control functions in the
Win32 API.

=head1 METHODS

=over 8

=item 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
	$cmdline	command line args
	$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.

=item 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.

=item Win32::Process::KillProcess($pid, $exitcode)

Terminates any process identified by $pid.  $exitcode will be set to
the exit code of the process.

=item $ProcessObj->Suspend()

Suspend the process associated with the $ProcessObj.

=item $ProcessObj->Resume()

Resume a suspended process.

=item $ProcessObj->Kill($exitcode)

Kill the associated process, have it terminate with exit code $ExitCode.

=item $ProcessObj->GetPriorityClass($class)

Get the priority class of the process.

=item $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.

=item $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.

=item $ProcessObj->SetProcessAffinityMask($processAffinityMask)

Set the process affinity mask.  Only available on Windows NT.

=item $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.

=item $ProcessObj->Wait($timeout)

Wait for the process to die.  $timeout should be specified in milliseconds.
To wait forever, specify the constant C<INFINITE>.

=item $ProcessObj->GetProcessID()

Returns the Process ID.

=item 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.

=back

=head1 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

=head1 LICENSE

This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut