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.
59 7. The second child opens STDIN, STDOUT and STDERR to the location
61 defined in the constructor ("new").
62 8. The second child returns to the calling script, or the program
64 defined in 'exec_command' is executed and the second child never
65 returns.
66 9. The first child transfers the PID of the second child (daemon) to
68 the parent and exits. Additionally the PID of the daemon process
69 can be written into a file if 'pid_file' is defined.
70 NOTE: Because of the second fork the daemon will not be a session-
72 leader and therefore Signals will not be send to other members of his
73 process group. If you need the functionality of a session-leader you
74 may want to call POSIX::setsid() manually on your daemon.
75
77 new ( %ARGS )
78 The constructor creates a new Proc::Daemon object based on the hash
79 %ARGS. The following keys from %ARGS are used:
80 work_dir
82 Defines the path to the daemon working directory. Defaults
83 to "/".
84 child_STDIN
86 Defines the path to STDIN of your daemon. Defaults to
87 "/dev/null". Mode is '<' (read).
88 child_STDOUT
90 Defines the path where the output of your daemon will go.
91 Defaults to "/dev/null". Mode is '+>' (write/read).
92 child_STDERR
94 Defines the path where the error output of your daemon will
95 go. Defaults to "/dev/null". Mode is '+>' (write/read).
96 pid_file
98 Defines the path to the file where the PID of the child
99 process is stored. Defaults to "undef" (= write no file).
100 exec_command
102 Scalar or arrayref with system command(s) that will be
103 executed by the daemon via Perls "exec PROGRAM_LIST". In
104 this case the child will never return to the parents
105 process!
106 Example:
108 my $daemon = Proc::Daemon->new(
110 work_dir => '/working/daemon/directory',
111 child_STDOUT => '/path/to/daemon/output.file',
112 child_STDERR => 'debug.txt',
113 pid_file => 'pid.txt',
114 exec_command => 'perl /home/my_script.pl',
115 # or:
116 # exec_command => [ 'perl /home/my_script.pl', 'perl /home/my_other_script.pl' ],
117 );
118 In this example:
120 · the PID of the daemon will be returned to $daemon in the
122 parent process and a pid-file will be created at
123 "/working/daemon/directory/pid.txt"
124 · all STDOUT of the daemon will go to
126 "/path/to/daemon/output.file" and all STDERR will go to
127 "/working/daemon/directory/debug.txt"
128 · the script "/home/my_script.pl" will be executed by "perl"
130 and run as daemon. Therefore the child process will never
131 return to this parent script.
132
134 Init( [ { %ARGS } ] )
135 Become a daemon.
136 If used for the first time after "new", you call "Init" with the
138 object reference to start the daemon.
139 $pid = $daemon->Init();
141 If you want to use the object reference created by "new" for other
143 daemons, you write "Init( { %ARGS } )". %ARGS are the same as
144 described in "new". Notice that you shouldn't call "Init()", or
145 this next daemon will do and write all in the same files as the
146 first daemon. At least use an empty anonymous hash.
147 $pid = $daemon->Init( {} );
149 @pid = $daemon->Init( {
150 work_dir => '/other/daemon/directory',
151 exec_command => [ 'perl /home/my_second_script.pl', 'perl /home/my_third_script.pl' ],
152 } );
153 If you don't need the Proc::Daemon object reference in your script,
155 you can also use the method without object reference:
156 $pid = Proc::Daemon::Init( [ { %ARGS } ] );
158 To the parent "Init" returns the PID (scalar) of the daemon, or the
160 PIDs (array) of the daemons created (if "exec_command" has more
161 then one program to execute). See examples above.
162 Returns 0 to the child (daemon).
164 If you call the "Init" method in the context without looking for a
166 return value (void context) the parent process will "exit" here
167 like in earlier versions:
168 Proc::Daemon::Init;
170 Status( [ $ARG ] )
172 This function checks the status of the process (daemon). Returns
173 the PID number (alive) or 0 (dead).
174 $ARG can be a string with:
176 · "undef", in this case it tries to get the PID to check out
178 of the object reference settings.
179 · a PID number to check.
181 · the path to a file containing the PID to check.
183 · the command line entry of the running program to check.
185 This requires Proc::ProcessTable to be installed.
186 Kill_Daemon( [ $ARG [, SIGNAL] ] )
188 This function kills the Daemon process. Returns the number of
189 processes successfully killed (which mostly is not the same as the
190 PID number), or 0 if the process wasn't found.
191 $ARG is the same as of "Status()". SIGNAL is an optional signal
193 name or number as required by Perls "kill" function and listed out
194 by "kill -l" on your system. Default value is 9 ('KILL' = non-
195 catchable, non-ignorable kill).
196 Fork
198 Is like the Perl built-in "fork", but it retries to fork over 30
199 seconds if necessary and if possible to fork at all. It returns the
200 child PID to the parent process and 0 to the child process. If the
201 fork is unsuccessful it "warn"s and returns "undef".
202
204 Proc::Daemon also defines some other functions. See source code for
205 more details:
206 OpenMax( [ $NUMBER ] )
208 Returns the maximum file descriptor number. If undetermined $NUMBER
209 will be returned.
210 adjust_settings
212 Does some fixes/adjustments on the "new" settings together with
213 "fix_filename".
214 fix_filename( $KEYNAME )
216 Prevents double use of same filename in different processes.
217 get_pid( [ $STRING ] )
219 Returns the wanted PID if it can be found.
220 get_pid_by_proc_table_attr( $ATTR, $MATCH )
222 Returns the wanted PID by looking into the process table, or
223 "undef". Requires the "Proc::ProcessTable" module to be installed.
224
226 "Proc::Daemon::init" is still available for backwards capability.
227
229 Primary-maintainer and code writer until version 0.03:
230 · Earl Hood, earl@earlhood.com, http://www.earlhood.com/
232 Co-maintainer and code writer since version 0.04:
234 · Detlef Pilzecker, http://search.cpan.org/~deti/,
236 http://www.secure-sip-server.net/
237
239 Initial implementation of "Proc::Daemon" derived from the following
240 sources:
241 · "Advanced Programming in the UNIX Environment" by W. Richard
243 Stevens. Addison-Wesley, Copyright 1992.
244 · "UNIX Network Progamming", Vol 1, by W. Richard Stevens. Prentice-
246 Hall PTR, Copyright 1998.
247
249 This module requires the "POSIX" module to be installed.
250 The "Proc::ProcessTable" module is not essentially required but it can
252 be usefull if it is installed (see above).
253
255 perl(1), POSIX, Proc::ProcessTable
256
258 This module is Copyright (C) 1997-2011 by Earl Hood and Detlef
259 Pilzecker.
260 All Rights Reserved.
262 This module is free software. It may be used, redistributed and/or
264 modified under the same terms as Perl itself.
265perl v5.12.3 2011-02-17 Proc::Daemon(3)