1Proc::Daemon(3) User Contributed Perl Documentation Proc::Daemon(3)
2
6 Proc::Daemon - Run Perl program(s) as a daemon process.
7
9 use Proc::Daemon;
10 $daemon = Proc::Daemon->new(
12 work_dir => '/my/daemon/directory',
13 .....
14 );
15 $Kid_1_PID = $daemon->Init;
17 unless ( $Kid_1_PID ) {
19 # code executed only by the child ...
20 }
21 $Kid_2_PID = $daemon->Init( {
23 work_dir => '/other/daemon/directory',
24 exec_command => 'perl /home/my_script.pl',
25 } );
26 $pid = $daemon->Status( ... );
28 $stopped = $daemon->Kill_Daemon( ... );
30
32 This module can be used by a Perl program to initialize itself as a
33 daemon or to execute ("exec") a system command as daemon. You can also
34 check the status of the daemon (alive or dead) and you can kill the
35 daemon.
36 A daemon is a process that runs in the background with no controlling
38 terminal. Generally servers (like FTP, HTTP and SIP servers) run as
39 daemon processes. Do not make the mistake to think that a daemon is a
40 server. ;-)
41 Proc::Daemon does the following:
43 1. The script forks a child.
45 2. The child changes the current working directory to the value of
47 'work_dir'.
48 3. The child clears the file creation mask.
50 4. The child becomes a session leader, which detaches the program from
52 the controlling terminal.
53 5. The child forks another child (the final daemon process). This
55 prevents the potential of acquiring a controlling terminal at all
56 and detaches the daemon completely from the first parent.
57 6. The second child closes all open file descriptors (unless you
59 define "dont_close_fh" and/or "dont_close_fd").
60 7. The second child opens STDIN, STDOUT and STDERR to the location
62 defined in the constructor ("new").
63 8. The second child returns to the calling script, or the program
65 defined in 'exec_command' is executed and the second child never
66 returns.
67 9. The first child transfers the PID of the second child (daemon) to
69 the parent. Additionally the PID of the daemon process can be
70 written into a file if 'pid_file' is defined. Then the first child
71 exits.
72 10. If the parent script is looking for a return value, then the PID(s)
74 of the child/ren will be returned. Otherwise the parent will exit.
75 NOTE: Because of the second fork the daemon will not be a session-
77 leader and therefore Signals will not be send to other members of his
78 process group. If you need the functionality of a session-leader you
79 may want to call POSIX::setsid() manually at your daemon.
80 INFO: Since "fork" is not performed the same way on Windows systems as
82 on Linux, this module does not work with Windows. Patches appreciated!
83
85 new ( %ARGS )
86 The constructor creates a new Proc::Daemon object based on the hash
87 %ARGS. The following keys from %ARGS are used:
88 work_dir
90 Defines the path to the working directory of your daemon.
91 Defaults to "/".
92 setuid Sets the real user identifier ($<) and the effective user
94 identifier ($>) for the daemon process using POSIX::setuid(
95 ... ), in case you want to run your daemon under an other
96 user than the parent. Obviously the first user must have
97 the rights to switch to the new user otherwise it will stay
98 the same. It is helpful to define the argument "setuid" if
99 you start your script at boot time by init with the
100 superuser, but wants the daemon to run under a normal user
101 account.
102 setgid Sets the real group identifier ($() and the effective group
104 identifier ($)) for the daemon process using POSXI::setgid(
105 ... ), just like "setuid". As with "setuid", the first
106 user must have the rights to switch to the new group,
107 otherwise the group id will not be changed.
108 child_STDIN
110 Defines the path to STDIN for your daemon. Defaults to
111 "/dev/null". Default Mode is '<' (read). You can define
112 other Mode the same way as you do using Perls "open" in a
113 two-argument form.
114 child_STDOUT
116 Defines the path where the output of your daemon will go.
117 Defaults to "/dev/null". Default Mode is '+>' (write/read).
118 You can define other Mode the same way as you do using
119 Perls "open" in a two-argument form.
120 child_STDERR
122 Defines the path where the error output of your daemon will
123 go. Defaults to "/dev/null". Default Mode is '+>'
124 (write/read). You can define other Mode the same way as you
125 do using Perls "open" in a two-argument form, see example
126 below.
127 dont_close_fh
129 If you define it, it must be an arrayref with file handles
130 you want to preserve from the parent into the child
131 (daemon). This may be the case if you have code below a
132 "__DATA__" token in your script or module called by "use"
133 or "require".
134 dont_close_fh => [ 'main::DATA', 'PackageName::DATA', $my_filehandle, ... ],
136 You can add any kind of file handle to the array
138 (expression in single quotes or a scalar variable),
139 including 'STDIN', 'STDOUT' and 'STDERR'. Logically the
140 path settings from above ("child_STDIN", ...) will be
141 ignored in this case.
142 DISCLAIMER: Using this argument may not detach your daemon
144 fully from the parent! Use it at your own risk.
145 dont_close_fd
147 Same function and disclaimer as "dont_close_fh", but
148 instead of file handles you write the numeric file
149 descriptors inside the arrayref.
150 pid_file
152 Defines the path to a file (owned by the parent user) where
153 the PID of the daemon process will be stored. Defaults to
154 "undef" (= write no file).
155 file_umask
157 Defines umask for "pid_file", "child_STDIN", "child_STDOUT"
158 and "child_STDERR" files. Defaults to 066 (other users may
159 not modify or read the files).
160 exec_command
162 Scalar or arrayref with system command(s) that will be
163 executed by the daemon via Perls "exec PROGRAM_LIST". In
164 this case the child will never return to the parents
165 process!
166 Example:
168 my $daemon = Proc::Daemon->new(
170 work_dir => '/working/daemon/directory',
171 child_STDOUT => '/path/to/daemon/output.file',
172 child_STDERR => '+>>debug.txt',
173 pid_file => 'pid.txt',
174 exec_command => 'perl /home/my_script.pl',
175 # or:
176 # exec_command => [ 'perl /home/my_script.pl', 'perl /home/my_other_script.pl' ],
177 );
178 In this example:
180 • the PID of the daemon will be returned to $daemon in the
182 parent process and a pid-file will be created at
183 "/working/daemon/directory/pid.txt".
184 • STDOUT will be open with Mode '+>' (write/read) to
186 "/path/to/daemon/output.file" and STDERR will be open to
187 "/working/daemon/directory/debug.txt" with Mode '+>>'
188 (write/read opened for appending).
189 • the script "/home/my_script.pl" will be executed by "perl"
191 and run as daemon. Therefore the child process will never
192 return to this parent script.
193
195 Init( [ { %ARGS } ] )
196 Become a daemon.
197 If used for the first time after "new", you call "Init" with the
199 object reference to start the daemon.
200 $pid = $daemon->Init();
202 If you want to use the object reference created by "new" for other
204 daemons, you write "Init( { %ARGS } )". %ARGS are the same as
205 described in "new". Notice that you shouldn't call Init() without
206 argument in this case, or the next daemon will execute and/or write
207 in the same files as the first daemon. To prevent this use at least
208 an empty anonymous hash here.
209 $pid = $daemon->Init( {} );
211 @pid = $daemon->Init( {
212 work_dir => '/other/daemon/directory',
213 exec_command => [ 'perl /home/my_second_script.pl', 'perl /home/my_third_script.pl' ],
214 } );
215 If you don't need the Proc::Daemon object reference in your script,
217 you can also use the method without object reference:
218 $pid = Proc::Daemon::Init();
220 # or
221 $pid = Proc::Daemon::Init( { %ARGS } );
222 "Init" returns the PID (scalar) of the daemon to the parent, or the
224 PIDs (array) of the daemons created if "exec_command" has more then
225 one program to execute. See examples above.
226 "Init" returns 0 to the child (daemon).
228 If you call the "Init" method in the context without looking for a
230 return value (void context) the parent process will "exit" here
231 like in earlier versions:
232 Proc::Daemon::Init();
234 Status( [ $ARG ] )
236 This function checks the status of the process (daemon). Returns
237 the PID number (alive) or 0 (dead).
238 $ARG can be a string with:
240 • "undef", in this case it tries to get the PID to check out
242 of the object reference settings.
243 • a PID number to check.
245 • the path to a file containing the PID to check.
247 • the command line entry of the running program to check.
249 This requires Proc::ProcessTable to be installed.
250 Kill_Daemon( [ $ARG [, SIGNAL] ] )
252 This function kills the Daemon process. Returns the number of
253 processes successfully killed (which mostly is not the same as the
254 PID number), or 0 if the process wasn't found.
255 $ARG is the same as of Status(). SIGNAL is an optional signal name
257 or number as required by Perls "kill" function and listed out by
258 "kill -l" on your system. Default value is 9 ('KILL' = non-
259 catchable, non-ignorable kill).
260 Fork
262 Is like the Perl built-in "fork", but it retries to fork over 30
263 seconds if necessary and if possible to fork at all. It returns the
264 child PID to the parent process and 0 to the child process. If the
265 fork is unsuccessful it "warn"s and returns "undef".
266
268 Proc::Daemon also defines some other functions. See source code for
269 more details:
270 OpenMax( [ $NUMBER ] )
272 Returns the maximum file descriptor number. If undetermined $NUMBER
273 will be returned.
274 adjust_settings
276 Does some fixes/adjustments on the "new" settings together with
277 "fix_filename".
278 fix_filename( $KEYNAME )
280 Prevents double use of same filename in different processes.
281 get_pid( [ $STRING ] )
283 Returns the wanted PID if it can be found.
284 get_pid_by_proc_table_attr( $ATTR, $MATCH )
286 Returns the wanted PID by looking into the process table, or
287 "undef". Requires the "Proc::ProcessTable" module to be installed.
288
290 "Proc::Daemon::init" is still available for backwards capability.
291 Proc::Daemon is now taint safe (assuming it is not passed any tainted
293 parameters).
294
296 Primary-maintainer and code writer until version 0.03:
297 • Earl Hood, earl@earlhood.com, http://www.earlhood.com/
299 Co-maintainer and code writer since version 0.04 until version 0.14:
301 • Detlef Pilzecker, http://search.cpan.org/~deti/,
303 http://www.secure-sip-server.net/
304 Co-maintainer and code writer since version 0.15:
306 • Pavel Denisov, http://search.cpan.org/~akreal/
308
310 Initial implementation of "Proc::Daemon" derived from the following
311 sources:
312 • "Advanced Programming in the UNIX Environment" by W. Richard
314 Stevens. Addison-Wesley, Copyright 1992.
315 • "UNIX Network Programming", Vol 1, by W. Richard Stevens.
317 Prentice-Hall PTR, Copyright 1998.
318
320 This module requires the "POSIX" module to be installed.
321 The "Proc::ProcessTable" module is not essentially required but it can
323 be useful if it is installed (see above).
324
326 <https://github.com/akreal/Proc-Daemon>
327
329 perl(1), POSIX, Proc::ProcessTable
330
332 This module is Copyright (C) 1997-2015 by Earl Hood, Detlef Pilzecker
333 and Pavel Denisov.
334 All Rights Reserved.
336 This module is free software. It may be used, redistributed and/or
338 modified under the same terms as Perl itself.
339perl v5.36.0 2023-01-20 Proc::Daemon(3)