NAME
Systemd::Daemon - Write systemd-aware daemons in Perl
VERSION
Version 0.07, released on 2015-11-12 13:35 UTC.
SYNOPSIS
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 ) { ... };DESCRIPTION
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 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).
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:
use Systemd::Daemon qw{ -hard };EXPORT
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.
Tags
The module defines following export tags (all tag is not listed):
- sd_booted
-
sd_booted.
- sd_is
-
sd_is_fifo, sd_is_mq, sd_is_socket, sd_is_socket_inet, sd_is_socket_unix, sd_is_special.
- sd_listen
-
$SD_LISTEN_FDS_START, sd_listen_fds.
- sd_log
-
$SD_ALERT, $SD_CRIT, $SD_DEBUG, $SD_EMERG, $SD_ERR, $SD_INFO, $SD_NOTICE, $SD_WARNING.
- sd_notify
-
sd_notify, sd_pid_notify.
- sd
-
All above.
FUNCTIONS
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:
notify
$int = notify( VAR => VALUE, … );notify is Perl wrapper for C functions sd_notify and sd_pid_notify, so read sd_notify(3) first.
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.:
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.
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.
CONSTANTS
The module re-exports (by explicit request) all the constants from underlying implementation, see "CONSTANTS" in Systemd::Daemon::XS.
BUGS
SEE ALSO
AUTHOR
Van de Bugger <van.de.bugger@gmail.com>
COPYRIGHT AND LICENSE
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.