From 50972aac44aaa21934d0b1f8985a9b3182f9a067 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Tue, 3 Jul 2018 01:11:11 +0200 Subject: [PATCH] man: document sd_bus_read(), add more about sd_bus_read_basic() --- man/rules/meson.build | 1 + man/sd_bus_message_append_basic.xml | 1 + man/sd_bus_message_read.xml | 231 ++++++++++++++++++++++++++++++++++++ man/sd_bus_message_read_basic.xml | 162 +++++++++++++++++++++++-- 4 files changed, 385 insertions(+), 10 deletions(-) create mode 100644 man/sd_bus_message_read.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index 9458a40..7457669 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -209,6 +209,7 @@ manpages = [ '3', ['sd_bus_message_get_realtime_usec', 'sd_bus_message_get_seqnum'], ''], + ['sd_bus_message_read', '3', ['sd_bus_message_readv'], ''], ['sd_bus_message_read_basic', '3', [], ''], ['sd_bus_message_set_destination', '3', ['sd_bus_message_set_sender'], ''], ['sd_bus_negotiate_fds', diff --git a/man/sd_bus_message_append_basic.xml b/man/sd_bus_message_append_basic.xml index 6c76569..f41c538 100644 --- a/man/sd_bus_message_append_basic.xml +++ b/man/sd_bus_message_append_basic.xml @@ -255,6 +255,7 @@ systemd1, sd-bus3, + sd_bus_message_read_basic3, sd_bus_message_append3, The D-Bus specification diff --git a/man/sd_bus_message_read.xml b/man/sd_bus_message_read.xml new file mode 100644 index 0000000..c86f55f --- /dev/null +++ b/man/sd_bus_message_read.xml @@ -0,0 +1,231 @@ + + + + + + + + + sd_bus_message_read + systemd + + + + sd_bus_message_read + 3 + + + + sd_bus_message_read + sd_bus_message_readv + + Read a sequence of values from a message + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_read + sd_bus_message *m + char char *types + ... + + + + int sd_bus_message_readv + sd_bus_message *m + char char *types + va_list ap + + + + + + Description + + sd_bus_message_read() reads a sequence of fields from + the D-Bus message object m and advances the read position + in the message. The type string types describes the types + of items expected in the message and the field arguments that follow. The type + string may be NULL or empty, in which case nothing is + read. + + The type string is composed of the elements described in + sd_bus_message_append3, + i.e. basic and container types. It must contain zero or more single "complete + types". The type string is NUL-terminated. + + For each type specified in the type string, one or more arguments need to be specified + after the types parameter, in the same order. The arguments must be + pointers to appropriate types (a pointer to int8_t for a y in + the type string, a pointer to int32_t for an i, a pointer to + const char* for an s, ...) which are set based on the values in + the message. As an exception, in case or array and variant types, the first argument is an + "input" argument that further specifies how the message should be read. See the table below for + a complete list of allowed arguments and their types. Note that, if the basic type is a pointer + (e.g., const char * in the case of a string), the argument is a pointer to a + pointer, and also the pointer value that is written is only borrowed and the contents must be + copied if they are to be used after the end of the messages lifetime. + + Each argument may also be NULL, in which case the value is read and + ignored. + + + Item type specifiers + + + + + + + + + + Specifier + Constant + Description + Type of the first argument + Types of the subsequent arguments, if any + + + + + + + + a + SD_BUS_TYPE_ARRAY + array + int, which specifies the expected length n of the array + n sets of arguments appropriate for the array element type + + + + v + SD_BUS_TYPE_VARIANT + variant + signature string + arguments appropriate for the types specified by the signature + + + + ( + SD_BUS_TYPE_STRUCT_BEGIN + array start + arguments appropriate for the structure elements + + + ) + SD_BUS_TYPE_STRUCT_END + array end + + + + { + SD_BUS_TYPE_DICT_ENTRY_BEGIN + dictionary entry start + arguments appropriate for the first type in the pair + arguments appropriate for the second type in the pair + + + } + SD_BUS_TYPE_DICT_ENTRY_END + dictionary entry end + + + +
+ + If objects of the specified types are not present at the current position + in the message, an error is returned. + + + The sd_bus_message_readv() is equivalent to the + sd_bus_message_read(), except that it is called with a + va_list instead of a variable number of arguments. This + function does not call the va_end() macro. Because it + invokes the va_arg() macro, the value of + ap is undefined after the call. + + + + Return Value + + + On success, sd_bus_message_read() and + sd_bus_message_readv() return 0 or a positive integer. On + failure, they return a negative errno-style error code. + + + + + + + + + Examples + + Read a single basic type (a 64-bit integer): + + + sd_bus_message *m; +int64_t x; + +sd_bus_message_read(m, "x", &x); + + Read all types of integers: + + uint8_t y; +int16_t n; +uint16_t q; +int32_t i; +uint32_t u; +int32_t x; +uint32_t t; +double d; + +sd_bus_message_read(m, "ynqiuxtd", &y, &n, &q, &i, &u, &x, &t, &d); + + Read a structure composed of a string and a D-Bus path: + + const char *s, *p; + +sd_bus_message_read(m, "(so)", &s, &p); + + + Read a variant, with the real type "gt" (signature, unsigned integer): + + + const char *s; +uint64_t *v; + +sd_bus_message_read(m, "v", "gt", &s, &v); + + Read a dictionary containing three pairs of type {integer=>string}: + + + int i, j, k; +const char *s, *t, *u; + +sd_bus_message_read(m, "a{is}", 3, &i, &s, &j, &t, &k, &u); + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_read_basic3, + sd_bus_message_append3 + + + + diff --git a/man/sd_bus_message_read_basic.xml b/man/sd_bus_message_read_basic.xml index c0e0466..fb687b5 100644 --- a/man/sd_bus_message_read_basic.xml +++ b/man/sd_bus_message_read_basic.xml @@ -52,18 +52,130 @@ - If p is not NULL, it should contain a pointer to an - appropriate object. For example, if type is - 'y', the object passed in p - should have type uint8_t *. If type - is 's', the object passed in p - should have type const char **. Note that, if the basic type - is a pointer (e.g., const char * in the case of a string), - the pointer is only borrowed and the contents must be copied if they are - to be used after the end of the messages lifetime. Similarly, during the - lifetime of such a pointer, the message must not be modified. + If p is not NULL, it should contain + a pointer to an appropriate object. For example, if type + is 'y', the object passed in p + should have type uint8_t *. If type is + 's', the object passed in p should + have type const char **. Note that, if the basic type is a pointer + (e.g., const char * in the case of a string), the pointer is only + borrowed and the contents must be copied if they are to be used after the end + of the messages lifetime. Similarly, during the lifetime of such a pointer, the + message must not be modified. See the table below for a complete list of allowed + types. + + Item type specifiers + + + + + + + + + Specifier + Constant + Description + Expected C Type + + + + + y + SD_BUS_TYPE_BYTE + unsigned integer + uint8_t * + + + + b + SD_BUS_TYPE_BOOLEAN + boolean + int * + + + + n + SD_BUS_TYPE_INT16 + signed integer + int16_t * + + + + q + SD_BUS_TYPE_UINT16 + unsigned integer + uint16_t * + + + + i + SD_BUS_TYPE_INT32 + signed integer + int32_t * + + + + u + SD_BUS_TYPE_UINT32 + unsigned integer + uint32_t * + + + + x + SD_BUS_TYPE_INT64 + signed integer + int64_t * + + + + t + SD_BUS_TYPE_UINT64 + unsigned integer + uint64_t * + + + + d + SD_BUS_TYPE_DOUBLE + floating-point + double * + + + + s + SD_BUS_TYPE_STRING + Unicode string + const char ** + + + + o + SD_BUS_TYPE_OBJECT_PATH + object path + const char ** + + + + g + SD_BUS_TYPE_SIGNATURE + signature + const char ** + + + + h + SD_BUS_TYPE_UNIX_FD + UNIX file descriptor + int * + + + +
+ If there is no object of the specified type at the current position in the message, an error is returned. @@ -80,12 +192,42 @@ + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + Specified type string is invalid or the message parameter is + NULL. + + + + -ENXIO + + The message does not contain the specified type at current + position. + + + + -EBADMSG + + The message cannot be parsed. + + + + See Also systemd1, sd-bus3, + sd_bus_message_append_basic3, + sd_bus_message_read3 -- 2.7.4