2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
8 Copyright © 2016 Julian Orth
11 <refentry id=
"sd_bus_message_read_basic">
14 <title>sd_bus_message_read_basic
</title>
15 <productname>systemd
</productname>
19 <refentrytitle>sd_bus_message_read_basic
</refentrytitle>
20 <manvolnum>3</manvolnum>
24 <refname>sd_bus_message_read_basic
</refname>
26 <refpurpose>Read a basic type from a message
</refpurpose>
31 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
34 <funcdef>int
<function>sd_bus_message_read_basic
</function></funcdef>
35 <paramdef>sd_bus_message *
<parameter>m
</parameter></paramdef>
36 <paramdef>char
<parameter>type
</parameter></paramdef>
37 <paramdef>void *
<parameter>p
</parameter></paramdef>
43 <title>Description
</title>
46 <function>sd_bus_message_read_basic()
</function> reads a basic type from a
47 message and advances the read position in the message. The set of basic
48 types and their ascii codes passed in
<parameter>type
</parameter> are
49 described in the
<ulink
50 url=
"https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus
51 Specification
</ulink>.
55 If
<parameter>p
</parameter> is not
<constant>NULL
</constant>, it should contain
56 a pointer to an appropriate object. For example, if
<parameter>type
</parameter>
57 is
<constant>'y'
</constant>, the object passed in
<parameter>p
</parameter>
58 should have type
<code>uint8_t *
</code>. If
<parameter>type
</parameter> is
59 <constant>'s'
</constant>, the object passed in
<parameter>p
</parameter> should
60 have type
<code>const char **
</code>. Note that, if the basic type is a pointer
61 (e.g.,
<code>const char *
</code> in the case of a string), the pointer is only
62 borrowed and the contents must be copied if they are to be used after the end
63 of the messages lifetime. Similarly, during the lifetime of such a pointer, the
64 message must not be modified. See the table below for a complete list of allowed
68 <table id='format-specifiers'
>
69 <title>Item type specifiers
</title>
72 <colspec colname='specifier'
/>
73 <colspec colname='constant'
/>
74 <colspec colname='description'
/>
75 <colspec colname='ctype'
/>
78 <entry>Specifier
</entry>
79 <entry>Constant
</entry>
80 <entry>Description
</entry>
81 <entry>Expected C Type
</entry>
86 <entry><literal>y
</literal></entry>
87 <entry><constant>SD_BUS_TYPE_BYTE
</constant></entry>
88 <entry>unsigned integer
</entry>
89 <entry>uint8_t *
</entry>
93 <entry><literal>b
</literal></entry>
94 <entry><constant>SD_BUS_TYPE_BOOLEAN
</constant></entry>
95 <entry>boolean
</entry>
100 <entry><literal>n
</literal></entry>
101 <entry><constant>SD_BUS_TYPE_INT16
</constant></entry>
102 <entry>signed integer
</entry>
103 <entry>int16_t *
</entry>
107 <entry><literal>q
</literal></entry>
108 <entry><constant>SD_BUS_TYPE_UINT16
</constant></entry>
109 <entry>unsigned integer
</entry>
110 <entry>uint16_t *
</entry>
114 <entry><literal>i
</literal></entry>
115 <entry><constant>SD_BUS_TYPE_INT32
</constant></entry>
116 <entry>signed integer
</entry>
117 <entry>int32_t *
</entry>
121 <entry><literal>u
</literal></entry>
122 <entry><constant>SD_BUS_TYPE_UINT32
</constant></entry>
123 <entry>unsigned integer
</entry>
124 <entry>uint32_t *
</entry>
128 <entry><literal>x
</literal></entry>
129 <entry><constant>SD_BUS_TYPE_INT64
</constant></entry>
130 <entry>signed integer
</entry>
131 <entry>int64_t *
</entry>
135 <entry><literal>t
</literal></entry>
136 <entry><constant>SD_BUS_TYPE_UINT64
</constant></entry>
137 <entry>unsigned integer
</entry>
138 <entry>uint64_t *
</entry>
142 <entry><literal>d
</literal></entry>
143 <entry><constant>SD_BUS_TYPE_DOUBLE
</constant></entry>
144 <entry>floating-point
</entry>
145 <entry>double *
</entry>
149 <entry><literal>s
</literal></entry>
150 <entry><constant>SD_BUS_TYPE_STRING
</constant></entry>
151 <entry>Unicode string
</entry>
152 <entry>const char **
</entry>
156 <entry><literal>o
</literal></entry>
157 <entry><constant>SD_BUS_TYPE_OBJECT_PATH
</constant></entry>
158 <entry>object path
</entry>
159 <entry>const char **
</entry>
163 <entry><literal>g
</literal></entry>
164 <entry><constant>SD_BUS_TYPE_SIGNATURE
</constant></entry>
165 <entry>signature
</entry>
166 <entry>const char **
</entry>
170 <entry><literal>h
</literal></entry>
171 <entry><constant>SD_BUS_TYPE_UNIX_FD
</constant></entry>
172 <entry>UNIX file descriptor
</entry>
180 If there is no object of the specified type at the current position in the
181 message, an error is returned.
186 <title>Return Value
</title>
189 On success,
<function>sd_bus_message_read_basic()
</function> returns
0 or
190 a positive integer. On failure, it returns a negative errno-style error
195 <refsect1 id='errors'
>
196 <title>Errors
</title>
198 <para>Returned errors may indicate the following problems:
</para>
202 <term><constant>-EINVAL
</constant></term>
204 <listitem><para>Specified type string is invalid or the message parameter is
205 <constant>NULL
</constant>.
</para></listitem>
209 <term><constant>-ENXIO
</constant></term>
211 <listitem><para>The message does not contain the specified type at current
212 position.
</para></listitem>
216 <term><constant>-EBADMSG
</constant></term>
218 <listitem><para>The message cannot be parsed.
</para></listitem>
224 <title>See Also
</title>
227 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
228 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
229 <citerefentry><refentrytitle>sd_bus_message_append_basic
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
230 <citerefentry><refentrytitle>sd_bus_message_skip
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
231 <citerefentry><refentrytitle>sd_bus_message_read
</refentrytitle><manvolnum>3</manvolnum></citerefentry>