man/sd_bus_message_read_strv.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-or-later -->
   5
   6 <refentry id="sd_bus_message_read_strv" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>sd_bus_message_read_strv</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>sd_bus_message_read_strv</refentrytitle>
  15     <manvolnum>3</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>sd_bus_message_read_strv</refname>
  20     <refname>sd_bus_message_read_strv_extend</refname>
  21
  22     <refpurpose>Access an array of strings in a message</refpurpose>
  23   </refnamediv>
  24
  25   <refsynopsisdiv>
  26     <funcsynopsis>
  27       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  28
  29       <funcprototype>
  30         <funcdef>int <function>sd_bus_message_read_strv</function></funcdef>
  31         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  32         <paramdef>char ***<parameter>l</parameter></paramdef>
  33       </funcprototype>
  34
  35       <funcprototype>
  36         <funcdef>int <function>sd_bus_message_read_strv_extend</function></funcdef>
  37         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  38         <paramdef>char ***<parameter>l</parameter></paramdef>
  39       </funcprototype>
  40     </funcsynopsis>
  41   </refsynopsisdiv>
  42
  43   <refsect1>
  44     <title>Description</title>
  45
  46     <para><function>sd_bus_message_read_strv()</function> reads an array of string-like items from the
  47     message <parameter>m</parameter>. The "read pointer" in the message must be right before an array of
  48     strings (D-Bus type <literal>as</literal>), object paths (D-Bus type <literal>ao</literal>), or
  49     signatures (D-Bus type <literal>ag</literal>). On success, a pointer to a
  50     <constant>NULL</constant>-terminated array of strings (strv) is returned in the output parameter
  51     <parameter>l</parameter>. Note that ownership of this array is transferred to the caller. Hence, the
  52     caller is responsible for freeing this array and its contents.</para>
  53
  54     <para><function>sd_bus_message_read_strv_extend()</function> is similar, but the second parameter is an
  55     input-output parameter. If <parameter>*l</parameter> is <constant>NULL</constant>, if behaves identically
  56     to <function>sd_bus_message_read_strv()</function>. Otherwise, <parameter>*l</parameter> must point to a
  57     strv, which will be reallocated and extended with additional strings. This function is particularly
  58     useful when combining multiple lists of strings in a message or messages into a single array of strings.
  59     </para>
  60   </refsect1>
  61
  62   <refsect1>
  63     <title>Return Value</title>
  64
  65     <para>On success, these functions return a non-negative integer. On failure, they return a negative
  66     errno-style error code.</para>
  67
  68     <refsect2>
  69       <title>Errors</title>
  70
  71       <para>Returned errors may indicate the following problems:</para>
  72
  73       <variablelist>
  74         <varlistentry>
  75           <term><constant>-EINVAL</constant></term>
  76
  77           <listitem><para><parameter>m</parameter> or <parameter>l</parameter> are <constant>NULL</constant>.
  78           </para>
  79
  80           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
  81         </varlistentry>
  82
  83         <varlistentry>
  84           <term><constant>-EPERM</constant></term>
  85
  86           <listitem><para>The message is not sealed.</para>
  87
  88           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
  89         </varlistentry>
  90
  91         <varlistentry>
  92           <term><constant>-EBADMSG</constant></term>
  93
  94           <listitem><para>The message cannot be parsed.</para>
  95
  96           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
  97         </varlistentry>
  98
  99         <varlistentry>
 100           <term><constant>-ENXIO</constant></term>
 101
 102           <listitem><para>The message "read pointer" is not right before an array of the appropriate type.
 103           </para>
 104
 105           <xi:include href="version-info.xml" xpointer="v248"/></listitem>
 106         </varlistentry>
 107       </variablelist>
 108     </refsect2>
 109   </refsect1>
 110
 111   <refsect1>
 112     <title>History</title>
 113     <para><function>sd_bus_message_read_strv()</function> was added in version 246.</para>
 114     <para><function>sd_bus_message_read_strv_extend()</function> was added in version 252.</para>
 115   </refsect1>
 116
 117   <refsect1>
 118     <title>See Also</title>
 119
 120     <para>
 121       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 122       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 123       <citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 124     </para>
 125   </refsect1>
 126
 127 </refentry>