.\" Automatically generated by Pod::Man 2.28 (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 "File 3pm" .TH File 3pm "2015-11-04" "perl v5.20.2" "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" Proc::PID::File \- a module to manage process id files .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use Proc::PID::File; \& die "Already running!" if Proc::PID::File\->running(); .Ve .PP Process that spawn child processes may want to protect each separately by using multiple \fIpidfiles\fR. .PP .Vb 2 \& my $child1 = Proc::PID::File\->new(name => "lock.1"); \& my $child2 = Proc::PID::File\->new(name => "lock.2"); .Ve .PP which may be checked like this: .PP .Vb 1 \& if $child1\->alive(); .Ve .PP and should be released manually: .PP .Vb 1 \& $child1\->release(); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This Perl module is useful for writers of daemons and other processes that need to tell whether they are already running, in order to prevent multiple process instances. The module accomplishes this via *nix\-style \fIpidfiles\fR, which are files that store a process identifier. .PP The module provides two interfaces: 1) a simple call, and 2) an object-oriented interface .SH "Simple Interface" .IX Header "Simple Interface" The simple interface consists of a call as indicated in the first example of the \fBSynopsis\fR section above. This approach avoids causing race conditions whereby one instance of a daemon could read the \fIpidfile\fR after a previous instance has read it but before it has had a chance to write to it. .SS "running [hash[\-ref]]" .IX Subsection "running [hash[-ref]]" The parameter signature for this function is identical to that of the \&\fI\->\fInew()\fI\fR method described below in the \fB\s-1OO\s0 Interface\fR section of this document. The method's return value is the same as that of \fI\->\fIalive()\fI\fR. .SH "OO Interface" .IX Header "OO Interface" The following methods are provided: .SS "new [hash[\-ref]]" .IX Subsection "new [hash[-ref]]" This method is used to create an instance object. It automatically calls the \fI\->\fIfile()\fI\fR method described below and receives the same paramters. For a listing of valid keys in this hash please refer to the aforementioned method documentation below. .PP In addition to the above, the following constitute valid keys: .IP "\fIverify\fR = 1 | string" 4 .IX Item "verify = 1 | string" This parameter implements the second solution outlined in the \s-1WARNING\s0 section of this document and is used to verify that an existing \fIpidfile\fR correctly represents a live process other than the current. If set to a string, it will be interpreted as a \fIregular expression\fR and used to search within the name of the running process. Alternatively, a 1 may be passed: For Linux/FreeBSD, this indicates that the value of \fI\f(CI$0\fI\fR will be used (stripped of its full path); for Cygwin, \fI$^X\fR (stripped of path and extension) will be used. .Sp If the parameter is not passed, no verification will take place. Please note that verification will only work for the operating systems listed below and that the \s-1OS\s0 will be auto-sensed. See also \s-1DEPENDENCIES\s0 section below. .Sp Supported platforms: Linux, FreeBSD, Cygwin .IP "\fIdebug\fR" 4 .IX Item "debug" Any non-zero value turns debugging output on. Additionally, if a string is passed containing the character \fBM\fR, the module name will be prefixed to the debugging output. .SS "file [hash[\-ref]]" .IX Subsection "file [hash[-ref]]" Use this method to set the path of the \fIpidfile\fR. The method receives an optional hash (or hash reference) with the keys listed below, from which it makes a path of the format: \fI\f(CI$dir\fI/$name.pid\fR. .IP "\fIdir\fR" 4 .IX Item "dir" Specifies the directory to place the pid file. If left unspecified, defaults to \fI/var/run\fR. .IP "\fIname\fR" 4 .IX Item "name" Indicates the name of the current process. When not specified, defaults to \fIbasename($0)\fR. .SS "alive" .IX Subsection "alive" Returns true when the process is already running. Please note that this call must be made *after* daemonisation i.e. subsequent to the call to \&\fIfork()\fR. If the \fBverify\fR flag was set during the instance creation, the process id is verified, alternatively the flag may be passed directly to this method. .SS "touch" .IX Subsection "touch" Causes for the current process id to be written to the \fIpidfile\fR. .SS "release" .IX Subsection "release" This method is used to delete the \fIpidfile\fR and is automatically called by \s-1DESTROY\s0 method. It should thus be unnecessary to call it directly. .SS "locktime [hash[\-ref]]" .IX Subsection "locktime [hash[-ref]]" This method returns the \fImtime\fR of the \fIpidfile\fR. .SH "AUTHOR" .IX Header "AUTHOR" Erick Calder .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" 1k thx to Steven Haryanto whose package (Proc::RID_File) inspired this implementation. .PP Our gratitude also to Alan Ferrency for fingering the boot-up problem and suggesting possible solutions. .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" For Linux, FreeBSD and Cygwin, support of the \fIverify\fR option requires availability of the \fBps\fR utility. For Linux/FreeBSD This is typically found in the \fBprocps\fR package. Cygwin users need to run version 1.5.20 or later for this to work. .SH "WARNING" .IX Header "WARNING" This module may prevent daemons from starting at system boot time. The problem occurs because the process id written to the \fIpidfile\fR by an instance of the daemon may coincidentally be reused by another process after a system restart, thus making the daemon think it's already running. .PP Some ideas on how to fix this problem are catalogued below, but unfortunately, no platform-independent solutions have yet been gleaned. .IP "\- leaving the \fIpidfile\fR open for the duration of the daemon's life" 4 .IX Item "- leaving the pidfile open for the duration of the daemon's life" .PD 0 .ie n .IP "\- checking a ""ps"" to make sure the pid is what one expects (current implementation)" 4 .el .IP "\- checking a \f(CWps\fR to make sure the pid is what one expects (current implementation)" 4 .IX Item "- checking a ps to make sure the pid is what one expects (current implementation)" .IP "\- looking at /proc/$PID/stat for a process name" 4 .IX Item "- looking at /proc/$PID/stat for a process name" .IP "\- check mtime of the pidfile versus uptime; don't trust old pidfiles" 4 .IX Item "- check mtime of the pidfile versus uptime; don't trust old pidfiles" .IP "\- try to get the script to nuke its pidfile when it exits (this is vulnerable to hardware resets and hard reboots)" 4 .IX Item "- try to get the script to nuke its pidfile when it exits (this is vulnerable to hardware resets and hard reboots)" .IP "\- try to nuke the pidfile at boot time before the script runs; this solution suffers from a race condition wherein two instances read the \fIpidfile\fR before one manages to lock it, thus allowing two instances to run simultaneously." 4 .IX Item "- try to nuke the pidfile at boot time before the script runs; this solution suffers from a race condition wherein two instances read the pidfile before one manages to lock it, thus allowing two instances to run simultaneously." .PD .SH "SUPPORT" .IX Header "SUPPORT" For help and thank you notes, e\-mail the author directly. To report a bug, submit a patch or add to our wishlist please visit the \s-1CPAN\s0 bug manager at: \fIhttp://rt.cpan.org\fR .SH "AVAILABILITY" .IX Header "AVAILABILITY" The latest version of the tarball, \s-1RPM\s0 and \s-1SRPM\s0 may always be found at: \fIhttp://perl.arix.com/\fR Additionally the module is available from \s-1CPAN.\s0 .SH "LICENCE" .IX Header "LICENCE" This utility is free and distributed under \s-1GPL,\s0 the Gnu Public License. A copy of this license was included in a file called \s-1LICENSE.\s0 If for some reason, this file was not included, please see \fIhttp://www.gnu.org/licenses/\fR to obtain a copy of this license. .PP \&\f(CW$Id:\fR File.pm,v 1.16 2004\-04\-08 02:27:25 ekkis Exp $