man/sd_journal_get_cutoff_realtime_usec.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   This file is part of systemd.
   7
   8   Copyright 2012 Lennart Poettering
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="sd_journal_get_cutoff_realtime_usec">
  25
  26         <refentryinfo>
  27                 <title>sd_journal_get_cutoff_realtime_usec</title>
  28                 <productname>systemd</productname>
  29
  30                 <authorgroup>
  31                         <author>
  32                                 <contrib>Developer</contrib>
  33                                 <firstname>Lennart</firstname>
  34                                 <surname>Poettering</surname>
  35                                 <email>lennart@poettering.net</email>
  36                         </author>
  37                 </authorgroup>
  38         </refentryinfo>
  39
  40         <refmeta>
  41                 <refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle>
  42                 <manvolnum>3</manvolnum>
  43         </refmeta>
  44
  45         <refnamediv>
  46                 <refname>sd_journal_get_cutoff_realtime_usec</refname>
  47                 <refname>sd_journal_get_cutoff_monotonic_usec</refname>
  48                 <refpurpose>Read cut-off timestamps from the current journal entry</refpurpose>
  49         </refnamediv>
  50
  51         <refsynopsisdiv>
  52                 <funcsynopsis>
  53                         <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  54
  55                         <funcprototype>
  56                                 <funcdef>int <function>sd_journal_get_cutoff_realtime_usec</function></funcdef>
  57                                 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  58                                 <paramdef>uint64_t *<parameter>from</parameter></paramdef>
  59                                 <paramdef>uint64_t *<parameter>to</parameter></paramdef>
  60                         </funcprototype>
  61
  62                         <funcprototype>
  63                                 <funcdef>int <function>sd_journal_get_cutoff_monotonic_usec</function></funcdef>
  64                                 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  65                                 <paramdef>sd_id128_t <parameter>boot_id</parameter></paramdef>
  66                                 <paramdef>uint64_t *<parameter>from</parameter></paramdef>
  67                                 <paramdef>uint64_t *<parameter>to</parameter></paramdef>
  68                         </funcprototype>
  69
  70                 </funcsynopsis>
  71         </refsynopsisdiv>
  72
  73         <refsect1>
  74                 <title>Description</title>
  75
  76                 <para><function>sd_journal_get_cutoff_realtime_usec()</function>
  77                 retrieves the realtime (wallclock) timestamps of the
  78                 first and last entries accessible in the journal.  It
  79                 takes three arguments: the journal context object
  80                 <parameter>j</parameter> and two pointers
  81                 <parameter>from</parameter> and
  82                 <parameter>to</parameter> pointing at 64-bit unsigned
  83                 integers to store the timestamps in. The timestamps
  84                 are in microseconds since the epoch,
  85                 i.e. <constant>CLOCK_REALTIME</constant>. Either one
  86                 of the two timestamp arguments may be passed as
  87                 <constant>NULL</constant> in case the timestamp is not
  88                 needed, but not both.</para>
  89
  90                 <para><function>sd_journal_get_cutoff_monotonic_usec()</function>
  91                 retrieves the monotonic timestamps of the first and
  92                 last entries accessible in the journal. It takes three
  93                 arguments: the journal context object
  94                 <parameter>j</parameter>, a 128-bit identifier for the
  95                 boot <parameter>boot_id</parameter>, and two pointers
  96                 to 64-bit unsigned integers to store the timestamps,
  97                 <parameter>from</parameter> and
  98                 <parameter>to</parameter>. The timestamps are in
  99                 microseconds since boot-up of the specific boot,
 100                 i.e. <constant>CLOCK_MONOTONIC</constant>. Since the
 101                 monotonic clock begins new with every reboot it only
 102                 defines a well-defined point in time when used
 103                 together with an identifier identifying the boot, see
 104                 <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 105                 for more information. The function will return the
 106                 timestamps for the boot identified by the passed boot
 107                 ID. Either one of the two timestamp arguments may be
 108                 passed as <constant>NULL</constant> in case the
 109                 timestamp is not needed, but not both.</para>
 110         </refsect1>
 111
 112         <refsect1>
 113                 <title>Return Value</title>
 114
 115                 <para><function>sd_journal_get_cutoff_realtime_usec()</function>
 116                 and
 117                 <function>sd_journal_get_cutoff_monotonic_usec()</function>
 118                 return 1 on success, 0 if not suitable entries are in
 119                 the journal or a negative errno-style error code.</para>
 120
 121                 <para>Locations pointed to by parameters
 122                 <parameter>from</parameter> and
 123                 <parameter>to</parameter> will be set only if the
 124                 return value is positive, and obviously, the
 125                 parameters are non-null.</para>
 126         </refsect1>
 127
 128         <refsect1>
 129                 <title>Notes</title>
 130
 131                 <para>The
 132                 <function>sd_journal_get_cutoff_realtime_usec()</function>
 133                 and
 134                 <function>sd_journal_get_cutoff_monotonic_usec()</function>
 135                 interfaces are available as a shared library, which can
 136                 be compiled and linked to with the
 137                 <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 138                 file.</para>
 139         </refsect1>
 140
 141         <refsect1>
 142                 <title>See Also</title>
 143
 144                 <para>
 145                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 146                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 147                         <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 148                         <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 149                         <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 150                         <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 151                 </para>
 152         </refsect1>
 153
 154 </refentry>