Systemd::Daemon - Write systemd-aware daemons in Perl
Version 0.07, released on 2015-11-12 13:35 UTC.
Note: The module is in experimental state, interface may be changed in the future.
Perlish functions:
use Systemd::Daemon qw{ -soft notify }; notify( RELOADING => 1 ); while ( $cond ) { notify( STATUS => "Loading, $percent\% done" ); ...; }; notify( READY => 1, STATUS => "Ready" ); ...; notify( STOPPING => 1 ); ...;
Low-level bare C functions:
use Systemd::Daemon qw{ -hard -sd }; sd_notify( 0, "READY=1\nSTATUS=Ready\n" ); sd_pid_notify( $pid, 0, "READY=1\nSTATUS=Ready\n" ); if ( sd_booted() > 0 ) { ... };
Systemd-Daemon distribution includes two implementations of sd-daemon API: XS and Stub. The first contains actual bindings to libsystemd shared library, the second is a library of stubs, which do nothing but immediately return error code.
Systemd-Daemon
Systemd::Daemon serves as interface to underlying implementations. It can work in two modes: hard and soft. In both modes, Systemd::Daemon loads XS implementation first. In case of any trouble (e. g. libsystemd shared library is not found) Systemd::Daemon either re-throws exception (in hard mode) or falls back to use stubs (in soft mode).
Systemd::Daemon
In other words, in hard mode you will get actual bindings or exception, while in soft mode you will get either actual binding or stubs (exception is possible if loading stubs also failed, but it should not occur in normal conditions).
Desired mode is specified as import pseudo-tag -hard or -soft:
-hard
-soft
use Systemd::Daemon qw{ -hard };
The module exports nothing by default. You have to specify symbols to import explicitly:
# Import function sd_listen_fds and constant $SD_LISTEN_FDS_START: use Systemd::Daemon qw{ sd_listen_fds $SD_LISTEN_FDS_START };
or use tags to import groups of related symbols:
# The same as as above: use Systemd::Daemon qw{ :sd_listen };
Either colon (:) or dash (-) can be used as tag prefix:
:
-
# Ditto: use Systemd::Daemon qw{ -sd_listen };
The module uses Exporter::Tiny to export symbols, so all advanced import features like renaming symbols, importing to another package, to a hash, by regexp, etc, can be used:
use Systemd::Daemon '$SD_ERR' => { -as => 'ERR' }, '$SD_DEBUG' => { -as => 'DBG' }; use Systemd::Daemon qw{ -all !notify };
See "TIPS AND TRICKS IMPORTING FROM EXPORTER::TINY" in Exporter::Tiny.
The module defines following export tags (all tag is not listed):
all
sd_booted.
sd_is_fifo, sd_is_mq, sd_is_socket, sd_is_socket_inet, sd_is_socket_unix, sd_is_special.
$SD_LISTEN_FDS_START, sd_listen_fds.
$SD_ALERT, $SD_CRIT, $SD_DEBUG, $SD_EMERG, $SD_ERR, $SD_INFO, $SD_NOTICE, $SD_WARNING.
sd_notify, sd_pid_notify.
All above.
The module re-exports (by explicit request) all the functions from underlying implementation, see "FUNCTIONS" in Systemd::Daemon::XS.
Additionally, the module defines following functions:
$int = notify( VAR => VALUE, … );
notify is Perl wrapper for C functions sd_notify and sd_pid_notify, so read sd_notify(3) first.
notify
sd_notify
sd_pid_notify
C functions accept status as one string of newline-separated variable assignments, e. g.:
sd_notify( 0, "RELOADING=1\nSTATUS=50% done\n" );
Unlike to C functions, notify accepts each variable separately as Perl "named arguments", e. g.:
notify( RELOADING => 1, STATUS => '50% done' );
unset_environment and pid parameters can be specified as named arguments unset and pid respectively, e. g.:
unset_environment
pid
unset
notify( pid => $pid, unset => 1, ... );
If pid value is defined, notify calls sd_pid_notify, otherwise sd_notify is called. unset is defaulted to zero.
sd_notify(3) describes some "well-known" variable assignments, for example, RELOADING=1. Systemd's reaction on assignment RELOADING=2 is not defined. In my experiments with systemd v217 any value but 1 does not have any effect. To make notify more Perlish, READY, RELOADING, STOPPING, WATCHDOG, and FDSTORE arguments are normalized: if its value is false (e. g. undef, zero or empty string), the respective variable is not passed to underlying C function at all; if its value is true (not false), the respective variable is set to 1.
RELOADING=1
RELOADING=2
1
READY
RELOADING
STOPPING
WATCHDOG
FDSTORE
notify returns result of underlying sd_notify (or sd_pid_notify). It should be negative integer in case of error, zero if $ENV{ NOTIFY_SOCKET } is not set (and so, systemd cannot be notified), and some positive value in case of success. However, sd_notify(3) recommends to ignore return value.
$ENV{ NOTIFY_SOCKET }
systemd
The module re-exports (by explicit request) all the constants from underlying implementation, see "CONSTANTS" in Systemd::Daemon::XS.
daemon
sd-daemon
Van de Bugger <van.de.bugger@gmail.com>
Copyright (C) 2015 Van de Bugger
License GPLv3+: The GNU General Public License version 3 or later <http://www.gnu.org/licenses/gpl-3.0.txt>.
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.
To install Systemd::Daemon, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Systemd::Daemon
CPAN shell
perl -MCPAN -e shell install Systemd::Daemon
For more information on module installation, please visit the detailed CPAN module installation guide.