man/sd_bus_message_read_basic.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
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1-or-later
   7
   8   Copyright © 2016 Julian Orth
   9 -->
  10
  11 <refentry id="sd_bus_message_read_basic">
  12
  13   <refentryinfo>
  14     <title>sd_bus_message_read_basic</title>
  15     <productname>systemd</productname>
  16   </refentryinfo>
  17
  18   <refmeta>
  19     <refentrytitle>sd_bus_message_read_basic</refentrytitle>
  20     <manvolnum>3</manvolnum>
  21   </refmeta>
  22
  23   <refnamediv>
  24     <refname>sd_bus_message_read_basic</refname>
  25
  26     <refpurpose>Read a basic type from a message</refpurpose>
  27   </refnamediv>
  28
  29   <refsynopsisdiv>
  30     <funcsynopsis>
  31       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  32
  33       <funcprototype>
  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>
  38       </funcprototype>
  39     </funcsynopsis>
  40   </refsynopsisdiv>
  41
  42   <refsect1>
  43     <title>Description</title>
  44
  45     <para>
  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>.
  52     </para>
  53
  54     <para>
  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 message's lifetime. Similarly, during the
  62       lifetime 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
  65       caller in order to keep an open reference to it after the message object is freed (for example by
  66       calling <literal>fcntl(fd, FD_DUPFD_CLOEXEC, 3)</literal>). See the table below for a complete list of
  67       allowed types.
  68     </para>
  69
  70     <table id='format-specifiers'>
  71       <title>Item type specifiers</title>
  72
  73       <tgroup cols='4'>
  74         <colspec colname='specifier' />
  75         <colspec colname='constant' />
  76         <colspec colname='description' />
  77         <colspec colname='ctype' />
  78         <thead>
  79           <row>
  80             <entry>Specifier</entry>
  81             <entry>Constant</entry>
  82             <entry>Description</entry>
  83             <entry>Expected C Type</entry>
  84           </row>
  85         </thead>
  86         <tbody>
  87           <row>
  88             <entry><literal>y</literal></entry>
  89             <entry><constant>SD_BUS_TYPE_BYTE</constant></entry>
  90             <entry>8-bit unsigned integer</entry>
  91             <entry><type>uint8_t *</type></entry>
  92           </row>
  93
  94           <row>
  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>
  99           </row>
 100
 101           <row>
 102             <entry><literal>n</literal></entry>
 103             <entry><constant>SD_BUS_TYPE_INT16</constant></entry>
 104             <entry>16-bit signed integer</entry>
 105             <entry><type>int16_t *</type></entry>
 106           </row>
 107
 108           <row>
 109             <entry><literal>q</literal></entry>
 110             <entry><constant>SD_BUS_TYPE_UINT16</constant></entry>
 111             <entry>16-bit unsigned integer</entry>
 112             <entry><type>uint16_t *</type></entry>
 113           </row>
 114
 115           <row>
 116             <entry><literal>i</literal></entry>
 117             <entry><constant>SD_BUS_TYPE_INT32</constant></entry>
 118             <entry>32-bit signed integer</entry>
 119             <entry><type>int32_t *</type></entry>
 120           </row>
 121
 122           <row>
 123             <entry><literal>u</literal></entry>
 124             <entry><constant>SD_BUS_TYPE_UINT32</constant></entry>
 125             <entry>32-bit unsigned integer</entry>
 126             <entry><type>uint32_t *</type></entry>
 127           </row>
 128
 129           <row>
 130             <entry><literal>x</literal></entry>
 131             <entry><constant>SD_BUS_TYPE_INT64</constant></entry>
 132             <entry>64-bit signed integer</entry>
 133             <entry><type>int64_t *</type></entry>
 134           </row>
 135
 136           <row>
 137             <entry><literal>t</literal></entry>
 138             <entry><constant>SD_BUS_TYPE_UINT64</constant></entry>
 139             <entry>64-bit unsigned integer</entry>
 140             <entry><type>uint64_t *</type></entry>
 141           </row>
 142
 143           <row>
 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>
 148           </row>
 149
 150           <row>
 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>
 155           </row>
 156
 157           <row>
 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>
 162           </row>
 163
 164           <row>
 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>
 169           </row>
 170
 171           <row>
 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>
 176           </row>
 177        </tbody>
 178       </tgroup>
 179     </table>
 180
 181     <para>
 182       If there is no object of the specified type at the current position in the
 183       message, an error is returned.
 184     </para>
 185   </refsect1>
 186
 187   <refsect1>
 188     <title>Return Value</title>
 189
 190     <para>
 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.
 194     </para>
 195
 196     <refsect2 id='errors'>
 197       <title>Errors</title>
 198
 199       <para>Returned errors may indicate the following problems:</para>
 200
 201       <variablelist>
 202         <varlistentry id="errors-einval">
 203           <term><constant>-EINVAL</constant></term>
 204
 205           <listitem><para>Specified type string is invalid or the message parameter is
 206           <constant>NULL</constant>.</para></listitem>
 207         </varlistentry>
 208
 209         <varlistentry id="errors-enxio">
 210           <term><constant>-ENXIO</constant></term>
 211
 212           <listitem><para>The message does not contain the specified type at current position.
 213           </para></listitem>
 214         </varlistentry>
 215
 216         <varlistentry id="errors-ebadmsg">
 217           <term><constant>-EBADMSG</constant></term>
 218
 219           <listitem><para>The message cannot be parsed.</para></listitem>
 220         </varlistentry>
 221       </variablelist>
 222     </refsect2>
 223   </refsect1>
 224
 225   <refsect1>
 226     <title>History</title>
 227     <para><function>sd_bus_message_read_basic()</function> was added in version 231.</para>
 228   </refsect1>
 229
 230   <refsect1>
 231     <title>See Also</title>
 232
 233     <para>
 234       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 235       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 236       <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 237       <citerefentry><refentrytitle>sd_bus_message_skip</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 238       <citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 239     </para>
 240   </refsect1>
 241
 242 </refentry>