sd_journal_get_cursor() tweaks (#36964)

man/sd_journal_get_cursor.xml

@@ -28,7 +28,7 @@
       <funcprototype>
         <funcdef>int <function>sd_journal_get_cursor</function></funcdef>
         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
-        <paramdef>char **<parameter>cursor</parameter></paramdef>
+        <paramdef>char **<parameter>ret_cursor</parameter></paramdef>
       </funcprototype>
 
       <funcprototype>
@@ -43,23 +43,21 @@
   <refsect1>
     <title>Description</title>
 
-    <para><function>sd_journal_get_cursor()</function> returns a
-    cursor string for the current journal entry. A cursor is a
-    serialization of the current journal position formatted as text.
-    The string only contains printable characters and can be passed
-    around in text form. The cursor identifies a journal entry
-    globally and in a stable way and may be used to later seek to it
-    via
+    <para><function>sd_journal_get_cursor()</function> returns a cursor string for the current journal
+    entry. A cursor is a serialization of the current journal position formatted as text.  The string only
+    contains printable characters and can be passed around in text form. The cursor identifies a journal
+    entry globally and in a stable way and may be used to later seek to it via
     <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
-    The cursor string should be considered opaque and not be parsed by
-    clients. Seeking to a cursor position without the specific entry
-    being available locally will seek to the next closest (in terms of
-    time) available entry. The call takes two arguments: a journal
-    context object and a pointer to a string pointer where the cursor
-    string will be placed. The string is allocated via libc
-    <citerefentry project='man-pages'><refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-    and should be freed after use with
-    <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+    The cursor string should be considered opaque and not be parsed by clients. Seeking to a cursor position
+    without the specific entry being available locally will seek to the next closest (in terms of time)
+    available entry. The call takes two arguments: a journal context object and a pointer to a string pointer
+    where the cursor string will be placed. The string is allocated via libc <citerefentry
+    project='man-pages'><refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
+    should be freed after use with <citerefentry
+    project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The
+    <parameter>ret_cursor</parameter> parameter may be passed as <constant>NULL</constant> in which case the
+    cursor string is not generated, however the return value will indicate whether the journal context is
+    currently positioned on an entry, and thus has a cursor associated.</para>
 
     <para><function>sd_journal_test_cursor()</function>
     may be used to check whether the current position in
@@ -91,6 +89,34 @@
     the current entry matches the specified cursor, 0 if it does not
     match the specified cursor or a negative errno-style error code on
     failure.</para>
+
+    <refsect2>
+      <title>Errors</title>
+
+      <para>Returned errors may indicate the following problems:</para>
+
+      <variablelist>
+        <varlistentry>
+          <term><constant>-EADDRNOTAVAIL</constant></term>
+
+          <listitem><para>The journal context is currently not positioned on any entry, and hence no cursor
+          string can be generated.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-EINVAL</constant></term>
+
+          <listitem><para>The journal context parameter is <constant>NULL</constant>.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-ECHILD</constant></term>
+
+          <listitem><para>The journal context object has been allocated in a different process than it is
+          being used in now.</para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
   </refsect1>
 
   <refsect1>

src/libsystemd/sd-journal/sd-journal.c

@@ -1234,13 +1234,12 @@ _public_ int sd_journal_previous_skip(sd_journal *j, uint64_t skip) {
         return real_journal_next_skip(j, DIRECTION_UP, skip);
 }
 
-_public_ int sd_journal_get_cursor(sd_journal *j, char **cursor) {
+_public_ int sd_journal_get_cursor(sd_journal *j, char **ret_cursor) {
         Object *o;
         int r;
 
         assert_return(j, -EINVAL);
         assert_return(!journal_origin_changed(j), -ECHILD);
-        assert_return(cursor, -EINVAL);
 
         if (!j->current_file || j->current_file->current_offset <= 0)
                 return -EADDRNOTAVAIL;
@@ -1249,7 +1248,10 @@ _public_ int sd_journal_get_cursor(sd_journal *j, char **cursor) {
         if (r < 0)
                 return r;
 
-        if (asprintf(cursor,
+        if (!ret_cursor)
+                return 0;
+
+        if (asprintf(ret_cursor,
                      "s=%s;i=%"PRIx64";b=%s;m=%"PRIx64";t=%"PRIx64";x=%"PRIx64,
                      SD_ID128_TO_STRING(j->current_file->header->seqnum_id), le64toh(o->entry.seqnum),
                      SD_ID128_TO_STRING(o->entry.boot_id), le64toh(o->entry.monotonic),

src/systemd/sd-journal.h

@@ -124,7 +124,7 @@ int sd_journal_seek_monotonic_usec(sd_journal *j, sd_id128_t boot_id, uint64_t u
 int sd_journal_seek_realtime_usec(sd_journal *j, uint64_t usec);
 int sd_journal_seek_cursor(sd_journal *j, const char *cursor);
 
-int sd_journal_get_cursor(sd_journal *j, char **cursor);
+int sd_journal_get_cursor(sd_journal *j, char **ret_cursor);
 int sd_journal_test_cursor(sd_journal *j, const char *cursor);
 
 int sd_journal_get_cutoff_realtime_usec(sd_journal *j, uint64_t *from, uint64_t *to);