
=head1 NAME

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




=head1 SYNOPSIS

    use Proc::Daemon;

    $daemon = Proc::Daemon->new(
        work_dir => '/my/daemon/directory',
        .....
    );

    $Kid_1_PID = $daemon->Init;

    unless ( $Kid_1_PID ) {
        # code executed only by the child ...
    }

    $Kid_2_PID = $daemon->Init( { 
                    work_dir     => '/other/daemon/directory',
                    exec_command => 'perl /home/my_script.pl',
                 } );

    $pid = $daemon->Status( ... );

    $stopped = $daemon->Kill_Daemon( ... );




=head1 DESCRIPTION

This module can be used by a Perl program to initialize itself as a daemon
or to execute (C<exec>) a system command as daemon. You can also check the status
of the daemon (alive or dead) and you can kill the daemon.

A daemon is a process that runs in the background with no controlling
terminal. Generally servers (like FTP, HTTP and SIP servers) run as daemon
processes. Do not make the mistake to think that a daemon is a server. ;-)

Proc::Daemon does the following:


=over 4

=item 1

The script forks a child.


=item 2

The child changes the current working directory to
the value of 'work_dir'.


=item 3

The child clears the file creation mask.


=item 4

The child becomes a session leader, which detaches the program from the
controlling terminal.


=item 5

The child forks another child (the final daemon process). This prevents
the potential of acquiring a controlling terminal at all and detaches the
daemon completely from the first parent.


=item 6

The second child closes all open file descriptors.


=item 7

The second child opens STDIN, STDOUT and STDERR to the location defined in the
constructor (C<new>).


=item 8

The second child returns to the calling script, or the program defined
in 'exec_command' is executed and the second child never returns.


=item 9

The first child transfers the PID of the second child (daemon) to the
parent and exits. Additionally the PID of the daemon process can be written
into a file if 'pid_file' is defined.

=back


NOTE: Because of the second fork the daemon will not be a session-leader and
therefore Signals will not be send to other members of his process group. If
you need the functionality of a session-leader you may want to call
POSIX::setsid() manually on your daemon.




=head1 CONSTRUCTOR


=over 4

=item new ( %ARGS )

The constructor creates a new Proc::Daemon object based on the hash %ARGS. The
following keys from %ARGS are used:


=over 8

=item work_dir

Defines the path to the daemon working directory. Defaults to C</>.


=item child_STDIN

Defines the path to STDIN of your daemon. Defaults to C</dev/null>. Mode is '<'
(read).


=item child_STDOUT

Defines the path where the output of your daemon will go. Defaults to
C</dev/null>. Mode is '+>' (write/read).


=item child_STDERR

Defines the path where the error output of your daemon will go. Defaults to
C</dev/null>. Mode is '+>' (write/read).


=item pid_file

Defines the path to the file where the PID of the child process is
stored. Defaults to C<undef> (= write no file).


=item exec_command

Scalar or arrayref with system command(s) that will be executed by the
daemon via Perls C<exec PROGRAM_LIST>. In this case the child will never
return to the parents process!

=back


Example:

    my $daemon = Proc::Daemon->new(
        work_dir     => '/working/daemon/directory',
        child_STDOUT => '/path/to/daemon/output.file',
        child_STDERR => 'debug.txt',
        pid_file     => 'pid.txt',
        exec_command => 'perl /home/my_script.pl',
      # or:
      # exec_command => [ 'perl /home/my_script.pl', 'perl /home/my_other_script.pl' ],
    );

In this example:

=over 8

=item *

the PID of the daemon will be returned to C<$daemon> in the parent process
and a pid-file will be created at C</working/daemon/directory/pid.txt>

=item *

all STDOUT of the daemon will go to C</path/to/daemon/output.file> and
all STDERR will go to C</working/daemon/directory/debug.txt>

=item *

the script C</home/my_script.pl> will be executed by C<perl> and run as
daemon. Therefore the child process will never return to this parent script.

=back

=back




=head1 METHODS

=over 4

=item Init( [ { %ARGS } ] )

Become a daemon.

If used for the first time after C<new>, you call C<Init> with the object
reference to start the daemon.

    $pid = $daemon->Init();

If you want to use the object reference created by C<new> for other daemons,
you write C<Init( { %ARGS } )>. %ARGS are the same as described in
C<new>. Notice that you shouldn't call C<Init()>, or
this next daemon will do and write all in the same files as the first daemon. At
least use an empty anonymous hash.

    $pid = $daemon->Init( {} );
    @pid = $daemon->Init( {
        work_dir     => '/other/daemon/directory',
        exec_command => [ 'perl /home/my_second_script.pl', 'perl /home/my_third_script.pl' ],
    } );

If you don't need the Proc::Daemon object reference in your script, you
can also use the method without object reference:

    $pid = Proc::Daemon::Init( [ { %ARGS } ] );

To the parent C<Init> returns the PID (scalar) of the daemon, or the PIDs
(array) of the daemons created (if C<exec_command> has more then one program
to execute). See examples above.

Returns 0 to the child (daemon).

If you call the C<Init> method in the context without looking for a return value
(void context) the parent process will C<exit> here like in earlier versions:

    Proc::Daemon::Init;


=item Status( [ $ARG ] )

This function checks the status of the process (daemon). Returns the PID number
(alive) or 0 (dead).

$ARG can be a string with:

=over 8

=item *

C<undef>, in this case it tries to get the PID to check out of the object
reference settings.

=item *

a PID number to check.

=item *

the path to a file containing the PID to check.

=item *

the command line entry of the running program to check. This requires
L<Proc::ProcessTable> to be installed.

=back


=item Kill_Daemon( [ $ARG ] )

This function kills the Daemon process. Returns the number of processes
successfully killed (which mostly is not the same as the PID number), or 0 if
the process wasn't found. 

$ARG is the same as of C<Status()>.


=item Fork

Is like the Perl built-in C<fork>, but it retries to fork over 30 seconds if
necessary and if possible to fork at all. It returns the child PID to the
parent process and 0 to the child process. If the fork is unsuccessful
it C<warn>s and returns C<undef>.

=back




=head1 OTHER METHODS

Proc::Daemon also defines some other functions. See source code for more
details:

=over 4

=item OpenMax( [ $NUMBER ] )

Returns the maximum file descriptor number. If undetermined $NUMBER will be
returned.


=item adjust_settings

Does some fixes/adjustments on the C<new> settings together with C<fix_filename>.


=item fix_filename( $KEYNAME )

Prevents double use of same filename in different processes.


=item get_pid( [ $STRING ] )

Returns the wanted PID if it can be found.


=item get_pid_by_proc_table_attr( $ATTR, $MATCH )

Returns the wanted PID by looking into the process table, or C<undef>. Requires
the C<Proc::ProcessTable> module to be installed.


=back




=head1 NOTES

C<Proc::Daemon::init> is still available for backwards capability.




=head1 AUTHORS

Primary-maintainer and code writer until version 0.03:

=over 4

=item *

Earl Hood, earl@earlhood.com, http://www.earlhood.com/

=back


Co-maintainer and code writer since version 0.04:

=over 4

=item *

Detlef Pilzecker, http://search.cpan.org/~deti/,
http://www.secure-sip-server.net/

=back




=head1 CREDITS

Initial implementation of C<Proc::Daemon> derived from the following sources:

=over 4

=item *

"Advanced Programming in the UNIX Environment" by W. Richard Stevens.
Addison-Wesley, Copyright 1992.

=item *

"UNIX Network Progamming", Vol 1, by W. Richard Stevens.
Prentice-Hall PTR, Copyright 1998.

=back




=head1 PREREQUISITES

This module requires the C<POSIX> module to be installed.

The C<Proc::ProcessTable> module is not essentially required but it can be
usefull if it is installed (see above).




=head1 SEE ALSO

L<perl(1)>, L<POSIX>, L<Proc::ProcessTable>




=head1 COPYRIGHT

This module is Copyright (C) 1997-2011 by Earl Hood and Detlef Pilzecker.

All Rights Reserved.

This module is free software. It may be used, redistributed and/or modified
under the same terms as Perl itself.

