diff --git a/man/rules/meson.build b/man/rules/meson.build index e59ad3769d..9b2e102dd1 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 58f53cda0b..590998941a 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 a716660a2c..1b9f36cd84 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.