The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Systemd-Daemon-0.07
River stage zero No dependents
3 ++
/ Systemd::Daemon

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.