Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_message_append_array.3

raw
1 '\" t
2 .TH "SD_BUS_MESSAGE_APPEND_ARRAY" "3" "" "systemd 261~rc3" "sd_bus_message_append_array"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_bus_message_append_array, sd_bus_message_append_array_memfd, sd_bus_message_append_array_iovec, sd_bus_message_append_array_space \- Append an array of fields to a D\-Bus message
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-bus\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_bus_message_append_array('u
32 .BI "int sd_bus_message_append_array(sd_bus_message\ *" "m" ", char\ " "type" ", const\ void\ *" "ptr" ", size_t\ " "size" ");"
33 .HP \w'int\ sd_bus_message_append_array_memfd('u
34 .BI "int sd_bus_message_append_array_memfd(sd_bus_message\ *" "m" ", char\ " "type" ", int\ " "memfd" ", uint64_t\ " "offset" ", uint64_t\ " "size" ");"
35 .HP \w'int\ sd_bus_message_append_array_iovec('u
36 .BI "int sd_bus_message_append_array_iovec(sd_bus_message\ *" "m" ", char\ " "type" ", const\ struct\ iovec\ *" "iov" ", unsigned\ " "n" ");"
37 .HP \w'int\ sd_bus_message_append_array_space('u
38 .BI "int sd_bus_message_append_array_space(sd_bus_message\ *" "m" ", char\ " "type" ", size_t\ " "size" ", void\ **" "ptr" ");"
39 .SH "DESCRIPTION"
40 .PP
41 The
42 \fBsd_bus_message_append_array()\fR
43 function appends an array to a D\-Bus message
44 \fIm\fR\&. A container will be opened, the array contents appended, and the container closed\&. The parameter
45 \fItype\fR
46 determines how the pointer
47 \fIp\fR
48 is interpreted\&.
49 \fItype\fR
50 must be one of the "trivial" types
51 "y",
52 "n",
53 "q",
54 "i",
55 "u",
56 "x",
57 "t",
58 "d"
59 (but not
60 "b"), as defined by the
61 \m[blue]\fBBasic D\-Bus Types\fR\m[]\&\s-2\u[1]\d\s+2
62 section of the D\-Bus specification, and listed in
63 \fBsd_bus_message_append_basic\fR(3)\&. Pointer
64 \fIp\fR
65 must point to an array of size
66 \fIsize\fR
67 bytes containing items of the respective type\&. Size
68 \fIsize\fR
69 must be a multiple of the size of the type
70 \fItype\fR\&. As a special case,
71 \fIp\fR
72 may be
73 \fBNULL\fR, if
74 \fIsize\fR
75 is 0\&. The memory pointed to by
76 \fIp\fR
77 is copied into the memory area containing the message and stays in possession of the caller\&. The caller may hence freely change the data after this call without affecting the message the array was appended to\&.
78 .PP
79 The
80 \fBsd_bus_message_append_array_memfd()\fR
81 function appends an array of a trivial type to message
82 \fIm\fR, similar to
83 \fBsd_bus_message_append_array()\fR\&. The contents of the memory file descriptor
84 \fImemfd\fR
85 starting at the specified offset and of the specified size is used as the contents of the array\&. The offset and size must be a multiple of the size of the type
86 \fItype\fR\&. However, as a special exception, if the offset is specified as zero and the size specified as UINT64_MAX the full memory file descriptor contents is used\&. The memory file descriptor is sealed by this call if it has not been sealed yet, and cannot be modified after this call\&. See
87 \fBmemfd_create\fR(2)
88 for details about memory file descriptors\&. Appending arrays with memory file descriptors enables efficient zero\-copy data transfer, as the memory file descriptor may be passed as\-is to the destination, without copying the memory in it to the destination process\&. Not all protocol transports support passing memory file descriptors between participants, in which case this call will automatically fall back to copying\&. Also, as memory file descriptor passing is inefficient for smaller amounts of data, copying might still be enforced even where memory file descriptor passing is supported\&.
89 .PP
90 The
91 \fBsd_bus_message_append_array_iovec()\fR
92 function appends an array of a trivial type to the message
93 \fIm\fR, similar to
94 \fBsd_bus_message_append_array()\fR\&. Contents of the I/O vector array
95 \fIiov\fR
96 are used as the contents of the array\&. The total size of
97 \fIiov\fR
98 payload (the sum of
99 \fIiov_len\fR
100 fields) must be a multiple of the size of the type
101 \fItype\fR\&. The
102 \fIiov\fR
103 argument must point to
104 \fIn\fR
105 I/O vector structures\&. Each structure may have the
106 iov_base
107 field set, in which case the memory pointed to will be copied into the message, or unset (set to zero), in which case a block of zeros of length
108 iov_len
109 bytes will be inserted\&. The memory pointed at by
110 \fIiov\fR
111 may be changed after this call\&.
112 .PP
113 The
114 \fBsd_bus_message_append_array_space()\fR
115 function appends space for an array of a trivial type to message
116 \fIm\fR\&. It behaves the same as
117 \fBsd_bus_message_append_array()\fR, but instead of copying items to the message, it returns a pointer to the destination area to the caller in pointer
118 \fIp\fR\&. The caller should subsequently write the array contents to this memory\&. Modifications to the memory pointed to should only occur until the next operation on the bus message is invoked\&. Most importantly, the memory should not be altered anymore when another field has been added to the message or the message has been sealed\&.
119 .SH "RETURN VALUE"
120 .PP
121 On success, these calls return 0 or a positive integer\&. On failure, they return a negative errno\-style error code\&.
122 .SS "Errors"
123 .PP
124 Returned errors may indicate the following problems:
125 .PP
126 \fB\-EINVAL\fR
127 .RS 4
128 Specified parameter is invalid\&.
129 .RE
130 .PP
131 \fB\-EPERM\fR
132 .RS 4
133 Message has been sealed\&.
134 .RE
135 .PP
136 \fB\-ESTALE\fR
137 .RS 4
138 Message is in invalid state\&.
139 .RE
140 .PP
141 \fB\-ENXIO\fR
142 .RS 4
143 Message cannot be appended to\&.
144 .RE
145 .PP
146 \fB\-ENOMEM\fR
147 .RS 4
148 Memory allocation failed\&.
149 .RE
150 .SH "NOTES"
151 .PP
152 Functions described here are available as a shared library, which can be compiled against and linked to with the
153 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
154 file\&.
155 .PP
156 The code described here uses
157 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
158 \fBsetenv\fR(3)
159 from a parallel thread\&. It is recommended to only do calls to
160 \fBsetenv()\fR
161 from an early phase of the program when no other threads have been started\&.
162 .SH "SEE ALSO"
163 .PP
164 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_message_append\fR(3), \fBsd_bus_message_append_basic\fR(3), \fBmemfd_create\fR(2), \m[blue]\fBThe D\-Bus specification\fR\m[]\&\s-2\u[2]\d\s+2
165 .SH "NOTES"
166 .IP " 1." 4
167 Basic D-Bus Types
168 .RS 4
169 \%https://dbus.freedesktop.org/doc/dbus-specification.html#basic-types
170 .RE
171 .IP " 2." 4
172 The D-Bus specification
173 .RS 4
174 \%https://dbus.freedesktop.org/doc/dbus-specification.html
175 .RE