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