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                 gets the realtime (wallclock) timestamps of the first
  78                 and last entries accessible in the journal.  It takes
  79                 three arguments: the journal context object and two
  80                 pointers to 64 Bit unsigned integers to store the
  81                 timestamps in. The timestamps are in microseconds
  82                 since the epoch, i.e. CLOCK_REALTIME. Either one of
  83                 the two timestamp arguments may be passed as NULL in
  84                 case the timestamp is not needed, but not both.</para>
  85
  86                 <para><function>sd_journal_get_cutoff_monotonic_usec()</function>
  87                 gets the monotonic timestamps of the first and last
  88                 entries accessible in the journal. It takes three
  89                 arguments: the journal context object, a 128 Bit
  90                 identifier for the boot, and two pointers to 64 Bit
  91                 unsigned integers to store the timestamps. The
  92                 timestamps are in microseconds since boot-up of the
  93                 specific boot, i.e. CLOCK_MONOTONIC. Since the
  94                 monotonic clock begins new with every reboot it only
  95                 defines a well-defined point in time when used
  96                 together with an identifier identifying the boot, see
  97                 <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  98                 for more information. The function will return the
  99                 timestamps for the boot identified by the passed boot
 100                 ID. Either one of the two timestamp arguments may be
 101                 passed as NULL in case the timestamp is not needed,
 102                 but not both.</para>
 103         </refsect1>
 104
 105         <refsect1>
 106                 <title>Return Value</title>
 107
 108                 <para><function>sd_journal_get_cutoff_realtime_usec()</function>
 109                 and
 110                 <function>sd_journal_get_cutoff_monotonic_usec()</function>
 111                 return 1 on success, 0 if not suitable entries are in
 112                 the journal or a negative errno-style error code.</para>
 113         </refsect1>
 114
 115         <refsect1>
 116                 <title>Notes</title>
 117
 118                 <para>The
 119                 <function>sd_journal_get_cutoff_realtime_usec()</function>
 120                 and
 121                 <function>sd_journal_get_cutoff_monotonic_usec()</function>
 122                 interfaces are available as shared library, which can
 123                 be compiled and linked to with the
 124                 <literal>libsystemd-journal</literal>
 125                 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 126                 file.</para>
 127         </refsect1>
 128
 129         <refsect1>
 130                 <title>See Also</title>
 131
 132                 <para>
 133                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 134                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 135                         <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 136                         <citerefentry><refentrytitle>sd_journal_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 137                         <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 138                         <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 139                 </para>
 140         </refsect1>
 141
 142 </refentry>