1Simple(3)             User Contributed Perl Documentation            Simple(3)
2
3
4

NAME

6       Proc::Simple -- launch and control background processes
7

SYNOPSIS

9          use Proc::Simple;
10
11          $myproc = Proc::Simple->new();        # Create a new process object
12
13          $myproc->start("shell-command-line"); # Launch an external program
14          $myproc->start("command",             # Launch an external program
15                         "param", ...);         # with parameters
16
17          $myproc->start(sub { ... });          # Launch a perl subroutine
18          $myproc->start(\&subroutine);         # Launch a perl subroutine
19          $myproc->start(\&subroutine,          # Launch a perl subroutine
20                         $param, ...);          # with parameters
21
22          $running = $myproc->poll();           # Poll Running Process
23
24          $exit_status = $myproc->wait();       # Wait until process is done
25
26          $proc->kill_on_destroy(1);            # Set kill on destroy
27          $proc->signal_on_destroy("KILL");     # Specify signal to be sent
28                                                # on destroy
29
30          $myproc->kill();                      # Kill Process (SIGTERM)
31
32
33
34          $myproc->kill("SIGUSR1");             # Send specified signal
35
36          $myproc->exit_status();               # Return exit status of process
37
38
39          Proc::Simple::debug($level);          # Turn debug on
40

DESCRIPTION

42       The Proc::Simple package provides objects mimicing real-life processes
43       from a user's point of view. A new process object is created by
44
45          $myproc = Proc::Simple->new();
46
47       Either external programs or perl subroutines can be launched and
48       controlled as processes in the background.
49
50       A 10-second sleep process, for example, can be launched as an external
51       program as in
52
53          $myproc->start("/bin/sleep 10");    # or
54          $myproc->start("/bin/sleep", "10");
55
56       or as a perl subroutine, as in
57
58          sub mysleep { sleep(shift); }    # Define mysleep()
59          $myproc->start(\&mysleep, 10);   # Launch it.
60
61       or even as
62
63          $myproc->start(sub { sleep(10); });
64
65       The start Method returns immediately after starting the specified
66       process in background, i.e. there's no blocking.  It returns 1 if the
67       process has been launched successfully and 0 if not.
68
69       The poll method checks if the process is still running
70
71          $running = $myproc->poll();
72
73       and returns 1 if it is, 0 if it's not. Finally,
74
75          $myproc->kill();
76
77       terminates the process by sending it the SIGTERM signal. As an option,
78       another signal can be specified.
79
80          $myproc->kill("SIGUSR1");
81
82       sends the SIGUSR1 signal to the running process. kill returns 1 if it
83       succeeds in sending the signal, 0 if it doesn't.
84
85       The methods are discussed in more detail in the next section.
86
87       A destructor is provided so that a signal can be sent to the forked
88       processes automatically should the process object be destroyed or if
89       the process exits. By default this behaviour is turned off (see the
90       kill_on_destroy and signal_on_destroy methods).
91

METHODS

93       The following methods are available:
94
95       new (Constructor)
96           Create a new instance of this class by writing
97
98             $proc = new Proc::Simple;
99
100           or
101
102             $proc = Proc::Simple->new();
103
104           It takes no arguments.
105
106       start
107           Launches a new process.  The "start()" method can be used to launch
108           both external programs (like "/bin/echo") or one of your self-
109           defined subroutines (like "foo()") in a new process.
110
111           For an external program to be started, call
112
113            $status = $proc->start("program-name");
114
115           If you want to pass a couple of parameters to the launched program,
116           there's two options: You can either pass them in one argument like
117           in
118
119            $status = $proc->start("/bin/echo hello world");
120
121           or in several arguments like in
122
123            $status = $proc->start("/bin/echo", "hello", "world");
124
125           Just as in Perl's function "system()", there's a big difference
126           between the two methods: If you provide one argument containing a
127           blank-separated command line, your shell is going to process any
128           meta-characters (if you choose to use some) before the process is
129           actually launched:
130
131            $status = $proc->start("/bin/ls -l /etc/initt*");
132
133           will expand "/etc/initt*" to "/etc/inittab" before running the "ls"
134           command. If, on the other hand, you say
135
136            $status = $proc->start("/bin/ls", "-l", "*");
137
138           the "*" will stay unexpanded, meaning you'll look for a file with
139           the literal name "*" (which is unlikely to exist on your system
140           unless you deliberately create confusingly named files :). For more
141           info on this, look up "perldoc -f exec".
142
143           If, on the other hand, you want to start a Perl subroutine in the
144           background, simply provide the function reference like
145
146            $status = $proc->start(\&your_function);
147
148           or supply an unnamed subroutine:
149
150            $status = $proc->start( sub { sleep(1) } );
151
152           You can also provide additional parameters to be passed to the
153           function:
154
155            $status = $proc->start(\&printme, "hello", "world");
156
157           The start Method returns immediately after starting the specified
158           process in background, i.e. non-blocking mode.  It returns 1 if the
159           process has been launched successfully and 0 if not.
160
161       poll
162           The poll method checks if the process is still running
163
164              $running = $myproc->poll();
165
166           and returns 1 if it is, 0 if it's not.
167
168       kill
169           The kill() method:
170
171              $myproc->kill();
172
173           terminates the process by sending it the SIGTERM signal. As an
174           option, another signal can be specified.
175
176              $myproc->kill("SIGUSR1");
177
178           sends the SIGUSR1 signal to the running process. kill returns 1 if
179           it succeeds in sending the signal, 0 if it doesn't.
180
181       kill_on_destroy
182           Set a flag to determine whether the process attached to this object
183           should be killed when the object is destroyed. By default, this
184           flag is set to false.  The current value is returned.
185
186             $current = $proc->kill_on_destroy;
187             $proc->kill_on_destroy(1); # Set flag to true
188             $proc->kill_on_destroy(0); # Set flag to false
189
190       signal_on_destroy
191           Method to set the signal that will be sent to the process when the
192           object is destroyed (Assuming kill_on_destroy is true). Returns the
193           current setting.
194
195             $current = $proc->signal_on_destroy;
196             $proc->signal_on_destroy("KILL");
197
198       redirect_output
199           Redirects stdout and/or stderr output to a file.  Specify undef to
200           leave the stderr/stdout handles of the process alone.
201
202             # stdout to a file, left stderr unchanged
203             $proc->redirect_output ("/tmp/someapp.stdout", undef);
204
205             # stderr to a file, left stdout unchanged
206             $proc->redirect_output (undef, "/tmp/someapp.stderr");
207
208             # stdout and stderr to a separate file
209             $proc->redirect_output ("/tmp/someapp.stdout", "/tmp/someapp.stderr");
210
211           Call this method before running the start method.
212
213       pid Returns the pid of the forked process associated with this object
214
215             $pid = $proc->pid;
216
217       t0  Returns the start time() of the forked process associated with this
218           object
219
220             $t0 = $proc->t0();
221
222       t1  Returns the stop time() of the forked process associated with this
223           object
224
225             $t1 = $proc->t1();
226
227       DESTROY (Destructor)
228           Object destructor. This method is called when the object is
229           destroyed (eg with "undef" or on exiting perl). If kill_on_destroy
230           is true the process associated with the object is sent the
231           signal_on_destroy signal (SIGTERM if undefined).
232
233       exit_status
234           Returns the exit status of the process as the $! variable
235           indicates.  If the process is still running, "undef" is returned.
236
237       wait
238           The wait method:
239
240              $exit_status = $myproc->wait();
241
242           waits until the process is done and returns its exit status.
243
244       debug
245           Switches debug messages on and off -- Proc::Simple::debug(1)
246           switches them on, Proc::Simple::debug(0) keeps Proc::Simple quiet.
247
248       cleanup
249           Proc::Simple keeps around data of terminated processes, e.g. you
250           can check via "t0()" and "t1()" how long a process ran, even if
251           it's long gone. Over time, this data keeps occupying more and more
252           memory and if you have a long-running program, you might want to
253           run "Proc::Simple->cleanup()" every once in a while to get rid of
254           data pertaining to processes no longer in use.
255

NOTE

257       Please keep in mind that there is no guarantee that the SIGTERM signal
258       really terminates a process. Processes can have signal handlers defined
259       that avoid the shutdown.  If in doubt, whether a process still exists,
260       check it repeatedly with the poll routine after sending the signal.
261

Shell Processes

263       If you pass a shell program to Proc::Simple, it'll use "exec()" to
264       launch it. As noted in Perl's "exec()" manpage, simple commands for the
265       one-argument version of "exec()" will be passed to "execvp()" directly,
266       while commands containing characters like ";" or "*" will be passed to
267       a shell to make sure those get the shell expansion treatment.
268
269       This has the interesting side effect that if you launch something like
270
271           $p->start("./womper *");
272
273       then you'll see two processes in your process list:
274
275           $ ps auxww | grep womper
276           mschilli  9126 11:21 0:00 sh -c ./womper *
277           mschilli  9127 11:21 0:00 /usr/local/bin/perl -w ./womper ...
278
279       A regular "kill()" on the process PID would only kill the first
280       process, but Proc::Simple's "kill()" will use a negative signal and
281       send it to the first process (9126). Since it has marked the process as
282       a process group leader when it created it previously (via setsid()),
283       this will cause both processes above to receive the signal sent by
284       "kill()".
285

Contributors

287       Tim Jenness  <t.jenness@jach.hawaii.edu>
288          did kill_on_destroy/signal_on_destroy/pid
289
290       Mark R. Southern <mark_southern@merck.com>
291          worked on EXIT_STATUS tracking
292
293       Tobias Jahn <tjahn@users.sourceforge.net>
294          added redirection to stdout/stderr
295
296       Clauss Strauch <Clauss_Strauch@aquila.fac.cs.cmu.edu> suggested the
297       multi-arg start()-methods.
298
299       Chip Capelik contributed a patch with the wait() method.
300
301       Jeff Holt provided a patch for time tracking with t0() and t1().
302
303       Brad Cavanagh fixed RT33440 (unreliable $?)
304

AUTHOR

306           1996, Mike Schilli <cpan@perlmeister.com>
307

LICENSE

309       Copyright 1996-2011 by Mike Schilli, all rights reserved.  This program
310       is free software, you can redistribute it and/or modify it under the
311       same terms as Perl itself.
312
313
314
315perl v5.34.0                      2021-07-22                         Simple(3)
Impressum