diff --git a/man/rules/meson.build b/man/rules/meson.build
index 9458a4012d..7457669fa0 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_error.xml b/man/sd_bus_error.xml
index 88c5f235e9..807ca86302 100644
--- a/man/sd_bus_error.xml
+++ b/man/sd_bus_error.xml
@@ -100,7 +100,7 @@
sd_bus_error *e
int error
const char *format
- va_list ap
+ va_list ap
diff --git a/man/sd_bus_message_append.xml b/man/sd_bus_message_append.xml
index 9a1c4bc53f..1fdda51dcc 100644
--- a/man/sd_bus_message_append.xml
+++ b/man/sd_bus_message_append.xml
@@ -94,13 +94,12 @@
values for each entry matching the element type of
the dictionary entries.
- The sd_bus_message_appendv() is equivalent to
- the function sd_bus_message_append(),
- 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.
+ The sd_bus_message_appendv() is equivalent to the
+ sd_bus_message_append(), 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.
For further details on the D-Bus type system, please consult
the
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 0000000000..c86f55fb54
--- /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 bc4220910e..e39cfd5bd6 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.
+
+
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