1SD_BUS_MESSAGE_APPEND(3) sd_bus_message_append SD_BUS_MESSAGE_APPEND(3)
2
6 sd_bus_message_append, sd_bus_message_appendv - Attach fields to a
7 D-Bus message based on a type string
8
10 #include <systemd/sd-bus.h>
11 int sd_bus_message_append(sd_bus_message *m, const char *types, ...);
13 int sd_bus_message_appendv(sd_bus_message *m, const char *types,
15 va_list ap);
16
18 The sd_bus_message_append() function appends a sequence of fields to
19 the D-Bus message object m. The type string types describes the types
20 of the field arguments that follow. For each type specified in the type
21 string, one or more arguments need to be specified, in the same order
22 as declared in the type string.
23 The type string is composed of the elements shown in the table below.
25 It contains zero or more single "complete types". Each complete type
26 may be one of the basic types or a fully described container type. A
27 container type may be a structure with the contained types, a variant,
28 an array with its element type, or a dictionary entry with the
29 contained types. The type string is NUL-terminated.
30 In case of a basic type, one argument of the corresponding type is
32 expected.
33 A structure is denoted by a sequence of complete types between "(" and
35 ")". This sequence cannot be empty — it must contain at least one type.
36 Arguments corresponding to this nested sequence follow the same rules
37 as if they were not nested.
38 A variant is denoted by "v". Corresponding arguments must begin with a
40 type string denoting a complete type, and following that, arguments
41 corresponding to the specified type.
42 An array is denoted by "a" followed by a complete type. Corresponding
44 arguments must begin with the number of entries in the array, followed
45 by the entries themselves, matching the element type of the array.
46 A dictionary is an array of dictionary entries, denoted by "a" followed
48 by a pair of complete types between "{" and "}". The first of those
49 types must be a basic type. Corresponding arguments must begin with the
50 number of dictionary entries, followed by a pair of values for each
51 entry matching the element type of the dictionary entries.
52 sd_bus_message_appendv() is equivalent to sd_bus_message_append(),
54 except that it is called with a "va_list" instead of a variable number
55 of arguments. This function does not call the va_end() macro. Because
56 it invokes the va_arg() macro, the value of ap is undefined after the
57 call.
58 For further details on the D-Bus type system, please consult the D-Bus
60 Specification[1].
61 Table 1. Item type specifiers
63 ┌──────────┬──────────────────────────────┬────────────────┬───────────────┬───────────────┐
64 │Specifier │ Constant │ Description │ Size │ Expected C │
65 │ │ │ │ │ Type │
66 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
67 │"y" │ SD_BUS_TYPE_BYTE │ unsigned │ 1 byte │ uint8_t │
68 │ │ │ integer │ │ │
69 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
70 │"b" │ SD_BUS_TYPE_BOOLEAN │ boolean │ 4 bytes │ int │
71 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
72 │"n" │ SD_BUS_TYPE_INT16 │ signed │ 2 bytes │ int16_t │
73 │ │ │ integer │ │ │
74 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
75 │"q" │ SD_BUS_TYPE_UINT16 │ unsigned │ 2 bytes │ uint16_t │
76 │ │ │ integer │ │ │
77 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
78 │"i" │ SD_BUS_TYPE_INT32 │ signed │ 4 bytes │ int32_t │
79 │ │ │ integer │ │ │
80 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
81 │"u" │ SD_BUS_TYPE_UINT32 │ unsigned │ 4 bytes │ uint32_t │
82 │ │ │ integer │ │ │
83 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
84 │"x" │ SD_BUS_TYPE_INT64 │ signed │ 8 bytes │ int64_t │
85 │ │ │ integer │ │ │
86 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
87 │"t" │ SD_BUS_TYPE_UINT64 │ unsigned │ 8 bytes │ uint64_t │
88 │ │ │ integer │ │ │
89 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
90 │"d" │ SD_BUS_TYPE_DOUBLE │ floating-point │ 8 bytes │ double │
91 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
92 │"s" │ SD_BUS_TYPE_STRING │ Unicode string │ variable │ char[] │
93 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
94 │"o" │ SD_BUS_TYPE_OBJECT_PATH │ object path │ variable │ char[] │
95 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
96 │"g" │ SD_BUS_TYPE_SIGNATURE │ signature │ variable │ char[] │
97 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
98 │"h" │ SD_BUS_TYPE_UNIX_FD │ UNIX file │ 4 bytes │ int │
99 │ │ │ descriptor │ │ │
100 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
101 │"a" │ SD_BUS_TYPE_ARRAY │ array │ determined by │ int, followed │
102 │ │ │ │ array type │ by array │
103 │ │ │ │ and size │ contents │
104 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
105 │"v" │ SD_BUS_TYPE_VARIANT │ variant │ determined by │ signature │
106 │ │ │ │ the type │ string, │
107 │ │ │ │ argument │ followed by │
108 │ │ │ │ │ variant │
109 │ │ │ │ │ contents │
110 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
111 │"(" │ SD_BUS_TYPE_STRUCT_BEGIN │ array start │ determined by │ structure │
112 ├──────────┼──────────────────────────────┼────────────────┤ the nested │ contents │
113 │")" │ SD_BUS_TYPE_STRUCT_END │ array end │ types │ │
114 ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
115 │"{" │ SD_BUS_TYPE_DICT_ENTRY_BEGIN │ dictionary │ │ │
116 │ │ │ entry start │ determined by │ dictionary │
117 ├──────────┼──────────────────────────────┼────────────────┤ the nested │ contents │
118 │"}" │ SD_BUS_TYPE_DICT_ENTRY_END │ dictionary │ types │ │
119 │ │ │ entry end │ │ │
120 └──────────┴──────────────────────────────┴────────────────┴───────────────┴───────────────┘
121 For types "s" and "g" (unicode string or signature), the pointer may be
123 NULL, which is equivalent to an empty string. For "h" (UNIX file
124 descriptor), the descriptor is duplicated by this call and the passed
125 descriptor stays in possession of the caller. See
126 sd_bus_message_append_basic(3) for the precise interpretation of those
127 and other types.
128
130 types ::= complete_type*
131 complete_type ::= basic_type | variant | structure | array | dictionary
132 basic_type ::= "y" | "n" | "q" | "u" | "i" | "x" | "t" | "d" |
133 "b" | "h" |
134 "s" | "o" | "g"
135 variant ::= "v"
136 structure ::= "(" complete_type+ ")"
137 array ::= "a" complete_type
138 dictionary ::= "a" "{" basic_type complete_type "}"
139
141 Append a single basic type (the string "a string"):
142 sd_bus_message *m;
144 ...
145 sd_bus_message_append(m, "s", "a string");
146 Append all types of integers:
148 uint8_t y = 1;
150 int16_t n = 2;
151 uint16_t q = 3;
152 int32_t i = 4;
153 uint32_t u = 5;
154 int32_t x = 6;
155 uint32_t t = 7;
156 double d = 8.0;
157 sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d);
158 Append a structure composed of a string and a D-Bus path:
160 sd_bus_message_append(m, "(so)", "a string", "/a/path");
162 Append an array of UNIX file descriptors:
165 sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO);
167 Append a variant, with the real type "g" (signature), and value
170 "sdbusisgood":
171 sd_bus_message_append(m, "v", "g", "sdbusisgood");
173 Append a dictionary containing the mapping {1=>"a", 2=>"b", 3=>""}:
175 sd_bus_message_append(m, "a{is}", 3, 1, "a", 2, "b", 3, NULL);
177
180 On success, these functions return a non-negative integer. On failure,
181 they return a negative errno-style error code.
182 Errors
184 Returned errors may indicate the following problems:
185 -EINVAL
187 Specified parameter is invalid.
188 -EPERM
190 Message has been sealed.
191 -ESTALE
193 Message is in invalid state.
194 -ENXIO
196 Message cannot be appended to.
197 -ENOMEM
199 Memory allocation failed.
200
202 Functions described here are available as a shared library, which can
203 be compiled against and linked to with the libsystemd pkg-config(1)
204 file.
205 The code described here uses getenv(3), which is declared to be not
207 multi-thread-safe. This means that the code calling the functions
208 described here must not call setenv(3) from a parallel thread. It is
209 recommended to only do calls to setenv() from an early phase of the
210 program when no other threads have been started.
211
213 systemd(1), sd-bus(3), sd_bus_message_append_basic(3),
214 sd_bus_message_append_array(3), sd_bus_message_open_container(3)
215
217 1. D-Bus Specification
218 https://dbus.freedesktop.org/doc/dbus-specification.html#type-system
219systemd 254 SD_BUS_MESSAGE_APPEND(3)