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+ -->
   5
   6 <refentry id="sd_bus_message_read_strv">
   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
  21     <refpurpose>Access an array of strings 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_strv</function></funcdef>
  30         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  31         <paramdef>char ***<parameter>l</parameter></paramdef>
  32       </funcprototype>
  33     </funcsynopsis>
  34   </refsynopsisdiv>
  35
  36   <refsect1>
  37     <title>Description</title>
  38
  39     <para><function>sd_bus_message_read_strv()</function> gives access to an array of strings in message
  40     <parameter>m</parameter>. The "read pointer" in the message must be right before an array of strings. On
  41     success, a pointer to the <constant>NULL</constant>-terminated array of strings is returned in the output
  42     parameter <parameter>l</parameter>. Note that ownership of this array is transferred to the caller.
  43     Hence, the caller is responsible for freeing this array and its contents.</para>
  44   </refsect1>
  45
  46   <refsect1>
  47     <title>Return Value</title>
  48
  49     <para>On success, <function>sd_bus_message_read_strv()</function> returns a non-negative integer. On
  50     failure, it returns a negative errno-style error code.</para>
  51
  52     <refsect2>
  53       <title>Errors</title>
  54
  55       <para>Returned errors may indicate the following problems:</para>
  56
  57       <variablelist>
  58         <varlistentry>
  59           <term><constant>-EINVAL</constant></term>
  60
  61           <listitem><para><parameter>m</parameter> or <parameter>l</parameter> are <constant>NULL</constant>.
  62           </para></listitem>
  63         </varlistentry>
  64
  65         <varlistentry>
  66           <term><constant>-EPERM</constant></term>
  67
  68           <listitem><para>The message is not sealed.</para></listitem>
  69         </varlistentry>
  70
  71         <varlistentry>
  72           <term><constant>-EBADMSG</constant></term>
  73
  74           <listitem><para>The message cannot be parsed.</para></listitem>
  75         </varlistentry>
  76       </variablelist>
  77     </refsect2>
  78   </refsect1>
  79
  80   <refsect1>
  81     <title>See Also</title>
  82
  83     <para>
  84       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  85       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  86       <citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  87     </para>
  88   </refsect1>
  89
  90 </refentry>