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