mirror of
https://git.proxmox.com/git/systemd
synced 2025-05-29 11:51:49 +00:00
423 lines
7.2 KiB
Groff
423 lines
7.2 KiB
Groff
'\" 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)
|