man/sd_bus_message_append_string_memfd.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   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_string_memfd" conditional="ENABLE_KDBUS"
  25           xmlns:xi="http://www.w3.org/2001/XInclude">
  26
  27   <refentryinfo>
  28     <title>sd_bus_message_append_string_memfd</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_string_memfd</refentrytitle>
  43     <manvolnum>3</manvolnum>
  44   </refmeta>
  45
  46   <refnamediv>
  47     <refname>sd_bus_message_append_string_memfd</refname>
  48     <refname>sd_bus_message_append_string_iovec</refname>
  49     <refname>sd_bus_message_append_string_space</refname>
  50
  51     <refpurpose>Attach a string to a message</refpurpose>
  52   </refnamediv>
  53
  54   <refsynopsisdiv>
  55     <funcsynopsis>
  56       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  57
  58       <funcprototype>
  59         <funcdef>int sd_bus_message_append_string_memfd</funcdef>
  60         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  61         <paramdef>int <parameter>memfd</parameter></paramdef>
  62       </funcprototype>
  63
  64       <funcprototype>
  65         <funcdef>int sd_bus_message_append_string_iovec</funcdef>
  66         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  67         <paramdef>const struct iovec *<parameter>iov</parameter></paramdef>
  68         <paramdef>unsigned <parameter>n</parameter></paramdef>
  69       </funcprototype>
  70
  71       <funcprototype>
  72         <funcdef>int sd_bus_message_append_string_space</funcdef>
  73         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  74         <paramdef>size_t <parameter>size</parameter></paramdef>
  75         <paramdef>char **<parameter>s</parameter></paramdef>
  76       </funcprototype>
  77     </funcsynopsis>
  78   </refsynopsisdiv>
  79
  80   <refsect1>
  81     <title>Description</title>
  82
  83     <para>The functions
  84     <function>sd_bus_message_append_string_memfd</function> and
  85     <function>sd_bus_message_append_string_iovec</function> can be
  86     used to append a single string (item of type <literal>s</literal>)
  87     to message <parameter>m</parameter>.</para>
  88
  89     <para>In case of
  90     <function>sd_bus_message_append_string_memfd</function>, the
  91     contents of <parameter>memfd</parameter> are the string. They must
  92     satisfy the same constraints as described for the
  93     <literal>s</literal> type in
  94     <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
  95
  96     <para>In case of
  97     <function>sd_bus_message_append_string_iovec</function>, the
  98     payload of <parameter>iov</parameter> is the string. It must
  99     satisfy the same constraints as described for the
 100     <literal>s</literal> type in
 101     <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 102
 103     <para>The <parameter>iov</parameter> argument must point to
 104     <parameter>n</parameter> <structname>struct iovec</structname>
 105     structures. Each structure may have the
 106     <structname>iov_base</structname> field set, in which case the
 107     memory pointed to will be copied into the message, or unset, in
 108     which case a block of spaces (ASCII 32) of length
 109     <structname>iov_len</structname> will be inserted. The
 110     memory pointed at by <parameter>iov</parameter> may be changed
 111     after this call.</para>
 112
 113     <para>The
 114     <function>sd_bus_message_append_string_space</function> function appends
 115     space for a string to message <parameter>m</parameter>. It behaves
 116     similar to <function>sd_bus_message_append_basic</function> with
 117     type <literal>s</literal>, but instead of copying a string into
 118     the message, it returns a pointer to the destination area to
 119     the caller in pointer <parameter>p</parameter>. Space for the string
 120     of length <parameter>size</parameter> plus the terminating
 121     <constant>NUL</constant> is allocated.</para>
 122   </refsect1>
 123
 124   <refsect1>
 125     <title>Return Value</title>
 126
 127     <para>On success, those calls return 0 or a positive integer. On
 128     failure, they returns a negative errno-style error code.</para>
 129   </refsect1>
 130
 131   <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" />
 132
 133   <refsect1>
 134     <title>Notes</title>
 135
 136     <para>The functions described here are available as a shared library,
 137     which can be compiled and linked to with the
 138     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 139     file.</para>
 140   </refsect1>
 141
 142   <refsect1>
 143     <title>See Also</title>
 144
 145     <para>
 146       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 147       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 148       <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 149       <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink>
 150     </para>
 151   </refsect1>
 152
 153 </refentry>