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   SPDX-License-Identifier: LGPL-2.1+
   7
   8   Copyright © 2014 Zbigniew Jędrzejewski-Szmek
   9 -->
  10
  11 <refentry id="sd_bus_message_append_array"
  12           xmlns:xi="http://www.w3.org/2001/XInclude">
  13
  14   <refentryinfo>
  15     <title>sd_bus_message_append_array</title>
  16     <productname>systemd</productname>
  17   </refentryinfo>
  18
  19   <refmeta>
  20     <refentrytitle>sd_bus_message_append_array</refentrytitle>
  21     <manvolnum>3</manvolnum>
  22   </refmeta>
  23
  24   <refnamediv>
  25     <refname>sd_bus_message_append_array</refname>
  26     <refname>sd_bus_message_append_array_memfd</refname>
  27     <refname>sd_bus_message_append_array_iovec</refname>
  28     <refname>sd_bus_message_append_array_space</refname>
  29
  30     <refpurpose>Append an array of fields to a D-Bus
  31     message</refpurpose>
  32   </refnamediv>
  33
  34   <refsynopsisdiv>
  35     <funcsynopsis>
  36       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  37
  38       <funcprototype>
  39         <funcdef>int sd_bus_message_append_array</funcdef>
  40         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  41         <paramdef>char <parameter>type</parameter></paramdef>
  42         <paramdef>char void *<parameter>ptr</parameter></paramdef>
  43         <paramdef>size_t <parameter>size</parameter></paramdef>
  44       </funcprototype>
  45
  46       <funcprototype>
  47         <funcdef>int sd_bus_message_append_array_memfd</funcdef>
  48         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  49         <paramdef>char <parameter>type</parameter></paramdef>
  50         <paramdef>int <parameter>memfd</parameter></paramdef>
  51         <paramdef>uint64_t <parameter>offset</parameter></paramdef>
  52         <paramdef>uint64_t <parameter>size</parameter></paramdef>
  53       </funcprototype>
  54
  55       <funcprototype>
  56         <funcdef>int sd_bus_message_append_array_iovec</funcdef>
  57         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  58         <paramdef>char <parameter>type</parameter></paramdef>
  59         <paramdef>const struct iovec *<parameter>iov</parameter></paramdef>
  60         <paramdef>unsigned <parameter>n</parameter></paramdef>
  61       </funcprototype>
  62
  63       <funcprototype>
  64         <funcdef>int sd_bus_message_append_array_space</funcdef>
  65         <paramdef>char <parameter>type</parameter></paramdef>
  66         <paramdef>size_t <parameter>size</parameter></paramdef>
  67         <paramdef>void **<parameter>ptr</parameter></paramdef>
  68       </funcprototype>
  69     </funcsynopsis>
  70   </refsynopsisdiv>
  71
  72   <refsect1>
  73     <title>Description</title>
  74
  75     <para>The <function>sd_bus_message_append_array()</function>
  76     function appends an array to a D-Bus message
  77     <parameter>m</parameter>. A container will be opened, the array
  78     contents appended, and the container closed. The parameter
  79     <parameter>type</parameter> determines how the pointer
  80     <parameter>p</parameter> is interpreted.
  81     <parameter>type</parameter> must be one of the "trivial" types
  82     <literal>y</literal>, <literal>n</literal>, <literal>q</literal>,
  83     <literal>i</literal>, <literal>u</literal>, <literal>x</literal>,
  84     <literal>t</literal>, <literal>d</literal> (but not
  85     <literal>b</literal>), as defined by the <ulink
  86     url="http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic
  87     Types</ulink> section of the D-Bus specification, and listed in
  88     <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  89     Pointer <parameter>p</parameter> must point to an array of size
  90     <parameter>size</parameter> bytes containing items of the
  91     respective type. Size <parameter>size</parameter> must be a
  92     multiple of the size of the type <parameter>type</parameter>. As a
  93     special case, <parameter>p</parameter> may be
  94     <constant>NULL</constant>, if <parameter>size</parameter> is 0.
  95     The memory pointed to by <parameter>p</parameter> is copied into
  96     the memory area containing the message and stays in possession of
  97     the caller. The caller may hence freely change the data after this
  98     call without affecting the message the array was appended
  99     to.</para>
 100
 101     <para>The <function>sd_bus_message_append_array_memfd()</function>
 102     function appends an array of a trivial type to message
 103     <parameter>m</parameter>, similar to
 104     <function>sd_bus_message_append_array()</function>. The contents
 105     of the memory file descriptor <parameter>memfd</parameter>
 106     starting at the specified offset and of the specified size is
 107     used as the contents of the array. The offset and size must be a
 108     multiple of the size of the type
 109     <parameter>type</parameter>. However, as a special exception, if
 110     the offset is specified as zero and the size specified as
 111     UINT64_MAX the full memory file descriptor contents is used. The
 112     memory file descriptor is sealed by this call if it has not been
 113     sealed yet, and cannot be modified after this call. See
 114     <citerefentry
 115     project='man-pages'><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 116     for details about memory file descriptors. Appending arrays with
 117     memory file descriptors enables efficient zero-copy data transfer,
 118     as the memory file descriptor may be passed as-is to the
 119     destination, without copying the memory in it to the destination
 120     process. Not all protocol transports support passing memory file
 121     descriptors between participants, in which case this call will
 122     automatically fall back to copying. Also, as memory file
 123     descriptor passing is inefficient for smaller amounts of data,
 124     copying might still be enforced even where memory file descriptor
 125     passing is supported.</para>
 126
 127     <para>The <function>sd_bus_message_append_array_iovec()</function>
 128     function appends an array of a trivial type to the message
 129     <parameter>m</parameter>, similar to
 130     <function>sd_bus_message_append_array()</function>. Contents of
 131     the I/O vector array <parameter>iov</parameter> are used as the
 132     contents of the array. The total size of
 133     <parameter>iov</parameter> payload (the sum of
 134     <structfield>iov_len</structfield> fields) must be a multiple of
 135     the size of the type <parameter>type</parameter>. The
 136     <parameter>iov</parameter> argument must point to
 137     <parameter>n</parameter> I/O vector structures. Each structure may
 138     have the <structname>iov_base</structname> field set, in which
 139     case the memory pointed to will be copied into the message, or
 140     unset (set to zero), in which case a block of zeros of length
 141     <structname>iov_len</structname> bytes will be inserted. The
 142     memory pointed at by <parameter>iov</parameter> may be changed
 143     after this call.</para>
 144
 145     <para>The <function>sd_bus_message_append_array_space()</function>
 146     function appends space for an array of a trivial type to message
 147     <parameter>m</parameter>.  It behaves the same as
 148     <function>sd_bus_message_append_array()</function>, but instead of
 149     copying items to the message, it returns a pointer to the
 150     destination area to the caller in pointer
 151     <parameter>p</parameter>. The caller should subsequently write the
 152     array contents to this memory. Modifications to the memory
 153     pointed to should only occur until the next operation on the bus
 154     message is invoked. Most importantly, the memory should not be
 155     altered anymore when another field has been added to the message
 156     or the message has been sealed.</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 return a negative errno-style error code.</para>
 164   </refsect1>
 165
 166   <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" />
 167
 168   <xi:include href="libsystemd-pkgconfig.xml" />
 169
 170   <refsect1>
 171     <title>See Also</title>
 172
 173     <para>
 174       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 175       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 176       <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 177       <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 178       <citerefentry project='man-pages'><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 179       <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink>
 180     </para>
 181   </refsect1>
 182
 183 </refentry>