1Proc::Daemon(3)       User Contributed Perl Documentation      Proc::Daemon(3)
2
3
4

NAME

6       Proc::Daemon - Run Perl program(s) as a daemon process.
7

SYNOPSIS

9           use Proc::Daemon;
10
11           $daemon = Proc::Daemon->new(
12               work_dir => '/my/daemon/directory',
13               .....
14           );
15
16           $Kid_1_PID = $daemon->Init;
17
18           unless ( $Kid_1_PID ) {
19               # code executed only by the child ...
20           }
21
22           $Kid_2_PID = $daemon->Init( {
23                           work_dir     => '/other/daemon/directory',
24                           exec_command => 'perl /home/my_script.pl',
25                        } );
26
27           $pid = $daemon->Status( ... );
28
29           $stopped = $daemon->Kill_Daemon( ... );
30

DESCRIPTION

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
37       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
42       Proc::Daemon does the following:
43
44       1.  The script forks a child.
45
46       2.  The child changes the current working directory to the value of
47           'work_dir'.
48
49       3.  The child clears the file creation mask.
50
51       4.  The child becomes a session leader, which detaches the program from
52           the controlling terminal.
53
54       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
58       6.  The second child closes all open file descriptors (unless you
59           define "dont_close_fh" and/or "dont_close_fd").
60
61       7.  The second child opens STDIN, STDOUT and STDERR to the location
62           defined in the constructor ("new").
63
64       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
68       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
73       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
76       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
81       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

CONSTRUCTOR

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
89           work_dir
90                   Defines the path to the working directory of your daemon.
91                   Defaults to "/".
92
93           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
103           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
109           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
115           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
121           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
128           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
135                       dont_close_fh => [ 'main::DATA', 'PackageName::DATA', $my_filehandle, ... ],
136
137                   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
143                   DISCLAIMER: Using this argument may not detach your daemon
144                   fully from the parent! Use it at your own risk.
145
146           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
151           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
156           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
161           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
167           Example:
168
169               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
179           In this example:
180
181           •       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
185           •       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
190           •       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

METHODS

195       Init( [ { %ARGS } ] )
196           Become a daemon.
197
198           If used for the first time after "new", you call "Init" with the
199           object reference to start the daemon.
200
201               $pid = $daemon->Init();
202
203           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
210               $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
216           If you don't need the Proc::Daemon object reference in your script,
217           you can also use the method without object reference:
218
219               $pid = Proc::Daemon::Init();
220               # or
221               $pid = Proc::Daemon::Init( { %ARGS } );
222
223           "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
227           "Init" returns 0 to the child (daemon).
228
229           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
233               Proc::Daemon::Init();
234
235       Status( [ $ARG ] )
236           This function checks the status of the process (daemon). Returns
237           the PID number (alive) or 0 (dead).
238
239           $ARG can be a string with:
240
241           •       "undef", in this case it tries to get the PID to check out
242                   of the object reference settings.
243
244           •       a PID number to check.
245
246           •       the path to a file containing the PID to check.
247
248           •       the command line entry of the running program to check.
249                   This requires Proc::ProcessTable to be installed.
250
251       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
256           $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
261       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

OTHER METHODS

268       Proc::Daemon also defines some other functions. See source code for
269       more details:
270
271       OpenMax( [ $NUMBER ] )
272           Returns the maximum file descriptor number. If undetermined $NUMBER
273           will be returned.
274
275       adjust_settings
276           Does some fixes/adjustments on the "new" settings together with
277           "fix_filename".
278
279       fix_filename( $KEYNAME )
280           Prevents double use of same filename in different processes.
281
282       get_pid( [ $STRING ] )
283           Returns the wanted PID if it can be found.
284
285       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

NOTES

290       "Proc::Daemon::init" is still available for backwards capability.
291
292       Proc::Daemon is now taint safe (assuming it is not passed any tainted
293       parameters).
294

AUTHORS

296       Primary-maintainer and code writer until version 0.03:
297
298       •   Earl Hood, earl@earlhood.com, http://www.earlhood.com/
299
300       Co-maintainer and code writer since version 0.04 until version 0.14:
301
302       •   Detlef Pilzecker, http://search.cpan.org/~deti/,
303           http://www.secure-sip-server.net/
304
305       Co-maintainer and code writer since version 0.15:
306
307       •   Pavel Denisov, http://search.cpan.org/~akreal/
308

CREDITS

310       Initial implementation of "Proc::Daemon" derived from the following
311       sources:
312
313       •   "Advanced Programming in the UNIX Environment" by W. Richard
314           Stevens.  Addison-Wesley, Copyright 1992.
315
316       •   "UNIX Network Programming", Vol 1, by W. Richard Stevens.
317           Prentice-Hall PTR, Copyright 1998.
318

PREREQUISITES

320       This module requires the "POSIX" module to be installed.
321
322       The "Proc::ProcessTable" module is not essentially required but it can
323       be useful if it is installed (see above).
324

REPOSITORY

326       <https://github.com/akreal/Proc-Daemon>
327

SEE ALSO

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
335       All Rights Reserved.
336
337       This module is free software. It may be used, redistributed and/or
338       modified under the same terms as Perl itself.
339
340
341
342perl v5.36.0                      2023-01-20                   Proc::Daemon(3)
Impressum