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 message was sent.
  81     This value is in microseconds since the
  82     <constant>CLOCK_MONOTONIC</constant> 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> returns
  88     the realtime (wallclock) timestamp of the time the message was
  89     sent. This value is in microseconds since Jan 1st, 1970, i.e. in
  90     the <constant>CLOCK_REALTIME</constant> clock.</para>
  91
  92     <para><function>sd_bus_message_get_seqnum()</function> returns the
  93     kernel-assigned sequence number of the message. The kernel assigns
  94     a global, monotonically increasing sequence number to all messages
  95     transmitted on the local system, at the time the message was sent.
  96     This sequence number is useful for determining message send order,
  97     even across different busses of the local system. The sequence
  98     number combined with the boot ID of the system (as returned by
  99     <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
 100     is a suitable globally unique identifier for bus messages.</para>
 101
 102     <para>Note that the sending order and receiving order of messages
 103     might differ, in particular for broadcast messages. This means
 104     that the sequence number and the timestamps of messages a client
 105     reads are not necessarily monotonically increasing.</para>
 106
 107     <para>These timestamps and the sequence number are attached to
 108     each message by the kernel and cannot be manipulated by the
 109     sender.</para>
 110
 111     <para>Note that these timestamps are only available on some bus
 112     transports, and only after support for them has been negotiated
 113     with the
 114     <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 115     call.</para>
 116   </refsect1>
 117
 118   <refsect1>
 119     <title>Return Value</title>
 120
 121     <para>On success, these calls return 0 or a positive integer. On
 122     failure, these calls return a negative errno-style error
 123     code.</para>
 124
 125     <para>On success, the timestamp or sequence number is returned in
 126     the specified 64-bit unsigned integer variable.</para>
 127   </refsect1>
 128
 129   <refsect1>
 130     <title>Errors</title>
 131
 132     <para>Returned errors may indicate the following problems:</para>
 133
 134     <variablelist>
 135       <varlistentry>
 136         <term><constant>-EINVAL</constant></term>
 137
 138         <listitem><para>A specified parameter is
 139         invalid.</para></listitem>
 140       </varlistentry>
 141
 142       <varlistentry>
 143         <term><constant>-ENODATA</constant></term>
 144
 145         <listitem><para>No timestamp or sequence number information is
 146         attached to the passed message. This error is returned if the
 147         underlying transport does not support timestamping or
 148         assigning of sequence numbers, or if this feature has not been
 149         negotiated with
 150         <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 151       </varlistentry>
 152     </variablelist>
 153   </refsect1>
 154
 155   <refsect1>
 156     <title>Notes</title>
 157
 158     <para>The
 159     <function>sd_bus_message_get_monotonic_usec()</function>,
 160     <function>sd_bus_message_get_realtime_usec()</function>, and
 161     <function>sd_bus_message_get_seqnum()</function> interfaces are
 162     available as a shared library, which can be compiled and linked to
 163     with the
 164     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 165     file.</para>
 166   </refsect1>
 167
 168   <refsect1>
 169     <title>See Also</title>
 170
 171     <para>
 172       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 173       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 174       <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 175       <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 176       <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 177       <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 178     </para>
 179   </refsect1>
 180
 181 </refentry>