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