1SD_BUS_MESSAGE_APPEND(3)     sd_bus_message_append    SD_BUS_MESSAGE_APPEND(3)
2
3
4

NAME

6       sd_bus_message_append, sd_bus_message_appendv - Attach fields to a
7       D-Bus message based on a type string
8

SYNOPSIS

10       #include <systemd/sd-bus.h>
11
12       int sd_bus_message_append(sd_bus_message *m, const char *types, ...);
13
14       int sd_bus_message_appendv(sd_bus_message *m, const char *types,
15                                  va_list ap);
16

DESCRIPTION

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
24       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
31       In case of a basic type, one argument of the corresponding type is
32       expected.
33
34       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
39       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
43       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
47       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
53       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
59       For further details on the D-Bus type system, please consult the D-Bus
60       Specification[1].
61
62       Table 1. Item type specifiers
63       ┌──────────┬──────────────────────────────┬────────────────┬───────────────┬───────────────┐
64Specifier 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
122       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

TYPES STRING GRAMMAR

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

EXAMPLES

141       Append a single basic type (the string "a string"):
142
143           sd_bus_message *m;
144           ...
145           sd_bus_message_append(m, "s", "a string");
146
147       Append all types of integers:
148
149           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
159       Append a structure composed of a string and a D-Bus path:
160
161           sd_bus_message_append(m, "(so)", "a string", "/a/path");
162
163
164       Append an array of UNIX file descriptors:
165
166           sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO);
167
168
169       Append a variant, with the real type "g" (signature), and value
170       "sdbusisgood":
171
172           sd_bus_message_append(m, "v", "g", "sdbusisgood");
173
174       Append a dictionary containing the mapping {1=>"a", 2=>"b", 3=>""}:
175
176           sd_bus_message_append(m, "a{is}", 3, 1, "a", 2, "b", 3, NULL);
177
178

RETURN VALUE

180       On success, these functions return a non-negative integer. On failure,
181       they return a negative errno-style error code.
182
183   Errors
184       Returned errors may indicate the following problems:
185
186       -EINVAL
187           Specified parameter is invalid.
188
189       -EPERM
190           Message has been sealed.
191
192       -ESTALE
193           Message is in invalid state.
194
195       -ENXIO
196           Message cannot be appended to.
197
198       -ENOMEM
199           Memory allocation failed.
200

NOTES

202       These APIs are implemented as a shared library, which can be compiled
203       and linked to with the libsystemd pkg-config(1) file.
204

SEE ALSO

206       systemd(1), sd-bus(3), sd_bus_message_append_basic(3),
207       sd_bus_message_append_array(3), sd_bus_message_open_container(3)
208

NOTES

210        1. D-Bus Specification
211           http://dbus.freedesktop.org/doc/dbus-specification.html#type-system
212
213
214
215systemd 246                                           SD_BUS_MESSAGE_APPEND(3)
Impressum