1SD_BUS_MESSAGE_READ_BASIC(3)sd_bus_message_read_basiScD_BUS_MESSAGE_READ_BASIC(3)
2
6 sd_bus_message_read_basic - Read a basic type from a message
7
9 #include <systemd/sd-bus.h>
10 int sd_bus_message_read_basic(sd_bus_message *m, char type, void *p);
12
14 sd_bus_message_read_basic() reads a basic type from a message and
15 advances the read position in the message. The set of basic types and
16 their ascii codes passed in type are described in the D-Bus
17 Specification[1].
18 If p is not NULL, it should contain a pointer to an appropriate object.
20 For example, if type is 'y', the object passed in p should have type
21 uint8_t *. If type is 's', the object passed in p should have type
22 const char **. Note that, if the basic type is a pointer (e.g., const
23 char * in the case of a string), the pointer is only borrowed and the
24 contents must be copied if they are to be used after the end of the
25 message's lifetime. Similarly, during the lifetime of such a pointer,
26 the message must not be modified. If type is 'h' (UNIX file
27 descriptor), the descriptor is not duplicated by this call and the
28 returned descriptor remains in possession of the message object, and
29 needs to be duplicated by the caller in order to keep an open reference
30 to it after the message object is freed (for example by calling
31 "fcntl(fd, FD_DUPFD_CLOEXEC, 3)"). See the table below for a complete
32 list of allowed types.
33 Table 1. Item type specifiers
35 ┌──────────┬─────────────────────────┬─────────────────┬─────────────────┐
36 │Specifier │ Constant │ Description │ Expected C Type │
37 ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
38 │"y" │ SD_BUS_TYPE_BYTE │ 8bit unsigned │ uint8_t * │
39 │ │ │ integer │ │
40 ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
41 │"b" │ SD_BUS_TYPE_BOOLEAN │ boolean │ int * (NB: not │
42 │ │ │ │ bool *) │
43 ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
44 │"n" │ SD_BUS_TYPE_INT16 │ 16bit signed │ int16_t * │
45 │ │ │ integer │ │
46 ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
47 │"q" │ SD_BUS_TYPE_UINT16 │ 16bit unsigned │ uint16_t * │
48 │ │ │ integer │ │
49 ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
50 │"i" │ SD_BUS_TYPE_INT32 │ 32bit signed │ int32_t * │
51 │ │ │ integer │ │
52 ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
53 │"u" │ SD_BUS_TYPE_UINT32 │ 32bit unsigned │ uint32_t * │
54 │ │ │ integer │ │
55 ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
56 │"x" │ SD_BUS_TYPE_INT64 │ 64bit signed │ int64_t * │
57 │ │ │ integer │ │
58 ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
59 │"t" │ SD_BUS_TYPE_UINT64 │ 64bit unsigned │ uint64_t * │
60 │ │ │ integer │ │
61 ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
62 │"d" │ SD_BUS_TYPE_DOUBLE │ IEEE 754 double │ double * │
63 │ │ │ precision │ │
64 │ │ │ floating-point │ │
65 ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
66 │"s" │ SD_BUS_TYPE_STRING │ UTF-8 string │ const char ** │
67 ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
68 │"o" │ SD_BUS_TYPE_OBJECT_PATH │ D-Bus object │ const char ** │
69 │ │ │ path string │ │
70 ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
71 │"g" │ SD_BUS_TYPE_SIGNATURE │ D-Bus signature │ const char ** │
72 │ │ │ string │ │
73 ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
74 │"h" │ SD_BUS_TYPE_UNIX_FD │ UNIX file │ int * │
75 │ │ │ descriptor │ │
76 └──────────┴─────────────────────────┴─────────────────┴─────────────────┘
77 If there is no object of the specified type at the current position in
79 the message, an error is returned.
80
82 On success, sd_bus_message_read_basic() returns a positive integer. If
83 the end of the currently opened array has been reached, it returns 0.
84 On failure, it returns a negative errno-style error code.
85 Errors
87 Returned errors may indicate the following problems:
88 -EINVAL
90 Specified type string is invalid or the message parameter is NULL.
91 -ENXIO
93 The message does not contain the specified type at current
94 position.
95 -EBADMSG
97 The message cannot be parsed.
98
100 systemd(1), sd-bus(3), sd_bus_message_append_basic(3),
101 sd_bus_message_skip(3), sd_bus_message_read(3)
102
104 1. D-Bus Specification
105 https://dbus.freedesktop.org/doc/dbus-specification.html
106systemd 253 SD_BUS_MESSAGE_READ_BASIC(3)