
=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_PID = $daemon->Init;

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

    $Kid_PID2 = $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 forked child becomes a session leader, which detaches the program from the
controlling terminal.


=item 3

This child forks another child (the final daemon process). This prevents
the potential of acquiring a controlling terminal at all.


=item 4

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


=item 5

The second child clears the file creation mask.


=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 first process (grandparent), 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




=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>.


=item child_STDOUT

Defines the path where the output of your daemon will go. Defaults to C<*\STDIN>.


=item child_STDERR

Defines the path where the error output of your daemon will go. Defaults
to C<*\STDIN>.


=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 into C<$daemon> of 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 program C<perl /home/my_script.pl> will be executed and run as
daemon. Therefore the child process will never return to this parent script.

=back

=back




=head1 METHODS

=over 4

=item Init

=item Init( { [ %ARGS ] } )

=item Init( [ { %ARGS } ] )

Become a daemon.

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

    $daemon->Init;

If you want to use the object created by C<new> for other daemons, you can
call C<Init( { [ %ARGS ] } )> with the object. Notice that it
shouldn't be called without arguments! At least it must be an empty anonymous
hash, or this next daemon will do and write all in the same files as the first
daemon.

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

If called without object reference and for backward compatibility you can use
the third depreciated method.

    Proc::Daemon::Init;
    Proc::Daemon::Init( \%ARGS );


=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
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
C<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 (if
undefined: 64) 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 of 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 *

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

=item *

B<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-2010 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.

