man/sd_bus_message_append_string_memfd.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 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2014 Zbigniew Jędrzejewski-Szmek
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="sd_bus_message_append_string_memfd" conditional="ENABLE_KDBUS"
  28           xmlns:xi="http://www.w3.org/2001/XInclude">
  29
  30   <refentryinfo>
  31     <title>sd_bus_message_append_string_memfd</title>
  32     <productname>systemd</productname>
  33
  34     <authorgroup>
  35       <author>
  36         <contrib>A monkey with a typewriter</contrib>
  37         <firstname>Zbigniew</firstname>
  38         <surname>Jędrzejewski-Szmek</surname>
  39         <email>zbyszek@in.waw.pl</email>
  40       </author>
  41     </authorgroup>
  42   </refentryinfo>
  43
  44   <refmeta>
  45     <refentrytitle>sd_bus_message_append_string_memfd</refentrytitle>
  46     <manvolnum>3</manvolnum>
  47   </refmeta>
  48
  49   <refnamediv>
  50     <refname>sd_bus_message_append_string_memfd</refname>
  51     <refname>sd_bus_message_append_string_iovec</refname>
  52     <refname>sd_bus_message_append_string_space</refname>
  53
  54     <refpurpose>Attach a string to a message</refpurpose>
  55   </refnamediv>
  56
  57   <refsynopsisdiv>
  58     <funcsynopsis>
  59       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  60
  61       <funcprototype>
  62         <funcdef>int sd_bus_message_append_string_memfd</funcdef>
  63         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  64         <paramdef>int <parameter>memfd</parameter></paramdef>
  65       </funcprototype>
  66
  67       <funcprototype>
  68         <funcdef>int sd_bus_message_append_string_iovec</funcdef>
  69         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  70         <paramdef>const struct iovec *<parameter>iov</parameter></paramdef>
  71         <paramdef>unsigned <parameter>n</parameter></paramdef>
  72       </funcprototype>
  73
  74       <funcprototype>
  75         <funcdef>int sd_bus_message_append_string_space</funcdef>
  76         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  77         <paramdef>size_t <parameter>size</parameter></paramdef>
  78         <paramdef>char **<parameter>s</parameter></paramdef>
  79       </funcprototype>
  80     </funcsynopsis>
  81   </refsynopsisdiv>
  82
  83   <refsect1>
  84     <title>Description</title>
  85
  86     <para>The functions
  87     <function>sd_bus_message_append_string_memfd</function> and
  88     <function>sd_bus_message_append_string_iovec</function> can be
  89     used to append a single string (item of type <literal>s</literal>)
  90     to message <parameter>m</parameter>.</para>
  91
  92     <para>In case of
  93     <function>sd_bus_message_append_string_memfd</function>, the
  94     contents of <parameter>memfd</parameter> are the string. They must
  95     satisfy the same constraints as described for the
  96     <literal>s</literal> type in
  97     <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
  98
  99     <para>In case of
 100     <function>sd_bus_message_append_string_iovec</function>, the
 101     payload of <parameter>iov</parameter> is the string. It must
 102     satisfy the same constraints as described for the
 103     <literal>s</literal> type in
 104     <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 105
 106     <para>The <parameter>iov</parameter> argument must point to
 107     <parameter>n</parameter> <structname>struct iovec</structname>
 108     structures. Each structure may have the
 109     <structname>iov_base</structname> field set, in which case the
 110     memory pointed to will be copied into the message, or unset, in
 111     which case a block of spaces (ASCII 32) of length
 112     <structname>iov_len</structname> will be inserted. The
 113     memory pointed at by <parameter>iov</parameter> may be changed
 114     after this call.</para>
 115
 116     <para>The
 117     <function>sd_bus_message_append_string_space</function> function appends
 118     space for a string to message <parameter>m</parameter>. It behaves
 119     similar to <function>sd_bus_message_append_basic</function> with
 120     type <literal>s</literal>, but instead of copying a string into
 121     the message, it returns a pointer to the destination area to
 122     the caller in pointer <parameter>p</parameter>. Space for the string
 123     of length <parameter>size</parameter> plus the terminating
 124     <constant>NUL</constant> is allocated.</para>
 125   </refsect1>
 126
 127   <refsect1>
 128     <title>Return Value</title>
 129
 130     <para>On success, those calls return 0 or a positive integer. On
 131     failure, they returns a negative errno-style error code.</para>
 132   </refsect1>
 133
 134   <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" />
 135
 136   <refsect1>
 137     <title>Notes</title>
 138
 139     <para>The functions described here are available as a shared library,
 140     which can be compiled and linked to with the
 141     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 142     file.</para>
 143   </refsect1>
 144
 145   <refsect1>
 146     <title>See Also</title>
 147
 148     <para>
 149       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 150       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 151       <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 152       <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink>
 153     </para>
 154   </refsect1>
 155
 156 </refentry>