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