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