1File(3) User Contributed Perl Documentation File(3)
2
6 Proc::PID::File - a module to manage process id files
7
9 use Proc::PID::File;
10 die "Already running!" if Proc::PID::File->running();
11 Process that spawn child processes may want to protect each separately
13 by using multiple pidfiles.
14 my $child1 = Proc::PID::File->new(name => "lock.1");
16 my $child2 = Proc::PID::File->new(name => "lock.2");
17 which may be checked like this:
19 <do-something> if $child1->alive();
21 and should be released manually:
23 $child1->release();
25
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 The module provides two interfaces: 1) a simple call, and 2) an object-
33 oriented interface
34
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 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
48 The following methods are provided:
49 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 In addition to the above, the following constitute valid keys:
57 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 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 Supported platforms: Linux, FreeBSD, Cygwin, macOS
75 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 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 dir Specifies the directory to place the pid file. If left
87 unspecified, defaults to /var/run.
88 name
90 Indicates the name of the current process. When not specified,
91 defaults to basename($0).
92 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 touch
101 Causes for the current process id to be written to the pidfile.
102 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 locktime [hash[-ref]]
108 This method returns the mtime of the pidfile.
109
111 Erick Calder <ecalder@cpan.org>
112
114 1k thx to Steven Haryanto <steven@haryan.to> whose package
115 (Proc::RID_File) inspired this implementation.
116 Our gratitude also to Alan Ferrency <alan@pair.com> for fingering the
118 boot-up problem and suggesting possible solutions.
119
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
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 Some ideas on how to fix this problem are catalogued below, but
134 unfortunately, no platform-independent solutions have yet been gleaned.
135 - 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
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
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
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 $Id: File.pm,v 1.16 2004-04-08 02:27:25 ekkis Exp $
164perl v5.30.0 2019-07-26 File(3)