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     <xi:include href="threads-aware.xml" xpointer="strict"/>
 124
 125     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 126   </refsect1>
 127
 128   <refsect1>
 129     <title>See Also</title>
 130
 131     <para>
 132       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 133       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 134       <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 135       <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 136       <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 137       <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 138       <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 139     </para>
 140   </refsect1>
 141
 142 </refentry>