man/sd_journal_seek_head.xml

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