.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Daemon::Generic 3pm"
.TH Daemon::Generic 3pm "2022-06-12" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\& Daemon::Generic \- framework to provide start/stop/reload for a daemon
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Daemon::Generic;
\&
\& sub gd_run { ... stuff }
\&
\& newdaemon();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Daemon::Generic provides a framework for starting, stopping,
reconfiguring daemon-like programs.  The framework provides
for standard commands that work for as init.d files and 
as apachectl-like commands.
.PP
Programs that use Daemon::Generic subclass Daemon::Generic
to override its behavior.  Almost everything that 
Genric::Daemon does can be overridden as needed.
.SH "EXAMPLE USAGE OUTPUT"
.IX Header "EXAMPLE USAGE OUTPUT"
Unless overridden, the usage output for your program will 
look something like this:
.PP
.Vb 11
\& Usage: $progname [ \-c file ] [ \-f ] { start | stop | reload | restart | help | version | check }
\&  \-c            Specify configuration file (defaults to $configfile)
\&  \-f            Run in the foreground (don\*(Aqt detach)
\&  start         Starts a new $progname if there isn\*(Aqt one running already
\&  stop          Stops a running $progname
\&  reload        Causes a running $progname to reload it\*(Aqs config file.  Starts
\&                a new one if none is running.
\&  restart       Stops a running $progname if one is running.  Starts a new one.
\&  check         Check the configuration file and report the daemon state
\&  help          Display this usage info
\&  version       Display the version of $progname
.Ve
.SH "CONSTRUCTION"
.IX Header "CONSTRUCTION"
To hand control over to \f(CW\*(C`Daemon::Generic\*(C'\fR, call \f(CW\*(C`newdaemon()\*(C'\fR.
Control will be handed back through method calls to functions you
define.
.PP
Your \f(CW@ISA\fR will be modified to include \f(CW\*(C`Daemon::Generic\*(C'\fR if 
if it isn't already there.
.PP
These are the arguments to \f(CW\*(C`newdaemon()\*(C'\fR.
Defaults are in (parenthesis).
.IP "progname" 15
.IX Item "progname"
(\f(CW$0\fR) The name of this program.  This will be used for 
logging and for naming the \s-1PID\s0 file.
.IP "configfile" 15
.IX Item "configfile"
(\f(CW\*(C`/etc/$progname.conf\*(C'\fR) The location of the configuration
file for this daemon.
.IP "pidbase" 15
.IX Item "pidbase"
(/var/run/$progname) We include the configuration file name
as part of the pid file in case there are multiple instances
of this daemon.  The pidbase is the part of the \s-1PID\s0 file
that does not include the configuration file name.
.IP "pidfile" 15
.IX Item "pidfile"
(\f(CW\*(C`$pidbase.$configfile.pid\*(C'\fR) The location of the
process id file.
.IP "foreground" 15
.IX Item "foreground"
(\f(CW0\fR) Do not detach/daemon and run in the foreground instead.
.IP "debug" 15
.IX Item "debug"
(\f(CW0\fR) Turn on debugging.
.IP "no_srand" 15
.IX Item "no_srand"
(\f(CW0\fR) Normall \fBsrand()\fR is called.  If no_srand is set then
\&\fBsrand()\fR won't be called.
.IP "options" 15
.IX Item "options"
() Additional arguments for Getopt::Long::GetOptions which
is used to parse \f(CW@ARGV\fR.  Alternatively: define \f(CW\*(C`&gd_more_opt()\*(C'\fR.
.IP "minimum_args" 15
.IX Item "minimum_args"
(\f(CW1\fR) Minimum number of \f(CW@ARGV\fR arguments after flags have been
processed.
.IP "maximum_args" 15
.IX Item "maximum_args"
(\f(CW1\fR) Maximum number of \f(CW@ARGV\fR arguments after flags have been
processed.
.IP "version" 15
.IX Item "version"
(\f(CW$pkg::VERSION\fR) The version number of the daemon.
.IP "logpriority" 15
.IX Item "logpriority"
Used for \f(CW\*(C`logger \-p\*(C'\fR.
.SH "MUST-OVERRIDE CALLBACK METHODS"
.IX Header "MUST-OVERRIDE CALLBACK METHODS"
The package that subclasses Daemon::Generic must provide the following
callback methods.
.IP "\fBgd_run()\fR" 15
.IX Item "gd_run()"
This is where you put your main program.
.Sp
It is okay to change userid/group as the first action of \fBgd_run()\fR.
.SH "MAY-OVERRIDE CALLBACK METHODS"
.IX Header "MAY-OVERRIDE CALLBACK METHODS"
The package that subclasses Daemon::Generic does not have to override these
methods but it may want to.
.IP "\fBgd_preconfig()\fR" 15
.IX Item "gd_preconfig()"
\&\f(CW\*(C`gd_preconfig()\*(C'\fR is called to parse the configuration file 
(\f(CW\*(C`$self\->{configfile}\*(C'\fR).  Preconfig is called on all invocations
of the daemon (\f(CW\*(C`daemon reload\*(C'\fR, \f(CW\*(C`daemon check\*(C'\fR, \f(CW\*(C`daemon stop\*(C'\fR, etc).
It shouldn't start anything but it can and should verify that
the config file is fine.
.Sp
The return value should be a hash.  With one exception, the return
value is only used by \f(CW\*(C`gd_postconfig()\*(C'\fR.  The exception is that 
\&\f(CW\*(C`gd_preconfig()\*(C'\fR may return a revised \s-1PID\s0 file location (key \f(CW\*(C`pidfile\*(C'\fR).
.Sp
Most uses of Daemon::Generic should define \f(CW\*(C`gd_preconfig\*(C'\fR.
.IP "gd_postconfig(%config)" 15
.IX Item "gd_postconfig(%config)"
\&\fBPostconfig()\fR is called only when the daemon is actually starting up.
(Or on reconfigs).  It is passed the return value from \f(CW\*(C`gd_preconfig\*(C'\fR.
.IP "\fBgd_setup_signals()\fR" 15
.IX Item "gd_setup_signals()"
Set things up so that \s-1SIGHUP\s0 calls \fBgd_reconfig_event()\fR and
\&\s-1SIGINT\s0 calls \fBgd_quit_event()\fR.  It will call these at any time
so if you want to delay signal delivery or something you should 
override this method.
.IP "\fBgd_getopt()\fR" 15
.IX Item "gd_getopt()"
This is invoked to parse the command line.  Useful things to modify are:
.RS 15
.ie n .IP "$self\->{configfile}" 20
.el .IP "\f(CW$self\fR\->{configfile}" 20
.IX Item "$self->{configfile}"
The location of the configuration file to be parsed by \f(CW\*(C`gd_preconfig()\*(C'\fR.
.ie n .IP "$self\->{foreground}" 20
.el .IP "\f(CW$self\fR\->{foreground}" 20
.IX Item "$self->{foreground}"
Run in the foreground (don't daemonize).
.ie n .IP "$self\->{debug}" 20
.el .IP "\f(CW$self\fR\->{debug}" 20
.IX Item "$self->{debug}"
Use it yourself.
.RE
.RS 15
.Sp
The supplied \f(CW\*(C`gd_getopt()\*(C'\fR method uses Getopt::Long.
.RE
.IP "\fBgd_parse_argv()\fR" 15
.IX Item "gd_parse_argv()"
Parse any additional command line arguments beyond what \f(CW\*(C`gd_getopt()\*(C'\fR
handled.
.Sp
\&\f(CW$ARGV[0]\fR needs to be left alone if it is one of the following
standard items:
.RS 15
.IP "start" 10
.IX Item "start"
Start up a new daemon.
.IP "stop" 10
.IX Item "stop"
Stop the running daemon.
.IP "restart" 10
.IX Item "restart"
Stop the running daemon, start a new one.
.IP "reload" 10
.IX Item "reload"
Send a signal to the running daemon, asking
it to reconfigure itself.
.IP "check" 10
.IX Item "check"
Just check the configuration file.
.IP "help" 10
.IX Item "help"
Print the help screen (probably \fBusage()\fR).
.IP "version" 10
.IX Item "version"
Display the daemon's version.
.RE
.RS 15
.Sp
There is no default \f(CW\*(C`gd_parse_argv()\*(C'\fR.
.RE
.ie n .IP "gd_check($pidfile, $pid)" 15
.el .IP "gd_check($pidfile, \f(CW$pid\fR)" 15
.IX Item "gd_check($pidfile, $pid)"
Normal behavior: return.  Define additional checks to run when
the \f(CW\*(C`check\*(C'\fR command is given.  A \f(CW$pid\fR will only be supplied
if there is a daemon running.
.IP "\fBgd_version()\fR" 15
.IX Item "gd_version()"
Normal behavior: display a version message and exit.
.IP "\fBgd_help()\fR" 15
.IX Item "gd_help()"
Normal behavior: call \f(CW\*(C`gd_usage()\*(C'\fR.
.IP "\fBgd_commands_more()\fR" 15
.IX Item "gd_commands_more()"
Used by \f(CW\*(C`gd_usage()\*(C'\fR: provide information on additional commands
beyond \f(CW\*(C`start\*(C'\fR, \f(CW\*(C`stop\*(C'\fR, \f(CW\*(C`reload\*(C'\fR, etc.  Return is an array of
key value pairs.
.Sp
.Vb 7
\& sub gd_commands_more 
\& {
\&        return (
\&                savestate => \*(AqTell xyz server to save its state\*(Aq,
\&                reset     => \*(AqTell xyz servr to reset\*(Aq,
\&        );
\& }
.Ve
.IP "gd_flags_more" 15
.IX Item "gd_flags_more"
Like \f(CW\*(C`gd_commands_more()\*(C'\fR but defines additional command line flags.
There should also be a \f(CW\*(C`gd_more_opt()\*(C'\fR or an \f(CW\*(C`options\*(C'\fR argument to
\&\f(CW\*(C`new()\*(C'\fR.
.IP "gd_positional_more" 15
.IX Item "gd_positional_more"
Like \f(CW\*(C`gd_commands_more()\*(C'\fR but defines positional arguments.
.IP "\fBgd_usage()\fR" 15
.IX Item "gd_usage()"
Display a usage message.  
The return value from \f(CW\*(C`gd_usage()\*(C'\fR is the exit code for the program.
.IP "\fBgd_more_opt()\fR" 15
.IX Item "gd_more_opt()"
() Additional arguments for Getopt::Long::GetOptions which
is used to parse \f(CW@ARGV\fR.  Alternatively: pass \f(CW\*(C`options\*(C'\fR to \f(CW\*(C`new()\*(C'\fR.
.IP "\fBgd_pidfile()\fR" 15
.IX Item "gd_pidfile()"
Figure out the \s-1PID\s0 file should be.
.IP "\fBgd_error()\fR" 15
.IX Item "gd_error()"
Print out an error (call die?)
.IP "\fBgd_other_cmd()\fR" 15
.IX Item "gd_other_cmd()"
Called \f(CW$ARGV[0]\fR isn't one of the commands that Daemon::Generic knows
by default.  Default behavior: call \f(CW\*(C`gd_usage()\*(C'\fR and \f(CWexit(1)\fR.
.IP "\fBgd_daemonize()\fR" 15
.IX Item "gd_daemonize()"
Normal behavior: \f(CW\*(C`fork()\*(C'\fR, \f(CW\*(C`fork()\*(C'\fR, detach from tty.
.IP "\fBgd_redirect_output()\fR" 15
.IX Item "gd_redirect_output()"
This is a mis-named method.  Sorry.  This directs \f(CW\*(C`STDOUT\*(C'\fR/\f(CW\*(C`STDERR\*(C'\fR/\f(CW\*(C`STDIN\*(C'\fR
to \f(CW\*(C`/dev/null\*(C'\fR as part of daemonizing.  Used by \f(CW\*(C`gd_daemonize()\*(C'\fR.
.IP "\fBgd_reopen_output()\fR" 15
.IX Item "gd_reopen_output()"
After daemonizing, output file descriptors are be re-established.
Normal behavior: redirect \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR to 
\&\f(CW\*(C`logger \-t $progname[$$]\*(C'\fR.  Used by \f(CW\*(C`gd_daemonize()\*(C'\fR.
.IP "\fBgd_logname()\fR" 15
.IX Item "gd_logname()"
Normal behavior: \f(CW$progname[$$]\fR.  Used by \f(CW\*(C`gd_redirect_output()\*(C'\fR.
.IP "\fBgd_reconfig_event()\fR" 15
.IX Item "gd_reconfig_event()"
Normal behavior: call \f(CW\*(C`gd_postconfig(gd_preconfig))\*(C'\fR.  
Only referenced by \f(CW\*(C`gd_setup_signals()\*(C'\fR.
.IP "\fBgd_quit_event()\fR" 15
.IX Item "gd_quit_event()"
Normal behavior: exit. 
Only referenced by \f(CW\*(C`gd_setup_signals()\*(C'\fR.
.IP "\fBgd_kill_groups()\fR" 15
.IX Item "gd_kill_groups()"
Return true if gd_kill should kill process groups ($pid) instead of just
the one daemon ($pid).  Default is false.
.IP "gd_kill($pid)" 15
.IX Item "gd_kill($pid)"
Used by the \f(CW\*(C`stop\*(C'\fR and \f(CW\*(C`restart\*(C'\fR commands to get rid of
the old daemon.
Normal behavior: send a \s-1SIGINT.\s0  
Check to see if process \f(CW$pid\fR has died.  If it has not, keep checking
and if it's still alive.  After 
\&\f(CW$Daemon::Generic::force_quit_delay\fR seconds,
send a \s-1SIGTERM.\s0  Keep checking.  After another
\&\f(CW$Daemon::Generic::force_quit_delay\fR seconds,
send a \s-1SIGKILL\s0 (\-9).  Keep checking.  After 
\&\f(CW\*(C`$Daemon::Generic::force_quit_delay * 4\*(C'\fR seconds or 60 seconds
(whichever is smaller), give up and \fBexit\fR\|(1).
.IP "gd_install" 15
.IX Item "gd_install"
Installs the daemon so that it runs automatically at next
reboot.  Currently done with a symlink to \f(CW$0\fR and 
\&\f(CW\*(C`/usr/sbin/update\-rc.d\*(C'\fR.  Please send patches for other 
methods!
.IP "gd_can_install" 15
.IX Item "gd_can_install"
Returns a function to do an \f(CW\*(C`gd_install\*(C'\fR if installation
is possible.  Returns \f(CW0\fR otherwise.
.IP "gd_install_pre($method)" 15
.IX Item "gd_install_pre($method)"
Normal behavior: return.  Called just before doing an installation.
The method indicates the installation method (currently always
\&\f(CW\*(C`update\-rc.d\*(C'\fR.)
.IP "gd_install_post($method)" 15
.IX Item "gd_install_post($method)"
Normal behavior: return.  Called just after doing an installation.
.IP "gd_uninstall" 15
.IX Item "gd_uninstall"
Will remove the daemon from the automatic startup regime.
.IP "gd_can_uninstall" 15
.IX Item "gd_can_uninstall"
Returns a function to do the work for \f(CW\*(C`gd_uninstall\*(C'\fR if it's
possible.  \f(CW0\fR otherwise.
.IP "gd_uninstall_pre($method)" 15
.IX Item "gd_uninstall_pre($method)"
Normal behavior: return.  Called just before doing an un-installation.
The method indicates the installation method (currently always
\&\f(CW\*(C`update\-rc.d\*(C'\fR.)
.IP "gd_install_post($method)" 15
.IX Item "gd_install_post($method)"
Normal behavior: return.  Called just after doing an un-installation.
.SH "MEMBER DATA"
.IX Header "MEMBER DATA"
Since you need to subclass Daemon::Generic, you need to know
what the internal data structures for Daemon::Generic are.  
With two exceptions, all of the member data items begin with 
the prefix \f(CW\*(C`gd_\*(C'\fR.
.IP "configfile" 15
.IX Item "configfile"
The location of the configuration file.  (Not used by
Daemon::Generic).
.IP "debug" 15
.IX Item "debug"
Display debugging?  (Not used by Daemon::Generic)
.IP "gd_args" 15
.IX Item "gd_args"
The original \f(CW%args\fR passed to \f(CW\*(C`new\*(C'\fR.
.IP "gd_progname" 15
.IX Item "gd_progname"
The process name.  (defaults to \f(CW$0\fR)
.IP "gd_pidfile" 15
.IX Item "gd_pidfile"
The location of the process \s-1ID\s0 file.
.IP "gd_logpriority" 15
.IX Item "gd_logpriority"
Used for \f(CW\*(C`logger \-p\*(C'\fR.
.IP "gd_foreground" 15
.IX Item "gd_foreground"
Are we running in the foreground?
.SH "EXAMPLE PROGRAM"
.IX Header "EXAMPLE PROGRAM"
.Vb 1
\& my $sleeptime = 1;
\&
\& newdaemon(
\&        progname        => \*(Aqticktockd\*(Aq,
\&        pidfile         => \*(Aq/var/run/ticktockd.pid\*(Aq,
\&        configfile      => \*(Aq/etc/ticktockd.conf\*(Aq,
\& );
\&
\& sub gd_preconfig
\& {
\&        my ($self) = @_;
\&        open(CONFIG, "<$self\->{configfile}") or die;
\&        while(<CONFIG>) {
\&                $sleeptime = $1 if /^sleeptime\es+(\ed+)/;
\&        }
\&        close(CONFIG);
\&        return ();
\& }
\&
\& sub gd_run
\& {
\&        while(1) {
\&                sleep($sleeptime);
\&                print scalar(localtime(time))."\en";
\&        }
\& }
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
With a \fBwhile\fR\|(1) and delayed signal delivery: Daemon::Generic::While1.
.PP
With Event: Daemon::Generic::Event.
.PP
With AnyEvent: Daemon::Generic::AnyEvent.
.PP
Modules that use Daemon::Generic:
SyslogScan::Daemon;
IO::Event (rinetd.pl)
.PP
Other modules that do similar things: 
Net::Daemon,
Net::Server,
Net::Server::Daemonize, 
NetServer::Generic,
Proc::Application::Daemon,
Proc::Daemon,
Proc::Forking.
.SH "LICENSE"
.IX Header "LICENSE"
Copyright (C) 2006\-2010 David Muir Sharnoff <cpan@dave.sharnoff.org>.
Copyright (C) 2011 Google, Inc.
This module may be used and distributed on the same terms
as Perl itself.
.SH "PACKAGERS"
.IX Header "PACKAGERS"
Daemon::Generic is packaged for Fedora by Emmanuel Seyman <emmanuel.seyman@club\-internet.fr>.