man: fully document sd-event interfaces

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.

1 files changed, 116 insertions, 51 deletions

diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml
index c5f7aee19d..df38f52fc9 100644
--- a/man/sd_event_add_time.xml
+++ b/man/sd_event_add_time.xml
@@ -21,7 +21,7 @@
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
-<refentry id="sd_event_add_time">
+<refentry id="sd_event_add_time" xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
     <title>sd_event_add_time</title>
@@ -49,13 +49,23 @@
     <refname>sd_event_source_get_time_accuracy</refname>
     <refname>sd_event_source_set_time_accuracy</refname>
     <refname>sd_event_source_get_time_clock</refname>
+    <refname>sd_event_time_handler_t</refname>
 
     <refpurpose>Add a timer event source to an event loop</refpurpose>
   </refnamediv>
 
   <refsynopsisdiv>
     <funcsynopsis>
-      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
+      <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
+
+      <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>typedef int (*<function>sd_event_time_handler_t</function>)</funcdef>
+        <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
+        <paramdef>uint64_t <parameter>usec</parameter></paramdef>
+        <paramdef>void *<parameter>userdata</parameter></paramdef>
+      </funcprototype>
 
       <funcprototype>
         <funcdef>int <function>sd_event_add_time</function></funcdef>
@@ -69,34 +79,27 @@
       </funcprototype>
 
       <funcprototype>
-        <funcdef>typedef int (*<function>sd_event_time_handler_t</function>)</funcdef>
-        <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
-        <paramdef>uint64_t <parameter>usec</parameter></paramdef>
-        <paramdef>void *<parameter>userdata</parameter></paramdef>
-      </funcprototype>
-
-      <funcprototype>
         <funcdef>int <function>sd_event_source_get_time</function></funcdef>
         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
-        <paramdef>usec_t *<parameter>usec</parameter></paramdef>
+        <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
       </funcprototype>
 
       <funcprototype>
         <funcdef>int <function>sd_event_source_set_time</function></funcdef>
         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
-        <paramdef>usec_t <parameter>usec</parameter></paramdef>
+        <paramdef>uint64_t <parameter>usec</parameter></paramdef>
       </funcprototype>
 
       <funcprototype>
         <funcdef>int <function>sd_event_source_get_time_accuracy</function></funcdef>
         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
-        <paramdef>usec_t *<parameter>usec</parameter></paramdef>
+        <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
       </funcprototype>
 
       <funcprototype>
         <funcdef>int <function>sd_event_source_set_time_accuracy</function></funcdef>
         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
-        <paramdef>usec_t <parameter>usec</parameter></paramdef>
+        <paramdef>uint64_t <parameter>usec</parameter></paramdef>
       </funcprototype>
 
       <funcprototype>
@@ -112,73 +115,130 @@
     <title>Description</title>
 
     <para><function>sd_event_add_time()</function> adds a new timer
-    event source to an event loop object. The event loop is specified
-    in <parameter>event</parameter>, the event source is returned in
-    the <parameter>source</parameter> parameter. The
-    <parameter>clock</parameter> parameter takes a clock identifier,
-    one of <constant>CLOCK_REALTIME</constant>,
-    <constant>CLOCK_MONOTONIC</constant> and
+    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>clock</parameter> parameter takes a
+    clock identifier, one of <constant>CLOCK_REALTIME</constant>,
+    <constant>CLOCK_MONOTONIC</constant>,
+    <constant>CLOCK_BOOTTIME</constant>,
+    <constant>CLOCK_REALTIME_ALARM</constant> or
     <constant>CLOCK_BOOTTIME_ALARM</constant>. See
     <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
     for details regarding the various types of clocks. The
     <parameter>usec</parameter> parameter takes a time value in
-    microseconds, relative to the clock's epoch specifying when the
-    timer shall elapse the earliest. The
+    microseconds (µs), relative to the clock's epoch, specifying when
+    the timer shall elapse the earliest. If a time that already lies
+    in the past is specified (including 0), the timer source is
+    dispatched immediately in the next event loop iterations. The
     <parameter>accuracy</parameter> parameter takes an additional
-    accuracy value in microseconds specifying a time the timer event
-    may be delayed. Specify 0 for selecting the default accuracy
-    (250ms). Specify 1 for most accurate timers. Consider specifying
-    60000000 or larger (1h) for long-running events that may be
+    accuracy value in µs specifying a time the timer event may be
+    delayed. Specify 0 for selecting the default accuracy
+    (250ms). Specify 1µs for most accurate timers. Consider specifying
+    60000000µs or larger (1min) for long-running events that may be
     delayed substantially. Picking higher accuracy values allows the
     system to coalesce timer events more aggressively, thus improving
-    power efficiency. The <parameter>handler</parameter> shall
-    reference a function to call when the timer elapses. The handler
-    function will be passed the <parameter>userdata</parameter>
-    pointer, which may be chosen freely by the caller. The handler is
-    also passed the configured time it was triggered, however it might
-    actually have been called at a slightly later time, subject to the
-    specified accuracy value, the kernel timer slack (see
+    power efficiency. The <parameter>handler</parameter> parameter
+    shall reference a function to call when the timer elapses. The
+    handler function will be passed the
+    <parameter>userdata</parameter> pointer, which may be chosen
+    freely by the caller. The handler is also passed the configured
+    time it was triggered, however it might actually have been called
+    at a slightly later time, subject to the specified accuracy value,
+    the kernel timer slack (see
     <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>)
-    and additional scheduling latencies.</para>
+    and additional scheduling latencies. To query the actual time the
+    handler was called use
+    <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 
     <para>By default, the timer will elapse once
     (<constant>SD_EVENT_ONESHOT</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
-    <constant>SD_EVENT_ON</constant> mode is set.
+    disabled after the invocation, even if the
+    <constant>SD_EVENT_ON</constant> mode was requested before. Note
+    that a timer event set to <constant>SD_EVENT_ON</constant> will
+    fire continously unless its configured time is updated using
+    <function>sd_event_source_set_time()</function>.
     </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_time()</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>If the <parameter>handler</parameter> to
+    <function>sd_event_add_time()</function> is passed as NULL, and
+    the event source fires, this will be considered a request to exit
+    the event loop. In this case, the <parameter>userdata</parameter>
+    parameter, cast to an integer is used for the exit code passed to
+    <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+
+    <para>Use <constant>CLOCK_BOOTTIME_ALARM</constant> and
+    <constant>CLOCK_REALTIME_ALARM</constant> to define event sources
+    that may wake up the system from suspend.</para>
+
+    <para>In order to set up relative timers (that is, relative to the
+    current time), retrieve the current time via
+    <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    add the desired timespan to sleep to it, and pass the result as
+    the <parameter>usec</parameter> parameter to
+    <function>sd_event_add_time()</function>.</para>
+
+    <para>In order to set up repetitive timers (that is, timers that
+    are triggered in regular intervals), set up the timer normally,
+    for the first invocation. Each time the event handler is invoked,
+    update the timer's trigger time with
+    <citerefentry><refentrytitle>sd_event_source_set_time</refentrytitle><manvolnum>3</manvolnum></citerefentry> for the next timer
+    iteration, and reenable the timer using
+    <function>sd_event_source_set_enabled()</function>. To calculate
+    the next point in time to pass to
+    <function>sd_event_source_set_time()</function>, either use as
+    base the <parameter>usec</parameter> parameter passed to the timer
+    callback, or the timestamp returned by
+    <function>sd_event_now()</function>. In the former case timer
+    events will be regular, while in the latter case the scheduling
+    latency will keep accumulating on the timer.</para>
+
     <para><function>sd_event_source_get_time()</function> retrieves
     the configured time value of a timer event source created
     previously with <function>sd_event_add_time()</function>. It takes
     the event source object and a pointer to a variable to store the
-    time in microseconds in.</para>
+    time, relative to the selected clock's epoch, in µs in.</para>
 
     <para><function>sd_event_source_set_time()</function> changes the
     configured time value of a timer event source created previously
     with <function>sd_event_add_time()</function>. It takes the event
     source object and a time relative to the selected clock's
-    epoch, in microseconds.</para>
+    epoch, in µs.</para>
 
     <para><function>sd_event_source_get_time_accuracy()</function>
     retrieves the configured accuracy value of a timer event source
     created previously with <function>sd_event_add_time()</function>. It
     takes the event source object and a pointer to a variable to store
-    the accuracy in microseconds in.</para>
+    the accuracy in µs in.</para>
 
     <para><function>sd_event_source_set_time_accuracy()</function>
     changes the configured accuracy of a timer event source created
     previously with <function>sd_event_add_time()</function>. It takes
-    the event source object and an accuracy, in microseconds.</para>
+    the event source object and an accuracy, in µs.</para>
 
     <para><function>sd_event_source_get_time_clock()</function>
     retrieves the configured clock of a timer event source created
     previously with <function>sd_event_add_time()</function>. It takes
     the event source object and a pointer to a variable to store the
     clock identifier in.</para>
-
   </refsect1>
 
   <refsect1>
@@ -228,19 +288,17 @@
         <listitem><para>The selected clock is not supported by the event loop implementation.</para></listitem>
 
       </varlistentry>
-    </variablelist>
-  </refsect1>
 
-  <refsect1>
-    <title>Notes</title>
+      <varlistentry>
+        <term><constant>-EDOM</constant></term>
 
-    <para><function>sd_event_add_time()</function> and the other functions
-    described here are available as a shared library, which can be
-    compiled and linked to with the
-    <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    file.</para>
+        <listitem><para>The passed event source is not a timer event source.</para></listitem>
+      </varlistentry>
+    </variablelist>
   </refsect1>
 
+  <xi:include href="libsystemd-pkgconfig.xml" />
+
   <refsect1>
     <title>See Also</title>
 
@@ -248,11 +306,18 @@
       <citerefentry><refentrytitle>systemd</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_io</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>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>sd_event_source_set_enabled</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 project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
+      <citerefentry project='man-pages'><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
     </para>
   </refsect1>