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">
6 SPDX-License-Identifier: LGPL-2.1+
8 This file is part of systemd.
10 Copyright 2014 Zbigniew Jędrzejewski-Szmek
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.
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.
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/>.
26 <refentry id=
"sd_bus_message_append_string_memfd"
27 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
30 <title>sd_bus_message_append_string_memfd
</title>
31 <productname>systemd
</productname>
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>
44 <refentrytitle>sd_bus_message_append_string_memfd
</refentrytitle>
45 <manvolnum>3</manvolnum>
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>
53 <refpurpose>Attach a string to a message
</refpurpose>
58 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
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>
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>
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>
83 <title>Description
</title>
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>
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>
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>
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>
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>
127 <title>Return Value
</title>
129 <para>On success, those calls return
0 or a positive integer. On
130 failure, they returns a negative errno-style error code.
</para>
133 <xi:include href=
"sd_bus_message_append_basic.xml" xpointer=
"errors" />
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>
145 <title>See Also
</title>
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>