man,journal: add note about sd_journal_get_cutoff_monotonic_usec return value

Also modify the function itself to be a bit simpler to read.

1 files changed, 23 insertions, 13 deletions

diff --git a/man/sd_journal_get_cutoff_realtime_usec.xml b/man/sd_journal_get_cutoff_realtime_usec.xml
index 0b24399088..673cff4591 100644
--- a/man/sd_journal_get_cutoff_realtime_usec.xml
+++ b/man/sd_journal_get_cutoff_realtime_usec.xml
@@ -74,25 +74,29 @@
                 <title>Description</title>
 
                 <para><function>sd_journal_get_cutoff_realtime_usec()</function>
-                gets the realtime (wallclock) timestamps of the first
-                and last entries accessible in the journal.  It takes
-                three arguments: the journal context object and two
-                pointers to 64-bit unsigned integers to store the
-                timestamps in. The timestamps are in microseconds
-                since the epoch,
+                retrieves the realtime (wallclock) timestamps of the
+                first and last entries accessible in the journal.  It
+                takes three arguments: the journal context object
+                <parameter>j</parameter> and two pointers
+                <parameter>from</parameter> and
+                <parameter>to</parameter> pointing at 64-bit unsigned
+                integers to store the timestamps in. The timestamps
+                are in microseconds since the epoch,
                 i.e. <constant>CLOCK_REALTIME</constant>. Either one
                 of the two timestamp arguments may be passed as
                 <constant>NULL</constant> in case the timestamp is not
                 needed, but not both.</para>
 
                 <para><function>sd_journal_get_cutoff_monotonic_usec()</function>
-                gets the monotonic timestamps of the first and last
-                entries accessible in the journal. It takes three
-                arguments: the journal context object, a 128-bit
-                identifier for the boot, and two pointers to 64-bit
-                unsigned integers to store the timestamps. The
-                timestamps are in microseconds since boot-up of the
-                specific boot,
+                retrieves the monotonic timestamps of the first and
+                last entries accessible in the journal. It takes three
+                arguments: the journal context object
+                <parameter>j</parameter>, a 128-bit identifier for the
+                boot <parameter>boot_id</parameter>, and two pointers
+                to 64-bit unsigned integers to store the timestamps,
+                <parameter>from</parameter> and
+                <parameter>to</parameter>. The timestamps are in
+                microseconds since boot-up of the specific boot,
                 i.e. <constant>CLOCK_MONOTONIC</constant>. Since the
                 monotonic clock begins new with every reboot it only
                 defines a well-defined point in time when used
@@ -113,6 +117,12 @@
                 <function>sd_journal_get_cutoff_monotonic_usec()</function>
                 return 1 on success, 0 if not suitable entries are in
                 the journal or a negative errno-style error code.</para>
+
+                <para>Locations pointed to by parameters
+                <parameter>from</parameter> and
+                <parameter>to</parameter> will be set only if the
+                return value is positive, and obviously, the
+                parameters are non-null.</para>
         </refsect1>
 
         <refsect1>