From aea6787f78fce73e45d1b4e6f2dd7927a90b4305 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Wed, 17 Apr 2024 18:11:31 +0200
Subject: [PATCH] man: mention that sd_journal_test_cursor() needs a
 positioning call

Fixes #30331.
---
 man/sd_journal_get_cursor.xml | 15 ++++++++-------
 man/sd_journal_seek_head.xml  | 10 ++++++++--
 2 files changed, 16 insertions(+), 9 deletions(-)

diff --git a/man/sd_journal_get_cursor.xml b/man/sd_journal_get_cursor.xml
index 305c08b910c..351c8984837 100644
--- a/man/sd_journal_get_cursor.xml
+++ b/man/sd_journal_get_cursor.xml
@@ -61,12 +61,6 @@
     and should be freed after use with
     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 
-    <para>Note that <function>sd_journal_get_cursor()</function> will
-    not work before
-    <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-    (or related call) has been called at least once, in order to
-    position the read pointer at a valid entry.</para>
-
     <para><function>sd_journal_test_cursor()</function>
     may be used to check whether the current position in
     the journal matches the specified cursor. This is
@@ -75,10 +69,17 @@
     multiple different cursor strings, and hence string
     comparing cursors is not possible. Use this call to
     verify after an invocation of
-    <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    <citerefentry><refentrytitle>sd_journal_seek_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
     whether the entry being sought to was actually found
     in the journal or the next closest entry was used
     instead.</para>
+
+    <para>Note that <function>sd_journal_get_cursor()</function>
+    and <function>sd_journal_test_cursor()</function>
+    will not work before
+    <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    (or one of the other functions which move to an entry)
+    has been called at least once to position the read pointer at a valid entry.</para>
   </refsect1>
 
   <refsect1>
diff --git a/man/sd_journal_seek_head.xml b/man/sd_journal_seek_head.xml
index 2172cae37ea..4e6fb9458ba 100644
--- a/man/sd_journal_seek_head.xml
+++ b/man/sd_journal_seek_head.xml
@@ -82,8 +82,7 @@
     string. For details on cursors, see
     <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
     If no entry matching the specified cursor is found the call will seek to the next closest entry (in terms
-    of time) instead. To verify whether the newly selected entry actually matches the cursor, use
-    <citerefentry><refentrytitle>sd_journal_test_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+    of time) instead.</para>
 
     <para>Note that these calls do not actually make any entry the new current entry, this needs to be done
     in a separate step with a subsequent
@@ -97,6 +96,13 @@
     used, the closest following entry will be sought to, if
     <citerefentry><refentrytitle>sd_journal_previous</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     is used the closest preceding entry is sought to.</para>
+
+    <para>After the seek is done, and
+    <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    or a similar call has been made,
+    <citerefentry><refentrytitle>sd_journal_test_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    may be used to verify whether the newly selected entry actually matches the cursor.
+    </para>
   </refsect1>
 
   <refsect1>