diff --git a/man/rules/meson.build b/man/rules/meson.build
index e59ad3769db..9b2e102dd15 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -325,7 +325,10 @@ manpages = [
'sd_bus_message_enter_container',
'sd_bus_message_exit_container'],
''],
- ['sd_bus_message_read', '3', ['sd_bus_message_readv'], ''],
+ ['sd_bus_message_read',
+ '3',
+ ['sd_bus_message_peek_type', 'sd_bus_message_readv'],
+ ''],
['sd_bus_message_read_array', '3', [], ''],
['sd_bus_message_read_basic', '3', [], ''],
['sd_bus_message_read_strv', '3', [], ''],
diff --git a/man/sd-bus.xml b/man/sd-bus.xml
index 58f53cda0b8..590998941ad 100644
--- a/man/sd-bus.xml
+++ b/man/sd-bus.xml
@@ -117,6 +117,7 @@
sd_bus_message_new_method_error3,
sd_bus_message_new_signal3,
sd_bus_message_open_container3,
+sd_bus_message_peek_type3,
sd_bus_message_read3,
sd_bus_message_read_array3,
sd_bus_message_read_basic3,
diff --git a/man/sd_bus_message_read.xml b/man/sd_bus_message_read.xml
index a716660a2c0..1b9f36cd84e 100644
--- a/man/sd_bus_message_read.xml
+++ b/man/sd_bus_message_read.xml
@@ -19,6 +19,7 @@
sd_bus_message_read
sd_bus_message_readv
+ sd_bus_message_peek_type
Read a sequence of values from a message
@@ -40,38 +41,42 @@
const char *types
va_list ap
+
+
+ int sd_bus_message_peek_type
+ char *type
+ const char **contents
+
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.
+ 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.
+ 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 of 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.
+ 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 of
+ 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.
+ Each argument may also be NULL, in which case the value is read and ignored.
+
Item type specifiers
@@ -139,24 +144,29 @@
- If objects of the specified types are not present at the current position
- in the message, an error is returned.
-
+ 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.
+ 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.
+
+ sd_bus_message_peek_type() determines the type of the next element in
+ m to be read by sd_bus_message_read() or similar functions.
+ On success, the type is stored in type, if it is not NULL.
+ If the type is a container type, the type of its elements is stored in contents,
+ if it is not NULL. If this function successfully determines the type of the next
+ element in m, it returns a positive integer. If there are no more elements to be
+ read, it returns zero.
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.
+ On success, these functions return a non-negative integer. On failure, they return a negative
+ errno-style error code.