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