1 <?xml version='
1.0'
?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id=
"sd_journal_seek_head" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
12 <title>sd_journal_seek_head
</title>
13 <productname>systemd
</productname>
17 <contrib>Developer
</contrib>
18 <firstname>Lennart
</firstname>
19 <surname>Poettering
</surname>
20 <email>lennart@poettering.net
</email>
26 <refentrytitle>sd_journal_seek_head
</refentrytitle>
27 <manvolnum>3</manvolnum>
31 <refname>sd_journal_seek_head
</refname>
32 <refname>sd_journal_seek_tail
</refname>
33 <refname>sd_journal_seek_monotonic_usec
</refname>
34 <refname>sd_journal_seek_realtime_usec
</refname>
35 <refname>sd_journal_seek_cursor
</refname>
36 <refpurpose>Seek to a position in the
42 <funcsynopsisinfo>#include
<systemd/sd-journal.h
></funcsynopsisinfo>
45 <funcdef>int
<function>sd_journal_seek_head
</function></funcdef>
46 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
50 <funcdef>int
<function>sd_journal_seek_tail
</function></funcdef>
51 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
55 <funcdef>int
<function>sd_journal_seek_monotonic_usec
</function></funcdef>
56 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
57 <paramdef>sd_id128_t
<parameter>boot_id
</parameter></paramdef>
58 <paramdef>uint64_t
<parameter>usec
</parameter></paramdef>
62 <funcdef>int
<function>sd_journal_seek_realtime_usec
</function></funcdef>
63 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
64 <paramdef>uint64_t
<parameter>usec
</parameter></paramdef>
68 <funcdef>int
<function>sd_journal_seek_cursor
</function></funcdef>
69 <paramdef>sd_journal *
<parameter>j
</parameter></paramdef>
70 <paramdef>const char *
<parameter>cursor
</parameter></paramdef>
76 <title>Description
</title>
78 <para><function>sd_journal_seek_head()
</function> seeks to the
79 beginning of the journal, i.e. the oldest available entry.
</para>
81 <para>Similarly,
<function>sd_journal_seek_tail()
</function> may
82 be used to seek to the end of the journal, i.e. the most recent
83 available entry.
</para>
85 <para><function>sd_journal_seek_monotonic_usec()
</function> seeks
86 to the entry with the specified monotonic timestamp, i.e.
87 <constant>CLOCK_MONOTONIC
</constant>. Since monotonic time
88 restarts on every reboot a boot ID needs to be specified as
91 <para><function>sd_journal_seek_realtime_usec()
</function> seeks
92 to the entry with the specified realtime (wallclock) timestamp,
93 i.e.
<constant>CLOCK_REALTIME
</constant>. Note that the realtime
94 clock is not necessarily monotonic. If a realtime timestamp is
95 ambiguous, it is not defined which position is sought to.
</para>
97 <para><function>sd_journal_seek_cursor()
</function> seeks to the
98 entry located at the specified cursor string. For details on
100 <citerefentry><refentrytitle>sd_journal_get_cursor
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
101 If no entry matching the specified cursor is found the call will
102 seek to the next closest entry (in terms of time) instead. To
103 verify whether the newly selected entry actually matches the
105 <citerefentry><refentrytitle>sd_journal_test_cursor
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
107 <para>Note that these calls do not actually make any entry the new
108 current entry, this needs to be done in a separate step with a
110 <citerefentry><refentrytitle>sd_journal_next
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
111 invocation (or a similar call). Only then, entry data may be
113 <citerefentry><refentrytitle>sd_journal_get_data
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
114 If no entry exists that matches exactly the specified seek
115 address, the next closest is sought to. If
116 <citerefentry><refentrytitle>sd_journal_next
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
117 is used, the closest following entry will be sought to, if
118 <citerefentry><refentrytitle>sd_journal_previous
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
119 is used the closest preceding entry is sought to.
</para>
123 <title>Return Value
</title>
125 <para>The functions return
0 on success or a negative errno-style
132 <para>All functions listed here are thread-agnostic and only a single thread may operate
133 on a given
<structname>sd_journal
</structname> object.
</para>
135 <xi:include href=
"libsystemd-pkgconfig.xml" xpointer=
"pkgconfig-text"/>
139 <title>See Also
</title>
142 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
143 <citerefentry><refentrytitle>sd-journal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
144 <citerefentry><refentrytitle>sd_journal_open
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
145 <citerefentry><refentrytitle>sd_journal_next
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
146 <citerefentry><refentrytitle>sd_journal_get_data
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
147 <citerefentry><refentrytitle>sd_journal_get_cursor
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
148 <citerefentry><refentrytitle>sd_journal_get_realtime_usec
</refentrytitle><manvolnum>3</manvolnum></citerefentry>