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+ -->
   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   </refsect1>
 102
 103   <refsect1>
 104     <title>Errors</title>
 105
 106     <para>Returned errors may indicate the following problems:</para>
 107
 108     <variablelist>
 109       <varlistentry>
 110         <term><constant>-EINVAL</constant></term>
 111
 112         <listitem><para>A specified parameter is
 113         invalid.</para></listitem>
 114       </varlistentry>
 115
 116       <varlistentry>
 117         <term><constant>-ENODATA</constant></term>
 118
 119         <listitem><para>No timestamp or sequence number information is
 120         attached to the passed message. This error is returned if the
 121         underlying transport does not support timestamping or
 122         assigning of sequence numbers, or if this feature has not been
 123         negotiated with
 124         <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 125       </varlistentry>
 126     </variablelist>
 127   </refsect1>
 128
 129   <xi:include href="libsystemd-pkgconfig.xml" />
 130
 131   <refsect1>
 132     <title>See Also</title>
 133
 134     <para>
 135       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 136       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 137       <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 138       <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 139       <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 140       <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 141     </para>
 142   </refsect1>
 143
 144 </refentry>