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