1SD_BUS_MESSAGE_READ(3)        sd_bus_message_read       SD_BUS_MESSAGE_READ(3)
2
3
4

NAME

6       sd_bus_message_read, sd_bus_message_readv, sd_bus_message_peek_type -
7       Read a sequence of values from a message
8

SYNOPSIS

10       #include <systemd/sd-bus.h>
11
12       int sd_bus_message_read(sd_bus_message *m, const char *types, ...);
13
14       int sd_bus_message_readv(sd_bus_message *m, const char *types,
15                                va_list ap);
16
17       int sd_bus_message_peek_type(sd_bus_message *m, char *type,
18                                    const char **contents);
19

DESCRIPTION

21       sd_bus_message_read() reads a sequence of fields from the D-Bus message
22       object m and advances the read position in the message. The type string
23       types describes the types of items expected in the message and the
24       field arguments that follow. The type string may be NULL or empty, in
25       which case nothing is read.
26
27       The type string is composed of the elements described in
28       sd_bus_message_append(3), i.e. basic and container types. It must
29       contain zero or more single "complete types". The type string is
30       NUL-terminated.
31
32       For each type specified in the type string, one or more arguments need
33       to be specified after the types parameter, in the same order. The
34       arguments must be pointers to appropriate types (a pointer to int8_t
35       for a "y" in the type string, a pointer to int32_t for an "i", a
36       pointer to const char* for an "s", ...) which are set based on the
37       values in the message. As an exception, in case of array and variant
38       types, the first argument is an "input" argument that further specifies
39       how the message should be read. See the table below for a complete list
40       of allowed arguments and their types. Note that, if the basic type is a
41       pointer (e.g., const char * in the case of a string), the argument is a
42       pointer to a pointer, and also the pointer value that is written is
43       only borrowed and the contents must be copied if they are to be used
44       after the end of the message's lifetime. If the type is "h" (UNIX file
45       descriptor), the descriptor is not duplicated by this call and the
46       returned descriptor remains in possession of the message object, and
47       needs to be duplicated by the caller in order to keep an open reference
48       to it after the message object is freed.
49
50       Each argument may also be NULL, in which case the value is read and
51       ignored.
52
53       Table 1. Item type specifiers
54       ┌──────────┬──────────────────────────────┬────────────────┬───────────────┬───────────────┐
55Specifier Constant                     Description    Type of the   Types of the  
56       │          │                              │                │ first         subsequent    
57       │          │                              │                │ argument      arguments, if 
58       │          │                              │                │               │ any           
59       ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
60       │"y"       │ SD_BUS_TYPE_BYTE             │ 8bit unsigned  │ uint8_t *     │               │
61       │          │                              │ integer        │               │               │
62       ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
63       │"b"       │ SD_BUS_TYPE_BOOLEAN          │ boolean        │ int * (NB:    │               │
64       │          │                              │                │ not bool *)   │               │
65       ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
66       │"n"       │ SD_BUS_TYPE_INT16            │ 16bit signed   │ int16_t *     │               │
67       │          │                              │ integer        │               │               │
68       ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
69       │"q"       │ SD_BUS_TYPE_UINT16           │ 16bit          │ uint16_t *    │               │
70       │          │                              │ unsigned       │               │               │
71       │          │                              │ integer        │               │               │
72       ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
73       │"i"       │ SD_BUS_TYPE_INT32            │ 32bit signed   │ int32_t *     │               │
74       │          │                              │ integer        │               │               │
75       ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
76       │"u"       │ SD_BUS_TYPE_UINT32           │ 32bit          │ uint32_t *    │               │
77       │          │                              │ unsigned       │               │               │
78       │          │                              │ integer        │               │               │
79       ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
80       │"x"       │ SD_BUS_TYPE_INT64            │ 64bit signed   │ int64_t *     │               │
81       │          │                              │ integer        │               │               │
82       ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
83       │"t"       │ SD_BUS_TYPE_UINT64           │ 64bit          │ uint64_t *    │               │
84       │          │                              │ unsigned       │               │               │
85       │          │                              │ integer        │               │               │
86       ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
87       │"d"       │ SD_BUS_TYPE_DOUBLE           │ IEEE 754       │ double *      │               │
88       │          │                              │ double         │               │               │
89       │          │                              │ precision      │               │               │
90       │          │                              │ floating-point │               │               │
91       ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
92       │"s"       │ SD_BUS_TYPE_STRING           │ UTF-8 string   │ const char ** │               │
93       ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
94       │"o"       │ SD_BUS_TYPE_OBJECT_PATH      │ D-Bus object   │ const char ** │               │
95       │          │                              │ path string    │               │               │
96       ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
97       │"g"       │ SD_BUS_TYPE_SIGNATURE        │ D-Bus          │ const char ** │               │
98       │          │                              │ signature      │               │               │
99       │          │                              │ string         │               │               │
100       ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
101       │"h"       │ SD_BUS_TYPE_UNIX_FD          │ UNIX file      │ int *         │               │
102       │          │                              │ descriptor     │               │               │
103       ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
104       │"a"       │ SD_BUS_TYPE_ARRAY            │ array          │ int, which    │ n sets of     │
105       │          │                              │                │ specifies the │ arguments     │
106       │          │                              │                │ expected      │ appropriate   │
107       │          │                              │                │ length n of   │ for the array │
108       │          │                              │                │ the array     │ element type  │
109       ├──────────┼──────────────────────────────┼────────────────┼───────────────┼───────────────┤
110       │"v"       │ SD_BUS_TYPE_VARIANT          │ variant        │ signature     │ arguments     │
111       │          │                              │                │ string        │ appropriate   │
112       │          │                              │                │               │ for the types │
113       │          │                              │                │               │ specified by  │
114       │          │                              │                │               │ the signature │
115       ├──────────┼──────────────────────────────┼────────────────┼───────────────┴───────────────┤
116       │"("       │ SD_BUS_TYPE_STRUCT_BEGIN     │ array start    │ arguments appropriate for     │
117       ├──────────┼──────────────────────────────┼────────────────┤ the structure elements        │
118       │")"       │ SD_BUS_TYPE_STRUCT_END       │ array end      │                               │
119       ├──────────┼──────────────────────────────┼────────────────┼───────────────┬───────────────┤
120       │"{"       │ SD_BUS_TYPE_DICT_ENTRY_BEGIN │ dictionary     │ arguments     │ arguments     │
121       │          │                              │ entry start    │ appropriate   │ appropriate   │
122       ├──────────┼──────────────────────────────┼────────────────┤ for the first │ for the       │
123       │"}"       │ SD_BUS_TYPE_DICT_ENTRY_END   │ dictionary     │ type in the   │ second type   │
124       │          │                              │ entry end      │ pair          │ in the pair   │
125       └──────────┴──────────────────────────────┴────────────────┴───────────────┴───────────────┘
126
127       If objects of the specified types are not present at the current
128       position in the message, an error is returned.
129
130       The sd_bus_message_readv() is equivalent to the sd_bus_message_read(),
131       except that it is called with a "va_list" instead of a variable number
132       of arguments. This function does not call the va_end() macro. Because
133       it invokes the va_arg() macro, the value of ap is undefined after the
134       call.
135
136       sd_bus_message_peek_type() determines the type of the next element in m
137       to be read by sd_bus_message_read() or similar functions. On success,
138       the type is stored in type, if it is not NULL. If the type is a
139       container type, the type of its elements is stored in contents, if it
140       is not NULL. If this function successfully determines the type of the
141       next element in m, it returns a positive integer. If there are no more
142       elements to be read, it returns zero.
143

RETURN VALUE

145       On success, these functions return a non-negative integer. On failure,
146       they return a negative errno-style error code.
147
148   Errors
149       Returned errors may indicate the following problems:
150
151       -EINVAL
152           Specified type string is invalid or the message parameter is NULL.
153
154       -ENXIO
155           The message does not contain the specified type at current
156           position.
157
158       -EBADMSG
159           The message cannot be parsed.
160

NOTES

162       These APIs are implemented as a shared library, which can be compiled
163       and linked to with the libsystemd pkg-config(1) file.
164

EXAMPLES

166       Read a single basic type (a 64-bit integer):
167
168           sd_bus_message *m;
169           int64_t x;
170
171           sd_bus_message_read(m, "x", &x);
172
173       Read a boolean value:
174
175           sd_bus_message *m;
176           int x; /* Do not use C99 'bool' type here, it's typically smaller
177                     in memory and would cause memory corruption */
178
179           sd_bus_message_read(m, "b", &x);
180
181       Read all types of integers:
182
183           uint8_t y;
184           int16_t n;
185           uint16_t q;
186           int32_t i;
187           uint32_t u;
188           int32_t x;
189           uint32_t t;
190           double d;
191
192           sd_bus_message_read(m, "ynqiuxtd", &y, &n, &q, &i, &u, &x, &t, &d);
193
194       Read a structure composed of a string and a D-Bus path:
195
196           const char *s, *p;
197
198           sd_bus_message_read(m, "(so)", &s, &p);
199
200       Read a variant, with the real type "gt" (signature, unsigned integer):
201
202           const char *s;
203           uint64_t *v;
204
205           sd_bus_message_read(m, "v", "gt", &s, &v);
206
207       Read a dictionary containing three pairs of type {integer=>string}:
208
209           int i, j, k;
210           const char *s, *t, *u;
211
212           sd_bus_message_read(m, "a{is}", 3, &i, &s, &j, &t, &k, &u);
213
214
215       Read a single file descriptor, and duplicate it in order to keep it
216       open after the message is freed.
217
218           sd_bus_message *m;
219           int fd, fd_copy;
220
221           sd_bus_message_read(m, "h", &fd);
222           fd_copy = fcntl(fd, FD_DUPFD_CLOEXEC, 3);
223

SEE ALSO

225       systemd(1), sd-bus(3), sd_bus_message_read_basic(3),
226       sd_bus_message_skip(3), sd_bus_message_append(3),
227       sd_bus_message_enter_container(3)
228
229
230
231systemd 248                                             SD_BUS_MESSAGE_READ(3)
Impressum