.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PID 3"
.TH PID 3 "2011-04-05" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Unix::PID \- Perl extension for getting PID info.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&   use Unix::PID;
\&   my $pid = Unix::PID\->new();
.Ve
.PP
or specify where ps is at:
.PP
.Vb 1
\&   my $pid = Unix::PID\->new({ \*(Aqps_path\*(Aq => \*(Aq/usr/util/bin\*(Aq });
.Ve
.PP
or simplify pid file use by:
.PP
.Vb 1
\&   use Unix::PID \*(Aq/var/run/this.pid\*(Aq;
.Ve
.PP
Aside from the obvious run time vs. compile time factor, this is *exactly* the same as doing
.PP
.Vb 2
\&   use Unix::PID;
\&   Unix::PID\->new()\->pid_file(\*(Aq/var/run/this.pid\*(Aq) or die \*(AqThe PID in /var/run/this.pid is still running.\*(Aq;
.Ve
.PP
So the \*(L"use Unix::PID 'pidfile';\*(R" will simplify 99% of the times you'd use \f(CW$pid\fR\->\fIpid_file()\fR;
.SH "METHODS"
.IX Header "METHODS"
.SS "Unix::PID\->\fInew()\fP"
.IX Subsection "Unix::PID->new()"
Get a Unix::PID object.
.PP
It takes an optional hashref with the following, optional, keys:
.IP "'minimum_pid'" 4
.IX Item "'minimum_pid'"
The minimum \s-1PID\s0 that can be \fIkill()\fRed. If not given or not all digits then it defaults to 11.
.IP "'ps_path'" 4
.IX Item "'ps_path'"
The path to the 'ps' binary you want to use. The value gets passed to the object's \fIset_ps_path()\fR.
.IP "'use_open3'" 4
.IX Item "'use_open3'"
By default this is true. When given a false value it will not load IPC::Open3 and it will use backtick execution of system commands.
.Sp
This will gain you the memory of IPC::Open3 but lose it's many benefits. One such benefit is the capturing of the command's \s-1STDERR\s0 for reporting via \fIget_errstr()\fR.
.ie n .SS "$pid\->\fIset_ps_path()\fP"
.el .SS "\f(CW$pid\fP\->\fIset_ps_path()\fP"
.IX Subsection "$pid->set_ps_path()"
Set the path where ps is at. If not set via this method or in \fInew()\fR or previously then \fI_raw_ps()\fR 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.
.PP
.Vb 1
\&    $pid\->set_ps_path(\*(Aq/usr/util/bin\*(Aq);
.Ve
.ie n .SS "$pid\->\fIget_ps_path()\fP"
.el .SS "\f(CW$pid\fP\->\fIget_ps_path()\fP"
.IX Subsection "$pid->get_ps_path()"
Get the path that the object thinks ps is at
.PP
.Vb 1
\&    print \*(AqI am using ps at \*(Aq . $pid\->get_ps_path();
.Ve
.ie n .SS "$pid\->\fIget_pidof()\fP"
.el .SS "\f(CW$pid\fP\->\fIget_pidof()\fP"
.IX Subsection "$pid->get_pidof()"
Gets the pid(s) matching the given command. In scalar context returns the first, in array returns all.
.PP
The first arg is a string to match against running PIDs, the second, option arg, if true makes it match exactly as given.
.PP
.Vb 1
\&    $pid\->get_pidof("waldo \-\-foo");
.Ve
.PP
returns pids whose commands contains \*(L"waldo \-\-foo\*(R" (\s-1IE\s0 would match 'bin/waldo \-\-foo')
.PP
.Vb 1
\&    $pids\->get_pidof(\*(Aqwaldo \-\-foo\*(Aq, 1);
.Ve
.PP
returns pids whose commands are *entirely* 'waldo \-\-foo' (\s-1IE\s0 would not match 'bin/waldo \-\-foo')
.PP
So for instance to see all processes that are exactly the same as the current:
.PP
.Vb 1
\&   $pids\->get_pidof( $pids\->get_command($$), 1 );
.Ve
.PP
To see in script.pl how many others of itself are running under force:
.PP
.Vb 1
\&   $pids\->get_pidof(\*(Aqscript.pl \-\-force\*(Aq);
.Ve
.PP
The current script's \s-1PID \s0(\s-1IE $$\s0) is never included in this output.
.ie n .SS "$pid\->pid_info( $pid )"
.el .SS "\f(CW$pid\fP\->pid_info( \f(CW$pid\fP )"
.IX Subsection "$pid->pid_info( $pid )"
Get an array (or array ref in scalar context ) of \f(CW$pid\fR's \s-1USER, PID,\s0 \f(CW%CPU\fR, \f(CW%MEM\fR, \s-1VSZ, RSS, TT, STAT, STARTED, TIME, COMMAND\s0
.PP
This may vary on your system so check the header of 'ps u \-p \s-1NUMERIC_PID_HERE\s0' on your system.
.ie n .SS "$pid\->\fIpid_info_hash()\fP"
.el .SS "\f(CW$pid\fP\->\fIpid_info_hash()\fP"
.IX Subsection "$pid->pid_info_hash()"
Same info as pid_info except you get a hash (or hashref in scalar context) with the keys: \s-1USER, PID,\s0 \f(CW%CPU\fR, \f(CW%MEM\fR, \s-1VSZ, RSS, TT, STAT, STARTED, TIME, COMMAND\s0 and values that correspond to each one.
.PP
This may vary on your system so check the header of 'ps u \-p \s-1NUMERIC_PID_HERE\s0' on your system.
.ie n .SS "$pid\->is_*running"
.el .SS "\f(CW$pid\fP\->is_*running"
.IX Subsection "$pid->is_*running"
Check if a pid or command is running or not, returns 1 or 0
.PP
\fI\f(CI$pid\fI\->\fIis_running()\fI\fR
.IX Subsection "$pid->is_running()"
.PP
If the first argument is all digits then this it calls \f(CW$pid\fR\->is_pid_running for you. Otherwise it calls \f(CW$pid\fR\->\fIis_command_running()\fR for you.
.PP
\fI\f(CI$pid\fI\->\fIis_pid_running()\fI\fR
.IX Subsection "$pid->is_pid_running()"
.PP
.Vb 3
\&    if($pid\->is_pid_running($miscpid)) {
\&        warn "PID $miscpid is running, you had better go catch it";
\&    }
.Ve
.PP
\fI\f(CI$pid\fI\->\fIis_pidfile_running()\fI\fR
.IX Subsection "$pid->is_pidfile_running()"
.PP
Takes one argument, the pid file whose \s-1PID\s0 you're interested in.
.PP
Returns the numeric pid stored in the given pid file if it is running, otherwise it return;s
.PP
\fI\f(CI$pid\fI\->\fIis_command_running()\fI\fR
.IX Subsection "$pid->is_command_running()"
.PP
.Vb 3
\&    if($pid\->is_comand_running($cmd)) {
\&        warn "$cmd is still going strong";
\&    }
.Ve
.PP
If the second argument is true it acts just like \fIget_pidof()\fR
.ie n .SS "$pid\->\fIpid_file()\fP"
.el .SS "\f(CW$pid\fP\->\fIpid_file()\fP"
.IX Subsection "$pid->pid_file()"
Takes three arguments, the first is the pid file, the second, optional, argument is the pid to write to the file (defaults to $$), the third, also optional, argument is \*(L"retry\*(R" configuration described below.
.PP
If the pid file 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.
.PP
It returns 0 if the pid file read or write \fIopen()\fR fails. (\s-1IE\s0 you could use $! in your \*(L"or whatever\*(R")
.PP
.Vb 2
\&    # make sure this only runs one at a time 
\&    Unix::PID\->new()\->pid_file(\*(Aq/var/run/this.pid\*(Aq) or die \*(AqThis is already running\*(Aq;
.Ve
.PP
Upon success it also sets up and \s-1END\s0 block to remove the file if the \s-1PID\s0 we setup was our \s-1PID.\s0
.PP
The \*(L"retry\*(R" configuration mentioned above is a reference to an array. The first item is the number of times to \*(L"retry\*(R" processing of an existing pid file. The additonal arguments are what to do after each pass (except the last pass which returns false afterward). The index corresponds to the pass number. e.g. \f(CW$ar\fR\->[1] is what to do after the first pass, \f(CW$ar\fR\->[2] is what to do after the second pass, and so on.
.PP
The value can be a number, in which case it \fIsleep()\fRs that many seconds, or a code ref. The code ref is passed the Unix::PID object as thre first argument, pid file in question as the second argument and the number of passes thus far as the third.
.PP
The default \*(L"retry\*(R" configuration is [3,1,2].
.ie n .SS "$pid\->\fIpid_file_no_unlink()\fP"
.el .SS "\f(CW$pid\fP\->\fIpid_file_no_unlink()\fP"
.IX Subsection "$pid->pid_file_no_unlink()"
Just like \f(CW$pid\fR\->\fIpid_file()\fR except no \s-1END\s0 block cleanup is setup. Useful for doing pid files for a sporking daemon.
.ie n .SS "$pid\->\fIget_pid_from_pidfile()\fP"
.el .SS "\f(CW$pid\fP\->\fIget_pid_from_pidfile()\fP"
.IX Subsection "$pid->get_pid_from_pidfile()"
Takes one argument, the pid file whose \s-1PID\s0 you want.
.PP
Returns the pid stored in the given pid file, 0 if the pid file does not exist or the contents are not numeric. return;s on failure to open the existing pid file.
.ie n .SS "$pid\->\fIkill_pid_file()\fP"
.el .SS "\f(CW$pid\fP\->\fIkill_pid_file()\fP"
.IX Subsection "$pid->kill_pid_file()"
Takes one argument, the pid file whose \s-1PID\s0 you want \fIkill()\fRed. It unlinks the pid file after its successful run.
.PP
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 successfully killed.
.ie n .SS "$pid\->\fIkill_pid_file_no_unlink()\fP;"
.el .SS "\f(CW$pid\fP\->\fIkill_pid_file_no_unlink()\fP;"
.IX Subsection "$pid->kill_pid_file_no_unlink();"
Just like \f(CW$pid\fR\->\fIkill_pid_file()\fR but the pid file is not \fIunlink()\fRed. (and it likewise does not return \-1)
.ie n .SS "$pid\->\fIkill()\fP"
.el .SS "\f(CW$pid\fP\->\fIkill()\fP"
.IX Subsection "$pid->kill()"
Takes one mandatory argumentL the \s-1PID\s0 to kill, and one option argument: the seconds to wait for \fIkill()\fR to finish before we check for the \s-1PID. \s0
.PP
If its running it first tries kill 1 and if that fails it tries kill 9.
.PP
Returns undef if the \s-1PID\s0 was running and could not be killed, true if its not running or was killed successfully.
.PP
.Vb 1
\&    $pid\->kill( $mypid ) or warn "Could not kill PID $mypid: $!";
.Ve
.ie n .SS "$pid\->\fInon_blocking_wait()\fP"
.el .SS "\f(CW$pid\fP\->\fInon_blocking_wait()\fP"
.IX Subsection "$pid->non_blocking_wait()"
Does a non-blocking wait for all pending zombie processes
.ie n .SS "$pid\->\fIwait_for_pidsof()\fP"
.el .SS "\f(CW$pid\fP\->\fIwait_for_pidsof()\fP"
.IX Subsection "$pid->wait_for_pidsof()"
This function waits for processes matching your criteria to finish before going on.
.PP
Its single argument is a hash ref whose keys are the following:
.IP "pid_list" 4
.IX Item "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
.IP "get_pidof" 4
.IX Item "get_pidof"
The value is the same as you'd pass to \f(CW$pid\fR\->get_pidof, defaults to \f(CW$pid\fR\->get_command($$) to wait for process that have the exact same command to stop.
.IP "sleep_for" 4
.IX Item "sleep_for"
Number of seconds to sleep between checking on the pids. defaults to 60
.Sp
If an array ref is passed the sleep time cycles through this list.
.Sp
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.
.Sp
See Math::Fibonacci::Phi
.IP "use_hires_usleep" 4
.IX Item "use_hires_usleep"
If true \fITime::HiRes::usleep()\fR is used instead of \fIsleep()\fR so that you can have it sleep (via \*(L"sleep_for\*(R") for fractions of seconds in microseconds.
.Sp
See Time::HiRes
.IP "use_hires_nanosleep" 4
.IX Item "use_hires_nanosleep"
If true \fITime::HiRes::nanosleep()\fR is used instead of \fIsleep()\fR so that you can have it sleep (via \*(L"sleep_for\*(R") for fractions of seconds in nanoseconds.
.Sp
See Time::HiRes
.Sp
If both use_hires_nanosleep and use_hires_usleep are true use_hires_nanosleep is used.
.IP "max_loops" 4
.IX Item "max_loops"
number of times to check before giving up, defaults to 5
.IP "pre_sleep" 4
.IX Item "pre_sleep"
An optional code reference to do before it sleeps, this would be useful to let everyone know whats going on.
.Sp
\&\f(CW@_\fR contains the number of the loop you're in and an array ref of the pids you're currently waiting on
.IP "hit_max_loops" 4
.IX Item "hit_max_loops"
A code reference to do once you've looped 'max_loops' times. By default it \fIdie()\fR's. I purposefully \fIdie()\fRed instead of croak to encourage you to specify it so you can handle it properly according to your needs.
.Sp
\&\f(CW@_\fR contains the number of the loop you're in and an array ref of the pids you're currently waiting on
.PP
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,
.PP
Here is a complete example:
.PP
.Vb 1
\&    # do some initialization stuff
\&
\&    $pid\->wait_for_pidsof(
\&        {
\&            \*(Aqget_pidof\*(Aq     => \*(Aqdeepthought \-\-get\-ultimate\-answer\*(Aq,
\&            \*(Aqsleep_for\*(Aq     => 31_556_926, # check once a year
\&            \*(Aqmax_loops\*(Aq     => 7_500_000,  # for 7.5 million years
\&            \*(Aqpre_sleep\*(Aq     => 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 \*(Aq,\*(Aq, @{ $waiting_on_these_pids_ref };
\&            },
\&            \*(Aqhit_max_loops\*(Aq => 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 \*(Aq,\*(Aq, @{ $waiting_on_these_pids_ref };
\&            },
\&        }
\&    );
\&
\&    # continue on now that the answer has been had :)
.Ve
.PP
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 :)
.ie n .SS "$pid\->\fIget_errstr()\fP;"
.el .SS "\f(CW$pid\fP\->\fIget_errstr()\fP;"
.IX Subsection "$pid->get_errstr();"
Any errors from _raw_ps can be fetched from \f(CW$pid\fR\->\fIget_errstr()\fR
.PP
The \*(L"or die \f(CW$pid\fR\->\fIget_errstr()\fR\*(R" paradigm doesn't work because any undef or otherwise \*(L"false\*(R" values do not necessarily indicate an error.
.PP
So you can do:
.PP
.Vb 1
\&   die $pid\->get_errstr() if $pid\->get_errstr();
.Ve
.ie n .SS "$pid\->get_*"
.el .SS "\f(CW$pid\fP\->get_*"
.IX Subsection "$pid->get_*"
There are get_ functions for each \ew+ that can be passed to ps's \-o option,
.PP
Each one takes a pid as the only argument.
.PP
.Vb 1
\&    my $i_am_command = $pid\->get_command($$);
.Ve
.ie n .SS "$pid\->_raw_ps(@ps_args);"
.el .SS "\f(CW$pid\fP\->_raw_ps(@ps_args);"
.IX Subsection "$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).
.SH "TO DO"
.IX Header "TO DO"
I'd be happy to add additional functionality if it belongs here, just drop me a line :)
.SH "AUTHOR"
.IX Header "AUTHOR"
Daniel Muey, <http://drmuey.com/cpan_contact.pl>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2005 by Daniel Muey
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.