2012-07-14 00:39:02 +04:00
<?xml version='1.0'?> <!-- * - nxml - * -->
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2012 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http: / / w w w . g n u . o r g / l i c e n s e s /> .
-->
<refentry id= "sd_journal_seek_head" >
<refentryinfo >
<title > sd_journal_seek_head</title>
<productname > systemd</productname>
<authorgroup >
<author >
<contrib > Developer</contrib>
<firstname > Lennart</firstname>
<surname > Poettering</surname>
<email > lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta >
<refentrytitle > sd_journal_seek_head</refentrytitle>
<manvolnum > 3</manvolnum>
</refmeta>
<refnamediv >
<refname > sd_journal_seek_head</refname>
<refname > sd_journal_seek_tail</refname>
<refname > sd_journal_seek_monotonic_usec</refname>
<refname > sd_journal_seek_realtime_usec</refname>
<refname > sd_journal_seek_cursor</refname>
<refpurpose > Seek to a position in the
journal</refpurpose>
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcsynopsisinfo > #include < systemd/sd-journal.h> </funcsynopsisinfo>
<funcprototype >
<funcdef > int <function > sd_journal_seek_head</function> </funcdef>
<paramdef > sd_journal* <parameter > j</parameter> </paramdef>
</funcprototype>
<funcprototype >
<funcdef > int <function > sd_journal_seek_tail</function> </funcdef>
<paramdef > sd_journal* <parameter > j</parameter> </paramdef>
</funcprototype>
<funcprototype >
<funcdef > int <function > sd_journal_seek_monotonic_usec</function> </funcdef>
<paramdef > sd_journal* <parameter > j</parameter> </paramdef>
<paramdef > sd_id128_t <parameter > boot_id</parameter> </paramdef>
<paramdef > uint64_t <parameter > usec</parameter> </paramdef>
</funcprototype>
<funcprototype >
<funcdef > int <function > sd_journal_seek_realtime_usec</function> </funcdef>
<paramdef > sd_journal* <parameter > j</parameter> </paramdef>
<paramdef > uint64_t <parameter > usec</parameter> </paramdef>
</funcprototype>
<funcprototype >
<funcdef > int <function > sd_journal_seek_cursor</function> </funcdef>
<paramdef > sd_journal* <parameter > j</parameter> </paramdef>
<paramdef > const char * <parameter > cursor</parameter> </paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 >
<title > Description</title>
<para > <function > sd_journal_seek_head()</function>
seeks to the beginning of the journal, i.e. the oldest
2012-07-15 12:41:40 +04:00
available entry.</para>
2012-07-14 00:39:02 +04:00
2013-12-26 05:47:43 +04:00
<para > Similarly,
2012-07-14 00:39:02 +04:00
<function > sd_journal_seek_tail()</function> may be
used to seek to the end of the journal, i.e. the most
recent available entry.</para>
<para > <function > sd_journal_seek_monotonic_usec()</function>
seeks to the entry with the specified monotonic
2013-06-27 03:47:34 +04:00
timestamp,
i.e. <constant > CLOCK_MONOTONIC</constant> . Since
monotonic time restarts on every reboot a boot ID
needs to be specified as well.</para>
2012-07-14 00:39:02 +04:00
<para > <function > sd_journal_seek_realtime_usec()</function>
seeks to the entry with the specified realtime
2013-06-27 03:47:34 +04:00
(wallclock) timestamp,
i.e. <constant > CLOCK_REALTIME</constant> . Note that
2012-10-26 02:16:47 +04:00
the realtime clock is not necessarily monotonic. If a
2013-09-12 23:12:49 +04:00
realtime timestamp is ambiguous, it is not defined
2012-07-15 12:41:40 +04:00
which position is sought to.</para>
2012-07-14 00:39:02 +04:00
<para > <function > sd_journal_seek_cursor()</function>
seeks to the entry located at the specified cursor
2013-09-12 23:12:49 +04:00
string. For details on cursors, see
2012-10-11 00:39:45 +04:00
<citerefentry > <refentrytitle > sd_journal_get_cursor</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> . If
no entry matching the specified cursor is found the
call will seek to the next closest entry (in terms of
time) instead. To verify whether the newly selected
2013-09-12 23:12:49 +04:00
entry actually matches the cursor, use
2012-10-11 00:39:45 +04:00
<citerefentry > <refentrytitle > sd_journal_test_cursor</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> .</para>
2012-07-14 00:39:02 +04:00
<para > Note that these calls do not actually make any
entry the new current entry, this needs to be done in
a separate step with a subsequent
<citerefentry > <refentrytitle > sd_journal_next</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
2013-09-12 23:12:49 +04:00
invocation (or a similar call). Only then, entry data
2012-07-14 00:39:02 +04:00
may be retrieved via
<citerefentry > <refentrytitle > sd_journal_get_data</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> . If
no entry exists that matches exactly the specified
2013-09-12 23:12:49 +04:00
seek address, the next closest is sought to. If
2012-07-14 00:39:02 +04:00
<citerefentry > <refentrytitle > sd_journal_next</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
2013-09-12 23:12:49 +04:00
is used, the closest following entry will be sought to,
2012-07-14 00:39:02 +04:00
if
<citerefentry > <refentrytitle > sd_journal_previous</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
2012-07-15 12:41:40 +04:00
is used the closest preceding entry is sought
2012-07-14 00:39:02 +04:00
to.</para>
</refsect1>
<refsect1 >
<title > Return Value</title>
<para > The functions return 0 on success or a negative
errno-style error code.</para>
</refsect1>
<refsect1 >
<title > Notes</title>
<para > The <function > sd_journal_seek_head()</function> ,
<function > sd_journal_seek_tail()</function> ,
<function > sd_journal_seek_monotonic_usec()</function> ,
<function > sd_journal_seek_realtime_usec()</function> ,
and <function > sd_journal_seek_cursor()</function>
2013-12-26 05:47:43 +04:00
interfaces are available as a shared library, which can
2012-07-14 00:39:02 +04:00
be compiled and linked to with the
2014-02-19 21:30:41 +04:00
<constant > libsystemd</constant> <citerefentry > <refentrytitle > pkg-config</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry>
2012-07-14 00:39:02 +04:00
file.</para>
</refsect1>
<refsect1 >
<title > See Also</title>
<para >
<citerefentry > <refentrytitle > systemd</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > sd-journal</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > sd_journal_open</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > sd_journal_next</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > sd_journal_get_data</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > sd_journal_get_cursor</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > sd_journal_get_realtime_usec</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
</para>
</refsect1>
</refentry>
