Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_message_open_container.3

raw
1 '\" t
2 .TH "SD_BUS_MESSAGE_OPEN_CONTAINER" "3" "" "systemd 261~rc3" "sd_bus_message_open_container"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 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
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-bus\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_bus_message_open_container('u
32 .BI "int sd_bus_message_open_container(sd_bus_message\ *" "m" ", char\ " "type" ", const\ char\ *" "contents" ");"
33 .HP \w'int\ sd_bus_message_close_container('u
34 .BI "int sd_bus_message_close_container(sd_bus_message\ *" "m" ");"
35 .HP \w'int\ sd_bus_message_enter_container('u
36 .BI "int sd_bus_message_enter_container(sd_bus_message\ *" "m" ", char\ " "type" ", const\ char\ *" "contents" ");"
37 .HP \w'int\ sd_bus_message_exit_container('u
38 .BI "int sd_bus_message_exit_container(sd_bus_message\ *" "m" ");"
39 .SH "DESCRIPTION"
40 .PP
41 \fBsd_bus_message_open_container()\fR
42 appends a new container to the message
43 \fIm\fR\&. After opening a new container, it can be filled with content using
44 \fBsd_bus_message_append\fR(3)
45 and similar functions\&. Containers behave like a stack\&. To nest containers inside each other, call
46 \fBsd_bus_message_open_container()\fR
47 multiple times without calling
48 \fBsd_bus_message_close_container()\fR
49 in between\&. Each container will be nested inside the previous container\&.
50 \fItype\fR
51 represents the container type and should be one of
52 "r",
53 "a",
54 "v"
55 or
56 "e"
57 as described in
58 \fBsd_bus_message_append\fR(3)\&. Instead of literals, the corresponding constants
59 \fBSD_BUS_TYPE_STRUCT\fR,
60 \fBSD_BUS_TYPE_ARRAY\fR,
61 \fBSD_BUS_TYPE_VARIANT\fR
62 or
63 \fBSD_BUS_TYPE_DICT_ENTRY\fR
64 can also be used\&.
65 \fIcontents\fR
66 describes the type of the container\*(Aqs elements and should be a D\-Bus type string following the rules described in
67 \fBsd_bus_message_append\fR(3)\&.
68 .PP
69 \fBsd_bus_message_close_container()\fR
70 closes the last container opened with
71 \fBsd_bus_message_open_container()\fR\&. On success, the write pointer of the message
72 \fIm\fR
73 is positioned after the closed container in its parent container or in
74 \fIm\fR
75 itself if there is no parent container\&.
76 .PP
77 \fBsd_bus_message_enter_container()\fR
78 enters the next container of the message
79 \fIm\fR
80 for reading\&. It behaves mostly the same as
81 \fBsd_bus_message_open_container()\fR\&. Entering a container allows reading its contents with
82 \fBsd_bus_message_read\fR(3)
83 and similar functions\&.
84 \fItype\fR
85 and
86 \fIcontents\fR
87 are the same as in
88 \fBsd_bus_message_open_container()\fR\&.
89 .PP
90 \fBsd_bus_message_exit_container()\fR
91 exits the scope of the last container entered with
92 \fBsd_bus_message_enter_container()\fR\&. It behaves mostly the same as
93 \fBsd_bus_message_close_container()\fR\&. Note that
94 \fBsd_bus_message_exit_container()\fR
95 may only be called after iterating through all members of the container, i\&.e\&. reading or skipping over them\&. Use
96 \fBsd_bus_message_skip\fR(3)
97 to skip over fields of a container in order to be able to exit the container with
98 \fBsd_bus_message_exit_container()\fR
99 without reading all members\&.
100 .SH "RETURN VALUE"
101 .PP
102 On success, these functions return a non\-negative integer\&.
103 \fBsd_bus_message_open_container()\fR
104 and
105 \fBsd_bus_message_close_container()\fR
106 return 0\&.
107 \fBsd_bus_message_enter_container()\fR
108 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\&.
109 \fBsd_bus_message_exit_container()\fR
110 returns 1 on success\&. On failure, all of these functions return a negative errno\-style error code\&.
111 .SS "Errors"
112 .PP
113 Returned errors may indicate the following problems:
114 .PP
115 \fB\-EINVAL\fR
116 .RS 4
117 \fIm\fR
118 or
119 \fIcontents\fR
120 are
121 \fBNULL\fR
122 or
123 \fItype\fR
124 is invalid\&.
125 .sp
126 Added in version 246\&.
127 .RE
128 .PP
129 \fB\-EBADMSG\fR
130 .RS 4
131 Message
132 \fIm\fR
133 has invalid structure\&.
134 .sp
135 Added in version 254\&.
136 .RE
137 .PP
138 \fB\-ENXIO\fR
139 .RS 4
140 Message
141 \fIm\fR
142 does not have a container of type
143 \fItype\fR
144 at the current position, or the contents do not match
145 \fIcontents\fR\&.
146 .sp
147 Added in version 254\&.
148 .RE
149 .PP
150 \fB\-EPERM\fR
151 .RS 4
152 The message
153 \fIm\fR
154 is already sealed\&.
155 .sp
156 Added in version 246\&.
157 .RE
158 .PP
159 \fB\-ESTALE\fR
160 .RS 4
161 The message
162 \fIm\fR
163 is in an invalid state\&.
164 .sp
165 Added in version 246\&.
166 .RE
167 .PP
168 \fB\-ENOMEM\fR
169 .RS 4
170 Memory allocation failed\&.
171 .sp
172 Added in version 246\&.
173 .RE
174 .PP
175 \fB\-EBUSY\fR
176 .RS 4
177 \fBsd_bus_message_exit_container()\fR
178 was called but there are unread members left in the container\&.
179 .sp
180 Added in version 247\&.
181 .RE
182 .SH "NOTES"
183 .PP
184 Functions described here are available as a shared library, which can be compiled against and linked to with the
185 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
186 file\&.
187 .PP
188 The code described here uses
189 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
190 \fBsetenv\fR(3)
191 from a parallel thread\&. It is recommended to only do calls to
192 \fBsetenv()\fR
193 from an early phase of the program when no other threads have been started\&.
194 .SH "EXAMPLES"
195 .PP
196 \fBExample\ \&1.\ \&Append an array of strings to a message\fR
197 .sp
198 .if n \{\
199 .RS 4
200 .\}
201 .nf
202 /* SPDX\-License\-Identifier: MIT\-0 */
203
204 #include <systemd/sd\-bus\&.h>
205
206 int append_strings_to_message(sd_bus_message *m, const char *const *arr) {
207 const char *s;
208 int r;
209
210 r = sd_bus_message_open_container(m, \*(Aqa\*(Aq, "s");
211 if (r < 0)
212 return r;
213
214 for (s = *arr; *s; s++) {
215 r = sd_bus_message_append(m, "s", s);
216 if (r < 0)
217 return r;
218 }
219
220 return sd_bus_message_close_container(m);
221 }
222 .fi
223 .if n \{\
224 .RE
225 .\}
226 .PP
227 \fBExample\ \&2.\ \&Read an array of strings from a message\fR
228 .sp
229 .if n \{\
230 .RS 4
231 .\}
232 .nf
233 /* SPDX\-License\-Identifier: MIT\-0 */
234
235 #include <stdio\&.h>
236
237 #include <systemd/sd\-bus\&.h>
238
239 int read_strings_from_message(sd_bus_message *m) {
240 int r;
241
242 r = sd_bus_message_enter_container(m, \*(Aqa\*(Aq, "s");
243 if (r < 0)
244 return r;
245
246 for (;;) {
247 const char *s;
248
249 r = sd_bus_message_read(m, "s", &s);
250 if (r < 0)
251 return r;
252 if (r == 0)
253 break;
254
255 printf("%s\en", s);
256 }
257
258 return sd_bus_message_exit_container(m);
259 }
260 .fi
261 .if n \{\
262 .RE
263 .\}
264 .SH "SEE ALSO"
265 .PP
266 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_message_append\fR(3), \fBsd_bus_message_read\fR(3), \fBsd_bus_message_skip\fR(3), \m[blue]\fBThe D\-Bus specification\fR\m[]\&\s-2\u[1]\d\s+2
267 .SH "NOTES"
268 .IP " 1." 4
269 The D-Bus specification
270 .RS 4
271 \%https://dbus.freedesktop.org/doc/dbus-specification.html
272 .RE