man/sd_bus_message_read_array.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_array">
   7
   8   <refentryinfo>
   9     <title>sd_bus_message_read_array</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>sd_bus_message_read_array</refentrytitle>
  15     <manvolnum>3</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>sd_bus_message_read_array</refname>
  20
  21     <refpurpose>Access an array of elements in a message</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <funcsynopsis>
  26       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  27
  28       <funcprototype>
  29         <funcdef>int <function>sd_bus_message_read_array</function></funcdef>
  30         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  31         <paramdef>char <parameter>type</parameter></paramdef>
  32         <paramdef>const void **<parameter>ptr</parameter></paramdef>
  33         <paramdef>size_t *<parameter>size</parameter></paramdef>
  34       </funcprototype>
  35     </funcsynopsis>
  36   </refsynopsisdiv>
  37
  38   <refsect1>
  39     <title>Description</title>
  40
  41     <para><function>sd_bus_message_read_array()</function> gives access to an element array in
  42     message <parameter>m</parameter>. The "read pointer" in the message must be right before an
  43     array of type <parameter>type</parameter>. As a special case, <parameter>type</parameter> may be
  44     <constant>NUL</constant>, in which case any type is acceptable. A pointer to the array data is
  45     returned in the parameter <parameter>ptr</parameter> and the size of array data (in bytes) is
  46     returned in the parameter <parameter>size</parameter>. If <parameter>size</parameter> is 0, a
  47     valid non-null pointer will be returned, but it may not be dereferenced. The data is aligned as
  48     appropriate for the data type. The data is part of the message — it may not be modified and is
  49     valid only as long as the message is referenced. After this function returns, the "read pointer"
  50     points at the next element after the array.</para>
  51   </refsect1>
  52
  53   <refsect1>
  54     <title>Return Value</title>
  55
  56     <para>
  57       On success, <function>sd_bus_message_read_array()</function> returns 0 or
  58       a positive integer. On failure, it returns a negative errno-style error
  59       code.
  60     </para>
  61
  62     <refsect2>
  63       <title>Errors</title>
  64
  65       <para>Returned errors may indicate the following problems:</para>
  66
  67       <variablelist>
  68         <varlistentry>
  69           <term><constant>-EINVAL</constant></term>
  70
  71           <listitem><para>Specified type is invalid or the message parameter or one of the output
  72           parameters are <constant>NULL</constant>.</para></listitem>
  73         </varlistentry>
  74
  75         <varlistentry>
  76           <term><constant>-EOPNOTSUPP</constant></term>
  77
  78           <listitem><para>The byte order in the message is different than native byte
  79           order.</para></listitem>
  80         </varlistentry>
  81
  82         <varlistentry>
  83           <term><constant>-EPERM</constant></term>
  84
  85           <listitem><para>The message is not sealed.</para></listitem>
  86         </varlistentry>
  87
  88         <varlistentry>
  89           <term><constant>-EBADMSG</constant></term>
  90
  91           <listitem><para>The message cannot be parsed.</para></listitem>
  92         </varlistentry>
  93
  94       </variablelist>
  95     </refsect2>
  96   </refsect1>
  97
  98   <refsect1>
  99     <title>See Also</title>
 100
 101     <para>
 102       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 103       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 104       <citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 105     </para>
 106   </refsect1>
 107
 108 </refentry>