From 4c5e74f71be6dab3d064690672cb84737b198be5 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Tue, 28 Jul 2020 11:18:08 +0200
Subject: [PATCH] man: document new relative time APIs in sd-event

---
 man/sd_event_add_time.xml | 53 +++++++++++++++++++++++++++++++--------
 1 file changed, 43 insertions(+), 10 deletions(-)

diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml
index 8d3511ef63..1fc24c8ab0 100644
--- a/man/sd_event_add_time.xml
+++ b/man/sd_event_add_time.xml
@@ -51,6 +51,17 @@
         <paramdef>void *<parameter>userdata</parameter></paramdef>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef>int <function>sd_event_add_time_relative</function></funcdef>
+        <paramdef>sd_event *<parameter>event</parameter></paramdef>
+        <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
+        <paramdef>clockid_t <parameter>clock</parameter></paramdef>
+        <paramdef>uint64_t <parameter>usec</parameter></paramdef>
+        <paramdef>uint64_t <parameter>accuracy</parameter></paramdef>
+        <paramdef>sd_event_time_handler_t <parameter>handler</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>
@@ -63,6 +74,12 @@
         <paramdef>uint64_t <parameter>usec</parameter></paramdef>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef>int <function>sd_event_source_set_time_relative</function></funcdef>
+        <paramdef>sd_event_source *<parameter>source</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>
@@ -123,6 +140,11 @@
     <function>sd_event_source_set_time()</function>.
     </para>
 
+    <para><function>sd_event_add_time_relative()</function> is like <function>sd_event_add_time()</function>,
+    but takes a relative time specification. It's relative to the current time of the event loop iteration,
+    as returned by
+    <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</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
@@ -173,17 +195,21 @@
     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 an 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, relative to the selected clock's epoch, in µs.</para>
+    <para><function>sd_event_source_get_time()</function> retrieves the configured time value of an event
+    source created previously with <function>sd_event_add_time()</function> or
+    <function>sd_event_add_time_relative()</function>. It takes the event source object and a pointer to a
+    variable to store the time in, relative to the selected clock's epoch, in µs. The returned value is
+    relative to the epoch, even if the event source was created with a relative time via
+    <function>sd_event_add_time_relative()</function>.</para>
 
-    <para><function>sd_event_source_set_time()</function> changes the
-    time of an 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 µs.</para>
+    <para><function>sd_event_source_set_time()</function> changes the time of an event source created
+    previously with <function>sd_event_add_time()</function> or
+    <function>sd_event_add_time_relative()</function>. It takes the event source object and a time relative
+    to the selected clock's epoch, in µs.</para>
+
+    <para><function>sd_event_source_set_time_relative()</function> is similar to
+    <function>sd_event_source_set_time()</function>, but takes a time relative to the current time of the
+    event loop iteration, as returned by <function>sd_event_now()</function>.</para>
 
     <para><function>sd_event_source_get_time_accuracy()</function>
     retrieves the configured accuracy value of an event source
@@ -255,6 +281,13 @@
 
           <listitem><para>The passed event source is not a timer event source.</para></listitem>
         </varlistentry>
+
+        <varlistentry>
+          <term><constant>-EOVERFLOW</constant></term>
+
+          <listitem><para>The passed relative time is outside of the allowed range for time values (i.e. the
+          specified value added to the current time is outside the 64 bit unsigned integer range).</para></listitem>
+        </varlistentry>
       </variablelist>
     </refsect2>
   </refsect1>