"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
- This file is part of systemd.
+ This file is part of elogind.
Copyright 2015 Lennart Poettering
- systemd is free software; you can redistribute it and/or modify it
+ elogind is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
- systemd is distributed in the hope that it will be useful, but
+ elogind is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
- along with systemd; If not, see <http://www.gnu.org/licenses/>.
+ along with elogind; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_source_unref" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_source_unref</title>
- <productname>systemd</productname>
+ <productname>elogind</productname>
<authorgroup>
<author>
<refsynopsisdiv>
<funcsynopsis>
- <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo>
+ <funcsynopsisinfo>#include <elogind/sd-event.h></funcsynopsisinfo>
<funcprototype>
<funcdef>sd_event_source* <function>sd_event_source_unref</function></funcdef>
watchdog timestamp. This is the keep-alive ping that services
need to issue in regular intervals if
<varname>WatchdogSec=</varname> is enabled for it. See
- <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for information how to enable this functionality and
<citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for the details of how the service can check whether the
<varlistentry>
<term>FDSTORE=1</term>
- <listitem><para>Stores additional file descriptors in the service manager. File descriptors sent this way will
- be maintained per-service by the service manager and will later be handed back using the usual file descriptor
- passing logic at the next invocation of the service, see
- <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This is
- useful for implementing services that can restart after an explicit request or a crash without losing
- state. Any open sockets and other file descriptors which should not be closed during the restart may be stored
- this way. Application state can either be serialized to a file in <filename>/run</filename>, or better, stored
- in a <citerefentry><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> memory
- file descriptor. Note that the service manager will accept messages for a service only if its
- <varname>FileDescriptorStoreMax=</varname> setting is non-zero (defaults to zero, see
- <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If file
- descriptors sent are pollable (see
- <citerefentry><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), then any
- <constant>EPOLLHUP</constant> or <constant>EPOLLERR</constant> event seen on them will result in their
- automatic removal from the store. Multiple arrays of file descriptors may be sent in separate messages, in
- which case the arrays are combined. Note that the service manager removes duplicate (pointing to the same
- object) file descriptors before passing them to the service. Use <function>sd_pid_notify_with_fds()</function>
- to send messages with <literal>FDSTORE=1</literal>, see below.</para></listitem>
+ <listitem><para>Stores additional file descriptors in the service manager. File
+ descriptors sent this way will be maintained per-service by the service manager
+ and will be passed again using the usual file descriptor passing logic on the next
+ invocation of the service, see
+ <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+ This is useful for implementing service restart schemes where services serialize
+ their state to <filename>/run</filename>, push their file descriptors to the
+ system manager, and are then restarted, retrieving their state again via socket
+ passing and <filename>/run</filename>. Note that the service manager will accept
+ messages for a service only if <varname>FileDescriptorStoreMax=</varname> is set
+ to non-zero for it (defaults to zero, see
+ <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
+ File descriptors must be pollable, see
+ <citerefentry><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
+ Multiple arrays of file descriptors may be sent in separate messages, in which
+ case the arrays are combined. Note that the service manager removes duplicate
+ file descriptors before passing them to the service. Use
+ <function>sd_pid_notify_with_fds()</function> to send messages with
+ <literal>FDSTORE=1</literal>, see below.</para></listitem>
</varlistentry>
<varlistentry>
<para>Note that elogind will accept status data sent from a
service only if the <varname>NotifyAccess=</varname> option is
correctly set in the service definition file. See
- <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details.</para>
<para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only if either
<refsect1>
<title>Return Value</title>
- <para>On failure, these calls return a negative errno-style error code. If <varname>$NOTIFY_SOCKET</varname> was
- not set and hence no status message could be sent, 0 is returned. If the status was sent, these functions return a
- positive value. In order to support both service managers that implement this scheme and those which do not, it is
- generally recommended to ignore the return value of this call. Note that the return value simply indicates whether
- the notification message was enqueued properly, it does not reflect whether the message could be processed
- successfully. Specifically, no error is returned when a file descriptor is attempted to be stored using
- <varname>FDSTORE=1</varname> but the service is not actually configured to permit storing of file descriptors (see
- above).</para>
+ <para>On failure, these calls return a negative errno-style error
+ code. If <varname>$NOTIFY_SOCKET</varname> was not set and hence
+ no status data could be sent, 0 is returned. If the status was
+ sent, these functions return with a positive return value. In
+ order to support both, init systems that implement this scheme and
+ those which do not, it is generally recommended to ignore the
+ return value of this call.</para>
</refsect1>
<refsect1>
<refsect1>
<title>See Also</title>
<para>
- <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
</para>
</refsect1>
~ianmdlvl / elogind.git / commitdiff