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>Append an array of fields to a D-Bus
  53     message</refpurpose>
  54   </refnamediv>
  55
  56   <refsynopsisdiv>
  57     <funcsynopsis>
  58       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  59
  60       <funcprototype>
  61         <funcdef>int sd_bus_message_append_array</funcdef>
  62         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  63         <paramdef>char <parameter>type</parameter></paramdef>
  64         <paramdef>char void *<parameter>ptr</parameter></paramdef>
  65         <paramdef>size_t <parameter>size</parameter></paramdef>
  66       </funcprototype>
  67
  68       <funcprototype>
  69         <funcdef>int sd_bus_message_append_array_memfd</funcdef>
  70         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  71         <paramdef>char <parameter>type</parameter></paramdef>
  72         <paramdef>int <parameter>memfd</parameter></paramdef>
  73         <paramdef>uint64_t <parameter>offset</parameter></paramdef>
  74         <paramdef>uint64_t <parameter>size</parameter></paramdef>
  75       </funcprototype>
  76
  77       <funcprototype>
  78         <funcdef>int sd_bus_message_append_array_iovec</funcdef>
  79         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  80         <paramdef>char <parameter>type</parameter></paramdef>
  81         <paramdef>const struct iovec *<parameter>iov</parameter></paramdef>
  82         <paramdef>unsigned <parameter>n</parameter></paramdef>
  83       </funcprototype>
  84
  85       <funcprototype>
  86         <funcdef>int sd_bus_message_append_array_space</funcdef>
  87         <paramdef>char <parameter>type</parameter></paramdef>
  88         <paramdef>size_t <parameter>size</parameter></paramdef>
  89         <paramdef>void **<parameter>ptr</parameter></paramdef>
  90       </funcprototype>
  91     </funcsynopsis>
  92   </refsynopsisdiv>
  93
  94   <refsect1>
  95     <title>Description</title>
  96
  97     <para>The <function>sd_bus_message_append_array()</function>
  98     function appends an array to a D-Bus message
  99     <parameter>m</parameter>. A container will be opened, the array
 100     contents appended, and the container closed. The parameter
 101     <parameter>type</parameter> determines how the pointer
 102     <parameter>p</parameter> is interpreted.
 103     <parameter>type</parameter> must be one of the "trivial" types
 104     <literal>y</literal>, <literal>n</literal>, <literal>q</literal>,
 105     <literal>i</literal>, <literal>u</literal>, <literal>x</literal>,
 106     <literal>t</literal>, <literal>d</literal> (but not
 107     <literal>b</literal>), as defined by the <ulink
 108     url="http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic
 109     Types</ulink> section of the D-Bus specification, and listed in
 110     <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 111     Pointer <parameter>p</parameter> must point to an array of size
 112     <parameter>size</parameter> bytes containing items of the
 113     respective type. Size <parameter>size</parameter> must be a
 114     multiple of the size of the type <parameter>type</parameter>. As a
 115     special case, <parameter>p</parameter> may be
 116     <constant>NULL</constant>, if <parameter>size</parameter> is 0.
 117     The memory pointed to by <parameter>p</parameter> is copied into
 118     the memory area containing the message and stays in possession of
 119     the caller. The caller may hence freely change the data after this
 120     call without affecting the message the array was appended
 121     to.</para>
 122
 123     <para>The <function>sd_bus_message_append_array_memfd()</function>
 124     function appends an array of a trivial type to message
 125     <parameter>m</parameter>, similar to
 126     <function>sd_bus_message_append_array()</function>. The contents
 127     of the memory file descriptor <parameter>memfd</parameter>
 128     starting at the specified offset and of the specified size is
 129     used as the contents of the array. The offset and size must be a
 130     multiple of the size of the type
 131     <parameter>type</parameter>. However, as a special exception, if
 132     the offset is specified as zero and the size specified as
 133     UINT64_MAX the full memory file descriptor contents is used. The
 134     memory file descriptor is sealed by this call if it has not been
 135     sealed yet, and cannot be modified after this call. See
 136     <citerefentry
 137     project='man-pages'><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 138     for details about memory file descriptors. Appending arrays with
 139     memory file descriptors enables efficient zero-copy data transfer,
 140     as the memory file descriptor may be passed as-is to the
 141     destination, without copying the memory in it to the destination
 142     process. Not all protocol transports support passing memory file
 143     descriptors between participants, in which case this call will
 144     automatically fall back to copying. Also, as memory file
 145     descriptor passing is inefficient for smaller amounts of data,
 146     copying might still be enforced even where memory file descriptor
 147     passing is supported.</para>
 148
 149     <para>The <function>sd_bus_message_append_array_iovec()</function>
 150     function appends an array of a trivial type to the message
 151     <parameter>m</parameter>, similar to
 152     <function>sd_bus_message_append_array()</function>. Contents of
 153     the I/O vector array <parameter>iov</parameter> are used as the
 154     contents of the array. The total size of
 155     <parameter>iov</parameter> payload (the sum of
 156     <structfield>iov_len</structfield> fields) must be a multiple of
 157     the size of the type <parameter>type</parameter>. The
 158     <parameter>iov</parameter> argument must point to
 159     <parameter>n</parameter> I/O vector structures. Each structure may
 160     have the <structname>iov_base</structname> field set, in which
 161     case the memory pointed to will be copied into the message, or
 162     unset (set to zero), in which case a block of zeros of length
 163     <structname>iov_len</structname> bytes will be inserted. The
 164     memory pointed at by <parameter>iov</parameter> may be changed
 165     after this call.</para>
 166
 167     <para>The <function>sd_bus_message_append_array_space()</function>
 168     function appends space for an array of a trivial type to message
 169     <parameter>m</parameter>.  It behaves the same as
 170     <function>sd_bus_message_append_array()</function>, but instead of
 171     copying items to the message, it returns a pointer to the
 172     destination area to the caller in pointer
 173     <parameter>p</parameter>. The caller should subsequently write the
 174     array contents to this memory. Modifications to the memory
 175     pointed to should only occur until the next operation on the bus
 176     message is invoked. Most importantly, the memory should not be
 177     altered anymore when another field has been added to the message
 178     or the message has been sealed.</para>
 179   </refsect1>
 180
 181   <refsect1>
 182     <title>Return Value</title>
 183
 184     <para>On success, these calls return 0 or a positive integer. On
 185     failure, they return a negative errno-style error code.</para>
 186   </refsect1>
 187
 188   <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" />
 189
 190   <refsect1>
 191     <title>Notes</title>
 192
 193     <para><function>sd_bus_append_array()</function> and other
 194     functions described here are available as a shared library, which
 195     can be compiled and linked to with the
 196     <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 197     file.</para>
 198   </refsect1>
 199
 200   <refsect1>
 201     <title>See Also</title>
 202
 203     <para>
 204       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 205       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 206       <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 207       <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 208       <citerefentry project='man-pages'><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 209       <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink>
 210     </para>
 211   </refsect1>
 212
 213 </refentry>