Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_message_append.3

raw
1 '\" t
2 .TH "SD_BUS_MESSAGE_APPEND" "3" "" "systemd 261~rc3" "sd_bus_message_append"
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_append, sd_bus_message_appendv \- Attach fields to a D\-Bus message based on a type string
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_append('u
32 .BI "int sd_bus_message_append(sd_bus_message\ *" "m" ", const\ char\ *" "types" ", \&...);"
33 .HP \w'int\ sd_bus_message_appendv('u
34 .BI "int sd_bus_message_appendv(sd_bus_message\ *" "m" ", const\ char\ *" "types" ", va_list\ " "ap" ");"
35 .SH "DESCRIPTION"
36 .PP
37 The
38 \fBsd_bus_message_append()\fR
39 function appends a sequence of fields to the D\-Bus message object
40 \fIm\fR\&. The type string
41 \fItypes\fR
42 describes the types of the field arguments that follow\&. For each type specified in the type string, one or more arguments need to be specified, in the same order as declared in the type string\&.
43 .PP
44 The type string is composed of the elements shown in the table below\&. It contains zero or more single "complete types"\&. Each complete type may be one of the basic types or a fully described container type\&. A container type may be a structure with the contained types, a variant, an array with its element type, or a dictionary entry with the contained types\&. The type string is
45 \fBNUL\fR\-terminated\&.
46 .PP
47 In case of a basic type, one argument of the corresponding type is expected\&.
48 .PP
49 A structure is denoted by a sequence of complete types between
50 "("
51 and
52 ")"\&. This sequence cannot be empty \(em it must contain at least one type\&. Arguments corresponding to this nested sequence follow the same rules as if they were not nested\&.
53 .PP
54 A variant is denoted by
55 "v"\&. Corresponding arguments must begin with a type string denoting a complete type, and following that, arguments corresponding to the specified type\&.
56 .PP
57 An array is denoted by
58 "a"
59 followed by a complete type\&. Corresponding arguments must begin with the number of entries in the array, followed by the entries themselves, matching the element type of the array\&.
60 .PP
61 A dictionary is an array of dictionary entries, denoted by
62 "a"
63 followed by a pair of complete types between
64 "{"
65 and
66 "}"\&. The first of those types must be a basic type\&. Corresponding arguments must begin with the number of dictionary entries, followed by a pair of values for each entry matching the element type of the dictionary entries\&.
67 .PP
68 \fBsd_bus_message_appendv()\fR
69 is equivalent to
70 \fBsd_bus_message_append()\fR, except that it is called with a
71 "va_list"
72 instead of a variable number of arguments\&. This function does not call the
73 \fBva_end()\fR
74 macro\&. Because it invokes the
75 \fBva_arg()\fR
76 macro, the value of
77 \fIap\fR
78 is undefined after the call\&.
79 .PP
80 For further details on the D\-Bus type system, please consult the
81 \m[blue]\fBD\-Bus Specification\fR\m[]\&\s-2\u[1]\d\s+2\&.
82 .sp
83 .it 1 an-trap
84 .nr an-no-space-flag 1
85 .nr an-break-flag 1
86 .br
87 .B Table\ \&1.\ \&Item type specifiers
88 .TS
89 allbox tab(:);
90 lB lB lB lB lB.
91 T{
92 Specifier
93 T}:T{
94 Constant
95 T}:T{
96 Description
97 T}:T{
98 Size
99 T}:T{
100 Expected C Type
101 T}
102 .T&
103 l l l l l
104 l l l l l
105 l l l l l
106 l l l l l
107 l l l l l
108 l l l l l
109 l l l l l
110 l l l l l
111 l l l l l
112 l l l l l
113 l l l l l
114 l l l l l
115 l l l l l
116 l l l l l
117 l l l l l
118 l l l l l
119 l l l ^ ^
120 l l l l l
121 l l l ^ ^.
122 T{
123 "y"
124 T}:T{
125 \fBSD_BUS_TYPE_BYTE\fR
126 T}:T{
127 unsigned integer
128 T}:T{
129 1 byte
130 T}:T{
131 uint8_t
132 T}
133 T{
134 "b"
135 T}:T{
136 \fBSD_BUS_TYPE_BOOLEAN\fR
137 T}:T{
138 boolean
139 T}:T{
140 4 bytes
141 T}:T{
142 int
143 T}
144 T{
145 "n"
146 T}:T{
147 \fBSD_BUS_TYPE_INT16\fR
148 T}:T{
149 signed integer
150 T}:T{
151 2 bytes
152 T}:T{
153 int16_t
154 T}
155 T{
156 "q"
157 T}:T{
158 \fBSD_BUS_TYPE_UINT16\fR
159 T}:T{
160 unsigned integer
161 T}:T{
162 2 bytes
163 T}:T{
164 uint16_t
165 T}
166 T{
167 "i"
168 T}:T{
169 \fBSD_BUS_TYPE_INT32\fR
170 T}:T{
171 signed integer
172 T}:T{
173 4 bytes
174 T}:T{
175 int32_t
176 T}
177 T{
178 "u"
179 T}:T{
180 \fBSD_BUS_TYPE_UINT32\fR
181 T}:T{
182 unsigned integer
183 T}:T{
184 4 bytes
185 T}:T{
186 uint32_t
187 T}
188 T{
189 "x"
190 T}:T{
191 \fBSD_BUS_TYPE_INT64\fR
192 T}:T{
193 signed integer
194 T}:T{
195 8 bytes
196 T}:T{
197 int64_t
198 T}
199 T{
200 "t"
201 T}:T{
202 \fBSD_BUS_TYPE_UINT64\fR
203 T}:T{
204 unsigned integer
205 T}:T{
206 8 bytes
207 T}:T{
208 uint64_t
209 T}
210 T{
211 "d"
212 T}:T{
213 \fBSD_BUS_TYPE_DOUBLE\fR
214 T}:T{
215 floating\-point
216 T}:T{
217 8 bytes
218 T}:T{
219 double
220 T}
221 T{
222 "s"
223 T}:T{
224 \fBSD_BUS_TYPE_STRING\fR
225 T}:T{
226 Unicode string
227 T}:T{
228 variable
229 T}:T{
230 char[]
231 T}
232 T{
233 "o"
234 T}:T{
235 \fBSD_BUS_TYPE_OBJECT_PATH\fR
236 T}:T{
237 object path
238 T}:T{
239 variable
240 T}:T{
241 char[]
242 T}
243 T{
244 "g"
245 T}:T{
246 \fBSD_BUS_TYPE_SIGNATURE\fR
247 T}:T{
248 signature
249 T}:T{
250 variable
251 T}:T{
252 char[]
253 T}
254 T{
255 "h"
256 T}:T{
257 \fBSD_BUS_TYPE_UNIX_FD\fR
258 T}:T{
259 UNIX file descriptor
260 T}:T{
261 4 bytes
262 T}:T{
263 int
264 T}
265 T{
266 "a"
267 T}:T{
268 \fBSD_BUS_TYPE_ARRAY\fR
269 T}:T{
270 array
271 T}:T{
272 determined by array type and size
273 T}:T{
274 int, followed by array contents
275 T}
276 T{
277 "v"
278 T}:T{
279 \fBSD_BUS_TYPE_VARIANT\fR
280 T}:T{
281 variant
282 T}:T{
283 determined by the type argument
284 T}:T{
285 signature string, followed by variant contents
286 T}
287 T{
288 "("
289 T}:T{
290 \fBSD_BUS_TYPE_STRUCT_BEGIN\fR
291 T}:T{
292 array start
293 T}:T{
294 determined by the nested types
295 T}:T{
296 structure contents
297 T}
298 T{
299 ")"
300 T}:T{
301 \fBSD_BUS_TYPE_STRUCT_END\fR
302 T}:T{
303 array end
304 T}::
305 T{
306 "{"
307 T}:T{
308 \fBSD_BUS_TYPE_DICT_ENTRY_BEGIN\fR
309 T}:T{
310 dictionary entry start
311 T}:T{
312 determined by the nested types
313 T}:T{
314 dictionary contents
315 T}
316 T{
317 "}"
318 T}:T{
319 \fBSD_BUS_TYPE_DICT_ENTRY_END\fR
320 T}:T{
321 dictionary entry end
322 T}::
323 .TE
324 .sp 1
325 .PP
326 For types
327 "s"
328 and
329 "g"
330 (unicode string or signature), the pointer may be
331 \fBNULL\fR, which is equivalent to an empty string\&. For
332 "h"
333 (UNIX file descriptor), the descriptor is duplicated by this call and the passed descriptor stays in possession of the caller\&. See
334 \fBsd_bus_message_append_basic\fR(3)
335 for the precise interpretation of those and other types\&.
336 .SH "TYPES STRING GRAMMAR"
337 .sp
338 .if n \{\
339 .RS 4
340 .\}
341 .nf
342 types ::= complete_type*
343 complete_type ::= basic_type | variant | structure | array | dictionary
344 basic_type ::= "y" | "n" | "q" | "u" | "i" | "x" | "t" | "d" |
345 "b" | "h" |
346 "s" | "o" | "g"
347 variant ::= "v"
348 structure ::= "(" complete_type+ ")"
349 array ::= "a" complete_type
350 dictionary ::= "a" "{" basic_type complete_type "}"
351 .fi
352 .if n \{\
353 .RE
354 .\}
355 .SH "EXAMPLES"
356 .PP
357 Append a single basic type (the string
358 "a string"):
359 .sp
360 .if n \{\
361 .RS 4
362 .\}
363 .nf
364 sd_bus_message *m;
365 \&...
366 sd_bus_message_append(m, "s", "a string");
367 .fi
368 .if n \{\
369 .RE
370 .\}
371 .PP
372 Append all types of integers:
373 .sp
374 .if n \{\
375 .RS 4
376 .\}
377 .nf
378 uint8_t y = 1;
379 int16_t n = 2;
380 uint16_t q = 3;
381 int32_t i = 4;
382 uint32_t u = 5;
383 int32_t x = 6;
384 uint32_t t = 7;
385 double d = 8\&.0;
386 sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d);
387 .fi
388 .if n \{\
389 .RE
390 .\}
391 .PP
392 Append a structure composed of a string and a D\-Bus path:
393 .sp
394 .if n \{\
395 .RS 4
396 .\}
397 .nf
398 sd_bus_message_append(m, "(so)", "a string", "/a/path");
399 .fi
400 .if n \{\
401 .RE
402 .\}
403 .PP
404 Append an array of UNIX file descriptors:
405 .sp
406 .if n \{\
407 .RS 4
408 .\}
409 .nf
410 sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO);
411 .fi
412 .if n \{\
413 .RE
414 .\}
415 .PP
416 Append a variant, with the real type "g" (signature), and value "sdbusisgood":
417 .sp
418 .if n \{\
419 .RS 4
420 .\}
421 .nf
422 sd_bus_message_append(m, "v", "g", "sdbusisgood");
423 .fi
424 .if n \{\
425 .RE
426 .\}
427 .PP
428 Append a dictionary containing the mapping {1=>"a", 2=>"b", 3=>""}:
429 .sp
430 .if n \{\
431 .RS 4
432 .\}
433 .nf
434 sd_bus_message_append(m, "a{is}", 3, 1, "a", 2, "b", 3, NULL);
435 .fi
436 .if n \{\
437 .RE
438 .\}
439 .SH "RETURN VALUE"
440 .PP
441 On success, these functions return a non\-negative integer\&. On failure, they return a negative errno\-style error code\&.
442 .SS "Errors"
443 .PP
444 Returned errors may indicate the following problems:
445 .PP
446 \fB\-EINVAL\fR
447 .RS 4
448 Specified parameter is invalid\&.
449 .RE
450 .PP
451 \fB\-EPERM\fR
452 .RS 4
453 Message has been sealed\&.
454 .RE
455 .PP
456 \fB\-ESTALE\fR
457 .RS 4
458 Message is in invalid state\&.
459 .RE
460 .PP
461 \fB\-ENXIO\fR
462 .RS 4
463 Message cannot be appended to\&.
464 .RE
465 .PP
466 \fB\-ENOMEM\fR
467 .RS 4
468 Memory allocation failed\&.
469 .RE
470 .SH "NOTES"
471 .PP
472 Functions described here are available as a shared library, which can be compiled against and linked to with the
473 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
474 file\&.
475 .PP
476 The code described here uses
477 \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
478 \fBsetenv\fR(3)
479 from a parallel thread\&. It is recommended to only do calls to
480 \fBsetenv()\fR
481 from an early phase of the program when no other threads have been started\&.
482 .SH "SEE ALSO"
483 .PP
484 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_message_append_basic\fR(3), \fBsd_bus_message_append_array\fR(3), \fBsd_bus_message_open_container\fR(3)
485 .SH "NOTES"
486 .IP " 1." 4
487 D-Bus Specification
488 .RS 4
489 \%https://dbus.freedesktop.org/doc/dbus-specification.html#type-system
490 .RE