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
  15     <authorgroup>
  16       <author>
  17         <contrib>Developer</contrib>
  18         <firstname>Lennart</firstname>
  19         <surname>Poettering</surname>
  20         <email>lennart@poettering.net</email>
  21       </author>
  22     </authorgroup>
  23   </refentryinfo>
  24
  25   <refmeta>
  26     <refentrytitle>sd_journal_seek_head</refentrytitle>
  27     <manvolnum>3</manvolnum>
  28   </refmeta>
  29
  30   <refnamediv>
  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
  37     journal</refpurpose>
  38   </refnamediv>
  39
  40   <refsynopsisdiv>
  41     <funcsynopsis>
  42       <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  43
  44       <funcprototype>
  45         <funcdef>int <function>sd_journal_seek_head</function></funcdef>
  46         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  47       </funcprototype>
  48
  49       <funcprototype>
  50         <funcdef>int <function>sd_journal_seek_tail</function></funcdef>
  51         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  52       </funcprototype>
  53
  54       <funcprototype>
  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>
  59       </funcprototype>
  60
  61       <funcprototype>
  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>
  65       </funcprototype>
  66
  67       <funcprototype>
  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>
  71       </funcprototype>
  72     </funcsynopsis>
  73   </refsynopsisdiv>
  74
  75   <refsect1>
  76     <title>Description</title>
  77
  78     <para><function>sd_journal_seek_head()</function> seeks to the
  79     beginning of the journal, i.e. the oldest available entry.</para>
  80
  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>
  84
  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
  89     well.</para>
  90
  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>
  96
  97     <para><function>sd_journal_seek_cursor()</function> seeks to the
  98     entry located at the specified cursor string. For details on
  99     cursors, see
 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
 104     cursor, use
 105     <citerefentry><refentrytitle>sd_journal_test_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 106
 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
 109     subsequent
 110     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 111     invocation (or a similar call). Only then, entry data may be
 112     retrieved via
 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>
 120   </refsect1>
 121
 122   <refsect1>
 123     <title>Return Value</title>
 124
 125     <para>The functions return 0 on success or a negative errno-style
 126     error code.</para>
 127   </refsect1>
 128
 129   <refsect1>
 130     <title>Notes</title>
 131
 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>
 134
 135     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 136   </refsect1>
 137
 138   <refsect1>
 139     <title>See Also</title>
 140
 141     <para>
 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>
 149     </para>
 150   </refsect1>
 151
 152 </refentry>