man/sd_bus_message_append_array.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2014 Zbigniew Jędrzejewski-Szmek
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="sd_bus_message_append_array"
  25           xmlns:xi="http://www.w3.org/2001/XInclude">
  26
  27   <refentryinfo>
  28     <title>sd_bus_message_append_array</title>
  29     <productname>systemd</productname>
  30
  31     <authorgroup>
  32       <author>
  33         <contrib>A monkey with a typewriter</contrib>
  34         <firstname>Zbigniew</firstname>
  35         <surname>Jędrzejewski-Szmek</surname>
  36         <email>zbyszek@in.waw.pl</email>
  37       </author>
  38     </authorgroup>
  39   </refentryinfo>
  40
  41   <refmeta>
  42     <refentrytitle>sd_bus_message_append_array</refentrytitle>
  43     <manvolnum>3</manvolnum>
  44   </refmeta>
  45
  46   <refnamediv>
  47     <refname>sd_bus_message_append_array</refname>
  48     <refname>sd_bus_message_append_array_memfd</refname>
  49     <refname>sd_bus_message_append_array_iovec</refname>
  50     <refname>sd_bus_message_append_array_space</refname>
  51
  52     <refpurpose>Attach an array of items to a message</refpurpose>
  53   </refnamediv>
  54
  55   <refsynopsisdiv>
  56     <funcsynopsis>
  57       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  58
  59       <funcprototype>
  60         <funcdef>int sd_bus_message_append_array</funcdef>
  61         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  62         <paramdef>char <parameter>type</parameter></paramdef>
  63         <paramdef>char void *<parameter>ptr</parameter></paramdef>
  64         <paramdef>size_t <parameter>size</parameter></paramdef>
  65       </funcprototype>
  66
  67       <funcprototype>
  68         <funcdef>int sd_bus_message_append_array_memfd</funcdef>
  69         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  70         <paramdef>char <parameter>type</parameter></paramdef>
  71         <paramdef>int <parameter>memfd</parameter></paramdef>
  72       </funcprototype>
  73
  74       <funcprototype>
  75         <funcdef>int sd_bus_message_append_array_iovec</funcdef>
  76         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  77         <paramdef>char <parameter>type</parameter></paramdef>
  78         <paramdef>const struct iovec *<parameter>iov</parameter></paramdef>
  79         <paramdef>unsigned <parameter>n</parameter></paramdef>
  80       </funcprototype>
  81
  82       <funcprototype>
  83         <funcdef>int sd_bus_message_append_array_space</funcdef>
  84         <paramdef>char <parameter>type</parameter></paramdef>
  85         <paramdef>size_t <parameter>size</parameter></paramdef>
  86         <paramdef>char void **<parameter>ptr</parameter></paramdef>
  87       </funcprototype>
  88     </funcsynopsis>
  89   </refsynopsisdiv>
  90
  91   <refsect1>
  92     <title>Description</title>
  93
  94     <para>The <function>sd_bus_message_append_array</function> functionc
  95     appends items to message <parameter>m</parameter> as the single
  96     array. A container will be opened, items appended, and the
  97     container closed. Parameter <parameter>type</parameter> determines
  98     how pointer <parameter>p</parameter> is interpreted.
  99     <parameter>type</parameter> must be one of the "trivial" types
 100     <literal>y</literal>, <literal>n</literal>, <literal>q</literal>,
 101     <literal>i</literal>, <literal>u</literal>, <literal>x</literal>,
 102     <literal>t</literal>, <literal>d</literal> (but not
 103     <literal>b</literal>), as defined by the
 104     <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic Types</ulink>
 105     section of the D-Bus specification, and listed in
 106     <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 107     Pointer <parameter>p</parameter> must point to an array of size
 108     <parameter>size</parameter> bytes containing items of the
 109     respective type. Size <parameter>size</parameter> must be a
 110     multiple of the size of the type <parameter>type</parameter>. As a
 111     special case, <parameter>p</parameter> may be
 112     <constant>NULL</constant>, if <parameter>size</parameter> is 0.
 113     </para>
 114
 115     <para>The memory pointed at by <parameter>p</parameter> is copied
 116     into the memory area containing the message and may be changed
 117     after this call.</para>
 118
 119     <para>The
 120     <function>sd_bus_message_append_array_memfd</function> function appends
 121     items to message <parameter>m</parameter>, similarly to
 122     <function>sd_bus_message_append_array</function>. Contents of the
 123     memory file descriptor <parameter>memfd</parameter> are used as
 124     the contents of the array. Their size must be a multiple of the
 125     size of the type <parameter>type</parameter>.</para>
 126
 127     <para>The descriptor specified with <parameter>memfd</parameter>
 128     will be sealed and cannot be modified after this call.</para>
 129
 130     <para>The
 131     <function>sd_bus_message_append_array_iovec</function> function appends
 132     items to message <parameter>m</parameter>, similarly to
 133     <function>sd_bus_message_append_array</function>. Contents of the
 134     iovec <parameter>iov</parameter> are used as the contents of the
 135     array. The total size of <parameter>iov</parameter> payload (the
 136     sum of <structfield>iov_len</structfield> fields) must be a multiple
 137     of the size of the type <parameter>type</parameter>.</para>
 138
 139     <para>The <parameter>iov</parameter> argument must point to
 140     <parameter>n</parameter> <structname>struct iovec</structname>
 141     structures. Each structure may have the
 142     <structname>iov_base</structname> field set, in which case the
 143     memory pointed to will be copied into the message, or unset, in
 144     which case a block of zeros of length
 145     <structname>iov_len</structname> bytes will be inserted. The
 146     memory pointed at by <parameter>iov</parameter> may be changed
 147     after this call.</para>
 148
 149     <para>The
 150     <function>sd_bus_message_append_array_space</function> function appends
 151     space for an array of items to message <parameter>m</parameter>.
 152     It behaves the same as
 153     <function>sd_bus_message_append_array</function>, but instead
 154     of copying items to the message, it returns a pointer to the
 155     destination area to the caller in pointer <parameter>p</parameter>.
 156     </para>
 157   </refsect1>
 158
 159   <refsect1>
 160     <title>Return Value</title>
 161
 162     <para>On success, these calls return 0 or a positive integer. On
 163     failure, they returns a negative errno-style error code.</para>
 164   </refsect1>
 165
 166   <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" />
 167
 168   <refsect1>
 169     <title>Notes</title>
 170
 171     <para><function>sd_bus_append_array()</function> and other
 172     functions described here are available as a shared library, which
 173     can be compiled and linked to with the
 174     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 175     file.</para>
 176   </refsect1>
 177
 178   <refsect1>
 179     <title>See Also</title>
 180
 181     <para>
 182       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 183       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 184       <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 185       <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 186       <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink>
 187     </para>
 188   </refsect1>
 189
 190 </refentry>