1SD_BUS_MESSAGE_OPEN_CONTAIsNdE_Rb(u3s)_message_open_coSnDt_aBiUnSe_rMESSAGE_OPEN_CONTAINER(3)
2
6 sd_bus_message_open_container, sd_bus_message_close_container,
7 sd_bus_message_enter_container, sd_bus_message_exit_container - Create
8 and move between containers in D-Bus messages
9
11 #include <systemd/sd-bus.h>
12 int sd_bus_message_open_container(sd_bus_message *m, char type,
14 const char *contents);
15 int sd_bus_message_close_container(sd_bus_message *m);
17 int sd_bus_message_enter_container(sd_bus_message *m, char type,
19 const char *contents);
20 int sd_bus_message_exit_container(sd_bus_message *m);
22
24 sd_bus_message_open_container() appends a new container to the message
25 m. After opening a new container, it can be filled with content using
26 sd_bus_message_append(3) and similar functions. Containers behave like
27 a stack. To nest containers inside each other, call
28 sd_bus_message_open_container() multiple times without calling
29 sd_bus_message_close_container() in between. Each container will be
30 nested inside the previous container. type represents the container
31 type and should be one of "r", "a", "v" or "e" as described in
32 sd_bus_message_append(3). Instead of literals, the corresponding
33 constants SD_BUS_TYPE_STRUCT, SD_BUS_TYPE_ARRAY, SD_BUS_TYPE_VARIANT or
34 SD_BUS_TYPE_DICT_ENTRY can also be used. contents describes the type
35 of the container's elements and should be a D-Bus type string following
36 the rules described in sd_bus_message_append(3).
37 sd_bus_message_close_container() closes the last container opened with
39 sd_bus_message_open_container(). On success, the write pointer of the
40 message m is positioned after the closed container in its parent
41 container or in m itself if there is no parent container.
42 sd_bus_message_enter_container() enters the next container of the
44 message m for reading. It behaves mostly the same as
45 sd_bus_message_open_container(). Entering a container allows reading
46 its contents with sd_bus_message_read(3) and similar functions. type
47 and contents are the same as in sd_bus_message_open_container().
48 sd_bus_message_exit_container() exits the scope of the last container
50 entered with sd_bus_message_enter_container(). It behaves mostly the
51 same as sd_bus_message_close_container(). Note that
52 sd_bus_message_exit_container() may only be called after iterating
53 through all members of the container, i.e. reading or skipping over
54 them. Use sd_bus_message_skip(3) to skip over fields of a container in
55 order to be able to exit the container with
56 sd_bus_message_exit_container() without reading all members.
57
59 On success, these functions return a non-negative integer.
60 sd_bus_message_open_container() and sd_bus_message_close_container()
61 return 0. sd_bus_message_enter_container() returns 1 if it
62 successfully opened a new container, and 0 if that was not possible
63 because the end of the currently open container or message was reached.
64 sd_bus_message_exit_container() returns 1 on success. On failure, all
65 of these functions return a negative errno-style error code.
66 Errors
68 Returned errors may indicate the following problems:
69 -EINVAL
71 m or contents are NULL or type is invalid.
72 -EBADMSG
74 Message m has invalid structure.
75 -ENXIO
77 Message m does not have a container of type type at the current
78 position, or the contents do not match contents.
79 -EPERM
81 The message m is already sealed.
82 -ESTALE
84 The message m is in an invalid state.
85 -ENOMEM
87 Memory allocation failed.
88 -EBUSY
90 sd_bus_message_exit_container() was called but there are unread
91 members left in the container.
92
94 Functions described here are available as a shared library, which can
95 be compiled against and linked to with the libsystemd pkg-config(1)
96 file.
97 The code described here uses getenv(3), which is declared to be not
99 multi-thread-safe. This means that the code calling the functions
100 described here must not call setenv(3) from a parallel thread. It is
101 recommended to only do calls to setenv() from an early phase of the
102 program when no other threads have been started.
103
105 Example 1. Append an array of strings to a message
106 /* SPDX-License-Identifier: MIT-0 */
108 #include <systemd/sd-bus.h>
110 int append_strings_to_message(sd_bus_message *m, const char *const *arr) {
112 int r;
113 r = sd_bus_message_open_container(m, 'a', "s");
115 if (r < 0)
116 return r;
117 for (const char *s = *arr; *s; s++) {
119 r = sd_bus_message_append(m, "s", s);
120 if (r < 0)
121 return r;
122 }
123 return sd_bus_message_close_container(m);
125 }
126 Example 2. Read an array of strings from a message
128 /* SPDX-License-Identifier: MIT-0 */
130 #include <stdio.h>
132 #include <systemd/sd-bus.h>
134 int read_strings_from_message(sd_bus_message *m) {
136 int r;
137 r = sd_bus_message_enter_container(m, 'a', "s");
139 if (r < 0)
140 return r;
141 for (;;) {
143 const char *s;
144 r = sd_bus_message_read(m, "s", &s);
146 if (r < 0)
147 return r;
148 if (r == 0)
149 break;
150 printf("%s\n", s);
152 }
153 return sd_bus_message_exit_container(m);
155 }
156
158 systemd(1), sd-bus(3), sd_bus_message_append(3),
159 sd_bus_message_read(3), sd_bus_message_skip(3), The D-Bus
160 specification[1]
161
163 1. The D-Bus specification
164 https://dbus.freedesktop.org/doc/dbus-specification.html
165systemd 254 SD_BUS_MESSAGE_OPEN_CONTAINER(3)