man/sd_bus_message_get_monotonic_usec.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sd_bus_message_get_monotonic_usec"
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>sd_bus_message_get_monotonic_usec</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle>
  16     <manvolnum>3</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>sd_bus_message_get_monotonic_usec</refname>
  21     <refname>sd_bus_message_get_realtime_usec</refname>
  22     <refname>sd_bus_message_get_seqnum</refname>
  23     <refpurpose>Retrieve the sender timestamps and sequence number of a message</refpurpose>
  24   </refnamediv>
  25
  26   <refsynopsisdiv>
  27     <funcsynopsis>
  28       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  29
  30       <funcprototype>
  31         <funcdef>int <function>sd_bus_message_get_monotonic_usec</function></funcdef>
  32         <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
  33         <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
  34       </funcprototype>
  35
  36       <funcprototype>
  37         <funcdef>int <function>sd_bus_message_get_realtime_usec</function></funcdef>
  38         <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
  39         <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
  40       </funcprototype>
  41
  42       <funcprototype>
  43         <funcdef>int <function>sd_bus_message_get_seqnum</function></funcdef>
  44         <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
  45         <paramdef>uint64_t *<parameter>seqnum</parameter></paramdef>
  46       </funcprototype>
  47     </funcsynopsis>
  48   </refsynopsisdiv>
  49
  50   <refsect1>
  51     <title>Description</title>
  52
  53     <para><function>sd_bus_message_get_monotonic_usec()</function>
  54     returns the monotonic timestamp of the time the message was sent.
  55     This value is in microseconds since the
  56     <constant>CLOCK_MONOTONIC</constant> epoch, see
  57     <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
  58     for details.</para>
  59
  60     <para>Similarly,
  61     <function>sd_bus_message_get_realtime_usec()</function> returns
  62     the realtime (wallclock) timestamp of the time the message was
  63     sent. This value is in microseconds since Jan 1st, 1970, i.e. in
  64     the <constant>CLOCK_REALTIME</constant> clock.</para>
  65
  66     <para><function>sd_bus_message_get_seqnum()</function> returns the
  67     kernel-assigned sequence number of the message. The kernel assigns
  68     a global, monotonically increasing sequence number to all messages
  69     transmitted on the local system, at the time the message was sent.
  70     This sequence number is useful for determining message send order,
  71     even across different buses of the local system. The sequence
  72     number combined with the boot ID of the system (as returned by
  73     <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
  74     is a suitable globally unique identifier for bus messages.</para>
  75
  76     <para>Note that the sending order and receiving order of messages
  77     might differ, in particular for broadcast messages. This means
  78     that the sequence number and the timestamps of messages a client
  79     reads are not necessarily monotonically increasing.</para>
  80
  81     <para>These timestamps and the sequence number are attached to
  82     each message by the kernel and cannot be manipulated by the
  83     sender.</para>
  84
  85     <para>Note that these timestamps are only available on some bus
  86     transports, and only after support for them has been negotiated
  87     with the
  88     <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  89     call.</para>
  90   </refsect1>
  91
  92   <refsect1>
  93     <title>Return Value</title>
  94
  95     <para>On success, these calls return 0 or a positive integer. On
  96     failure, these calls return a negative errno-style error
  97     code.</para>
  98
  99     <para>On success, the timestamp or sequence number is returned in
 100     the specified 64-bit unsigned integer variable.</para>
 101
 102     <refsect2>
 103       <title>Errors</title>
 104
 105       <para>Returned errors may indicate the following problems:</para>
 106
 107       <variablelist>
 108         <varlistentry>
 109           <term><constant>-EINVAL</constant></term>
 110
 111           <listitem><para>A specified parameter is invalid.</para></listitem>
 112         </varlistentry>
 113
 114         <varlistentry>
 115           <term><constant>-ENODATA</constant></term>
 116
 117           <listitem><para>No timestamp or sequence number information is attached to the passed message. This
 118           error is returned if the underlying transport does not support timestamping or assigning of
 119           sequence numbers, or if this feature has not been negotiated with
 120           <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 121         </varlistentry>
 122       </variablelist>
 123     </refsect2>
 124   </refsect1>
 125
 126   <xi:include href="libsystemd-pkgconfig.xml" />
 127
 128   <refsect1>
 129     <title>History</title>
 130     <para><function>sd_bus_message_get_monotonic_usec()</function>,
 131     <function>sd_bus_message_get_realtime_usec()</function>, and
 132     <function>sd_bus_message_get_seqnum()</function> were added in version 209.</para>
 133   </refsect1>
 134
 135   <refsect1>
 136     <title>See Also</title>
 137
 138     <para>
 139       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 140       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 141       <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 142       <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 143       <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 144       <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 145     </para>
 146   </refsect1>
 147
 148 </refentry>