NAME

PTools::Proc::Daemonize - Turn a script into a daemon process

VERSION

This document describes version 0.09, released April, 2006.

SYNOPSIS

    use PTools::Proc::Daemonize;

 or use PTools::Proc::Daemonize qw( LoadEtcPath );

    run PTools::Proc::Daemonize();

 or run PTools::Proc::Daemonize( Debug, UID, GID, WorkingDir, Umask, EvListRef, PATH, OutFile, PidFile );

 or $daemon = new PTools::Proc::Daemonize;

    $daemon->verifyProcess( Debug, PidFile );
    die $daemon->err()  if $daemon->stat();     # Exit if a daemon is running

    $daemon->verifyUserGroup( Debug, UID, GID );

    $daemon->changeWorkingDir( Debug, WorkingDir );

    $daemon->setUmask( Debug, Umask );

    $daemon->untaintEnv( Debug, EvListRef );

    $daemon->resetPath( Debug, PATH );

    $daemon->redirectIO( Debug, OutFile );      # Skipped when Debug true

    $daemon->detachSession( Debug );            # Skipped when Debug true

    $daemon->writePidToFile( Debug, PidFile );

The following methods are provided for convenience when running Perl scripts that use the '-T' switch (highly recommended for scripts that will become daemon processes).

    $allow = $daemon->allowedChars();

    $text = $daemon->untaintString( $text, $allow );

DESCRIPTION

This class simplifies all of the tasks necessary to turn a Perl script into a daemon process. Tasks performed can include any or all of the following.

 .  verifying the current Uid and/or Gid
 .  changing the current working directory
 .  setting a new file/dir creation Umask value
 .  cleaning/untainting the runtime environment
 .  resetting the PATH environment variable
 .  redirecting standard IO file descriptors
 .  detaching process from a terminal
 .  writing the new PID to a log file

When used with a 'LoadEtcPath' parameter, the 'untaintEnvironment' method will process the '/etc/PATH' file as done in '/etc/profile'.

Constructor

run ( Debug, UID, GID, WorkingDir, Umask, EvListRef, PATH, OutFile, PidFile )

The run method can be used to accomplish any or all of the necessary tasks described in the Description section, above. As an alternative, each of the specific tasks can be accomplished separately, by making explicit calls to each of the various methods described below. Each of the arguments described here are the same for the various methods.

Note that 'runAs' is a synonymous name for this method, and all arguments to the methods are optional.

Also note that when using the run method there is no default for the WorkingDir argument. However, when explicitly calling the changeWorkingDir method, described below, the / (system root) directory is the default. And, when using a PidFile for a given daemon, the run method will verify the contents of the named file does not match an active process ID (if so, an error condition is set).

Debug: Any non-zero value enables Debug mode. When set, the current standard IO is not redirected, and the session is not detached from a controlling terminal.
UID: A Unix account User Id, expected to be an integer between 0 and 65535.
GID: A Unix account Group Id, expected to be an integer between 0 and 65535.
WorkingDir: A path that will become the script's new Working Directory. Default is '/'.
Umask: A numeric value that will become the script's new file creation Umask value. Default is '0'.
EvListRef: This parameter must be a reference to a list of environment variable names. Any listed EV names will not be removed from the script's environment.
Path: A colon separated string of directory paths that will become the script's new Search Path. Default is '/usr/bin:/usr/sbin'.
Outfile: A path that will become the script's new STDOUT and STDERR output file. Default is '/dev/null'.
PidFile: A path to which the script's new <Process ID> will be written. Default is to not save the new PID.

Methods

verifyProcess ( [ Debug ], PidFile )

Verify that the process identification number contained in the named PidFile does not match a currently active process. If the 'pid' does match, an error condition is set.