Unix::PID
PID(3) User Contributed Perl Documentation PID(3)
NAME
Unix::PID - Perl extension for getting PID info.
SYNOPSIS
use Unix::PID;
my $pid = Unix::PID->new();
or specify where ps is at:
my $pid = Unix::PID->new({ ’ps_path’ => ’/usr/util/bin’ });
or simplify pid file use by:
use Unix::PID ’/var/run/this.pid’;
This is *exactly* the same as:
use Unix::PID;
Unix::PID->new()->pid_file(’/var/run/this.pid’) or die ’The PID in /var/run/this.pid is still running.’;
So the "use Unix::PID ’pidfile’;" will simplify 99% of the times you’d
use $pid->pid_file();
METHODS
$pid->set_ps_path()
Set the path where ps is at. If not set here or in new() or previously
then _raw_ps() looks for it in several common places and sets it to
that if it finds it. returns true if what you specify is ok and false
otherwise.
$pid->set_ps_path(’/usr/util/bin’);
$pid->get_ps_path()
Get the path that the object thinks ps is at
print ’I am using ps at ’ . $pid->get_ps_path();
$pid->get_pidof()
Gets the pid(s) matching the given command. In scalar context returns
the first, in array returns all.
The first arg is a string to match against running PIDs, the second,
option arg, if true makes it match exactly as given.
$pid->get_pidof("waldo --foo");
returns pids whose commands contains "waldo --foo" (IE would match
’bin/waldo --foo’)
$pids->get_pidof(’waldo --foo’, 1);
returns pids whose commands are *entirely* ’waldo --foo’ (IE would not
match ’bin/waldo --foo’)
So for instance to see all processes that are exactly the same as the
current:
$pids->get_pidof( $pids->get_command($$), 1 );
To see in script.pl how many others of itself are running under force:
$pids->get_pidof(’script.pl --force’);
The current script’s PID (IE $$) is never included in this output.
$pid->pid_info( $pid )
Get an array (or array ref in scalar context ) of $pid’s USER, PID,
%CPU, %MEM, VSZ, RSS, TT, STAT, STARTED, TIME, COMMAND
This may vary on your system so check the header of ’ps u -p
NUMERIC_PID_HERE’ on your system.
$pid->pid_info_hash()
Same info as pid_info except you get a hash (or hashref in scalar con-
text) with the keys: USER, PID, %CPU, %MEM, VSZ, RSS, TT, STAT,
STARTED, TIME, COMMAND and values that correspond to each one.
This may vary on your system so check the header of ’ps u -p
NUMERIC_PID_HERE’ on your system.
$pid->is_*running
Check if a pid or command is running or not, returns 1 or 0
$pid->is_running()
If the first argument is all digits then this it calls
$pid->is_pid_running for you. Otherwise it calls $pid->is_command_run-
ning() for you.
$pid->is_pid_running()
if($pid->is_pid_running($miscpid)) {
warn "PID $miscpid is running, you had better go catch it";
}
$pid->is_command_running()
if($pid->is_comand_running($cmd)) {
warn "$cmd is still goign strong";
}
If the second argument is true it acts just like get_pidof()
$pid->pid_file()
Takes two arguments, the first is the pid file, the second, optional,
argument is the pid to write to the file: defaults to $$.
If the pidfile exists it checks to see if the pid in it is running and
if so it returns undef, if not it writes the second argument (or $$)
to the file and returns 1.
It returns 0 if the pid file read or write open() fails. (IE you could
use $! in your "or whatever")
# make sure this only runs one at a time
Unix::PID->new()->pid_file(’/var/run/this.pid’) or die ’This is already running’;
Also sets up and END block to remove file.
$pid->pid_file_no_unlink()
Just like $pid->pid_file() except no END block cleanup is setup. Use-
ful for doing pid files for a sporking daemon.
$pid->kill_pid_file()
Takes one argument, the pidfile whose PID you want kill()ed. It
unlinks the pidfile after its successful run.
It returns true (if the file exists, the pid. otherwise 1) if all is
well, 0 if it exists but could not be opened, undef if the pid could
not be killed, and -1 if it could not be cleaned up after it was suc-
cessfully killed.
$pid->kill_pid_file_no_unlink();
Just like $pid->kill_pid_file() but the pid file is not unlink()ed.
(and it likewise does not return -1)
$pid->kill()
Takes one argument, the PID to kill. If its running it first tries
kill 1 and if that fails it tries kill 9.
Returns undef if the PID was running and could not be killed, true if
its not running or was killed successfully.
$pid->kill( $mypid ) or warn "Could not kill PID $mypid: $!";
$pid->non_blocking_wait()
Does a non-blocking wait for all pending zombie processes
$pid->wait_for_pidsof()
This function waits for processes matching your criteria to finish
before going on.
Its single argument is a hash ref whose keys are the following:
pid_list
An array ref of numeric PIDs to wait on. If this exists and is an
array ref it will be used instead of get_pidof
get_pidof
The value is the same as you’d pass to $pid->get_pidof, defaults
to $pid->get_command($$) to wait for process that have the exact
same command to stop.
sleep_for
Number of seconds to sleep between checking on the pids. defaults
to 60
If an array ref is passed the sleep time cycles through this list.
If a hashref is sent, and it has a key of the value ’fibonacci’
each cycle uses the next fibonnaci number as the time to sleep,
starting with the first.
See Math::Fibonacci::Phi
use_hires_usleep
If true Time::HiRes::usleep() is used instead of sleep() so that
you can have it sleep (via "sleep_for") for fractions of seconds
in microseconds.
See Time::HiRes
use_hires_nanosleep
If true Time::HiRes::nanosleep() is used instead of sleep() so
that you can have it sleep (via "sleep_for") for fractions of sec-
onds in nanoseconds.
See Time::HiRes
If both use_hires_nanosleep and use_hires_usleep are true
use_hires_nanosleep is used.
max_loops
number of times to check before giving up, defaults to 5
pre_sleep
An optional code reference to do before it sleeps, this would be
useful to let everyone know whats going on.
@_ contains the number of the loop you’re in and an array ref of
the pids you’re currently waiting on
hit_max_loops
A code reference to do once you’ve looped ’max_loops’ times. By
default it die()’s. I purposefully die()ed instead of croak to
encourage you to specify it so you can handle it properly accord-
ing to your needs.
@_ contains the number of the loop you’re in and an array ref of
the pids you’re currently waiting on
For clarity and maintainability I highly recommend specifying each
option so you (and the poor souls who have to maintain your code
later) will have some sort of idea what you were trying for instead
having to guess and hack away deeper into code,
Here is a complete example:
# do some initialization stuff
$pid->wait_for_pidsof(
{
’get_pidof’ => ’deepthought --get-ultimate-answer’,
’sleep_for’ => 31_556_926, # check once a year
’max_loops’ => 7_500_000, # for 7.5 million years
’pre_sleep’ => sub {
my($we_are_in_loop_number, $waiting_on_these_pids_ref) = @_;
print "Currently in year $we_are_in_loop_number waiting for deepthought: "
. join ’,’, @{ $waiting_on_these_pids_ref };
},
’hit_max_loops’ => sub {
my($we_are_in_loop_number, $waiting_on_these_pids_ref) = @_;
croak "Sorry mice, even after $we_are_in_loop_number years deepthought is still just watching TV: "
. join ’,’, @{ $waiting_on_these_pids_ref };
},
}
);
# continue on now that the answer has been had :)
Obviously its not efficient to have it sleep for a year between checks
7.5 million times just to calculate 42, its just an example :)
$pid->get_errstr();
Any errors from _raw_ps can be fetched from $pid->get_errstr()
The "or die $pid->get_errstr()" paradigm doesn’t work because any
undef or otherwise "false" values do not necessarily indicate an
error.
So you can do:
die $pid->get_errstr() if $pid->get_errstr();
$pid->get_*
There are get_ functions for each \w+ that can be passed to ps’s -o
option,
Each one takes a pid as the only argument.
my $i_am_command = $pid->get_command($$);
$pid->_raw_ps(@ps_args);
Calls ps with the given args and returns an array of each line (or the
first line in scalar context).
TO DO
I’d be happy to add additional functionality if it belongs here, just
drop me a line :)
AUTHOR
Daniel Muey, <http://drmuey.com/cpan_contact.pl>
COPYRIGHT AND LICENSE
Copyright 2005 by Daniel Muey
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
perl v5.8.8 2008-04-11 PID(3)
