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   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="sd_journal_get_realtime_usec"
  10           xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>sd_journal_get_realtime_usec</title>
  14     <productname>systemd</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>sd_journal_get_realtime_usec</refentrytitle>
  19     <manvolnum>3</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>sd_journal_get_realtime_usec</refname>
  24     <refname>sd_journal_get_monotonic_usec</refname>
  25     <refpurpose>Read timestamps from the current journal entry</refpurpose>
  26   </refnamediv>
  27
  28   <refsynopsisdiv>
  29     <funcsynopsis>
  30       <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  31
  32       <funcprototype>
  33         <funcdef>int <function>sd_journal_get_realtime_usec</function></funcdef>
  34         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  35         <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
  36       </funcprototype>
  37
  38       <funcprototype>
  39         <funcdef>int <function>sd_journal_get_monotonic_usec</function></funcdef>
  40         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  41         <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
  42         <paramdef>sd_id128_t *<parameter>boot_id</parameter></paramdef>
  43       </funcprototype>
  44
  45     </funcsynopsis>
  46   </refsynopsisdiv>
  47
  48   <refsect1>
  49     <title>Description</title>
  50
  51     <para><function>sd_journal_get_realtime_usec()</function> gets the
  52     realtime (wallclock) timestamp of the current journal entry. It
  53     takes two arguments: the journal context object and a pointer to a
  54     64-bit unsigned integer to store the timestamp in. The timestamp
  55     is in microseconds since the epoch, i.e.
  56     <constant>CLOCK_REALTIME</constant>.</para>
  57
  58     <para><function>sd_journal_get_monotonic_usec()</function> gets
  59     the monotonic timestamp of the current journal entry. It takes
  60     three arguments: the journal context object, a pointer to a 64-bit
  61     unsigned integer to store the timestamp in, as well as a 128-bit
  62     ID buffer to store the boot ID of the monotonic timestamp. The
  63     timestamp is in microseconds since boot-up of the specific boot,
  64     i.e. <constant>CLOCK_MONOTONIC</constant>. Since the monotonic
  65     clock begins new with every reboot, it only defines a well-defined
  66     point in time when used together with an identifier identifying
  67     the boot. See
  68     <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  69     for more information. If the boot ID parameter is passed
  70     <constant>NULL</constant>, the function will fail if the monotonic
  71     timestamp of the current entry is not of the current system
  72     boot.</para>
  73
  74     <para>Note that these functions will not work before
  75     <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  76     (or related call) has been called at least
  77     once, in order to position the read pointer at a valid entry.</para>
  78   </refsect1>
  79
  80   <refsect1>
  81     <title>Return Value</title>
  82
  83     <para><function>sd_journal_get_realtime_usec()</function> and
  84     <function>sd_journal_get_monotonic_usec()</function> returns 0 on
  85     success or a negative errno-style error code. If the boot ID
  86     parameter was passed <constant>NULL</constant> and the monotonic
  87     timestamp of the current journal entry is not of the current
  88     system boot, <constant>-ESTALE</constant> is returned by
  89     <function>sd_journal_get_monotonic_usec()</function>.</para>
  90   </refsect1>
  91
  92   <xi:include href="libsystemd-pkgconfig.xml" />
  93
  94   <refsect1>
  95     <title>See Also</title>
  96
  97     <para>
  98       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  99       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 100       <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 101       <citerefentry><refentrytitle>sd_journal_next</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 102       <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 103       <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 104       <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 105       <citerefentry><refentrytitle>sd_journal_get_cutoff_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 106     </para>
 107   </refsect1>
 108
 109 </refentry>