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">
6 This file is part of systemd.
8 Copyright 2014 Zbigniew Jędrzejewski-Szmek
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.
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.
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/>.
24 <refentry id="sd_bus_message_append_string_memfd" conditional="ENABLE_KDBUS"
25 xmlns:xi="http://www.w3.org/2001/XInclude">
28 <title>sd_bus_message_append_string_memfd</title>
29 <productname>systemd</productname>
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>
42 <refentrytitle>sd_bus_message_append_string_memfd</refentrytitle>
43 <manvolnum>3</manvolnum>
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>
51 <refpurpose>Attach a string to a message</refpurpose>
56 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
59 <funcdef>int sd_bus_message_append_string_memfd</funcdef>
60 <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
61 <paramdef>sd_memfd *<parameter>memfd</parameter></paramdef>
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>
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>
81 <title>Description</title>
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>
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>
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>
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>
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>
125 <title>Return Value</title>
127 <para>On success, those calls return 0 or a positive integer. On
128 failure, they returns a negative errno-style error code.</para>
131 <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" />
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><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
143 <title>See Also</title>
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>