3802a3d3d7af51ddff31943d5514382f01265770Lennart Poettering<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5de0ccffcc4a5a946102a14e0b0e681d964e3225Zbigniew Jędrzejewski-Szmek This file is part of systemd.
5de0ccffcc4a5a946102a14e0b0e681d964e3225Zbigniew Jędrzejewski-Szmek Copyright 2014 Zbigniew Jędrzejewski-Szmek
5de0ccffcc4a5a946102a14e0b0e681d964e3225Zbigniew Jędrzejewski-Szmek systemd is free software; you can redistribute it and/or modify it
5de0ccffcc4a5a946102a14e0b0e681d964e3225Zbigniew Jędrzejewski-Szmek under the terms of the GNU Lesser General Public License as published by
5de0ccffcc4a5a946102a14e0b0e681d964e3225Zbigniew Jędrzejewski-Szmek the Free Software Foundation; either version 2.1 of the License, or
5de0ccffcc4a5a946102a14e0b0e681d964e3225Zbigniew Jędrzejewski-Szmek (at your option) any later version.
5de0ccffcc4a5a946102a14e0b0e681d964e3225Zbigniew Jędrzejewski-Szmek systemd is distributed in the hope that it will be useful, but
5de0ccffcc4a5a946102a14e0b0e681d964e3225Zbigniew Jędrzejewski-Szmek WITHOUT ANY WARRANTY; without even the implied warranty of
5de0ccffcc4a5a946102a14e0b0e681d964e3225Zbigniew Jędrzejewski-Szmek MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
5de0ccffcc4a5a946102a14e0b0e681d964e3225Zbigniew Jędrzejewski-Szmek Lesser General Public License for more details.
5de0ccffcc4a5a946102a14e0b0e681d964e3225Zbigniew Jędrzejewski-Szmek You should have received a copy of the GNU Lesser General Public License
5de0ccffcc4a5a946102a14e0b0e681d964e3225Zbigniew Jędrzejewski-Szmek along with systemd; If not, see <http://www.gnu.org/licenses/>.
48f69d8fb4d0cf34d578352572c96d86e13caa79Lennart Poettering<refentry id="sd_bus_message_append_array"
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek xmlns:xi="http://www.w3.org/2001/XInclude">
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <title>sd_bus_message_append_array</title>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <productname>systemd</productname>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <contrib>A monkey with a typewriter</contrib>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <surname>Jędrzejewski-Szmek</surname>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <email>zbyszek@in.waw.pl</email>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <refentrytitle>sd_bus_message_append_array</refentrytitle>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <refname>sd_bus_message_append_array</refname>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <refname>sd_bus_message_append_array_memfd</refname>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <refname>sd_bus_message_append_array_iovec</refname>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <refname>sd_bus_message_append_array_space</refname>
dd2b607b7d1ce355e93f9f71cd256ec20b8ae9c4Thomas Hindoe Paaboel Andersen <refpurpose>Append an array of fields to a D-Bus
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering message</refpurpose>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <refsynopsisdiv>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <funcdef>int sd_bus_message_append_array</funcdef>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <paramdef>char <parameter>type</parameter></paramdef>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <paramdef>char void *<parameter>ptr</parameter></paramdef>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <paramdef>size_t <parameter>size</parameter></paramdef>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek </funcprototype>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <funcdef>int sd_bus_message_append_array_memfd</funcdef>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <paramdef>char <parameter>type</parameter></paramdef>
fac9c0d508f72cc5d469c969a4acc3694247c03bDaniel Mack <paramdef>int <parameter>memfd</parameter></paramdef>
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <paramdef>uint64_t <parameter>offset</parameter></paramdef>
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <paramdef>uint64_t <parameter>size</parameter></paramdef>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek </funcprototype>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <funcdef>int sd_bus_message_append_array_iovec</funcdef>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <paramdef>char <parameter>type</parameter></paramdef>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <paramdef>const struct iovec *<parameter>iov</parameter></paramdef>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <paramdef>unsigned <parameter>n</parameter></paramdef>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek </funcprototype>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <funcdef>int sd_bus_message_append_array_space</funcdef>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <paramdef>char <parameter>type</parameter></paramdef>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <paramdef>size_t <parameter>size</parameter></paramdef>
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <paramdef>void **<parameter>ptr</parameter></paramdef>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek </funcprototype>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek </refsynopsisdiv>
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <para>The <function>sd_bus_message_append_array()</function>
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering function appends an array to a D-Bus message
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <parameter>m</parameter>. A container will be opened, the array
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering contents appended, and the container closed. The parameter
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <parameter>type</parameter> determines how the pointer
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <parameter>type</parameter> must be one of the "trivial" types
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <literal>y</literal>, <literal>n</literal>, <literal>q</literal>,
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <literal>i</literal>, <literal>u</literal>, <literal>x</literal>,
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <literal>t</literal>, <literal>d</literal> (but not
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <literal>b</literal>), as defined by the <ulink
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering url="http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering Types</ulink> section of the D-Bus specification, and listed in
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
cbfaff65cb086e3eb3709cf86dcf63b46622389bKarel Zak Pointer <parameter>p</parameter> must point to an array of size
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <parameter>size</parameter> bytes containing items of the
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek respective type. Size <parameter>size</parameter> must be a
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek multiple of the size of the type <parameter>type</parameter>. As a
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek special case, <parameter>p</parameter> may be
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <constant>NULL</constant>, if <parameter>size</parameter> is 0.
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering The memory pointed to by <parameter>p</parameter> is copied into
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering the memory area containing the message and stays in possession of
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering the caller. The caller may hence freely change the data after this
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering call without affecting the message the array was appended
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <para>The <function>sd_bus_message_append_array_memfd()</function>
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering function appends an array of a trivial type to message
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <function>sd_bus_message_append_array()</function>. The contents
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering of the memory file descriptor <parameter>memfd</parameter>
dd2b607b7d1ce355e93f9f71cd256ec20b8ae9c4Thomas Hindoe Paaboel Andersen starting at the specified offset and of the specified size is
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering used as the contents of the array. The offset and size must be a
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering multiple of the size of the type
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <parameter>type</parameter>. However, as a special exception, if
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering the offset is specified as zero and the size specified as
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering UINT64_MAX the full memory file descriptor contents is used. The
7ca4155737730ece73ae4b4ac80571005cb99b69Jan Engelhardt memory file descriptor is sealed by this call if it has not been
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt sealed yet, and cannot be modified after this call. See
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering project='man-pages'><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering for details about memory file descriptors. Appending arrays with
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering memory file descriptors enables efficient zero-copy data transfer,
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering as the memory file descriptor may be passed as-is to the
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering destination, without copying the memory in it to the destination
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering process. Not all protocol transports support passing memory file
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering descriptors between participants, in which case this call will
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering automatically fall back to copying. Also, as memory file
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt descriptor passing is inefficient for smaller amounts of data,
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering copying might still be enforced even where memory file descriptor
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering passing is supported.</para>
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <para>The <function>sd_bus_message_append_array_iovec()</function>
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering function appends an array of a trivial type to the message
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <function>sd_bus_message_append_array()</function>. Contents of
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt the I/O vector array <parameter>iov</parameter> are used as the
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering contents of the array. The total size of
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <parameter>iov</parameter> payload (the sum of
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <structfield>iov_len</structfield> fields) must be a multiple of
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering the size of the type <parameter>type</parameter>. The
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <parameter>iov</parameter> argument must point to
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <parameter>n</parameter> I/O vector structures. Each structure may
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering have the <structname>iov_base</structname> field set, in which
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering case the memory pointed to will be copied into the message, or
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering unset (set to zero), in which case a block of zeros of length
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <structname>iov_len</structname> bytes will be inserted. The
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek memory pointed at by <parameter>iov</parameter> may be changed
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek after this call.</para>
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <para>The <function>sd_bus_message_append_array_space()</function>
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering function appends space for an array of a trivial type to message
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <parameter>m</parameter>. It behaves the same as
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <function>sd_bus_message_append_array()</function>, but instead of
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering copying items to the message, it returns a pointer to the
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering destination area to the caller in pointer
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <parameter>p</parameter>. The caller should subsequently write the
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt array contents to this memory. Modifications to the memory
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering pointed to should only occur until the next operation on the bus
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt message is invoked. Most importantly, the memory should not be
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering altered anymore when another field has been added to the message
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering or the message has been sealed.</para>
b8bde11658366290521e3d03316378b482600323Jan Engelhardt <para>On success, these calls return 0 or a positive integer. On
dd2b607b7d1ce355e93f9f71cd256ec20b8ae9c4Thomas Hindoe Paaboel Andersen failure, they return a negative errno-style error code.</para>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" />
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <para><function>sd_bus_append_array()</function> and other
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek functions described here are available as a shared library, which
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek can be compiled and linked to with the
5aded369782f28255bc6b494ca905d7acaea7a56Zbigniew Jędrzejewski-Szmek <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
e8216945a97bc2a2b04bc286e67ab5bba313b83eLennart Poettering <citerefentry project='man-pages'><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22Zbigniew Jędrzejewski-Szmek <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink>