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