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

NAME

6       Proc::PID::File - a module to manage process id files
7

SYNOPSIS

9         use Proc::PID::File;
10         die "Already running!" if Proc::PID::File->running();
11
12       Process that spawn child processes may want to protect each separately
13       by using multiple pidfiles.
14
15         my $child1 = Proc::PID::File->new(name => "lock.1");
16         my $child2 = Proc::PID::File->new(name => "lock.2");
17
18       which may be checked like this:
19
20         <do-something> if $child1->alive();
21
22       and should be released manually:
23
24         $child1->release();
25

DESCRIPTION

27       This Perl module is useful for writers of daemons and other processes
28       that need to tell whether they are already running, in order to prevent
29       multiple process instances.  The module accomplishes this via
30       *nix-style pidfiles, which are files that store a process identifier.
31
32       The module provides two interfaces: 1) a simple call, and 2) an object-
33       oriented interface
34

Simple Interface

36       The simple interface consists of a call as indicated in the first
37       example of the Synopsis section above.  This approach avoids causing
38       race conditions whereby one instance of a daemon could read the pidfile
39       after a previous instance has read it but before it has had a chance to
40       write to it.
41
42   running [hash[-ref]]
43       The parameter signature for this function is identical to that of the
44       ->new() method described below in the OO Interface section of this
45       document. The method's return value is the same as that of ->alive().
46

OO Interface

48       The following methods are provided:
49
50   new [hash[-ref]]
51       This method is used to create an instance object.  It automatically
52       calls the ->file() method described below and receives the same
53       parameters.  For a listing of valid keys in this hash please refer to
54       the aforementioned method documentation below.
55
56       In addition to the above, the following constitute valid keys:
57
58       verify = 1 | string
59           This parameter implements the second solution outlined in the
60           WARNING section of this document and is used to verify that an
61           existing pidfile correctly represents a live process other than the
62           current.  If set to a string, it will be interpreted as a regular
63           expression and used to search within the name of the running
64           process.  Alternatively, a 1 may be passed: For
65           Linux/FreeBSD/macOS, this indicates that the value of $0 will be
66           used (stripped of its full path); for Cygwin, $^X (stripped of path
67           and extension) will be used.
68
69           If the parameter is not passed, no verification will take place.
70           Please note that verification will only work for the operating
71           systems listed below and that the OS will be auto-sensed.  See also
72           DEPENDENCIES section below.
73
74           Supported platforms: Linux, FreeBSD, Cygwin, macOS
75
76       debug
77           Any non-zero value turns debugging output on.  Additionally, if a
78           string is passed containing the character M, the module name will
79           be prefixed to the debugging output.
80
81   file [hash[-ref]]
82       Use this method to set the path of the pidfile.  The method receives an
83       optional hash (or hash reference) with the keys listed below, from
84       which it makes a path of the format: $dir/$name.pid.
85
86       dir Specifies the directory to place the pid file.  If left
87           unspecified, defaults to /var/run.
88
89       name
90           Indicates the name of the current process.  When not specified,
91           defaults to basename($0).
92
93   alive
94       Returns true when the process is already running.  Please note that
95       this call must be made *after* daemonisation i.e. subsequent to the
96       call to fork(). If the verify flag was set during the instance
97       creation, the process id is verified, alternatively the flag may be
98       passed directly to this method.
99
100   touch
101       Causes for the current process id to be written to the pidfile.
102
103   release
104       This method is used to delete the pidfile and is automatically called
105       by DESTROY method.  It should thus be unnecessary to call it directly.
106
107   locktime [hash[-ref]]
108       This method returns the mtime of the pidfile.
109

AUTHOR

111       Erick Calder <ecalder@cpan.org>
112

ACKNOWLEDGEMENTS

114       1k thx to Steven Haryanto <steven@haryan.to> whose package
115       (Proc::RID_File) inspired this implementation.
116
117       Our gratitude also to Alan Ferrency <alan@pair.com> for fingering the
118       boot-up problem and suggesting possible solutions.
119

DEPENDENCIES

121       For Linux, FreeBSD, Cygwin, and macOS, support of the verify option
122       requires availability of the ps utility.  For Linux/FreeBSD this is
123       typically found in the procps package. Cygwin users need to run version
124       1.5.20 or later for this to work. ps is included in macOS.
125

WARNING

127       This module may prevent daemons from starting at system boot time.  The
128       problem occurs because the process id written to the pidfile by an
129       instance of the daemon may coincidentally be reused by another process
130       after a system restart, thus making the daemon think it's already
131       running.
132
133       Some ideas on how to fix this problem are catalogued below, but
134       unfortunately, no platform-independent solutions have yet been gleaned.
135
136       - leaving the pidfile open for the duration of the daemon's life
137       - checking a "ps" to make sure the pid is what one expects (current
138       implementation)
139       - looking at /proc/$PID/stat for a process name
140       - check mtime of the pidfile versus uptime; don't trust old pidfiles
141       - try to get the script to nuke its pidfile when it exits (this is
142       vulnerable to hardware resets and hard reboots)
143       - try to nuke the pidfile at boot time before the script runs; this
144       solution suffers from a race condition wherein two instances read the
145       pidfile before one manages to lock it, thus allowing two instances to
146       run simultaneously.
147

SUPPORT

149       For help and thank you notes, e-mail the author directly.  To report a
150       bug, submit a patch or add to our wishlist please visit the CPAN bug
151       manager at: http://rt.cpan.org
152

AVAILABILITY

154       The latest version of the tarball, RPM and SRPM may always be found at:
155       http://perl.arix.com/  Additionally the module is available from CPAN.
156

LICENCE

158       This utility is free and distributed under GPL, the Gnu Public License.
159       A copy of this license was included in a file called LICENSE. If for
160       some reason, this file was not included, please see
161       http://www.gnu.org/licenses/ to obtain a copy of this license.
162
163       $Id: File.pm,v 1.16 2004-04-08 02:27:25 ekkis Exp $
164
165
166
167perl v5.34.0                      2021-07-22                           File(3)
Impressum