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