From b750101eb236130cf056c675997decbac904cc49 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:35:18 +0200 Subject: Adding upstream version 252.22. Signed-off-by: Daniel Baumann --- man/sd_bus_message_open_container.xml | 183 ++++++++++++++++++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 man/sd_bus_message_open_container.xml (limited to 'man/sd_bus_message_open_container.xml') diff --git a/man/sd_bus_message_open_container.xml b/man/sd_bus_message_open_container.xml new file mode 100644 index 0000000..89c75f0 --- /dev/null +++ b/man/sd_bus_message_open_container.xml @@ -0,0 +1,183 @@ + + + + + + + + sd_bus_message_open_container + systemd + + + + sd_bus_message_open_container + 3 + + + + sd_bus_message_open_container + sd_bus_message_close_container + sd_bus_message_enter_container + sd_bus_message_exit_container + + Create and move between containers in D-Bus messages + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_open_container + sd_bus_message *m + char type + const char *contents + + + + int sd_bus_message_close_container + sd_bus_message *m + + + + int sd_bus_message_enter_container + sd_bus_message *m + char type + const char *contents + + + + int sd_bus_message_exit_container + sd_bus_message *m + + + + + + Description + + sd_bus_message_open_container() appends a new container to the message + m. After opening a new container, it can be filled with content using + sd_bus_message_append3 + and similar functions. Containers behave like a stack. To nest containers inside each other, call + sd_bus_message_open_container() multiple times without calling + sd_bus_message_close_container() in between. Each container will be nested inside the + previous container. type represents the container type and should be one of + r, a, v or e as described in + sd_bus_message_append3. + Instead of literals, the corresponding constants SD_BUS_TYPE_STRUCT, + SD_BUS_TYPE_ARRAY, SD_BUS_TYPE_VARIANT or + SD_BUS_TYPE_DICT_ENTRY can also be used. contents describes + the type of the container's elements and should be a D-Bus type string following the rules described in + sd_bus_message_append3. + + + sd_bus_message_close_container() closes the last container opened with + sd_bus_message_open_container(). On success, the write pointer of the message + m is positioned after the closed container in its parent container or in + m itself if there is no parent container. + + sd_bus_message_enter_container() enters the next container of the message + m for reading. It behaves mostly the same as + sd_bus_message_open_container(). Entering a container allows reading its contents + with + sd_bus_message_read3 + and similar functions. type and contents are the same as in + sd_bus_message_open_container(). + + sd_bus_message_exit_container() exits the scope of the last container entered + with sd_bus_message_enter_container(). It behaves mostly the same as + sd_bus_message_close_container(). Note that + sd_bus_message_exit_container() may only be called after iterating through all + members of the container, i.e. reading or skipping them. Use + sd_bus_message_skip3 + to skip over felds of a container in order to be able to exit the container with + sd_bus_message_exit_container() without reading all members. + + + + Return Value + + On success, these functions return a non-negative integer. + sd_bus_message_open_container() and sd_bus_message_close_container() + return 0. + sd_bus_message_enter_container() returns 1 if it successfully opened a new container, and 0 if + that was not possible because the end of the currently open container or message was reached. + sd_bus_message_exit_container() returns 1 on success. + On failure, all of these functions return a negative errno-style error code. + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + m or contents are + NULL or type is invalid. + + + + -EPERM + + The message m is already sealed. + + + + -ESTALE + + The message m is in an invalid state. + + + + -ENOMEM + + Memory allocation failed. + + + + -EBUSY + + sd_bus_message_exit_container() was called but there are + unread members left in the container. + + + + + + + + + Examples + + + Append an array of strings to a message + + + + + + Read an array of strings from a message + + + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_append3, + sd_bus_message_read3, + sd_bus_message_skip3, + The D-Bus specification + + + + -- cgit v1.2.3