SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE




YUM REPOSITORY

 
 

MAN page from Mandriva 2010 perl-Proc-Simple-1.260.0-1mdv2010.0.noarch.rpm

Simple

Section: User Contributed Perl Documentation (3)
Updated: 2009-07-08
Index 

NAME

Proc::Simple -- launch and control background processes 

SYNOPSIS

   use Proc::Simple;   $myproc = Proc::Simple->new();        # Create a new process object   $myproc->start("shell-command-line"); # Launch an external program   $myproc->start("command",             # Launch an external program                  "param", ...);         # with parameters                                           $myproc->start(sub { ... });          # Launch a perl subroutine   $myproc->start(\&subroutine);         # Launch a perl subroutine   $myproc->start(\&subroutine,          # Launch a perl subroutine                  $param, ...);          # with parameters   $running = $myproc->poll();           # Poll Running Process   $exit_status = $myproc->wait();       # Wait until process is done   $proc->kill_on_destroy(1);            # Set kill on destroy   $proc->signal_on_destroy("KILL");     # Specify signal to be sent                                         # on destroy   $myproc->kill();                      # Kill Process (SIGTERM)   $myproc->kill("SIGUSR1");             # Send specified signal   $myproc->exit_status();               # Return exit status of process   Proc::Simple::debug($level);          # Turn debug on
 

DESCRIPTION

The Proc::Simple package provides objects mimicing real-lifeprocesses from a user's point of view. A new process object is created by

   $myproc = Proc::Simple->new();

Either external programs or perl subroutines can be launched andcontrolled as processes in the background.

A 10-second sleep process, for example, can be launched as an external program as in

   $myproc->start("/bin/sleep 10");    # or   $myproc->start("/bin/sleep", "10");

or as a perl subroutine, as in

   sub mysleep { sleep(shift); }    # Define mysleep()   $myproc->start(\&mysleep, 10);   # Launch it.

or even as

   $myproc->start(sub { sleep(10); });

The start Method returns immediately after starting thespecified process in background, i.e. there's no blocking.It returns 1 if the process has been launchedsucessfully and 0 if not.

The poll method checks if the process is still running

   $running = $myproc->poll();

and returns 1 if it is, 0 if it's not. Finally,

   $myproc->kill();

terminates the process by sending it the SIGTERM signal. As anoption, another signal can be specified.

   $myproc->kill("SIGUSR1");

sends the SIGUSR1 signal to the running process. kill returns 1 ifit succeeds in sending the signal, 0 if it doesn't.

The methods are discussed in more detail in the next section.

A destructor is provided so that a signal can be sent tothe forked processes automatically should the process object bedestroyed or if the process exits. By default thisbehaviour is turned off (see the kill_on_destroy andsignal_on_destroy methods). 

METHODS

The following methods are available:
new (Constructor)
Create a new instance of this class by writing

  $proc = new Proc::Simple;

or

  $proc = Proc::Simple->new();

It takes no arguments.

start
Launches a new process.The "start()" method can be used to launch both external programs (like "/bin/echo") or one of your self-defined subroutines(like "foo()") in a new process.
 

Starting External Programs

For an external program to be started, call

 $status = $proc->start("program-name");

If you want to pass a couple of parameters to the launched program,there's two options: You can either pass them in one argument likein

 $status = $proc->start("/bin/echo hello world");

or in several arguments like in

 $status = $proc->start("/bin/echo", "hello", "world");

Just as in Perl's function "system()", there's a big difference between the two methods: If you provide one argument containinga blank-separated command line, your shell is going toprocess any meta-characters (if you choose to use some) beforethe process is actually launched:

 $status = $proc->start("/bin/ls -l /etc/initt*");

will expand "/etc/initt*" to "/etc/inittab" before running the "ls"command. If, on the other hand, you say

 $status = $proc->start("/bin/ls", "-l", "*");

the "*" will stay unexpanded, meaning you'll look for a file with theliteral name "*" (which is unlikely to exist on your system unlessyou deliberately create confusingly named files :). Formore info on this, look up "perldoc -f exec". 

Starting Subroutines

If, on the other hand, you want to start a Perl subroutinein the background, simply provide the function reference like

 $status = $proc->start(\&your_function);

or supply an unnamed subroutine:

 $status = $proc->start( sub { sleep(1) } );

You can also provide additional parameters to be passed to the function:

 $status = $proc->start(\&printme, "hello", "world");

The start Method returns immediately after starting thespecified process in background, i.e. non-blocking mode.It returns 1 if the process has been launchedsucessfully and 0 if not.

poll
The poll method checks if the process is still running

   $running = $myproc->poll();

and returns 1 if it is, 0 if it's not.

kill
The kill() method:

   $myproc->kill();

terminates the process by sending it the SIGTERM signal. As anoption, another signal can be specified.

   $myproc->kill("SIGUSR1");

sends the SIGUSR1 signal to the running process. kill returns 1 ifit succeeds in sending the signal, 0 if it doesn't.

kill_on_destroy
Set a flag to determine whether the process attachedto this object should be killed when the object isdestroyed. By default, this flag is set to false.The current value is returned.

  $current = $proc->kill_on_destroy;  $proc->kill_on_destroy(1); # Set flag to true  $proc->kill_on_destroy(0); # Set flag to false
signal_on_destroy
Method to set the signal that will be sent to theprocess when the object is destroyed (Assumingkill_on_destroy is true). Returns the current setting.

  $current = $proc->signal_on_destroy;  $proc->signal_on_destroy("KILL");
redirect_output
This allows to redirect the stdout and/or stderr output to a file.Specify undef to leave th

  # stdout to a file, left stderr unchanged  $proc->redirect_output ("/tmp/someapp.stdout", undef);    # stderr to a file, left stdout unchanged  $proc->redirect_output (undef, "/tmp/someapp.stderr");    # stdout and stderr to a separate file  $proc->redirect_output ("/tmp/someapp.stdout", "/tmp/someapp.stderr");

Call this method before running the start method.

pid
Returns the pid of the forked process associated withthis object

  $pid = $proc->pid;
t0
Returns the start time() of the forked process associated withthis object

  $t0 = $proc->t0();
t1
Returns the stop time() of the forked process associated withthis object

  $t1 = $proc->t1();
DESTROY (Destructor)
Object destructor. This method is called when theobject is destroyed (eg with ``undef'' or on exitingperl). If kill_on_destroy is true the processassociated with the object is sent the signal_on_destroysignal (SIGTERM if undefined).
exit_status
Returns the exit status of the process as the $! variable indicates.If the process is still running, "undef" is returned.
wait
The wait method:

   $exit_status = $myproc->wait();

waits until the process is done and returns its exit status.

debug
Switches debug messages on and off --- Proc::Simple::debug(1) switchesthem on, Proc::Simple::debug(0) keeps Proc::Simple quiet.
 

NOTE

Please keep in mind that there is no guarantee that the SIGTERMsignal really terminates a process. Processes can have signalhandlers defined that avoid the shutdown.If in doubt, whether a process still exists, check itrepeatedly with the poll routine after sending the signal. 

REQUIREMENTS

I'd recommend using perl 5.6.0 although it might also run with 5.003--- if you don't have it, this is the time to upgrade!

LEGALESECopyright 1996 by Mike Schilli, all rights reserved. This program isfree software, you can redistribute it and/or modify it under the sameterms as Perl itself. 

AUTHOR

Michael Schilli <michaelAATTperlmeister.com>

Contributors:

Tim Jenness <t.jennessAATTjach.hawaii.edu>
   did kill_on_destroy/signal_on_destroy/pid

Mark R. Southern <mark_southernAATTmerck.com>
   worked on EXIT_STATUS tracking

Tobias Jahn <tjahnAATTusers.sourceforge.net>
   added redirection to stdout/stderr

Clauss Strauch <Clauss_StrauchAATTaquila.fac.cs.cmu.edu>suggested the multi-arg start()-methods.

Chip Capelik contributed a patch with the wait() method.

Jeff Holt provided a patch for time tracking with t0() and t1().

Brad Cavanagh fixed RT33440 (unreliable $?) 

POD ERRORS

Hey! The above document had some coding errors, which are explained below:
Around line 178:
You forgot a '=back' before '=head2'
Around line 282:
'=item' outside of any '=over'
Around line 720:
You forgot a '=back' before '=head1'


 

Index

NAME
SYNOPSIS
DESCRIPTION
METHODS
Starting External Programs
Starting Subroutines
NOTE
REQUIREMENTS
AUTHOR
POD ERRORS

This document was created byman2html,using the manual pages.