Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_message_read_basic.3

raw
1 '\" t
2 .TH "SD_BUS_MESSAGE_READ_BASIC" "3" "" "systemd 261~rc3" "sd_bus_message_read_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_read_basic \- Read a basic type from 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_read_basic('u
32 .BI "int sd_bus_message_read_basic(sd_bus_message\ *" "m" ", char\ " "type" ", void\ *" "p" ");"
33 .SH "DESCRIPTION"
34 .PP
35 \fBsd_bus_message_read_basic()\fR
36 reads a basic type from a message and advances the read position in the message\&. The set of basic types and their ascii codes passed in
37 \fItype\fR
38 are described in the
39 \m[blue]\fBD\-Bus Specification\fR\m[]\&\s-2\u[1]\d\s+2\&.
40 .PP
41 If
42 \fIp\fR
43 is not
44 \fBNULL\fR, it should contain a pointer to an appropriate object\&. For example, if
45 \fItype\fR
46 is
47 \fB\*(Aqy\*(Aq\fR, the object passed in
48 \fIp\fR
49 should have type
50 \fBuint8_t *\fR\&. If
51 \fItype\fR
52 is
53 \fB\*(Aqs\*(Aq\fR, the object passed in
54 \fIp\fR
55 should have type
56 \fBconst char **\fR\&. Note that, if the basic type is a pointer (e\&.g\&.,
57 \fBconst char *\fR
58 in the case of a string), the pointer is only borrowed and the contents must be copied if they are to be used after the end of the message\*(Aqs lifetime\&. Similarly, during the lifetime of such a pointer, the message must not be modified\&. If
59 \fItype\fR
60 is
61 \fB\*(Aqh\*(Aq\fR
62 (UNIX file descriptor), the descriptor is not duplicated by this call and the returned descriptor remains in possession of the message object, and needs to be duplicated by the caller in order to keep an open reference to it after the message object is freed (for example by calling
63 "fcntl(fd, FD_DUPFD_CLOEXEC, 3)")\&. See the table below for a complete list of allowed types\&.
64 .sp
65 .it 1 an-trap
66 .nr an-no-space-flag 1
67 .nr an-break-flag 1
68 .br
69 .B Table\ \&1.\ \&Item type specifiers
70 .TS
71 allbox tab(:);
72 lB lB lB lB.
73 T{
74 Specifier
75 T}:T{
76 Constant
77 T}:T{
78 Description
79 T}:T{
80 Expected C Type
81 T}
82 .T&
83 l l l l
84 l l l l
85 l l l l
86 l l l l
87 l l l l
88 l l l l
89 l l l l
90 l l l l
91 l l l l
92 l l l l
93 l l l l
94 l l l l
95 l l l l.
96 T{
97 "y"
98 T}:T{
99 \fBSD_BUS_TYPE_BYTE\fR
100 T}:T{
101 8\-bit unsigned integer
102 T}:T{
103 \fBuint8_t *\fR
104 T}
105 T{
106 "b"
107 T}:T{
108 \fBSD_BUS_TYPE_BOOLEAN\fR
109 T}:T{
110 boolean
111 T}:T{
112 \fBint *\fR (NB: not \fBbool *\fR)
113 T}
114 T{
115 "n"
116 T}:T{
117 \fBSD_BUS_TYPE_INT16\fR
118 T}:T{
119 16\-bit signed integer
120 T}:T{
121 \fBint16_t *\fR
122 T}
123 T{
124 "q"
125 T}:T{
126 \fBSD_BUS_TYPE_UINT16\fR
127 T}:T{
128 16\-bit unsigned integer
129 T}:T{
130 \fBuint16_t *\fR
131 T}
132 T{
133 "i"
134 T}:T{
135 \fBSD_BUS_TYPE_INT32\fR
136 T}:T{
137 32\-bit signed integer
138 T}:T{
139 \fBint32_t *\fR
140 T}
141 T{
142 "u"
143 T}:T{
144 \fBSD_BUS_TYPE_UINT32\fR
145 T}:T{
146 32\-bit unsigned integer
147 T}:T{
148 \fBuint32_t *\fR
149 T}
150 T{
151 "x"
152 T}:T{
153 \fBSD_BUS_TYPE_INT64\fR
154 T}:T{
155 64\-bit signed integer
156 T}:T{
157 \fBint64_t *\fR
158 T}
159 T{
160 "t"
161 T}:T{
162 \fBSD_BUS_TYPE_UINT64\fR
163 T}:T{
164 64\-bit unsigned integer
165 T}:T{
166 \fBuint64_t *\fR
167 T}
168 T{
169 "d"
170 T}:T{
171 \fBSD_BUS_TYPE_DOUBLE\fR
172 T}:T{
173 IEEE 754 double precision floating\-point
174 T}:T{
175 \fBdouble *\fR
176 T}
177 T{
178 "s"
179 T}:T{
180 \fBSD_BUS_TYPE_STRING\fR
181 T}:T{
182 UTF\-8 string
183 T}:T{
184 \fBconst char **\fR
185 T}
186 T{
187 "o"
188 T}:T{
189 \fBSD_BUS_TYPE_OBJECT_PATH\fR
190 T}:T{
191 D\-Bus object path string
192 T}:T{
193 \fBconst char **\fR
194 T}
195 T{
196 "g"
197 T}:T{
198 \fBSD_BUS_TYPE_SIGNATURE\fR
199 T}:T{
200 D\-Bus signature string
201 T}:T{
202 \fBconst char **\fR
203 T}
204 T{
205 "h"
206 T}:T{
207 \fBSD_BUS_TYPE_UNIX_FD\fR
208 T}:T{
209 UNIX file descriptor
210 T}:T{
211 \fBint *\fR
212 T}
213 .TE
214 .sp 1
215 .PP
216 If there is no object of the specified type at the current position in the message, an error is returned\&.
217 .SH "RETURN VALUE"
218 .PP
219 On success,
220 \fBsd_bus_message_read_basic()\fR
221 returns a positive integer\&. If the end of the currently opened array has been reached, it returns 0\&. On failure, it returns a negative errno\-style error code\&.
222 .SS "Errors"
223 .PP
224 Returned errors may indicate the following problems:
225 .PP
226 \fB\-EINVAL\fR
227 .RS 4
228 Specified type string is invalid or the message parameter is
229 \fBNULL\fR\&.
230 .RE
231 .PP
232 \fB\-ENXIO\fR
233 .RS 4
234 The message does not contain the specified type at current position\&.
235 .RE
236 .PP
237 \fB\-EBADMSG\fR
238 .RS 4
239 The message cannot be parsed\&.
240 .RE
241 .SH "HISTORY"
242 .PP
243 \fBsd_bus_message_read_basic()\fR
244 was added in version 221\&.
245 .SH "SEE ALSO"
246 .PP
247 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_message_append_basic\fR(3), \fBsd_bus_message_skip\fR(3), \fBsd_bus_message_read\fR(3)
248 .SH "NOTES"
249 .IP " 1." 4
250 D-Bus Specification
251 .RS 4
252 \%https://dbus.freedesktop.org/doc/dbus-specification.html
253 .RE