]>
Commit | Line | Data |
---|---|---|
50972aac | 1 | <?xml version='1.0'?> |
3a54a157 ZJS |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | |
db9ecf05 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
50972aac ZJS |
5 | |
6 | <refentry id="sd_bus_message_read" | |
7 | xmlns:xi="http://www.w3.org/2001/XInclude"> | |
8 | ||
9 | <refentryinfo> | |
10 | <title>sd_bus_message_read</title> | |
11 | <productname>systemd</productname> | |
12 | </refentryinfo> | |
13 | ||
14 | <refmeta> | |
15 | <refentrytitle>sd_bus_message_read</refentrytitle> | |
16 | <manvolnum>3</manvolnum> | |
17 | </refmeta> | |
18 | ||
19 | <refnamediv> | |
20 | <refname>sd_bus_message_read</refname> | |
21 | <refname>sd_bus_message_readv</refname> | |
3df22bb5 | 22 | <refname>sd_bus_message_peek_type</refname> |
50972aac ZJS |
23 | |
24 | <refpurpose>Read a sequence of values from a message</refpurpose> | |
25 | </refnamediv> | |
26 | ||
27 | <refsynopsisdiv> | |
28 | <funcsynopsis> | |
29 | <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> | |
30 | ||
31 | <funcprototype> | |
32 | <funcdef>int <function>sd_bus_message_read</function></funcdef> | |
33 | <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> | |
9735c644 | 34 | <paramdef>const char *<parameter>types</parameter></paramdef> |
50972aac ZJS |
35 | <paramdef>...</paramdef> |
36 | </funcprototype> | |
37 | ||
38 | <funcprototype> | |
39 | <funcdef>int <function>sd_bus_message_readv</function></funcdef> | |
40 | <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> | |
9735c644 | 41 | <paramdef>const char *<parameter>types</parameter></paramdef> |
50972aac ZJS |
42 | <paramdef>va_list <parameter>ap</parameter></paramdef> |
43 | </funcprototype> | |
3df22bb5 DDM |
44 | |
45 | <funcprototype> | |
46 | <funcdef>int <function>sd_bus_message_peek_type</function></funcdef> | |
483abcc6 | 47 | <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> |
3df22bb5 DDM |
48 | <paramdef>char *<parameter>type</parameter></paramdef> |
49 | <paramdef>const char **<parameter>contents</parameter></paramdef> | |
50 | </funcprototype> | |
50972aac ZJS |
51 | </funcsynopsis> |
52 | </refsynopsisdiv> | |
53 | ||
54 | <refsect1> | |
55 | <title>Description</title> | |
56 | ||
3df22bb5 DDM |
57 | <para><function>sd_bus_message_read()</function> reads a sequence of fields from the D-Bus message object |
58 | <parameter>m</parameter> and advances the read position in the message. The type string | |
59 | <parameter>types</parameter> describes the types of items expected in the message and the field arguments | |
60 | that follow. The type string may be <constant>NULL</constant> or empty, in which case nothing is read. | |
61 | </para> | |
50972aac ZJS |
62 | |
63 | <para>The type string is composed of the elements described in | |
64 | <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
3df22bb5 DDM |
65 | i.e. basic and container types. It must contain zero or more single "complete types". The type string is |
66 | <constant>NUL</constant>-terminated.</para> | |
67 | ||
68 | <para>For each type specified in the type string, one or more arguments need to be specified after the | |
69 | <parameter>types</parameter> parameter, in the same order. The arguments must be pointers to appropriate | |
70 | types (a pointer to <type>int8_t</type> for a <literal>y</literal> in the type string, a pointer to | |
71 | <type>int32_t</type> for an <literal>i</literal>, a pointer to <type>const char*</type> for an | |
72 | <literal>s</literal>, ...) which are set based on the values in the message. As an exception, in case of | |
73 | array and variant types, the first argument is an "input" argument that further specifies how the message | |
74 | should be read. See the table below for a complete list of allowed arguments and their types. Note that, | |
75 | if the basic type is a pointer (e.g., <type>const char *</type> in the case of a string), the argument is | |
76 | a pointer to a pointer, and also the pointer value that is written is only borrowed and the contents must | |
beca342d | 77 | be copied if they are to be used after the end of the message's lifetime. If the type is |
e2b40db6 LP |
78 | <literal>h</literal> (UNIX file descriptor), the descriptor is not duplicated by this call and the |
79 | returned descriptor remains in possession of the message object, and needs to be duplicated by the caller | |
80 | in order to keep an open reference to it after the message object is freed.</para> | |
3df22bb5 DDM |
81 | |
82 | <para>Each argument may also be <constant>NULL</constant>, in which case the value is read and ignored. | |
83 | </para> | |
50972aac ZJS |
84 | |
85 | <table> | |
86 | <title>Item type specifiers</title> | |
87 | ||
88 | <tgroup cols='5'> | |
89 | <colspec colname='specifier' /> | |
90 | <colspec colname='constant' /> | |
91 | <colspec colname='description' /> | |
92 | <colspec colname='type1' /> | |
93 | <colspec colname='type2' /> | |
94 | <thead> | |
95 | <row> | |
96 | <entry>Specifier</entry> | |
97 | <entry>Constant</entry> | |
98 | <entry>Description</entry> | |
99 | <entry>Type of the first argument</entry> | |
100 | <entry>Types of the subsequent arguments, if any</entry> | |
101 | </row> | |
102 | </thead> | |
103 | ||
104 | <tbody> | |
105 | <xi:include href="sd_bus_message_read_basic.xml" xpointer="xpointer(//table[@id='format-specifiers']//tbody/*)" /> | |
106 | ||
107 | <row> | |
108 | <entry><literal>a</literal></entry> | |
109 | <entry><constant>SD_BUS_TYPE_ARRAY</constant></entry> | |
110 | <entry>array</entry> | |
979bdc47 | 111 | <entry><type>int</type>, which specifies the expected length <parameter>n</parameter> of the array</entry> |
50972aac ZJS |
112 | <entry><parameter>n</parameter> sets of arguments appropriate for the array element type</entry> |
113 | </row> | |
114 | ||
115 | <row> | |
116 | <entry><literal>v</literal></entry> | |
117 | <entry><constant>SD_BUS_TYPE_VARIANT</constant></entry> | |
118 | <entry>variant</entry> | |
119 | <entry>signature string</entry> | |
120 | <entry>arguments appropriate for the types specified by the signature</entry> | |
121 | </row> | |
122 | ||
123 | <row> | |
124 | <entry><literal>(</literal></entry> | |
125 | <entry><constant>SD_BUS_TYPE_STRUCT_BEGIN</constant></entry> | |
126 | <entry>array start</entry> | |
127 | <entry morerows="1" namest="type1" nameend="type2">arguments appropriate for the structure elements</entry> | |
128 | </row> | |
129 | <row> | |
130 | <entry><literal>)</literal></entry> | |
131 | <entry><constant>SD_BUS_TYPE_STRUCT_END</constant></entry> | |
132 | <entry>array end</entry> | |
133 | </row> | |
134 | ||
135 | <row> | |
136 | <entry><literal>{</literal></entry> | |
137 | <entry><constant>SD_BUS_TYPE_DICT_ENTRY_BEGIN</constant></entry> | |
138 | <entry>dictionary entry start</entry> | |
139 | <entry morerows="1">arguments appropriate for the first type in the pair</entry> | |
140 | <entry morerows="1">arguments appropriate for the second type in the pair</entry> | |
141 | </row> | |
142 | <row> | |
143 | <entry><literal>}</literal></entry> | |
144 | <entry><constant>SD_BUS_TYPE_DICT_ENTRY_END</constant></entry> | |
145 | <entry>dictionary entry end</entry> | |
146 | </row> | |
147 | </tbody> | |
148 | </tgroup> | |
149 | </table> | |
150 | ||
3df22bb5 DDM |
151 | <para>If objects of the specified types are not present at the current position in the message, an error |
152 | is returned.</para> | |
50972aac ZJS |
153 | |
154 | <para>The <function>sd_bus_message_readv()</function> is equivalent to the | |
3df22bb5 DDM |
155 | <function>sd_bus_message_read()</function>, except that it is called with a <literal>va_list</literal> |
156 | instead of a variable number of arguments. This function does not call the <function>va_end()</function> | |
157 | macro. Because it invokes the <function>va_arg()</function> macro, the value of <parameter>ap</parameter> | |
158 | is undefined after the call.</para> | |
159 | ||
160 | <para><function>sd_bus_message_peek_type()</function> determines the type of the next element in | |
161 | <parameter>m</parameter> to be read by <function>sd_bus_message_read()</function> or similar functions. | |
162 | On success, the type is stored in <parameter>type</parameter>, if it is not <constant>NULL</constant>. | |
163 | If the type is a container type, the type of its elements is stored in <parameter>contents</parameter>, | |
164 | if it is not <constant>NULL</constant>. If this function successfully determines the type of the next | |
165 | element in <parameter>m</parameter>, it returns a positive integer. If there are no more elements to be | |
166 | read, it returns zero.</para> | |
50972aac ZJS |
167 | </refsect1> |
168 | ||
169 | <refsect1> | |
170 | <title>Return Value</title> | |
171 | ||
3df22bb5 DDM |
172 | <para>On success, these functions return a non-negative integer. On failure, they return a negative |
173 | errno-style error code.</para> | |
50972aac | 174 | |
a1a03fa5 | 175 | <refsect2 id='errors'> |
176 | <title>Errors</title> | |
177 | ||
178 | <para>Returned errors may indicate the following problems:</para> | |
179 | ||
180 | <variablelist> | |
181 | <xi:include href="sd_bus_message_read_basic.xml" xpointer="errors-einval"/> | |
182 | <xi:include href="sd_bus_message_read_basic.xml" xpointer="errors-enxio"/> | |
183 | <xi:include href="sd_bus_message_read_basic.xml" xpointer="errors-ebadmsg"/> | |
184 | <varlistentry> | |
185 | <term><constant>-EBUSY</constant></term> | |
186 | ||
187 | <listitem><para>When reading from a container, this error will be returned if unread elements | |
ec07c3c8 AK |
188 | are left in the container.</para> |
189 | ||
190 | <xi:include href="version-info.xml" xpointer="v251"/></listitem> | |
a1a03fa5 | 191 | </varlistentry> |
192 | </variablelist> | |
193 | </refsect2> | |
b1de39de | 194 | </refsect1> |
50972aac ZJS |
195 | |
196 | <xi:include href="libsystemd-pkgconfig.xml" /> | |
197 | ||
198 | <refsect1> | |
199 | <title>Examples</title> | |
200 | ||
201 | <para>Read a single basic type (a 64-bit integer): | |
202 | </para> | |
203 | ||
204 | <programlisting>sd_bus_message *m; | |
205 | int64_t x; | |
206 | ||
207 | sd_bus_message_read(m, "x", &x);</programlisting> | |
208 | ||
10c238b2 LP |
209 | <para>Read a boolean value:</para> |
210 | ||
211 | <programlisting>sd_bus_message *m; | |
212 | int x; /* Do not use C99 'bool' type here, it's typically smaller | |
213 | in memory and would cause memory corruption */ | |
214 | ||
215 | sd_bus_message_read(m, "b", &x);</programlisting> | |
216 | ||
50972aac ZJS |
217 | <para>Read all types of integers:</para> |
218 | ||
219 | <programlisting>uint8_t y; | |
220 | int16_t n; | |
221 | uint16_t q; | |
222 | int32_t i; | |
223 | uint32_t u; | |
224 | int32_t x; | |
225 | uint32_t t; | |
226 | double d; | |
227 | ||
228 | sd_bus_message_read(m, "ynqiuxtd", &y, &n, &q, &i, &u, &x, &t, &d);</programlisting> | |
229 | ||
230 | <para>Read a structure composed of a string and a D-Bus path:</para> | |
231 | ||
232 | <programlisting>const char *s, *p; | |
233 | ||
234 | sd_bus_message_read(m, "(so)", &s, &p); | |
235 | </programlisting> | |
236 | ||
237 | <para>Read a variant, with the real type "gt" (signature, unsigned integer): | |
238 | </para> | |
239 | ||
240 | <programlisting>const char *s; | |
241 | uint64_t *v; | |
242 | ||
243 | sd_bus_message_read(m, "v", "gt", &s, &v);</programlisting> | |
244 | ||
245 | <para>Read a dictionary containing three pairs of type {integer=>string}: | |
246 | </para> | |
247 | ||
248 | <programlisting>int i, j, k; | |
249 | const char *s, *t, *u; | |
250 | ||
251 | sd_bus_message_read(m, "a{is}", 3, &i, &s, &j, &t, &k, &u); | |
252 | </programlisting> | |
e2b40db6 LP |
253 | |
254 | <para>Read a single file descriptor, and duplicate it in order to keep it open after the message is | |
255 | freed.</para> | |
256 | ||
257 | <programlisting>sd_bus_message *m; | |
258 | int fd, fd_copy; | |
259 | ||
260 | sd_bus_message_read(m, "h", &fd); | |
261 | fd_copy = fcntl(fd, FD_DUPFD_CLOEXEC, 3);</programlisting> | |
50972aac ZJS |
262 | </refsect1> |
263 | ||
264 | <refsect1> | |
265 | <title>See Also</title> | |
266 | ||
267 | <para> | |
268 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
269 | <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
270 | <citerefentry><refentrytitle>sd_bus_message_read_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
58df2afb | 271 | <citerefentry><refentrytitle>sd_bus_message_skip</refentrytitle><manvolnum>3</manvolnum></citerefentry>, |
7cd40caa DDM |
272 | <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, |
273 | <citerefentry><refentrytitle>sd_bus_message_enter_container</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
50972aac ZJS |
274 | </para> |
275 | </refsect1> | |
276 | ||
277 | </refentry> |