From 88f739cb117d5c8a01ca69244b0b867e2960bf10 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 13 Mar 2019 12:29:25 +0100 Subject: [PATCH] man: clarify that sd_journal_seek_head() seeks *before* the first entry --- man/sd_journal_seek_head.xml | 56 ++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 32 deletions(-) diff --git a/man/sd_journal_seek_head.xml b/man/sd_journal_seek_head.xml index da88d241e8..cb349e6dda 100644 --- a/man/sd_journal_seek_head.xml +++ b/man/sd_journal_seek_head.xml @@ -66,46 +66,38 @@ Description - sd_journal_seek_head() seeks to the - beginning of the journal, i.e. the oldest available entry. + sd_journal_seek_head() seeks to the beginning of the journal, i.e. to the + position before the oldest available entry. - Similarly, sd_journal_seek_tail() may - be used to seek to the end of the journal, i.e. the most recent - available entry. + Similarly, sd_journal_seek_tail() may be used to seek to the end of the + journal, i.e. the position after the most recent available entry. - sd_journal_seek_monotonic_usec() seeks - to the entry with the specified monotonic timestamp, i.e. - CLOCK_MONOTONIC. Since monotonic time - restarts on every reboot a boot ID needs to be specified as - well. + sd_journal_seek_monotonic_usec() seeks to a position with the specified + monotonic timestamp, i.e. CLOCK_MONOTONIC. Since monotonic time restarts on every + reboot a boot ID needs to be specified as well. - sd_journal_seek_realtime_usec() seeks - to the entry with the specified realtime (wallclock) timestamp, - i.e. CLOCK_REALTIME. Note that the realtime - clock is not necessarily monotonic. If a realtime timestamp is - ambiguous, it is not defined which position is sought to. + sd_journal_seek_realtime_usec() seeks to a position with the specified + realtime (wallclock) timestamp, i.e. CLOCK_REALTIME. Note that the realtime clock is + not necessarily monotonic. If a realtime timestamp is ambiguous, it is not defined which position is + sought to. - sd_journal_seek_cursor() seeks to the - entry located at the specified cursor string. For details on - cursors, see + sd_journal_seek_cursor() seeks to the position at the specified cursor + string. For details on cursors, see sd_journal_get_cursor3. - 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 + 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 sd_journal_test_cursor3. - 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 + 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 sd_journal_next3 - invocation (or a similar call). Only then, entry data may be - retrieved via - sd_journal_get_data3. - If no entry exists that matches exactly the specified seek - address, the next closest is sought to. If - sd_journal_next3 - is used, the closest following entry will be sought to, if + invocation (or a similar call). Only then, entry data may be retrieved via + sd_journal_get_data3 + or an entry cursor be retrieved via + sd_journal_get_cursor3. + If no entry exists that matches exactly the specified seek address, the next closest is sought to. If + sd_journal_next3 is + used, the closest following entry will be sought to, if sd_journal_previous3 is used the closest preceding entry is sought to.