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