man/sd_journal_get_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_realtime_usec">
  25
  26         <refentryinfo>
  27                 <title>sd_journal_get_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_realtime_usec</refentrytitle>
  42                 <manvolnum>3</manvolnum>
  43         </refmeta>
  44
  45         <refnamediv>
  46                 <refname>sd_journal_get_realtime_usec</refname>
  47                 <refname>sd_journal_get_monotonic_usec</refname>
  48                 <refpurpose>Read 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_realtime_usec</function></funcdef>
  57                                 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  58                                 <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
  59                         </funcprototype>
  60
  61                         <funcprototype>
  62                                 <funcdef>int <function>sd_journal_get_monotonic_usec</function></funcdef>
  63                                 <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  64                                 <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
  65                                 <paramdef>sd_id128_t *<parameter>boot_id</parameter></paramdef>
  66                         </funcprototype>
  67
  68                 </funcsynopsis>
  69         </refsynopsisdiv>
  70
  71         <refsect1>
  72                 <title>Description</title>
  73
  74                 <para><function>sd_journal_get_realtime_usec()</function>
  75                 gets the realtime (wallclock) timestamp of the
  76                 current journal entry. It takes two arguments: the
  77                 journal context object and a pointer to a 64-bit
  78                 unsigned integer to store the timestamp in. The
  79                 timestamp is in microseconds since the epoch,
  80                 i.e. <constant>CLOCK_REALTIME</constant>.</para>
  81
  82                 <para><function>sd_journal_get_monotonic_usec()</function>
  83                 gets the monotonic timestamp of the current journal
  84                 entry. It takes three arguments: the journal context
  85                 object, a pointer to a 64-bit unsigned integer to
  86                 store the timestamp in, as well as a 128-bit ID buffer
  87                 to store the boot ID of the monotonic timestamp.
  88                 The timestamp is in microseconds since boot-up of
  89                 the specific boot,
  90                 i.e. <constant>CLOCK_MONOTONIC</constant>. Since the
  91                 monotonic clock begins new with every reboot, it only
  92                 defines a well-defined point in time when used
  93                 together with an identifier identifying the boot. See
  94                 <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  95                 for more information. If the boot ID parameter is
  96                 passed <constant>NULL</constant>, the function will
  97                 fail if the monotonic timestamp of the current entry
  98                 is not of the current system boot.</para>
  99
 100                 <para>Note that these functions will not work before
 101                 <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 102                 (or related call) has been called at least
 103                 once, in order to position the read pointer at a valid entry.</para>
 104         </refsect1>
 105
 106         <refsect1>
 107                 <title>Return Value</title>
 108
 109                 <para><function>sd_journal_get_realtime_usec()</function>
 110                 and
 111                 <function>sd_journal_get_monotonic_usec()</function>
 112                 returns 0 on success or a negative errno-style error
 113                 code. If the boot ID parameter was passed <constant>NULL</constant> and the
 114                 monotonic timestamp of the current journal entry is
 115                 not of the current system boot, -ESTALE is returned by <function>sd_journal_get_monotonic_usec()</function>.</para>
 116         </refsect1>
 117
 118         <refsect1>
 119                 <title>Notes</title>
 120
 121                 <para>The
 122                 <function>sd_journal_get_realtime_usec()</function>
 123                 and
 124                 <function>sd_journal_get_monotonic_usec()</function>
 125                 interfaces are available as a shared library, which can
 126                 be compiled and linked to with the
 127                 <constant>libsystemd</constant> <citerefentry project='die-net'><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_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 139                         <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 140                         <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 141                         <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 142                         <citerefentry><refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 143                 </para>
 144         </refsect1>
 145
 146 </refentry>