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