man/sd_bus_message_read.xml

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