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   This file is part of systemd.
   9
  10   Copyright 2012 Lennart Poettering
  11
  12   systemd is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   systemd is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <refentry id="sd_journal_seek_head">
  27
  28   <refentryinfo>
  29     <title>sd_journal_seek_head</title>
  30     <productname>systemd</productname>
  31
  32     <authorgroup>
  33       <author>
  34         <contrib>Developer</contrib>
  35         <firstname>Lennart</firstname>
  36         <surname>Poettering</surname>
  37         <email>lennart@poettering.net</email>
  38       </author>
  39     </authorgroup>
  40   </refentryinfo>
  41
  42   <refmeta>
  43     <refentrytitle>sd_journal_seek_head</refentrytitle>
  44     <manvolnum>3</manvolnum>
  45   </refmeta>
  46
  47   <refnamediv>
  48     <refname>sd_journal_seek_head</refname>
  49     <refname>sd_journal_seek_tail</refname>
  50     <refname>sd_journal_seek_monotonic_usec</refname>
  51     <refname>sd_journal_seek_realtime_usec</refname>
  52     <refname>sd_journal_seek_cursor</refname>
  53     <refpurpose>Seek to a position in the
  54     journal</refpurpose>
  55   </refnamediv>
  56
  57   <refsynopsisdiv>
  58     <funcsynopsis>
  59       <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  60
  61       <funcprototype>
  62         <funcdef>int <function>sd_journal_seek_head</function></funcdef>
  63         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  64       </funcprototype>
  65
  66       <funcprototype>
  67         <funcdef>int <function>sd_journal_seek_tail</function></funcdef>
  68         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  69       </funcprototype>
  70
  71       <funcprototype>
  72         <funcdef>int <function>sd_journal_seek_monotonic_usec</function></funcdef>
  73         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  74         <paramdef>sd_id128_t <parameter>boot_id</parameter></paramdef>
  75         <paramdef>uint64_t <parameter>usec</parameter></paramdef>
  76       </funcprototype>
  77
  78       <funcprototype>
  79         <funcdef>int <function>sd_journal_seek_realtime_usec</function></funcdef>
  80         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  81         <paramdef>uint64_t <parameter>usec</parameter></paramdef>
  82       </funcprototype>
  83
  84       <funcprototype>
  85         <funcdef>int <function>sd_journal_seek_cursor</function></funcdef>
  86         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  87         <paramdef>const char *<parameter>cursor</parameter></paramdef>
  88       </funcprototype>
  89     </funcsynopsis>
  90   </refsynopsisdiv>
  91
  92   <refsect1>
  93     <title>Description</title>
  94
  95     <para><function>sd_journal_seek_head()</function> seeks to the
  96     beginning of the journal, i.e. the oldest available entry.</para>
  97
  98     <para>Similarly, <function>sd_journal_seek_tail()</function> may
  99     be used to seek to the end of the journal, i.e. the most recent
 100     available entry.</para>
 101
 102     <para><function>sd_journal_seek_monotonic_usec()</function> seeks
 103     to the entry with the specified monotonic timestamp, i.e.
 104     <constant>CLOCK_MONOTONIC</constant>. Since monotonic time
 105     restarts on every reboot a boot ID needs to be specified as
 106     well.</para>
 107
 108     <para><function>sd_journal_seek_realtime_usec()</function> seeks
 109     to the entry with the specified realtime (wallclock) timestamp,
 110     i.e. <constant>CLOCK_REALTIME</constant>. Note that the realtime
 111     clock is not necessarily monotonic. If a realtime timestamp is
 112     ambiguous, it is not defined which position is sought to.</para>
 113
 114     <para><function>sd_journal_seek_cursor()</function> seeks to the
 115     entry located at the specified cursor string. For details on
 116     cursors, see
 117     <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 118     If no entry matching the specified cursor is found the call will
 119     seek to the next closest entry (in terms of time) instead. To
 120     verify whether the newly selected entry actually matches the
 121     cursor, use
 122     <citerefentry><refentrytitle>sd_journal_test_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 123
 124     <para>Note that these calls do not actually make any entry the new
 125     current entry, this needs to be done in a separate step with a
 126     subsequent
 127     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 128     invocation (or a similar call). Only then, entry data may be
 129     retrieved via
 130     <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 131     If no entry exists that matches exactly the specified seek
 132     address, the next closest is sought to. If
 133     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 134     is used, the closest following entry will be sought to, if
 135     <citerefentry><refentrytitle>sd_journal_previous</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 136     is used the closest preceding entry is sought to.</para>
 137   </refsect1>
 138
 139   <refsect1>
 140     <title>Return Value</title>
 141
 142     <para>The functions return 0 on success or a negative errno-style
 143     error code.</para>
 144   </refsect1>
 145
 146   <refsect1>
 147     <title>Notes</title>
 148
 149     <para>All functions listed here are thread-agnostic and only a single thread may operate
 150     on a given <structname>sd_journal</structname> object.</para>
 151
 152     <para>The <function>sd_journal_seek_head()</function>,
 153     <function>sd_journal_seek_tail()</function>,
 154     <function>sd_journal_seek_monotonic_usec()</function>,
 155     <function>sd_journal_seek_realtime_usec()</function>,
 156     and <function>sd_journal_seek_cursor()</function>
 157     interfaces are available as a shared library, which can
 158     be compiled and linked to with the
 159     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 160     file.</para>
 161   </refsect1>
 162
 163   <refsect1>
 164     <title>See Also</title>
 165
 166     <para>
 167       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 168       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 169       <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 170       <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 171       <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 172       <citerefentry><refentrytitle>sd_journal_get_cursor</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 173       <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 174     </para>
 175   </refsect1>
 176
 177 </refentry>