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