mirror of
https://github.com/systemd/systemd
synced 2024-10-15 04:24:19 +00:00
man: clarify that sd_journal_seek_head() seeks *before* the first entry
This commit is contained in:
parent
a3b1790c1a
commit
88f739cb11
|
@ -66,46 +66,38 @@
|
|||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para><function>sd_journal_seek_head()</function> seeks to the
|
||||
beginning of the journal, i.e. the oldest available entry.</para>
|
||||
<para><function>sd_journal_seek_head()</function> seeks to the beginning of the journal, i.e. to the
|
||||
position before the oldest available entry.</para>
|
||||
|
||||
<para>Similarly, <function>sd_journal_seek_tail()</function> may
|
||||
be used to seek to the end of the journal, i.e. the most recent
|
||||
available entry.</para>
|
||||
<para>Similarly, <function>sd_journal_seek_tail()</function> may be used to seek to the end of the
|
||||
journal, i.e. the position after the most recent available entry.</para>
|
||||
|
||||
<para><function>sd_journal_seek_monotonic_usec()</function> seeks
|
||||
to the entry with the specified monotonic timestamp, i.e.
|
||||
<constant>CLOCK_MONOTONIC</constant>. Since monotonic time
|
||||
restarts on every reboot a boot ID needs to be specified as
|
||||
well.</para>
|
||||
<para><function>sd_journal_seek_monotonic_usec()</function> seeks to a position with the specified
|
||||
monotonic timestamp, i.e. <constant>CLOCK_MONOTONIC</constant>. Since monotonic time restarts on every
|
||||
reboot a boot ID needs to be specified as well.</para>
|
||||
|
||||
<para><function>sd_journal_seek_realtime_usec()</function> seeks
|
||||
to the entry with the specified realtime (wallclock) timestamp,
|
||||
i.e. <constant>CLOCK_REALTIME</constant>. Note that the realtime
|
||||
clock is not necessarily monotonic. If a realtime timestamp is
|
||||
ambiguous, it is not defined which position is sought to.</para>
|
||||
<para><function>sd_journal_seek_realtime_usec()</function> seeks to a position with the specified
|
||||
realtime (wallclock) timestamp, i.e. <constant>CLOCK_REALTIME</constant>. Note that the realtime clock is
|
||||
not necessarily monotonic. If a realtime timestamp is ambiguous, it is not defined which position is
|
||||
sought to.</para>
|
||||
|
||||
<para><function>sd_journal_seek_cursor()</function> seeks to the
|
||||
entry located at the specified cursor string. For details on
|
||||
cursors, see
|
||||
<para><function>sd_journal_seek_cursor()</function> seeks to the position at the specified cursor
|
||||
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
|
||||
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>
|
||||
|
||||
<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
|
||||
<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
|
||||
<citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
invocation (or a similar call). Only then, entry data may be
|
||||
retrieved via
|
||||
<citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||
If no entry exists that matches exactly the specified seek
|
||||
address, the next closest is sought to. If
|
||||
<citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
is used, the closest following entry will be sought to, if
|
||||
invocation (or a similar call). Only then, entry data may be retrieved via
|
||||
<citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
or an entry cursor be retrieved via
|
||||
<citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||
If no entry exists that matches exactly the specified seek address, the next closest is sought to. If
|
||||
<citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry> is
|
||||
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>
|
||||
</refsect1>
|
||||
|
|
Loading…
Reference in a new issue