'\" t
.TH "SD_BUS_MESSAGE_APPEND" "3" "" "systemd 219" "sd_bus_message_append"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sd_bus_message_append \- Attach parts of message based on a format string
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <systemd/sd\-bus\&.h>
.fi
.ft
.HP \w'int\ sd_bus_message_append('u
.BI "int sd_bus_message_append(sd_bus_message\ *" "m" ", const\ char\ *" "types" ", \&.\&.\&.);"
.SH "DESCRIPTION"
.PP
The
\fBsd_bus_message_append\fR
function appends a sequence of items to message
\fIm\fR\&. The format string
\fItypes\fR
describes the types of arguments that follow\&.
.PP
The format string is composed of the elements shown in the table below\&. It contains zero or more single "complete types"\&. Each complete type may be one of the basic types or a fully described container type\&. A container type may be a structure, a variant type code, an array with its element type, or a dictionary with its entry type\&. The format string is
\fBNUL\fR\-terminated\&.
.PP
In case of a basic type, one argument of the corresponding type is expected\&.
.PP
A structure is denoted by a sequence of complete types between
"("
and
")"\&. This sequence cannot be empty \(em it must contain at least one type\&. Arguments corresponding to this nested sequence follow the same rules as if they were not nested\&.
.PP
A variant is denoted by
"v"\&. Correspoding arguments must include a format string denoting a complete type, and following that, arguments corresponding to the specified type\&.
.PP
An array is denoted by
"a"
followed by a complete type\&. Corresponding arguments must include the size of the array, and then repeated this number of times, arguments corresponding to the nested type\&.
.PP
A dictionary is an array of dictionary entries, denoted by
"a"
followed by a pair of complete types between
"{"
and
"}"\&. The first of those types must be a basic type\&. Corresponding arguments must include the size of the dictionary, and then repeated this number of times, arguments corresponding to each of the two nested types\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.B Table\ \&1.\ \&Item format specifiers
.TS
allbox tab(:);
lB lB lB lB.
T{
Specifier
T}:T{
Constant
T}:T{
Description
T}:T{
Size
T}
.T&
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l ^
l l l l
l l l ^.
T{
"y"
T}:T{
\fBSD_BUS_TYPE_BYTE\fR
T}:T{
unsigned integer
T}:T{
1 byte
T}
T{
"b"
T}:T{
\fBSD_BUS_TYPE_BOOLEAN\fR
T}:T{
boolean
T}:T{
4 bytes
T}
T{
"n"
T}:T{
\fBSD_BUS_TYPE_INT16\fR
T}:T{
signed integer
T}:T{
2 bytes
T}
T{
"q"
T}:T{
\fBSD_BUS_TYPE_UINT16\fR
T}:T{
unsigned integer
T}:T{
2 bytes
T}
T{
"i"
T}:T{
\fBSD_BUS_TYPE_INT32\fR
T}:T{
signed integer
T}:T{
4 bytes
T}
T{
"u"
T}:T{
\fBSD_BUS_TYPE_UINT32\fR
T}:T{
unsigned integer
T}:T{
4 bytes
T}
T{
"x"
T}:T{
\fBSD_BUS_TYPE_INT64\fR
T}:T{
signed integer
T}:T{
8 bytes
T}
T{
"t"
T}:T{
\fBSD_BUS_TYPE_UINT64\fR
T}:T{
unsigned integer
T}:T{
8 bytes
T}
T{
"d"
T}:T{
\fBSD_BUS_TYPE_DOUBLE\fR
T}:T{
floating\-point
T}:T{
8 bytes
T}
T{
"s"
T}:T{
\fBSD_BUS_TYPE_STRING\fR
T}:T{
Unicode string
T}:T{
variable
T}
T{
"o"
T}:T{
\fBSD_BUS_TYPE_OBJECT_PATH\fR
T}:T{
object path
T}:T{
variable
T}
T{
"g"
T}:T{
\fBSD_BUS_TYPE_SIGNATURE\fR
T}:T{
signature
T}:T{
variable
T}
T{
"h"
T}:T{
\fBSD_BUS_TYPE_UNIX_FD\fR
T}:T{
UNIX file descriptor
T}:T{
4 bytes
T}
T{
"a"
T}:T{
\fBSD_BUS_TYPE_ARRAY\fR
T}:T{
array
T}:T{
determined by array type and size
T}
T{
"v"
T}:T{
\fBSD_BUS_TYPE_VARIANT\fR
T}:T{
variant
T}:T{
determined by the type argument
T}
T{
"("
T}:T{
\fBSD_BUS_TYPE_STRUCT_BEGIN\fR
T}:T{
array start
T}:T{
determined by the nested types
T}
T{
")"
T}:T{
\fBSD_BUS_TYPE_STRUCT_END\fR
T}:T{
array end
T}:
T{
"{"
T}:T{
\fBSD_BUS_TYPE_DICT_ENTRY_BEGIN\fR
T}:T{
dictionary entry start
T}:T{
determined by the nested types
T}
T{
"}"
T}:T{
\fBSD_BUS_TYPE_DICT_ENTRY_END\fR
T}:T{
dictionary entry end
T}:
.TE
.sp 1
.SH "TYPES STRING GRAMMAR"
.sp
.if n \{\
.RS 4
.\}
.nf
types ::= complete_type*
complete_type ::= basic_type | variant | structure | array | dictionary
basic_type ::= "y" | "n" | "q" | "u" | "i" | "x" | "t" | "d" |
               "b" | "h" |
               "s" | "o" | "g"
variant ::= "v"
structure ::= "(" complete_type+ ")"
array ::= "a" complete_type
dictionary ::= "a" "{" basic_type complete_type "}"
.fi
.if n \{\
.RE
.\}
.SH "EXAMPLES"
.PP
Append a single basic type (the string
"a string"):
.sp
.if n \{\
.RS 4
.\}
.nf
sd_bus_message *m;
\&.\&.\&.
sd_bus_message_append(m, "s", "a string");
.fi
.if n \{\
.RE
.\}
.PP
Append all types of integers:
.sp
.if n \{\
.RS 4
.\}
.nf
uint8_t y = 1;
int16_t n = 2;
uint16_t q = 3;
int32_t i = 4;
uint32_t u = 5;
int32_t x = 6;
uint32_t t = 7;
double d = 8\&.0;
sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d);
.fi
.if n \{\
.RE
.\}
.PP
Append a structure composed of string and a D\-Bus path:
.sp
.if n \{\
.RS 4
.\}
.nf
sd_bus_message_append(m, "(so)", "a string", "/a/path");
.fi
.if n \{\
.RE
.\}
.PP
Append an array of UNIX file descriptors:
.sp
.if n \{\
.RS 4
.\}
.nf
sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO);
.fi
.if n \{\
.RE
.\}
.PP
Append a variant, with the real type "g" (signature), and value "sdbusisgood":
.sp
.if n \{\
.RS 4
.\}
.nf
sd_bus_message_append(m, "v", "g", "sdbusisgood");
.fi
.if n \{\
.RE
.\}
.PP
Append a dictionary containing the mapping {1=>"a", 2=>"b", 3=>""}:
.sp
.if n \{\
.RS 4
.\}
.nf
sd_bus_message_append(m, "a{is}", 3, 1, "a", 2, "b", 3, NULL);
     
.fi
.if n \{\
.RE
.\}
.SH "RETURN VALUE"
.PP
On success, this call returns 0 or a positive integer\&. On failure, this call returns a negative errno\-style error code\&.
.SH "ERRORS"
.PP
Returned errors may indicate the following problems:
.PP
\fB\-EINVAL\fR
.RS 4
Specified parameter is invalid\&.
.RE
.PP
\fB\-EPERM\fR
.RS 4
Message has been sealed\&.
.RE
.PP
\fB\-ESTALE\fR
.RS 4
Message is in invalid state\&.
.RE
.PP
\fB\-ENXIO\fR
.RS 4
Message cannot be appended to\&.
.RE
.PP
\fB\-ENOMEM\fR
.RS 4
Memory allocation failed\&.
.RE
.SH "NOTES"
.PP
\fBsd_bus_open_user()\fR
and other functions described here are available as a shared library, which can be compiled and linked to with the
\fBlibsystemd\-bus\fR\ \&\fBpkg-config\fR(1)
file\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBsd-bus\fR(3),
\fBsd_bus_new\fR(3),
\fBsd_bus_ref\fR(3),
\fBsd_bus_unref\fR(3),
\fBssh\fR(1),
\fBsystemd-machined.service\fR(8),
\fBmachinectl\fR(1)