3736955368e8a3a24962f5fdd25cce3281885c30Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3736955368e8a3a24962f5fdd25cce3281885c30Lennart Poettering This file is part of systemd.
3736955368e8a3a24962f5fdd25cce3281885c30Lennart Poettering Copyright 2013 Lennart Poettering
3736955368e8a3a24962f5fdd25cce3281885c30Lennart Poettering systemd is free software; you can redistribute it and/or modify it
3736955368e8a3a24962f5fdd25cce3281885c30Lennart Poettering under the terms of the GNU Lesser General Public License as published by
3736955368e8a3a24962f5fdd25cce3281885c30Lennart Poettering the Free Software Foundation; either version 2.1 of the License, or
3736955368e8a3a24962f5fdd25cce3281885c30Lennart Poettering (at your option) any later version.
3736955368e8a3a24962f5fdd25cce3281885c30Lennart Poettering systemd is distributed in the hope that it will be useful, but
3736955368e8a3a24962f5fdd25cce3281885c30Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
3736955368e8a3a24962f5fdd25cce3281885c30Lennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
3736955368e8a3a24962f5fdd25cce3281885c30Lennart Poettering Lesser General Public License for more details.
3736955368e8a3a24962f5fdd25cce3281885c30Lennart Poettering You should have received a copy of the GNU Lesser General Public License
3736955368e8a3a24962f5fdd25cce3281885c30Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
48f69d8fb4d0cf34d578352572c96d86e13caa79Lennart Poettering<refentry id="sd_bus_message_get_monotonic_usec">
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>sd_bus_message_get_monotonic_usec</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <productname>systemd</productname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <email>lennart@poettering.net</email>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>sd_bus_message_get_monotonic_usec</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>sd_bus_message_get_realtime_usec</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>sd_bus_message_get_seqnum</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refpurpose>Retrieve the sender timestamps and sequence number of a message</refpurpose>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_bus_message_get_monotonic_usec</function></funcdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </funcprototype>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_bus_message_get_realtime_usec</function></funcdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </funcprototype>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_bus_message_get_seqnum</function></funcdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>uint64_t *<parameter>seqnum</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </funcprototype>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><function>sd_bus_message_get_monotonic_usec()</function>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek returns the monotonic timestamp of the time the message was sent.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek This value is in microseconds since the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <constant>CLOCK_MONOTONIC</constant> epoch, see
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek for details.</para>
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt <para>Similarly,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_bus_message_get_realtime_usec()</function> returns
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the realtime (wallclock) timestamp of the time the message was
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek sent. This value is in microseconds since Jan 1st, 1970, i.e. in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the <constant>CLOCK_REALTIME</constant> clock.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><function>sd_bus_message_get_seqnum()</function> returns the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek kernel-assigned sequence number of the message. The kernel assigns
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek a global, monotonically increasing sequence number to all messages
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek transmitted on the local system, at the time the message was sent.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek This sequence number is useful for determining message send order,
ff9b60f38bf68eba4a47cabff14547d92e083214Torstein Husebø even across different buses of the local system. The sequence
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek number combined with the boot ID of the system (as returned by
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek is a suitable globally unique identifier for bus messages.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Note that the sending order and receiving order of messages
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek might differ, in particular for broadcast messages. This means
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek that the sequence number and the timestamps of messages a client
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek reads are not necessarily monotonically increasing.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>These timestamps and the sequence number are attached to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek each message by the kernel and cannot be manipulated by the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Note that these timestamps are only available on some bus
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek transports, and only after support for them has been negotiated
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>On success, these calls return 0 or a positive integer. On
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek failure, these calls return a negative errno-style error
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>On success, the timestamp or sequence number is returned in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the specified 64-bit unsigned integer variable.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Returned errors may indicate the following problems:</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><constant>-EINVAL</constant></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>A specified parameter is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><constant>-ENODATA</constant></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>No timestamp or sequence number information is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek attached to the passed message. This error is returned if the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek underlying transport does not support timestamping or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek assigning of sequence numbers, or if this feature has not been
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_bus_message_get_monotonic_usec()</function>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_bus_message_get_realtime_usec()</function>, and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_bus_message_get_seqnum()</function> interfaces are
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek available as a shared library, which can be compiled and linked to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_id128_get_boot</refentrytitle><manvolnum>3</manvolnum></citerefentry>