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