chiark / gitweb /
man: fully document sd-event interfaces
authorLennart Poettering <lennart@poettering.net>
Thu, 19 Nov 2015 22:38:54 +0000 (23:38 +0100)
committerSven Eden <yamakuzure@gmx.net>
Wed, 17 May 2017 13:22:14 +0000 (15:22 +0200)
This completes the set of man pages for sd-event and contains some minor
other fixes for other man pages too.

The sd_event_set_name(3) man page is renamed to
sd_event_source_set_description(3), which is the correct name of the
concept today.

13 files changed:
man/sd-event.xml [new file with mode: 0644]
man/sd_event_add_io.xml [new file with mode: 0644]
man/sd_event_exit.xml [new file with mode: 0644]
man/sd_event_now.xml [new file with mode: 0644]
man/sd_event_set_watchdog.xml [new file with mode: 0644]
man/sd_event_source_get_event.xml [new file with mode: 0644]
man/sd_event_source_get_pending.xml [new file with mode: 0644]
man/sd_event_source_set_description.xml [new file with mode: 0644]
man/sd_event_source_set_enabled.xml [new file with mode: 0644]
man/sd_event_source_set_prepare.xml [new file with mode: 0644]
man/sd_event_source_set_priority.xml [new file with mode: 0644]
man/sd_event_source_set_userdata.xml [new file with mode: 0644]
man/sd_event_source_unref.xml [new file with mode: 0644]

diff --git a/man/sd-event.xml b/man/sd-event.xml
new file mode 100644 (file)
index 0000000..c7d9377
--- /dev/null
@@ -0,0 +1,187 @@
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of elogind.
+
+  Copyright 2015 Lennart Poettering
+
+  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.
+
+  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 elogind; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="sd-event" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd-event</title>
+    <productname>elogind</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Lennart</firstname>
+        <surname>Poettering</surname>
+        <email>lennart@poettering.net</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd-event</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd-event</refname>
+    <refpurpose>A generic event loop implementation</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
+    </funcsynopsis>
+
+    <cmdsynopsis>
+      <command>pkg-config --cflags --libs libelogind</command>
+    </cmdsynopsis>
+
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><filename>sd-event.h</filename> provides a generic event
+    loop implementation, based on Linux <citerefentry
+    project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+    </para>
+
+    <para>See
+    <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_source_get_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    for more information about the functions available.</para>
+
+    <para>The event loop design is targeted on running a separate
+    instance of the event loop in each thread; it has no concept of
+    distributing events from a single event loop instance onto
+    multiple worker threads. Dispatching events is strictly ordered
+    and subject to configurable priorities. In each event loop
+    iteration a single event source is dispatched. Each time an event
+    source is dispatched the kernel is polled for new events, before
+    the next event source is dispatched. The event loop is designed to
+    honour priorities and provide fairness within each priority. It is
+    not designed to provide optimal throughput, as this contradicts
+    these goals due the limitations of the underlying <citerefentry
+    project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+    primitives.</para>
+
+    <para>The event loop implementation provides the following features:</para>
+
+    <orderedlist>
+      <listitem><para>I/O event sources, based on <citerefentry
+      project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>'s
+      file descriptor watching, including edge triggered events (<constant>EPOLLET</constant>). See <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
+
+      <listitem><para>Timer event sources, based on <citerefentry
+      project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
+      supporting the <constant>CLOCK_MONOTONIC</constant>,
+      <constant>CLOCK_REALTIME</constant>,
+      <constant>CLOCK_BOOTIME</constant> clocks, as well as the
+      <constant>CLOCK_REALTIME_ALARM</constant> and
+      <constant>CLOCK_BOOTTIME_ALARM</constant> clocks that can resume
+      the system from suspend. When creating timer events a required
+      accuracy parameter may be specified which allows coalescing of
+      timer events to minimize power consumption. See <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
+
+      <listitem><para>UNIX process signal events, based on
+      <citerefentry
+      project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
+      including full support for real-time signals, and queued parameters. See <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
+
+      <listitem><para>Child process state change events, based on
+      <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>. See <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
+
+      <listitem><para>Static event sources, of three types: defer,
+      post and exit, for invoking calls in each event loop, after
+      other event sources or at event loop termination. See
+      <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
+
+      <listitem><para>Event sources may be assigned a 64bit priority
+      value, that controls the order in which event sources are
+      dispatched if multiple are pending simultanously. See
+      <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
+
+      <listitem><para>The event loop may automatically send watchdog
+      notification messages to the service manager. See
+      <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
+
+      <listitem><para>The event loop may be integrated into foreign
+      event loops, such as the GLib one. See
+      <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+      for an example.</para></listitem>
+    </orderedlist>
+
+  </refsect1>
+
+  <xi:include href="libelogind-pkgconfig.xml" />
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_get_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/man/sd_event_add_io.xml b/man/sd_event_add_io.xml
new file mode 100644 (file)
index 0000000..4e01d27
--- /dev/null
@@ -0,0 +1,300 @@
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of elogind.
+
+  Copyright 2015 Lennart Poettering
+
+  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.
+
+  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 elogind; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="sd_event_add_io" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_event_add_io</title>
+    <productname>elogind</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Lennart</firstname>
+        <surname>Poettering</surname>
+        <email>lennart@poettering.net</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_event_add_io</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_event_add_io</refname>
+    <refname>sd_event_source_get_io_events</refname>
+    <refname>sd_event_source_set_io_events</refname>
+    <refname>sd_event_source_get_io_revents</refname>
+    <refname>sd_event_source_get_io_fd</refname>
+    <refname>sd_event_source_set_io_fd</refname>
+    <refname>sd_event_source</refname>
+    <refname>sd_event_io_handler_t</refname>
+
+    <refpurpose>Add an I/O event source to an event loop</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
+
+      <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>typedef int (*<function>sd_event_io_handler_t</function>)</funcdef>
+        <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
+        <paramdef>int <parameter>fd</parameter></paramdef>
+        <paramdef>uint32_t <parameter>revents</parameter></paramdef>
+        <paramdef>void *<parameter>userdata</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_add_io</function></funcdef>
+        <paramdef>sd_event *<parameter>event</parameter></paramdef>
+        <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
+        <paramdef>int <parameter>fd</parameter></paramdef>
+        <paramdef>uint32_t <parameter>events</parameter></paramdef>
+        <paramdef>sd_event_io_handler_t <parameter>handler</parameter></paramdef>
+        <paramdef>void *<parameter>userdata</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_get_io_events</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+        <paramdef>uint32_t *<parameter>events</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_set_io_events</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+        <paramdef>uint32_t <parameter>events</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_get_io_revents</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+        <paramdef>uint32_t *<parameter>revents</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_get_io_fd</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_set_io_fd</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+        <paramdef>int <parameter>fd</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_event_add_io()</function> adds a new I/O event
+    source to an event loop. The event loop object is specified in the
+    <parameter>event</parameter> parameter, the event source object is
+    returned in the <parameter>source</parameter> parameter. The
+    <parameter>fd</parameter> parameter takes the UNIX file descriptor
+    to watch, which may refer to a socket, a FIFO, a message queue, a
+    serial connection, a character device or any other file descriptor
+    compatible with Linux <citerefentry
+    project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
+    <parameter>events</parameter> parameter takes a bit mask of I/O
+    events to watch the file descriptor for, a combination of the
+    following event flags: <constant>EPOLLIN</constant>,
+    <constant>EPOLLOUT</constant>, <constant>EPOLLRDHUP</constant>,
+    <constant>EPOLLPRI</constant> and <constant>EPOLLET</constant>,
+    see <citerefentry
+    project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+    for details. The <parameter>handler</parameter> shall reference a
+    function to call when the I/O event source is triggered. The
+    handler function will be passed the
+    <parameter>userdata</parameter> pointer, which may be chosen
+    freely by the caller. The handler will also be passed the file
+    descriptor the event was seen on as well as the actual event flags
+    seen. It's generally a subset of the events watched, however may
+    additionally have <constant>EPOLLERR</constant> and
+    <constant>EPOLLHUP</constant> set.</para>
+
+    <para>By default, the I/O event source will stay enabled
+    continously (<constant>SD_EVENT_ON</constant>), but this may be
+    changed with
+    <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+    If the handler function returns a negative error code, it will be
+    disabled after the invocation, even if the
+    <constant>SD_EVENT_ON</constant> mode was requested before. Note
+    that an I/O event source set to <constant>SD_EVENT_ON</constant> will
+    fire continously unless data is read or written to the file
+    descriptor in order to reset the mask of events seen.
+    </para>
+
+    <para>Setting the I/O event mask to watch for to 0 does not mean
+    that the event source won't be triggered anymore, as
+    <constant>EPOLLHUP</constant> and <constant>EPOLLERR</constant>
+    may be triggered even with a zero event mask. To temporarily
+    disable an I/O event source use
+    <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    with <constant>SD_EVENT_OFF</constant> instead.</para>
+
+    <para>To destroy an event source object use
+    <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    but note that the event source is only removed from the event loop
+    when all references to the event source are dropped. To make sure
+    an event source does not fire anymore, even when there's still a
+    reference to it kept, consider setting the event source to
+    <constant>SD_EVENT_OFF</constant> with
+    <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+
+    <para>If the the second parameter of
+    <function>sd_event_add_io()</function> is passed as NULL no
+    reference to the event source object is returned. In this case the
+    event source is considered "floating", and will be destroyed
+    implicitly when the event loop itself is destroyed.</para>
+
+    <para>It is recommended to use
+    <function>sd_event_add_io()</function> only in conjunction with
+    file descriptors that have <constant>O_NONBLOCK</constant> set, to
+    ensure that all I/O operations from invoked handlers are properly
+    asynchronous and non-blocking. Using file descriptors without
+    <constant>O_NONBLOCK</constant> might result in unexpected
+    starving of other event sources. See <citerefentry
+    project='man-pages'><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+    for details on enabling <constant>O_NONBLOCK</constant> mode.</para>
+
+    <para><function>sd_event_source_get_io_events()</function> retrieves
+    the configured I/O event mask to watch of an I/O event source created
+    previously with <function>sd_event_add_io()</function>. It takes
+    the event source object and a pointer to a variable to store the
+    event mask in.</para>
+
+    <para><function>sd_event_source_set_io_events()</function> changes the
+    configured I/O event mask to watch of an I/O event source created previously
+    with <function>sd_event_add_io()</function>. It takes the event
+    source object and the new event mask to set.</para>
+
+    <para><function>sd_event_source_get_io_events()</function>
+    retrieves the I/O event mask of currently seen but undispatched
+    events from an I/O event source created previously with
+    <function>sd_event_add_io()</function>. It takes the event source
+    object and a pointer to a variable to store the event mask
+    in. When called from a handler function on the handler's event
+    source object this will return the same mask as passed to the
+    handler's <parameter>revents</parameter> parameter. This call is
+    primarily useful to check for undispatched events of an event
+    source from the handler of an unrelated (possibly higher priority)
+    event source. Note the relation between
+    <function>sd_event_source_get_pending()</function> and
+    <function>sd_event_source_get_io_revents()</function>: both
+    functions will report non-zero results when there's an event
+    pending for the event source, but the former applies to all event
+    source types, the latter only to I/O event sources.</para>
+
+    <para><function>sd_event_source_get_io_fd()</function> retrieves
+    the UNIX file descriptor of an I/O event source created previously
+    with <function>sd_event_add_io()</function>. It takes the event
+    source object and returns the positive file descriptor in the return
+    value, or a negative error number on error (see below).</para>
+
+    <para><function>sd_event_source_set_io_fd()</function>
+    changes the UNIX file descriptor of an I/O event source created
+    previously with <function>sd_event_add_io()</function>. It takes
+    the event source object and the new file descriptor to set.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On success, these functions return 0 or a positive
+    integer. On failure, they return a negative errno-style error
+    code. </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Errors</title>
+
+    <para>Returned errors may indicate the following problems:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><constant>-ENOMEM</constant></term>
+
+        <listitem><para>Not enough memory to allocate an object.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-EINVAL</constant></term>
+
+        <listitem><para>An invalid argument has been passed.</para></listitem>
+
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ESTALE</constant></term>
+
+        <listitem><para>The event loop is already terminated.</para></listitem>
+
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ECHILD</constant></term>
+
+        <listitem><para>The event loop has been created in a different process.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-EDOM</constant></term>
+
+        <listitem><para>The passed event source is not an I/O event source.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <xi:include href="libelogind-pkgconfig.xml" />
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/man/sd_event_exit.xml b/man/sd_event_exit.xml
new file mode 100644 (file)
index 0000000..20ef7b1
--- /dev/null
@@ -0,0 +1,163 @@
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of elogind.
+
+  Copyright 2015 Lennart Poettering
+
+  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.
+
+  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 elogind; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="sd_event_exit" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_event_exit</title>
+    <productname>elogind</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Lennart</firstname>
+        <surname>Poettering</surname>
+        <email>lennart@poettering.net</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_event_exit</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_event_exit</refname>
+    <refname>sd_event_get_exit_code</refname>
+
+    <refpurpose>Ask the event loop to exit</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_exit</function></funcdef>
+        <paramdef>sd_event *<parameter>event</parameter></paramdef>
+        <paramdef>int <parameter>code</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_get_exit_code</function></funcdef>
+        <paramdef>sd_event *<parameter>event</parameter></paramdef>
+        <paramdef>int *<parameter>code</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_event_exit()</function> requests the event loop
+    specified in the <parameter>event</parameter> event loop object to
+    exit. The <parameter>code</parameter> parameter may be any integer
+    value and is returned as-is by
+    <citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    after the last event loop iteration. It may also be be queried
+    using <function>sd_event_get_exit_code()</function>, see
+    below. </para>
+
+    <para>When exiting is requested the event loop will stop listening
+    for and dispatching regular event sources. Instead it will proceed
+    with executing only event sources registered with
+    <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    in the order defined by their priority. After all exit event
+    sources have been dispatched the event loop is terminated.</para>
+
+    <para>If <function>sd_event_exit()</function> is invoked a second
+    time while the event loop is still processing exit event sources,
+    the exit code stored in the event loop object is updated, but
+    otherwise no further operation is executed.</para>
+
+    <para><function>sd_event_get_exit_code()</function> may be used to
+    query the exit code passed into
+    <function>sd_event_exit()</function> earlier.</para>
+
+    <para>While the full positive and negative integer ranges may be used
+    for the exit code, care should be taken not pick exit codes that
+    conflict with regular exit codes returned by
+    <function>sd_event_loop()</function>, if these exit codes shall be
+    distinguishable.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On success, <function>sd_event_exit()</function> and
+    <function>sd_event_get_exit_code()</function> return 0 or a positive
+    integer. On failure, they return a negative errno-style error
+    code.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Errors</title>
+
+    <para>Returned errors may indicate the following problems:</para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term><constant>-EINVAL</constant></term>
+
+        <listitem><para>The event loop object or error code pointer are invalid.</para></listitem>
+
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ECHILD</constant></term>
+
+        <listitem><para>The event loop was created in a different process.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ESTALE</constant></term>
+
+        <listitem><para>The event loop has exited already and all exit handlers are already processed.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ENODATA</constant></term>
+
+        <listitem><para>The event loop has not been requested to exit yet.</para></listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <xi:include href="libelogind-pkgconfig.xml" />
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/man/sd_event_now.xml b/man/sd_event_now.xml
new file mode 100644 (file)
index 0000000..b410523
--- /dev/null
@@ -0,0 +1,141 @@
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of elogind.
+
+  Copyright 2015 Lennart Poettering
+
+  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.
+
+  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 elogind; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="sd_event_now" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_event_now</title>
+    <productname>elogind</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Lennart</firstname>
+        <surname>Poettering</surname>
+        <email>lennart@poettering.net</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_event_now</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_event_now</refname>
+
+    <refpurpose>Retrieve current event loop iteration timestamp</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_now</function></funcdef>
+        <paramdef>sd_event *<parameter>event</parameter></paramdef>
+        <paramdef>clockid_t <parameter>clock</parameter></paramdef>
+        <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_event_now()</function> returns the timestamp
+    the most recent event loop iteration began. This timestamp is
+    taken right after after returning from the event sleep, and before
+    dispatching any event sources. The <parameter>event</parameter>
+    parameter takes the even loop object to retrieve the timestamp
+    from. The <parameter>clock</parameter> parameter specifies the clock to
+    retrieve the timestamp for, and is one of
+    <constant>CLOCK_REALTIME</constant> (or its equivalent
+    <constant>CLOCK_REALTIME_ALARM</constant>),
+    <constant>CLOCK_MONOTONIC</constant> or
+    <constant>CLOCK_BOOTTIME</constant> (or its equivalent
+    <constant>CLOCK_BOOTTIME_ALARM</constant>), see <citerefentry
+    project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+    for more information on the various clocks. The retrieved
+    timestamp is stored in the <parameter>usec</parameter> parameter,
+    in µs since the clock's epoch. If this function is invoked before
+    the first event loop iteration the current time is returned, as
+    reported by <function>clock_gettime()</function>. To distinguish
+    this case from a regular invocation the return value will be
+    positive non-zero in this case, while it is zero when the returned
+    timestamp refers to the actual event loop iteration.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>If the first event loop iteration has not run yet
+    <function>sd_event_now()</function> returns the requested
+    timestamp in <parameter>usec</parameter> and returns a positive,
+    non-zero return value. Otherwise, on success it will return the
+    iteration's timestamp in <parameter>usec</parameter> and 0 as
+    return value. On failure, the call returns a negative errno-style
+    error code.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Errors</title>
+
+    <para>Returned errors may indicate the following problems:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><constant>-EINVAL</constant></term>
+
+        <listitem><para>An invalid parameter was
+        passed.</para></listitem>
+
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ECHILD</constant></term>
+
+        <listitem><para>The event loop object was created in a
+        different process.</para></listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <xi:include href="libelogind-pkgconfig.xml" />
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/man/sd_event_set_watchdog.xml b/man/sd_event_set_watchdog.xml
new file mode 100644 (file)
index 0000000..58a052d
--- /dev/null
@@ -0,0 +1,177 @@
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of elogind.
+
+  Copyright 2015 Lennart Poettering
+
+  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.
+
+  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 elogind; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="sd_event_set_watchdog" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_event_set_watchdog</title>
+    <productname>elogind</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Lennart</firstname>
+        <surname>Poettering</surname>
+        <email>lennart@poettering.net</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_event_set_watchdog</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_event_set_watchdog</refname>
+    <refname>sd_event_get_watchdog</refname>
+
+    <refpurpose>Enable event loop watchdog support</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_set_watchdog</function></funcdef>
+        <paramdef>sd_event *<parameter>event</parameter></paramdef>
+        <paramdef>int b</paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_get_watchdog</function></funcdef>
+        <paramdef>sd_event *<parameter>event</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_event_set_watchdog()</function> may be used to
+    enable or disable automatic watchdog notification support in the
+    event loop object specified in the <parameter>event</parameter>
+    parameter. Specifically, depending on the <parameter>b</parameter>
+    boolean argument this will make sure the event loop wakes up in
+    regular intervals and sends watchdog notification messages to the
+    service manager, if this was requested by the service
+    manager. Watchdog support is determined with
+    <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    and watchdog messages are sent with
+    <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. See
+    the <varname>WatchdogSec=</varname> setting in
+    <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    for details on how to enable watchdog support for a service and
+    the protocol used. The wake-up interval is chosen as half the
+    watchdog timeout declared by the service manager via the
+    <varname>$WATCHDOG_USEC</varname> environment variable. If the
+    service manager did not request watchdog notifications, or if the
+    process was not invoked by the service manager this call with a
+    true <parameter>b</parameter> parameter executes no
+    operation. Passing a false <parameter>b</parameter> parameter will
+    disable the automatic sending of watchdog notification messages if
+    it was enabled before. Newly allocated event loop objects have
+    this feature disabled.</para>
+
+    <para>The first watchdog notification message is sent immediately
+    when <function>set_event_set_watchdog()</function> is invoked with
+    a true <parameter>b</parameter> parameter.</para>
+
+    <para>The watchdog logic is designed to allow the service manager
+    to automatically detect services that ceased processing of
+    incoming events, and thus appear "hung". Watchdog notifications
+    are sent out only at the beginning of each event loop
+    iteration. If an event source dispatch function blocks for an
+    excessively long time and does not return execution to the event
+    loop quickly, this might hence cause the notification message to
+    be delayed, and possibly result in abnormal program termination,
+    as configured in the service unit file.</para>
+
+    <para><function>sd_event_get_watchdog()</function> may be used to
+    determine whether watchdog support was previously requested by a
+    call to <function>sd_event_set_watchdog()</function> with a true
+    <parameter>b</parameter> parameter and successfully
+    enabled.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On success, <function>sd_event_set_watchdog()</function> and
+    <function>sd_event_get_watchdog()</function> return a non-zero
+    positive integer if the service manager requested watchdog support
+    and watchdog support was successfully enabled. They return zero if
+    the service manager did not request watchdog support, or if
+    watchdog support was explicitly disabled with a false
+    <parameter>b</parameter> parameter. On failure, they return a
+    negative errno-style error
+    code.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Errors</title>
+
+    <para>Returned errors may indicate the following problems:</para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term><constant>-ECHILD</constant></term>
+
+        <listitem><para>The event loop has been created in a different process.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-EINVAL</constant></term>
+
+        <listitem><para>The passed event loop object was invalid.</para></listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <xi:include href="libelogind-pkgconfig.xml" />
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/man/sd_event_source_get_event.xml b/man/sd_event_source_get_event.xml
new file mode 100644 (file)
index 0000000..c9a52af
--- /dev/null
@@ -0,0 +1,100 @@
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of elogind.
+
+  Copyright 2015 Lennart Poettering
+
+  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.
+
+  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 elogind; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="sd_event_source_get_event" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_event_source_get_event</title>
+    <productname>elogind</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Lennart</firstname>
+        <surname>Poettering</surname>
+        <email>lennart@poettering.net</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_event_source_get_event</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_event_source_get_event</refname>
+
+    <refpurpose>Retrieve the event loop of an event source</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>sd_event* <function>sd_event_source_get_event</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_event_source_get_event()</function> may be used
+    to retrieve the event loop object the event source object specified
+    as <parameter>source</parameter> is associated with. The event
+    loop object is specified when creating an event source object with
+    calls such as
+    <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    or
+    <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On success, <function>sd_event_source_get_event()</function>
+    returns the associated event loop object. On failure, it returns
+    NULL.</para>
+  </refsect1>
+
+  <xi:include href="libelogind-pkgconfig.xml" />
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/man/sd_event_source_get_pending.xml b/man/sd_event_source_get_pending.xml
new file mode 100644 (file)
index 0000000..1339d50
--- /dev/null
@@ -0,0 +1,167 @@
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of elogind.
+
+  Copyright 2015 Lennart Poettering
+
+  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.
+
+  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 elogind; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="sd_event_source_get_pending" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_event_source_get_pending</title>
+    <productname>elogind</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Lennart</firstname>
+        <surname>Poettering</surname>
+        <email>lennart@poettering.net</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_event_source_get_pending</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_event_source_get_pending</refname>
+
+    <refpurpose>Determine pending state of event sources</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_get_pending</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_event_source_get_pending()</function> may be
+    used to determine whether the event source object specified as
+    <parameter>source</parameter> has seen events but has not been
+    dispatched yet (and thus is marked "pending").</para>
+
+    <para>Event source objects initially are not marked pending, when
+    they are created with calls such as
+    <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    with the exception of those created with
+    <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    which are immediately marked pending, and
+    <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    for which the "pending" concept is not defined. For details see
+    the respective manual pages.</para>
+
+    <para>In each event loop iteration one event source of those
+    marked pending is dispatched, in the order defined by the event
+    source priority, as set with
+    <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+
+    <para>For I/O event sources, as created with
+    <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    the call
+    <citerefentry><refentrytitle>sd_event_get_io_revents</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    may be used to query the type of event pending in more
+    detail.</para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On success,
+    <function>sd_event_source_get_pending()</function> returns an
+    integer greater than zero when the event source is marked pending,
+    and zero when the event source is not marked pending. On failure,
+    it returns a negative errno-style error code.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Errors</title>
+
+    <para>Returned errors may indicate the following problems:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><constant>-EINVAL</constant></term>
+
+        <listitem><para><parameter>source</parameter> is not a valid
+        pointer to an <structname>sd_event_source</structname>
+        object.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-EDOM</constant></term>
+
+        <listitem><para><parameter>source</parameter> refers to an
+        event source object created with
+        <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ENOMEM</constant></term>
+
+        <listitem><para>Not enough memory.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ESTALE</constant></term>
+
+        <listitem><para>The event loop is already terminated.</para></listitem>
+
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ECHILD</constant></term>
+
+        <listitem><para>The event loop has been created in a different process.</para></listitem>
+
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <xi:include href="libelogind-pkgconfig.xml" />
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/man/sd_event_source_set_description.xml b/man/sd_event_source_set_description.xml
new file mode 100644 (file)
index 0000000..9e8a1d6
--- /dev/null
@@ -0,0 +1,170 @@
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of elogind.
+
+  Copyright 2014 Zbigniew Jędrzejewski-Szmek
+
+  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.
+
+  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 elogind; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="sd_event_source_set_description" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_event_source_set_description</title>
+    <productname>elogind</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>More text</contrib>
+        <firstname>Zbigniew</firstname>
+        <surname>Jędrzejewski-Szmek</surname>
+        <email>zbyszek@in.waw.pl</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_event_source_set_description</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_event_source_set_description</refname>
+    <refname>sd_event_source_get_description</refname>
+
+    <refpurpose>Set or retrieve descriptive names of event sources</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_set_description</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+        <paramdef>const char *<parameter>description</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_get_description</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+        <paramdef>const char **<parameter>description</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_event_source_set_description()</function> may
+    be used to set an arbitrary descriptive name for the event source
+    object specified as <parameter>source</parameter>. This name will
+    be used in debugging messages generated by
+    <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    for this event source, and may be queried using
+    <function>sd_event_source_get_description()</function> for
+    debugging purposes. The <parameter>description</parameter> parameter shall
+    point to a <constant>NUL</constant>-terminated string or be
+    <constant>NULL</constant>. In the latter case, the descriptive
+    name will be unset. The string is copied internally, hence the
+    <parameter>description</parameter> argument is not referenced
+    after the function returns.</para>
+
+    <para><function>sd_event_source_get_description()</function> may
+    be used to query the current descriptive name assigned to the
+    event source object <parameter>source</parameter>. It returns a
+    pointer to the current name in <parameter>description</parameter>,
+    stored in memory internal to the event source. The memory is
+    invalidated when the event source is destroyed or the descriptive
+    name is changed.</para>
+
+    <para>Event source objects generally have no description set when
+    they are created, except for UNIX signal event sources created
+    with
+    <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    whose descriptive name is initialized to the signal's C constant
+    name (e.g. <literal>SIGINT</literal> or
+    <literal>SIGTERM</literal>).</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On success, <function>sd_event_source_set_description()</function> and
+    <function>sd_event_source_get_description()</function> return a
+    non-negative integer. On failure, they return a negative
+    errno-style error code.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Errors</title>
+
+    <para>Returned errors may indicate the following problems:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><constant>-EINVAL</constant></term>
+
+        <listitem><para><parameter>source</parameter> is not a valid
+        pointer to an <structname>sd_event_source</structname>
+        object or the <parameter>description</parameter> argument for
+        <function>sd_event_source_get_description()</function> is
+        <constant>NULL</constant>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ENOMEM</constant></term>
+
+        <listitem><para>Not enough memory to copy the
+        name.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ECHILD</constant></term>
+
+        <listitem><para>The event loop has been created in a different process.</para></listitem>
+
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ENXIO</constant></term>
+
+        <listitem><para>No name was set for the event
+        source.</para></listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <xi:include href="libelogind-pkgconfig.xml" />
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/man/sd_event_source_set_enabled.xml b/man/sd_event_source_set_enabled.xml
new file mode 100644 (file)
index 0000000..1dad6f0
--- /dev/null
@@ -0,0 +1,179 @@
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of elogind.
+
+  Copyright 2015 Lennart Poettering
+
+  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.
+
+  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 elogind; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="sd_event_source_set_enabled" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_event_source_set_enabled</title>
+    <productname>elogind</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Lennart</firstname>
+        <surname>Poettering</surname>
+        <email>lennart@poettering.net</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_event_source_set_enabled</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_event_source_set_enabled</refname>
+    <refname>sd_event_source_get_enabled</refname>
+    <refname>SD_EVENT_ON</refname>
+    <refname>SD_EVENT_OFF</refname>
+    <refname>SD_EVENT_ONESHOT</refname>
+
+    <refpurpose>Enable or disable event sources</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
+
+      <funcsynopsisinfo><token>enum</token> {
+        <constant>SD_EVENT_OFF</constant> = 0,
+        <constant>SD_EVENT_ON</constant> = 1,
+        <constant>SD_EVENT_ONESHOT</constant> = -1,
+};</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_set_enabled</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+        <paramdef>int <parameter>enabled</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_get_enabled</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+        <paramdef>int *<parameter>enabled</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_event_source_set_enabled()</function> may be
+    used to enable or disable the event source object specified as
+    <parameter>source</parameter>. The <parameter>enabled</parameter>
+    parameter takes one of <constant>SD_EVENT_ON</constant> (to
+    enable), <constant>SD_EVENT_OFF</constant> (to disable) or
+    <constant>SD_EVENT_ONESHOT</constant>. If invoked with
+    <constant>SD_EVENT_ONESHOT</constant> the event source will be
+    enabled but automatically reset to
+    <constant>SD_EVENT_OFF</constant> after the event source was
+    dispatched once.</para>
+
+    <para>Event sources that are disabled will not result in event
+    loop wakeups and will not be dispatched, until they are enabled
+    again.</para>
+
+    <para><function>sd_event_source_get_enabled()</function> may be
+    used to query whether the event source object
+    <parameter>source</parameter> is currently enabled or not. It
+    returns the enablement state in
+    <parameter>enabled</parameter>.</para>
+
+    <para>Event source objects are enabled when they are first created
+    with calls such as
+    <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. However,
+    depending on the event source type they are enabled continously
+    (<constant>SD_EVENT_ON</constant>) or only for a single invocation
+    of the event source handler
+    (<constant>SD_EVENT_ONESHOT</constant>). For details see the
+    respective manual pages.</para>
+
+    <para>As event source objects stay active and may be dispatched as
+    long as there is at least one reference to them, in many cases it
+    is a good idea to combine a call to
+    <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    with a prior call to
+    <function>sd_event_source_set_enabled()</function> with
+    <constant>SD_EVENT_OFF</constant>, to ensure the event source is
+    not dispatched again until all other remaining references are dropped.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On success, <function>sd_event_source_set_enabled()</function> and
+    <function>sd_event_source_get_enabled()</function> return a
+    non-negative integer. On failure, they return a negative
+    errno-style error code.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Errors</title>
+
+    <para>Returned errors may indicate the following problems:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><constant>-EINVAL</constant></term>
+
+        <listitem><para><parameter>source</parameter> is not a valid
+        pointer to an <structname>sd_event_source</structname>
+        object.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ENOMEM</constant></term>
+
+        <listitem><para>Not enough memory.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ECHILD</constant></term>
+
+        <listitem><para>The event loop has been created in a different process.</para></listitem>
+
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <xi:include href="libelogind-pkgconfig.xml" />
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/man/sd_event_source_set_prepare.xml b/man/sd_event_source_set_prepare.xml
new file mode 100644 (file)
index 0000000..e1763e6
--- /dev/null
@@ -0,0 +1,171 @@
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of elogind.
+
+  Copyright 2015 Lennart Poettering
+
+  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.
+
+  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 elogind; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="sd_event_source_set_prepare" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_event_source_set_prepare</title>
+    <productname>elogind</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Lennart</firstname>
+        <surname>Poettering</surname>
+        <email>lennart@poettering.net</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_event_source_set_prepare</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_event_source_set_prepare</refname>
+
+    <refpurpose>Set a preparation callback for event sources</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_set_prepare</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+        <paramdef>sd_event_handler_t <parameter>callback</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef>
+        <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
+        <paramdef>void *<parameter>userdata</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_event_source_set_prepare()</function> may be
+    used to set a prepartion callback for the event source object
+    specified as <parameter>source</parameter>. The callback function
+    specified as <parameter>callback</parameter> will be invoked
+    immediately before the event loop goes to sleep to wait for
+    incoming events. It is invoked with the user data pointer passed
+    when the event source was created. The callback function may be
+    used to reconfigure the precise events to wait for. If the
+    <parameter>callback</parameter> parameter is passed as NULL the
+    callback function is reset. </para>
+
+    <para>Event source objects have no preparation callback associated
+    when they are first created with calls such as
+    <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation
+    callback functions are supported for all event source types with
+    the exception of those created with
+    <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation
+    callback functions are dispatched in the order indicated by the
+    event source's priority field, as set with
+    <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation
+    callbacks of disabled event sources (see
+    <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
+    are not invoked.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On success,
+    <function>sd_event_source_set_prepare()</function> returns a
+    non-negative integer. On failure, it returns a negative
+    errno-style error code.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Errors</title>
+
+    <para>Returned errors may indicate the following problems:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><constant>-EINVAL</constant></term>
+
+        <listitem><para><parameter>source</parameter> is not a valid
+        pointer to an <structname>sd_event_source</structname>
+        object.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ESTALE</constant></term>
+
+        <listitem><para>The event loop is already terminated.</para></listitem>
+
+      </varlistentry>
+      <varlistentry>
+        <term><constant>-ENOMEM</constant></term>
+
+        <listitem><para>Not enough memory.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ECHILD</constant></term>
+
+        <listitem><para>The event loop has been created in a different process.</para></listitem>
+
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-EDOM</constant></term>
+
+        <listitem><para>The specified event source has been created
+        with
+        <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
+
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <xi:include href="libelogind-pkgconfig.xml" />
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/man/sd_event_source_set_priority.xml b/man/sd_event_source_set_priority.xml
new file mode 100644 (file)
index 0000000..0f7fde2
--- /dev/null
@@ -0,0 +1,189 @@
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of elogind.
+
+  Copyright 2015 Lennart Poettering
+
+  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.
+
+  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 elogind; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="sd_event_source_set_priority" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_event_source_set_priority</title>
+    <productname>elogind</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Lennart</firstname>
+        <surname>Poettering</surname>
+        <email>lennart@poettering.net</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_event_source_set_priority</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_event_source_set_priority</refname>
+    <refname>sd_event_source_get_priority</refname>
+    <refname>SD_EVENT_PRIORITY_IMPORTANT</refname>
+    <refname>SD_EVENT_PRIORITY_NORMAL</refname>
+    <refname>SD_EVENT_PRIORITY_IDLE</refname>
+
+    <refpurpose>Set or retrieve the priority of event sources</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
+
+      <funcsynopsisinfo><token>enum</token> {
+        <constant>SD_EVENT_SOURCE_IMPORTANT</constant> = -100,
+        <constant>SD_EVENT_SOURCE_NORMAL</constant> = 0,
+        <constant>SD_EVENT_SOURCE_IDLE</constant> = 100,
+};</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_set_priority</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+        <paramdef>int64_t <parameter>priority</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_get_priority</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+        <paramdef>int64_t *<parameter>priority</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_event_source_set_priority()</function> may be
+    used to set the priority for the event source object specified as
+    <parameter>source</parameter>. The priority is specified as an
+    arbitrary signed 64bit integer. The priority is initialized to
+    <constant>SD_EVENT_PRIORITY_NORMAL</constant> (0) when the event
+    source is allocated with a call such as
+    <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    or
+    <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    and may be changed with this call. If multiple event sources have seen events at the same time, they are dispatched in the order indicated by the
+    event sources' priorities. Event sources with smaller priority
+    values are dispatched first. As well-known points of reference,
+    the constants <constant>SD_EVENT_PRIORITY_IMPORTANT</constant>
+    (-100), <constant>SD_EVENT_PRIORITY_NORMAL</constant> (0) and
+    <constant>SD_EVENT_PRIORITY_IDLE</constant> (100) may be used to
+    indicate event sources that shall be dispatched early, normally or
+    late. It is recommended to specify priorities based on these
+    definitions, and relative to them -- however, the full 64bit
+    signed integer range is available for ordering event
+    sources.</para>
+
+    <para>Priorities define the order in which event sources that have
+    seen events are dispatched. Care should be taken to ensure that
+    high-priority event sources (those with negative priority values
+    assigned) do not cause starvation of low-priority event sources
+    (those with positive priority values assigned).</para>
+
+    <para>The order in which event sources with the same priority are
+    dispatched is undefined, but the event loop generally tries to
+    dispatch them in the order it learnt about events on them. As the
+    backing kernel primitives do not provide accurate information
+    about the order in which events occured this is not necessarily
+    reliable. However, it is guaranteed that if events are seen on
+    multiple same-priority event sources at the same time, each one is
+    not dispatched again until all others have been dispatched
+    once. This behaviour guarantees that within each priority
+    particular event sources do not starve or dominate the event
+    loop.</para>
+
+    <para><function>sd_event_source_get_priority()</function> may be
+    used to query the current priority assigned to the event source
+    object <parameter>source</parameter>.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On success,
+    <function>sd_event_source_set_priority()</function> and
+    <function>sd_event_source_get_priority()</function> return a
+    non-negative integer. On failure, they return a negative
+    errno-style error code.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Errors</title>
+
+    <para>Returned errors may indicate the following problems:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><constant>-EINVAL</constant></term>
+
+        <listitem><para><parameter>source</parameter> is not a valid
+        pointer to an <structname>sd_event_source</structname>
+        object.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ENOMEM</constant></term>
+
+        <listitem><para>Not enough memory.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ESTALE</constant></term>
+
+        <listitem><para>The event loop is already terminated.</para></listitem>
+
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ECHILD</constant></term>
+
+        <listitem><para>The event loop has been created in a different process.</para></listitem>
+
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <xi:include href="libelogind-pkgconfig.xml" />
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/man/sd_event_source_set_userdata.xml b/man/sd_event_source_set_userdata.xml
new file mode 100644 (file)
index 0000000..6975396
--- /dev/null
@@ -0,0 +1,119 @@
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of elogind.
+
+  Copyright 2015 Lennart Poettering
+
+  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.
+
+  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 elogind; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="sd_event_source_set_userdata" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_event_source_set_userdata</title>
+    <productname>elogind</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Lennart</firstname>
+        <surname>Poettering</surname>
+        <email>lennart@poettering.net</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_event_source_set_userdata</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_event_source_set_userdata</refname>
+    <refname>sd_event_source_get_userdata</refname>
+
+    <refpurpose>Set or retrieve user data pointer of event sources</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>void* <function>sd_event_source_set_userdata</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+        <paramdef>void *<parameter>userdata</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>void* <function>sd_event_source_get_userdata</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_event_source_set_userdata()</function> may be
+    used to set an arbitrary user data pointer for the event source
+    object specified as <parameter>source</parameter>. The user data
+    pointer is usually specified when creating an event source object
+    with calls such as
+    <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    or
+    <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    and may be updated with this call. The user data pointer is also
+    passed to all handler callback functions associated with the event
+    source. The <parameter>userdata</parameter> parameter specifies
+    the new user data pointer to set, the function returns the
+    previous user data pointer. Note that <constant>NULL</constant> is
+    a valid user data pointer.</para>
+
+    <para><function>sd_event_source_get_userdata()</function> may be
+    used to query the current user data pointer assigned to the event
+    source object <parameter>source</parameter>.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On success,
+    <function>sd_event_source_set_userdata()</function> and
+    <function>sd_event_source_get_userdata()</function> return the
+    previously set user data pointer. On failure, they return
+    NULL.</para>
+  </refsect1>
+
+  <xi:include href="libelogind-pkgconfig.xml" />
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/man/sd_event_source_unref.xml b/man/sd_event_source_unref.xml
new file mode 100644 (file)
index 0000000..3c1a64d
--- /dev/null
@@ -0,0 +1,125 @@
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of elogind.
+
+  Copyright 2015 Lennart Poettering
+
+  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.
+
+  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 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>elogind</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Lennart</firstname>
+        <surname>Poettering</surname>
+        <email>lennart@poettering.net</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_event_source_unref</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_event_source_unref</refname>
+    <refname>sd_event_source_ref</refname>
+
+    <refpurpose>Increase or decrease event source reference counters</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>sd_event_source* <function>sd_event_source_unref</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>sd_event_source* <function>sd_event_source_ref</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_event_source_unref()</function> may be used to
+    decrement by one the reference counter of the event source object
+    specified as <parameter>source</parameter>. The reference counter
+    is initially set to one, when the event source is created with calls
+    such as
+    <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    or
+    <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. When
+    the reference counter reaches zero it is removed from its event loop
+    object and destroyed.</para>
+
+    <para><function>sd_event_source_ref()</function> may be used
+    to increase by one the reference counter of the event source object
+    specified as <parameter>source</parameter>.</para>
+
+    <para>Both functions execute no operation if the passed event
+    source object is <constant>NULL</constant>.</para>
+
+    <para>Note that event source objects stay alive and may be
+    dispatched as long as they have a reference counter greater than
+    zero. In order to drop a reference of an event source and make
+    sure the associated event source handler function is not called
+    anymore it is recommended to combine a call of
+    <function>sd_event_source_unref()</function> with a prior call to
+    <function>sd_event_source_set_enabled()</function> with
+    <constant>SD_EVENT_OFF</constant>.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para><function>sd_event_source_unref()</function> always returns
+    <constant>NULL</constant>.
+    <function>sd_event_source_ref()</function> always returns the
+    event source object passed in.</para>
+  </refsect1>
+
+  <xi:include href="libelogind-pkgconfig.xml" />
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>