Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_message_append_basic.3

raw
1 '\" t
2 .TH "SD_BUS_MESSAGE_APPEND_BASIC" "3" "" "systemd 261~rc3" "sd_bus_message_append_basic"
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_basic \- Attach a single field to a message
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_basic('u
32 .BI "int sd_bus_message_append_basic(sd_bus_message\ *" "m" ", char\ " "type" ", const\ void\ *" "p" ");"
33 .SH "DESCRIPTION"
34 .PP
35 \fBsd_bus_message_append_basic()\fR
36 appends a single field to the message
37 \fIm\fR\&. The parameter
38 \fItype\fR
39 determines how the pointer
40 \fIp\fR
41 is interpreted\&.
42 \fItype\fR
43 must be one of the basic types as defined by the
44 \m[blue]\fBBasic Types\fR\m[]\&\s-2\u[1]\d\s+2
45 section of the D\-Bus specification, and listed in the table below\&.
46 .sp
47 .it 1 an-trap
48 .nr an-no-space-flag 1
49 .nr an-break-flag 1
50 .br
51 .B Table\ \&1.\ \&Item type specifiers
52 .TS
53 allbox tab(:);
54 lB lB lB lB lB.
55 T{
56 Specifier
57 T}:T{
58 Constant
59 T}:T{
60 Description
61 T}:T{
62 Size
63 T}:T{
64 Expected C Type
65 T}
66 .T&
67 l l l l l
68 l l l l l
69 l l l l l
70 l l l l l
71 l l l l l
72 l l l l l
73 l l l l l
74 l l l l l
75 l l l l l
76 l l l l l
77 l l l l l
78 l l l l l
79 l l l l l.
80 T{
81 "y"
82 T}:T{
83 \fBSD_BUS_TYPE_BYTE\fR
84 T}:T{
85 unsigned integer
86 T}:T{
87 1 byte
88 T}:T{
89 uint8_t
90 T}
91 T{
92 "b"
93 T}:T{
94 \fBSD_BUS_TYPE_BOOLEAN\fR
95 T}:T{
96 boolean
97 T}:T{
98 4 bytes
99 T}:T{
100 int
101 T}
102 T{
103 "n"
104 T}:T{
105 \fBSD_BUS_TYPE_INT16\fR
106 T}:T{
107 signed integer
108 T}:T{
109 2 bytes
110 T}:T{
111 int16_t
112 T}
113 T{
114 "q"
115 T}:T{
116 \fBSD_BUS_TYPE_UINT16\fR
117 T}:T{
118 unsigned integer
119 T}:T{
120 2 bytes
121 T}:T{
122 uint16_t
123 T}
124 T{
125 "i"
126 T}:T{
127 \fBSD_BUS_TYPE_INT32\fR
128 T}:T{
129 signed integer
130 T}:T{
131 4 bytes
132 T}:T{
133 int32_t
134 T}
135 T{
136 "u"
137 T}:T{
138 \fBSD_BUS_TYPE_UINT32\fR
139 T}:T{
140 unsigned integer
141 T}:T{
142 4 bytes
143 T}:T{
144 uint32_t
145 T}
146 T{
147 "x"
148 T}:T{
149 \fBSD_BUS_TYPE_INT64\fR
150 T}:T{
151 signed integer
152 T}:T{
153 8 bytes
154 T}:T{
155 int64_t
156 T}
157 T{
158 "t"
159 T}:T{
160 \fBSD_BUS_TYPE_UINT64\fR
161 T}:T{
162 unsigned integer
163 T}:T{
164 8 bytes
165 T}:T{
166 uint64_t
167 T}
168 T{
169 "d"
170 T}:T{
171 \fBSD_BUS_TYPE_DOUBLE\fR
172 T}:T{
173 floating\-point
174 T}:T{
175 8 bytes
176 T}:T{
177 double
178 T}
179 T{
180 "s"
181 T}:T{
182 \fBSD_BUS_TYPE_STRING\fR
183 T}:T{
184 Unicode string
185 T}:T{
186 variable
187 T}:T{
188 char[]
189 T}
190 T{
191 "o"
192 T}:T{
193 \fBSD_BUS_TYPE_OBJECT_PATH\fR
194 T}:T{
195 object path
196 T}:T{
197 variable
198 T}:T{
199 char[]
200 T}
201 T{
202 "g"
203 T}:T{
204 \fBSD_BUS_TYPE_SIGNATURE\fR
205 T}:T{
206 signature
207 T}:T{
208 variable
209 T}:T{
210 char[]
211 T}
212 T{
213 "h"
214 T}:T{
215 \fBSD_BUS_TYPE_UNIX_FD\fR
216 T}:T{
217 UNIX file descriptor
218 T}:T{
219 4 bytes
220 T}:T{
221 int
222 T}
223 .TE
224 .sp 1
225 .PP
226 The value of the parameter is copied into a memory area held by the message object, stays in the possession of the caller and may hence be freely changed after this call without affecting the bus message it has been added to\&. If
227 \fItype\fR
228 is
229 "h"
230 (UNIX file descriptor), the descriptor is duplicated by this call and the passed descriptor stays in possession of the caller\&.
231 .PP
232 For types
233 "s",
234 "o", and
235 "g", the parameter
236 \fIp\fR
237 is interpreted as a pointer to a
238 \fBNUL\fR\-terminated character sequence\&. As a special case, a
239 \fBNULL\fR
240 pointer is interpreted as an empty string\&. The string should be valid Unicode string encoded as UTF\-8\&. In case of the two latter types, the additional requirements for a D\-Bus object path or type signature should be satisfied\&. Those requirements should be verified by the recipient of the message\&.
241 .SH "RETURN VALUE"
242 .PP
243 On success, this call returns 0 or a positive integer\&. On failure, it returns a negative errno\-style error code\&.
244 .SS "Errors"
245 .PP
246 Returned errors may indicate the following problems:
247 .PP
248 \fB\-EINVAL\fR
249 .RS 4
250 Specified parameter is invalid\&.
251 .RE
252 .PP
253 \fB\-EPERM\fR
254 .RS 4
255 Message has been sealed\&.
256 .RE
257 .PP
258 \fB\-ESTALE\fR
259 .RS 4
260 Message is in invalid state\&.
261 .RE
262 .PP
263 \fB\-ENXIO\fR
264 .RS 4
265 Message cannot be appended to\&.
266 .RE
267 .PP
268 \fB\-ENOMEM\fR
269 .RS 4
270 Memory allocation failed\&.
271 .RE
272 .SH "NOTES"
273 .PP
274 Functions described here are available as a shared library, which can be compiled against and linked to with the
275 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
276 file\&.
277 .PP
278 The code described here uses
279 \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
280 \fBsetenv\fR(3)
281 from a parallel thread\&. It is recommended to only do calls to
282 \fBsetenv()\fR
283 from an early phase of the program when no other threads have been started\&.
284 .SH "SEE ALSO"
285 .PP
286 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_message_read_basic\fR(3), \fBsd_bus_message_append\fR(3), \m[blue]\fBThe D\-Bus specification\fR\m[]\&\s-2\u[2]\d\s+2
287 .SH "NOTES"
288 .IP " 1." 4
289 Basic Types
290 .RS 4
291 \%https://dbus.freedesktop.org/doc/dbus-specification.html#basic-types
292 .RE
293 .IP " 2." 4
294 The D-Bus specification
295 .RS 4
296 \%https://dbus.freedesktop.org/doc/dbus-specification.html
297 .RE