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-or-later
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 a pointer to an
56 appropriate object. For example, if
<parameter>type
</parameter> is
<constant>'y'
</constant>, the object
57 passed in
<parameter>p
</parameter> should have type
<type>uint8_t *
</type>. If
58 <parameter>type
</parameter> is
<constant>'s'
</constant>, the object passed in
<parameter>p
</parameter>
59 should have type
<type>const char **
</type>. Note that, if the basic type is a pointer (e.g.,
60 <type>const char *
</type> in the case of a string), the pointer is only borrowed and the contents must
61 be copied if they are to be used after the end of the messages lifetime. Similarly, during the lifetime
62 of such a pointer, the message must not be modified. If
<parameter>type
</parameter> is
63 <constant>'h'
</constant> (UNIX file descriptor), the descriptor is not duplicated by this call and the
64 returned descriptor remains in possession of the message object, and needs to be duplicated by the caller
65 in order to keep an open reference to it after the message object is freed (for example by calling
66 <literal>fcntl(fd, FD_DUPFD_CLOEXEC,
3)
</literal>). See the table below for a complete list of
70 <table id='format-specifiers'
>
71 <title>Item type specifiers
</title>
74 <colspec colname='specifier'
/>
75 <colspec colname='constant'
/>
76 <colspec colname='description'
/>
77 <colspec colname='ctype'
/>
80 <entry>Specifier
</entry>
81 <entry>Constant
</entry>
82 <entry>Description
</entry>
83 <entry>Expected C Type
</entry>
88 <entry><literal>y
</literal></entry>
89 <entry><constant>SD_BUS_TYPE_BYTE
</constant></entry>
90 <entry>8bit unsigned integer
</entry>
91 <entry><type>uint8_t *
</type></entry>
95 <entry><literal>b
</literal></entry>
96 <entry><constant>SD_BUS_TYPE_BOOLEAN
</constant></entry>
97 <entry>boolean
</entry>
98 <entry><type>int *
</type> (NB: not
<type>bool *
</type>)
</entry>
102 <entry><literal>n
</literal></entry>
103 <entry><constant>SD_BUS_TYPE_INT16
</constant></entry>
104 <entry>16bit signed integer
</entry>
105 <entry><type>int16_t *
</type></entry>
109 <entry><literal>q
</literal></entry>
110 <entry><constant>SD_BUS_TYPE_UINT16
</constant></entry>
111 <entry>16bit unsigned integer
</entry>
112 <entry><type>uint16_t *
</type></entry>
116 <entry><literal>i
</literal></entry>
117 <entry><constant>SD_BUS_TYPE_INT32
</constant></entry>
118 <entry>32bit signed integer
</entry>
119 <entry><type>int32_t *
</type></entry>
123 <entry><literal>u
</literal></entry>
124 <entry><constant>SD_BUS_TYPE_UINT32
</constant></entry>
125 <entry>32bit unsigned integer
</entry>
126 <entry><type>uint32_t *
</type></entry>
130 <entry><literal>x
</literal></entry>
131 <entry><constant>SD_BUS_TYPE_INT64
</constant></entry>
132 <entry>64bit signed integer
</entry>
133 <entry><type>int64_t *
</type></entry>
137 <entry><literal>t
</literal></entry>
138 <entry><constant>SD_BUS_TYPE_UINT64
</constant></entry>
139 <entry>64bit unsigned integer
</entry>
140 <entry><type>uint64_t *
</type></entry>
144 <entry><literal>d
</literal></entry>
145 <entry><constant>SD_BUS_TYPE_DOUBLE
</constant></entry>
146 <entry>IEEE
754 double precision floating-point
</entry>
147 <entry><type>double *
</type></entry>
151 <entry><literal>s
</literal></entry>
152 <entry><constant>SD_BUS_TYPE_STRING
</constant></entry>
153 <entry>UTF-
8 string
</entry>
154 <entry><type>const char **
</type></entry>
158 <entry><literal>o
</literal></entry>
159 <entry><constant>SD_BUS_TYPE_OBJECT_PATH
</constant></entry>
160 <entry>D-Bus object path string
</entry>
161 <entry><type>const char **
</type></entry>
165 <entry><literal>g
</literal></entry>
166 <entry><constant>SD_BUS_TYPE_SIGNATURE
</constant></entry>
167 <entry>D-Bus signature string
</entry>
168 <entry><type>const char **
</type></entry>
172 <entry><literal>h
</literal></entry>
173 <entry><constant>SD_BUS_TYPE_UNIX_FD
</constant></entry>
174 <entry>UNIX file descriptor
</entry>
175 <entry><type>int *
</type></entry>
182 If there is no object of the specified type at the current position in the
183 message, an error is returned.
188 <title>Return Value
</title>
191 On success,
<function>sd_bus_message_read_basic()
</function> returns a positive integer.
192 If the end of the currently opened array has been reached, it returns
0.
193 On failure, it returns a negative errno-style error code.
196 <refsect2 id='errors'
>
197 <title>Errors
</title>
199 <para>Returned errors may indicate the following problems:
</para>
203 <term><constant>-EINVAL
</constant></term>
205 <listitem><para>Specified type string is invalid or the message parameter is
206 <constant>NULL
</constant>.
</para></listitem>
210 <term><constant>-ENXIO
</constant></term>
212 <listitem><para>The message does not contain the specified type at current position.
217 <term><constant>-EBADMSG
</constant></term>
219 <listitem><para>The message cannot be parsed.
</para></listitem>
226 <title>See Also
</title>
229 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
230 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
231 <citerefentry><refentrytitle>sd_bus_message_append_basic
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
232 <citerefentry><refentrytitle>sd_bus_message_skip
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
233 <citerefentry><refentrytitle>sd_bus_message_read
</refentrytitle><manvolnum>3</manvolnum></citerefentry>