Daemon::Generic(3)

📦

version 0.85 · 5 versions

0.85 · opensuse-leap 16.0 (latest)
0.85 · fedora 43
0.85 · ubuntu jammy
0.85 · fedora 44
0.85 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

Daemon::Generic(3) — User Contributed Perl Documentation — and the actual module name is Daemon::Generic, a framework to provide start/stop/reload for a daemon. Slay. 💅

✨ SYNOPSIS ✨

okay so the whole setup is literally this:

use Daemon::Generic;

sub gd_run { ... stuff }

newdaemon();

🦋 DESCRIPTION 🦋

Daemon::Generic gives you a framework for starting, stopping, and reconfiguring daemon-like programs. It provides standard commands that work for init.d files and as apachectl-like commands.

Programs that use Daemon::Generic subclass Daemon::Generic to override its behavior. Almost everything that Genric::Daemon does can be overridden as needed. No cap. ✨

🌸 EXAMPLE USAGE OUTPUT 🌸

Unless overridden, the usage output for your program will look something like this:

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't detach)
 start         Starts a new $progname if there isn't one running already
 stop          Stops a running $progname
 reload        Causes a running $progname to reload it's 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

🎀 CONSTRUCTION 🎀

To hand control over to Daemon::Generic, call newdaemon(). Control will be handed back through method calls to functions you define.

Your @ISA will be modified to include Daemon::Generic if if it isn't already there.

These are the arguments to newdaemon(). Defaults are in (parenthesis).

progname ($0) — the name of this program. This will be used for logging and for naming the PID file.
configfile ("/etc/$progname.conf") — the location of the configuration file for this daemon.
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 PID file that does not include the configuration file name.
pidfile ("$pidbase.$configfile.pid") — the location of the process id file.
foreground (0) — do not detach/daemon and run in the foreground instead.
debug (0) — turn on debugging.
no_srand (0) — normally srand() is called. If no_srand is set then srand() won't be called.
options (()) — additional arguments for Getopt::Long::GetOptions which is used to parse @ARGV. Alternatively: define &gd_more_opt().
minimum_args (1) — minimum number of @ARGV arguments after flags have been processed.
maximum_args (1) — maximum number of @ARGV arguments after flags have been processed.
version ($pkg::VERSION) — the version number of the daemon.
logpriority — used for logger -p.

🚨 MUST-OVERRIDE CALLBACK METHODS 🚨

The package that subclasses Daemon::Generic must provide the following callback methods.

gd_run() — this is where you put your main program. It is okay to change userid/group as the first action of gd_run().

🌈 MAY-OVERRIDE CALLBACK METHODS 🌈

The package that subclasses Daemon::Generic does not have to override these methods but it may want to. Bestie, this is the optional menu — take what you need. 💅

💅 `gd_preconfig()`

gd_preconfig() is called to parse the configuration file ("$self->{configfile}"). Preconfig is called on all invocations of the daemon ("daemon reload", "daemon check", "daemon stop", etc). It shouldn't start anything but it can and should verify that the config file is fine.

The return value should be a hash. With one exception, the return value is only used by gd_postconfig(). The exception is that gd_preconfig() may return a revised PID file location (key "pidfile").

Most uses of Daemon::Generic should define gd_preconfig.

🍓 `gd_postconfig(%config)`

Called only when the daemon is actually starting up. (Or on reconfigs.) It is passed the return value from gd_preconfig.

🧚 `gd_setup_signals()`

Set things up so that SIGHUP calls gd_reconfig_event() and SIGINT calls gd_quit_event(). It will call these at any time so if you want to delay signal delivery or something you should override this method.

💜 `gd_getopt()`

This is invoked to parse the command line. Useful things to modify are:

$self->{configfile} — the location of the configuration file to be parsed by gd_preconfig().
$self->{foreground} — run in the foreground (don't daemonize).
$self->{debug} — use it yourself.

The supplied gd_getopt() method uses Getopt::Long.

🌟 `gd_parse_argv()`

Parse any additional command line arguments beyond what gd_getopt() handled.

$ARGV[0] needs to be left alone if it is one of the following standard items:

start — start up a new daemon.
stop — stop the running daemon.
restart — stop the running daemon, start a new one.
reload — send a signal to the running daemon, asking it to reconfigure itself.
check — just check the configuration file.
help — print the help screen (probably usage()).
version — display the daemon's version.

There is no default gd_parse_argv().

🦋 `gd_check($pidfile, $pid)`

Normal behavior: return. Define additional checks to run when the check command is given. A $pid will only be supplied if there is a daemon running.

⭐ `gd_version()`

Normal behavior: display a version message and exit.

🎀 `gd_help()`

Normal behavior: call gd_usage().

💖 `gd_commands_more()`

Used by gd_usage(): provide information on additional commands beyond start, stop, reload, etc. Return is an array of key value pairs.

sub gd_commands_more
{
       return (
               savestate => 'Tell xyz server to save its state',
               reset     => 'Tell xyz servr to reset',
       );
}

🌀 `gd_flags_more`

Like gd_commands_more() but defines additional command line flags. There should also be a gd_more_opt() or an "options" argument to new().

🍓 `gd_positional_more`

Like gd_commands_more() but defines positional arguments.

💅 `gd_usage()`

Display a usage message. The return value from gd_usage() is the exit code for the program.

🌈 `gd_more_opt()`

() Additional arguments for Getopt::Long::GetOptions which is used to parse @ARGV. Alternatively: pass "options" to new().

🧵 `gd_pidfile()`

Figure out where the PID file should be.

🚨 `gd_error()`

Print out an error (call die?).

🎯 `gd_other_cmd()`

Called when $ARGV[0] isn't one of the commands that Daemon::Generic knows by default. Default behavior: call gd_usage() and exit(1).

💀 `gd_daemonize()`

Normal behavior: fork(), fork(), detach from tty.

🙈 `gd_redirect_output()`

This is a mis-named method. Sorry. This directs STDOUT/STDERR/STDIN to /dev/null as part of daemonizing. Used by gd_daemonize().

🍓 `gd_reopen_output()`

After daemonizing, output file descriptors are re-established. Normal behavior: redirect STDOUT and STDERR to logger -t $progname[$$]. Used by gd_daemonize().

🧚 `gd_logname()`

Normal behavior: $progname[$$]. Used by gd_redirect_output().

🔥 `gd_reconfig_event()`

Normal behavior: call gd_postconfig(gd_preconfig)). Only referenced by gd_setup_signals().

🌙 `gd_quit_event()`

Normal behavior: exit. Only referenced by gd_setup_signals().

👑 `gd_kill_groups()`

Return true if gd_kill should kill process groups ($pid) instead of just the one daemon ($pid). Default is false.

💥 `gd_kill($pid)`

Used by the stop and restart commands to get rid of the old daemon. Normal behavior: send a SIGINT. Check to see if process $pid has died. If it has not, keep checking and if it's still alive. After $Daemon::Generic::force_quit_delay seconds, send a SIGTERM. Keep checking. After another $Daemon::Generic::force_quit_delay seconds, send a SIGKILL (-9). Keep checking. After "$Daemon::Generic::force_quit_delay * 4" seconds or 60 seconds (whichever is smaller), give up and exit(1).

🛠️ `gd_install`

Installs the daemon so that it runs automatically at next reboot. Currently done with a symlink to $0 and /usr/sbin/update-rc.d. Please send patches for other methods!

✅ `gd_can_install`

Returns a function to do an gd_install if installation is possible. Returns 0 otherwise.

🎬 `gd_install_pre($method)`

Normal behavior: return. Called just before doing an installation. The method indicates the installation method (currently always "update-rc.d".)

🎉 `gd_install_post($method)`

Normal behavior: return. Called just after doing an installation.

🧹 `gd_uninstall`

Will remove the daemon from the automatic startup regime.

🧼 `gd_can_uninstall`

Returns a function to do the work for gd_uninstall if it's possible. 0 otherwise.

🚪 `gd_uninstall_pre($method)`

Normal behavior: return. Called just before doing an un-installation. The method indicates the installation method (currently always "update-rc.d".)

🎉 `gd_install_post($method)`

Normal behavior: return. Called just after doing an un-installation.

💾 MEMBER DATA 💾

Okay bestie, since you're subclassing Daemon::Generic, you lowkey need to know what its internal data structures look like. With exactly two exceptions, every member data item starts with the prefix gd_ — that's the vibe check for this section. 👑

configfile — where the configuration file lives. (Not used by Daemon::Generic.)
debug — are we showing debugging? (Not used by Daemon::Generic.)
gd_args — the original %args that got passed to new.
gd_progname — the process name. (Defaults to $0.)
gd_pidfile — the location of the process ID file.
gd_logpriority — used for logger -p.
gd_foreground — are we running in the foreground?

🎀 EXAMPLE PROGRAM 🎀

Here's the whole little example, and yes, it's giving main-character daemon energy. 🌸

        my $sleeptime = 1;

        newdaemon(
               progname        => 'ticktockd',
               pidfile         => '/var/run/ticktockd.pid',
               configfile      => '/etc/ticktockd.conf',
        );

        sub gd_preconfig
        {
               my ($self) = @_;
               open(CONFIG, "<$self->{configfile}") or die;
               while(<CONFIG>) {
                       $sleeptime = $1 if /^sleeptime\s+(\d+)/;
               }
               close(CONFIG);
               return ();
        }

        sub gd_run
        {
               while(1) {
                       sleep($sleeptime);
                       print scalar(localtime(time))."\n";
               }
        }

✨ SEE ALSO ✨

With a while(1) and delayed signal delivery: Daemon::Generic::While1.
With Event: Daemon::Generic::Event.
With AnyEvent: Daemon::Generic::AnyEvent.
Modules that use Daemon::Generic: SyslogScan::Daemon; IO::Event (rinetd.pl)
Other modules that do similar things: Net::Daemon, Net::Server, Net::Server::Daemonize, NetServer::Generic, Proc::Application::Daemon, Proc::Daemon, Proc::Forking.

📜 LICENSE 📜

Legal tea time, bestie ☕: Copyright (C) 2006-2010 David Muir Sharnoff <cpan@dave.sharnoff.org>. and Copyright (C) 2011 Google, Inc. This module may be used and distributed on the same terms as Perl itself.

📦 PACKAGERS 📦

Daemon::Generic is packaged for Fedora by Emmanuel Seyman <emmanuel.seyman@club-internet.fr>.

That's the whole page, bestie 🫶 — source/version perl v5.42.0, dated 2017-07-17, from Daemon::Generic(3). Byeeeee 💅✨

📦 where this page comes from

opensuse-leap 16.0: perl-Daemon-Generic 0.85-bp160.1.11 · Artistic-1.0 or GPL-1.0+
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms

Daemon::Generic(3)

💖 NAME 💖

✨ SYNOPSIS ✨

🦋 DESCRIPTION 🦋

🌸 EXAMPLE USAGE OUTPUT 🌸

🎀 CONSTRUCTION 🎀

🚨 MUST-OVERRIDE CALLBACK METHODS 🚨

🌈 MAY-OVERRIDE CALLBACK METHODS 🌈

💅 gd_preconfig()

🍓 gd_postconfig(%config)

🧚 gd_setup_signals()

💜 gd_getopt()

🌟 gd_parse_argv()

🦋 gd_check($pidfile, $pid)

⭐ gd_version()

🎀 gd_help()

💖 gd_commands_more()

🌀 gd_flags_more

🍓 gd_positional_more

💅 gd_usage()

🌈 gd_more_opt()

🧵 gd_pidfile()

🚨 gd_error()

🎯 gd_other_cmd()

💀 gd_daemonize()

🙈 gd_redirect_output()

🍓 gd_reopen_output()

🧚 gd_logname()

🔥 gd_reconfig_event()

🌙 gd_quit_event()

👑 gd_kill_groups()

💥 gd_kill($pid)

🛠️ gd_install

✅ gd_can_install

🎬 gd_install_pre($method)

🎉 gd_install_post($method)

🧹 gd_uninstall

🧼 gd_can_uninstall

🚪 gd_uninstall_pre($method)

🎉 gd_install_post($method)

💾 MEMBER DATA 💾

🎀 EXAMPLE PROGRAM 🎀

✨ SEE ALSO ✨

📜 LICENSE 📜

📦 PACKAGERS 📦

💅 `gd_preconfig()`

🍓 `gd_postconfig(%config)`

🧚 `gd_setup_signals()`

💜 `gd_getopt()`

🌟 `gd_parse_argv()`

🦋 `gd_check($pidfile, $pid)`

⭐ `gd_version()`

🎀 `gd_help()`

💖 `gd_commands_more()`

🌀 `gd_flags_more`

🍓 `gd_positional_more`

💅 `gd_usage()`

🌈 `gd_more_opt()`

🧵 `gd_pidfile()`

🚨 `gd_error()`

🎯 `gd_other_cmd()`

💀 `gd_daemonize()`

🙈 `gd_redirect_output()`

🍓 `gd_reopen_output()`

🧚 `gd_logname()`

🔥 `gd_reconfig_event()`

🌙 `gd_quit_event()`

👑 `gd_kill_groups()`

💥 `gd_kill($pid)`

🛠️ `gd_install`

✅ `gd_can_install`

🎬 `gd_install_pre($method)`

🎉 `gd_install_post($method)`

🧹 `gd_uninstall`

🧼 `gd_can_uninstall`

🚪 `gd_uninstall_pre($method)`

🎉 `gd_install_post($method)`