]> git.ipfire.org Git - thirdparty/systemd.git/blob - man/sd_journal_seek_head.xml
Merge pull request #8822 from fbuihuu/rfc-tmpfiles-safe-upstream
[thirdparty/systemd.git] / man / sd_journal_seek_head.xml
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">
4
5 <!--
6 SPDX-License-Identifier: LGPL-2.1+
7 -->
8
9 <refentry id="sd_journal_seek_head" xmlns:xi="http://www.w3.org/2001/XInclude">
10
11 <refentryinfo>
12 <title>sd_journal_seek_head</title>
13 <productname>systemd</productname>
14 </refentryinfo>
15
16 <refmeta>
17 <refentrytitle>sd_journal_seek_head</refentrytitle>
18 <manvolnum>3</manvolnum>
19 </refmeta>
20
21 <refnamediv>
22 <refname>sd_journal_seek_head</refname>
23 <refname>sd_journal_seek_tail</refname>
24 <refname>sd_journal_seek_monotonic_usec</refname>
25 <refname>sd_journal_seek_realtime_usec</refname>
26 <refname>sd_journal_seek_cursor</refname>
27 <refpurpose>Seek to a position in the
28 journal</refpurpose>
29 </refnamediv>
30
31 <refsynopsisdiv>
32 <funcsynopsis>
33 <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
34
35 <funcprototype>
36 <funcdef>int <function>sd_journal_seek_head</function></funcdef>
37 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
38 </funcprototype>
39
40 <funcprototype>
41 <funcdef>int <function>sd_journal_seek_tail</function></funcdef>
42 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
43 </funcprototype>
44
45 <funcprototype>
46 <funcdef>int <function>sd_journal_seek_monotonic_usec</function></funcdef>
47 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
48 <paramdef>sd_id128_t <parameter>boot_id</parameter></paramdef>
49 <paramdef>uint64_t <parameter>usec</parameter></paramdef>
50 </funcprototype>
51
52 <funcprototype>
53 <funcdef>int <function>sd_journal_seek_realtime_usec</function></funcdef>
54 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
55 <paramdef>uint64_t <parameter>usec</parameter></paramdef>
56 </funcprototype>
57
58 <funcprototype>
59 <funcdef>int <function>sd_journal_seek_cursor</function></funcdef>
60 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
61 <paramdef>const char *<parameter>cursor</parameter></paramdef>
62 </funcprototype>
63 </funcsynopsis>
64 </refsynopsisdiv>
65
66 <refsect1>
67 <title>Description</title>
68
69 <para><function>sd_journal_seek_head()</function> seeks to the
70 beginning of the journal, i.e. the oldest available entry.</para>
71
72 <para>Similarly, <function>sd_journal_seek_tail()</function> may
73 be used to seek to the end of the journal, i.e. the most recent
74 available entry.</para>
75
76 <para><function>sd_journal_seek_monotonic_usec()</function> seeks
77 to the entry with the specified monotonic timestamp, i.e.
78 <constant>CLOCK_MONOTONIC</constant>. Since monotonic time
79 restarts on every reboot a boot ID needs to be specified as
80 well.</para>
81
82 <para><function>sd_journal_seek_realtime_usec()</function> seeks
83 to the entry with the specified realtime (wallclock) timestamp,
84 i.e. <constant>CLOCK_REALTIME</constant>. Note that the realtime
85 clock is not necessarily monotonic. If a realtime timestamp is
86 ambiguous, it is not defined which position is sought to.</para>
87
88 <para><function>sd_journal_seek_cursor()</function> seeks to the
89 entry located at the specified cursor string. For details on
90 cursors, see
91 <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
92 If no entry matching the specified cursor is found the call will
93 seek to the next closest entry (in terms of time) instead. To
94 verify whether the newly selected entry actually matches the
95 cursor, use
96 <citerefentry><refentrytitle>sd_journal_test_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
97
98 <para>Note that these calls do not actually make any entry the new
99 current entry, this needs to be done in a separate step with a
100 subsequent
101 <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
102 invocation (or a similar call). Only then, entry data may be
103 retrieved via
104 <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
105 If no entry exists that matches exactly the specified seek
106 address, the next closest is sought to. If
107 <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
108 is used, the closest following entry will be sought to, if
109 <citerefentry><refentrytitle>sd_journal_previous</refentrytitle><manvolnum>3</manvolnum></citerefentry>
110 is used the closest preceding entry is sought to.</para>
111 </refsect1>
112
113 <refsect1>
114 <title>Return Value</title>
115
116 <para>The functions return 0 on success or a negative errno-style
117 error code.</para>
118 </refsect1>
119
120 <refsect1>
121 <title>Notes</title>
122
123 <para>All functions listed here are thread-agnostic and only a single thread may operate
124 on a given <structname>sd_journal</structname> object.</para>
125
126 <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
127 </refsect1>
128
129 <refsect1>
130 <title>See Also</title>
131
132 <para>
133 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
134 <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
135 <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
136 <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
137 <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
138 <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
139 <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>
140 </para>
141 </refsect1>
142
143 </refentry>