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