From 3736955368e8a3a24962f5fdd25cce3281885c30 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 22 Jan 2014 11:44:54 +0100 Subject: man: document message timestamping/sequence number API --- Makefile-man.am | 12 ++ man/sd_bus_message_get_monotonic_usec.xml | 183 ++++++++++++++++++++++++++++++ 2 files changed, 195 insertions(+) create mode 100644 man/sd_bus_message_get_monotonic_usec.xml diff --git a/Makefile-man.am b/Makefile-man.am index 288d3da53..fca842daa 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -26,6 +26,7 @@ MANPAGES += \ man/sd_bus_error.3 \ man/sd_bus_label_escape.3 \ man/sd_bus_message_get_cookie.3 \ + man/sd_bus_message_get_monotonic_usec.3 \ man/sd_bus_new.3 \ man/sd_bus_open_user.3 \ man/sd_bus_request_name.3 \ @@ -180,7 +181,9 @@ MANPAGES_ALIAS += \ man/sd_bus_error_set_errno.3 \ man/sd_bus_error_set_errnof.3 \ man/sd_bus_label_unescape.3 \ + man/sd_bus_message_get_realtime_usec.3 \ man/sd_bus_message_get_reply_cookie.3 \ + man/sd_bus_message_get_seqnum.3 \ man/sd_bus_open_system.3 \ man/sd_bus_open_system_container.3 \ man/sd_bus_open_system_remote.3 \ @@ -327,7 +330,9 @@ man/sd_bus_error_set_const.3: man/sd_bus_error.3 man/sd_bus_error_set_errno.3: man/sd_bus_error.3 man/sd_bus_error_set_errnof.3: man/sd_bus_error.3 man/sd_bus_label_unescape.3: man/sd_bus_label_escape.3 +man/sd_bus_message_get_realtime_usec.3: man/sd_bus_message_get_monotonic_usec.3 man/sd_bus_message_get_reply_cookie.3: man/sd_bus_message_get_cookie.3 +man/sd_bus_message_get_seqnum.3: man/sd_bus_message_get_monotonic_usec.3 man/sd_bus_open_system.3: man/sd_bus_open_user.3 man/sd_bus_open_system_container.3: man/sd_bus_open_user.3 man/sd_bus_open_system_remote.3: man/sd_bus_open_user.3 @@ -606,9 +611,15 @@ man/sd_bus_error_set_errnof.html: man/sd_bus_error.html man/sd_bus_label_unescape.html: man/sd_bus_label_escape.html $(html-alias) +man/sd_bus_message_get_realtime_usec.html: man/sd_bus_message_get_monotonic_usec.html + $(html-alias) + man/sd_bus_message_get_reply_cookie.html: man/sd_bus_message_get_cookie.html $(html-alias) +man/sd_bus_message_get_seqnum.html: man/sd_bus_message_get_monotonic_usec.html + $(html-alias) + man/sd_bus_open_system.html: man/sd_bus_open_user.html $(html-alias) @@ -1340,6 +1351,7 @@ EXTRA_DIST += \ man/sd_bus_error.xml \ man/sd_bus_label_escape.xml \ man/sd_bus_message_get_cookie.xml \ + man/sd_bus_message_get_monotonic_usec.xml \ man/sd_bus_new.xml \ man/sd_bus_open_user.xml \ man/sd_bus_request_name.xml \ diff --git a/man/sd_bus_message_get_monotonic_usec.xml b/man/sd_bus_message_get_monotonic_usec.xml new file mode 100644 index 000000000..57b115c63 --- /dev/null +++ b/man/sd_bus_message_get_monotonic_usec.xml @@ -0,0 +1,183 @@ + + + + + + + + + sd_bus_message_get_monotonic_usec + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_bus_message_get_monotonic_usec + 3 + + + + sd_bus_message_get_monotonic_usec + sd_bus_message_get_realtime_usec + sd_bus_message_get_seqnum + Retrieve the sender timestamps and sequence number of a message + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_get_monotonic_usec + sd_bus_message* message + uint64_t* usec + + + + int sd_bus_message_get_realtime_usec + sd_bus_message* message + uint64_t* usec + + + + int sd_bus_message_get_seqnum + sd_bus_message* message + uint64_t* seqnum + + + + + + Description + + sd_bus_message_get_monotonic_usec() + returns the monotonic timestamp of the time the + message was sent. This value is in microseconds since + the CLOCK_MONOTONIC epoch, see + clock_gettime2 + for details. + + Similar, + sd_bus_message_get_realtime_usec() + 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 + CLOCK_REALTIME clock. + + sd_bus_message_get_seqnum() + returns the kernel-assigned sequence number of the + message. The kernel assigns a global monotonically increasing + sequence number to all messages sent on the local + system. This sequence number is useful for determining + message send order, even across different busses of + the local system. The sequence number combined with + the boot ID of the system (as returned by + sd_id128_get_boot3) + is a suitable globally unique identifier for bus + messages. + + These timestamps and the sequence number are + attached to each message by the kernel and cannot be + manipulated by the sending userspace. + + Note that these timestamps are only available on + some bus transports, and only after support for them + has been negotiated with the + sd_bus_negotiate_timestamp3 + call. + + + + Return Value + + On success, these calls return 0 or a positive + integer. On failure, these calls return a negative + errno-style error code. + + On success, the timestamp or sequence number is + returned in the specified 64-bit unsigned integer + variable. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + A specified parameter + is invalid. + + + + -ENODATA + + 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 + sd_bus_negotiate_timestamp3. + + + + + + Notes + + The + sd_bus_message_get_monotonic_usec(), + sd_bus_message_get_realtime_usec(), + and sd_bus_message_get_seqnum() + interfaces are available as a shared library, which + can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_new3, + sd_bus_negotiate_timestamp3, + clock_gettime2, + sd_id128_get_boot3 + + + + -- cgit v1.2.3