447be1550523114f96c7f9eacb9d6a1ff6ca4197Lennart Poettering<?xml version='1.0'?> <!--*-nxml-*-->

447be1550523114f96c7f9eacb9d6a1ff6ca4197Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

447be1550523114f96c7f9eacb9d6a1ff6ca4197Lennart Poettering "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering

<refentry id="sd_bus_message_get_monotonic_usec">

<refentryinfo>

<title>sd_bus_message_get_monotonic_usec</title>

<productname>systemd</productname>

<authorgroup>

<author>

<contrib>Developer</contrib>

<firstname>Lennart</firstname>

<surname>Poettering</surname>

<email>lennart@poettering.net</email>

</author>

</authorgroup>

</refentryinfo>

<refmeta>

<refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle>

<manvolnum>3</manvolnum>

</refmeta>

<refnamediv>

<refname>sd_bus_message_get_monotonic_usec</refname>

<refname>sd_bus_message_get_realtime_usec</refname>

<refname>sd_bus_message_get_seqnum</refname>

<refpurpose>Retrieve the sender timestamps and sequence number of a message</refpurpose>

</refnamediv>

<refsynopsisdiv>

<funcsynopsis>

<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>

<funcprototype>

<funcdef>int <function>sd_bus_message_get_monotonic_usec</function></funcdef>

<paramdef>sd_bus_message *<parameter>message</parameter></paramdef>

<paramdef>uint64_t *<parameter>usec</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_bus_message_get_realtime_usec</function></funcdef>

<paramdef>sd_bus_message *<parameter>message</parameter></paramdef>

<paramdef>uint64_t *<parameter>usec</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_bus_message_get_seqnum</function></funcdef>

<paramdef>sd_bus_message *<parameter>message</parameter></paramdef>

<paramdef>uint64_t *<parameter>seqnum</parameter></paramdef>

</funcprototype>

</funcsynopsis>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para><function>sd_bus_message_get_monotonic_usec()</function>

returns the monotonic timestamp of the time the message was sent.

This value is in microseconds since the

<constant>CLOCK_MONOTONIC</constant> epoch, see

<citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>

for details.</para>

<para>Similarly,

<function>sd_bus_message_get_realtime_usec()</function> returns

the realtime (wallclock) timestamp of the time the message was

sent. This value is in microseconds since Jan 1st, 1970, i.e. in

the <constant>CLOCK_REALTIME</constant> clock.</para>

<para><function>sd_bus_message_get_seqnum()</function> returns the

kernel-assigned sequence number of the message. The kernel assigns

a global, monotonically increasing sequence number to all messages

transmitted on the local system, at the time the message was sent.

This sequence number is useful for determining message send order,

even across different buses of the local system. The sequence

number combined with the boot ID of the system (as returned by

<citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>)

is a suitable globally unique identifier for bus messages.</para>

<para>Note that the sending order and receiving order of messages

might differ, in particular for broadcast messages. This means

that the sequence number and the timestamps of messages a client

reads are not necessarily monotonically increasing.</para>

<para>These timestamps and the sequence number are attached to

each message by the kernel and cannot be manipulated by the

sender.</para>

<para>Note that these timestamps are only available on some bus

transports, and only after support for them has been negotiated

with the

<citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>

call.</para>

</refsect1>

<refsect1>

<title>Return Value</title>

<para>On success, these calls return 0 or a positive integer. On

failure, these calls return a negative errno-style error

code.</para>

<para>On success, the timestamp or sequence number is returned in

the specified 64-bit unsigned integer variable.</para>

</refsect1>

<refsect1>

<title>Errors</title>

<para>Returned errors may indicate the following problems:</para>

<variablelist>

<varlistentry>

<term><constant>-EINVAL</constant></term>

<listitem><para>A specified parameter is

invalid.</para></listitem>

</varlistentry>

<varlistentry>

<term><constant>-ENODATA</constant></term>

<listitem><para>No timestamp or sequence number information is

attached to the passed message. This error is returned if the

underlying transport does not support timestamping or

assigning of sequence numbers, or if this feature has not been

negotiated with

<citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1>

<title>Notes</title>

<para>The

<function>sd_bus_message_get_monotonic_usec()</function>,

<function>sd_bus_message_get_realtime_usec()</function>, and

<function>sd_bus_message_get_seqnum()</function> interfaces are

available as a shared library, which can be compiled and linked to

with the

<constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>

file.</para>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>