X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=man%2Fsd_bus_message_read.xml;h=646943325f5bf04307f4a9fe26e3711e9016b062;hb=3df22bb5c8340b68b07028941a09da1fe5ad69ec;hp=2afa44174229bba1e687e418bd13508462f790d4;hpb=239bf9409de373cd5057142dd632dde8adb51b82;p=thirdparty%2Fsystemd.git
diff --git a/man/sd_bus_message_read.xml b/man/sd_bus_message_read.xml
index 2afa4417422..646943325f5 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
@@ -30,48 +31,52 @@
int sd_bus_message_read
sd_bus_message *m
- char char *types
+ const char *types
...
int sd_bus_message_readv
sd_bus_message *m
- char char *types
+ 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.
-
- 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.
+ 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.
+
+ 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.