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" >
9 This file is part of systemd.
11 Copyright 2014 Zbigniew Jędrzejewski-Szmek
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.
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.
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/>.
27 <refentry id=
"sd_bus_message_append_string_memfd"
28 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
31 <title>sd_bus_message_append_string_memfd
</title>
32 <productname>systemd
</productname>
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>
45 <refentrytitle>sd_bus_message_append_string_memfd
</refentrytitle>
46 <manvolnum>3</manvolnum>
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>
54 <refpurpose>Attach a string to a message
</refpurpose>
59 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
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>
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>
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>
84 <title>Description
</title>
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>
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>
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>
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>
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>
128 <title>Return Value
</title>
130 <para>On success, those calls return
0 or a positive integer. On
131 failure, they returns a negative errno-style error code.
</para>
134 <xi:include href=
"sd_bus_message_append_basic.xml" xpointer=
"errors" />
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>
146 <title>See Also
</title>
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>