focal (3) sd_bus_message_read_basic.3.gz
NAME
sd_bus_message_read_basic - Read a basic type from a message
SYNOPSIS
#include <systemd/sd-bus.h>
int sd_bus_message_read_basic(sd_bus_message *m, char type, void *p);
DESCRIPTION
sd_bus_message_read_basic() reads a basic type from a message and advances the read position in the
message. The set of basic types and their ascii codes passed in type are described in the D-Bus
Specification[1].
If p is not NULL, it should contain a pointer to an appropriate object. For example, if type is 'y', the
object passed in p should have type uint8_t *. If type is 's', the object passed in p should have type
const char **. Note that, if the basic type is a pointer (e.g., const char * in the case of a string),
the pointer is only borrowed and the contents must be copied if they are to be used after the end of the
messages lifetime. Similarly, during the lifetime of such a pointer, the message must not be modified.
See the table below for a complete list of allowed types.
Table 1. Item type specifiers
┌──────────┬─────────────────────────┬────────────────────────┬────────────────────────┐
│Specifier │ Constant │ Description │ Expected C Type │
├──────────┼─────────────────────────┼────────────────────────┼────────────────────────┤
│"y" │ SD_BUS_TYPE_BYTE │ 8bit unsigned integer │ uint8_t * │
├──────────┼─────────────────────────┼────────────────────────┼────────────────────────┤
│"b" │ SD_BUS_TYPE_BOOLEAN │ boolean │ int * (NB: not bool *) │
├──────────┼─────────────────────────┼────────────────────────┼────────────────────────┤
│"n" │ SD_BUS_TYPE_INT16 │ 16bit signed integer │ int16_t * │
├──────────┼─────────────────────────┼────────────────────────┼────────────────────────┤
│"q" │ SD_BUS_TYPE_UINT16 │ 16bit unsigned integer │ uint16_t * │
├──────────┼─────────────────────────┼────────────────────────┼────────────────────────┤
│"i" │ SD_BUS_TYPE_INT32 │ 32bit signed integer │ int32_t * │
├──────────┼─────────────────────────┼────────────────────────┼────────────────────────┤
│"u" │ SD_BUS_TYPE_UINT32 │ 32bit unsigned integer │ uint32_t * │
├──────────┼─────────────────────────┼────────────────────────┼────────────────────────┤
│"x" │ SD_BUS_TYPE_INT64 │ 64bit signed integer │ int64_t * │
├──────────┼─────────────────────────┼────────────────────────┼────────────────────────┤
│"t" │ SD_BUS_TYPE_UINT64 │ 64bit unsigned integer │ uint64_t * │
├──────────┼─────────────────────────┼────────────────────────┼────────────────────────┤
│"d" │ SD_BUS_TYPE_DOUBLE │ IEEE 754 double │ double * │
│ │ │ precision │ │
│ │ │ floating-point │ │
├──────────┼─────────────────────────┼────────────────────────┼────────────────────────┤
│"s" │ SD_BUS_TYPE_STRING │ UTF-8 string │ const char ** │
├──────────┼─────────────────────────┼────────────────────────┼────────────────────────┤
│"o" │ SD_BUS_TYPE_OBJECT_PATH │ D-Bus object path │ const char ** │
│ │ │ string │ │
├──────────┼─────────────────────────┼────────────────────────┼────────────────────────┤
│"g" │ SD_BUS_TYPE_SIGNATURE │ D-Bus signature string │ const char ** │
├──────────┼─────────────────────────┼────────────────────────┼────────────────────────┤
│"h" │ SD_BUS_TYPE_UNIX_FD │ UNIX file descriptor │ int * │
└──────────┴─────────────────────────┴────────────────────────┴────────────────────────┘
If there is no object of the specified type at the current position in the message, an error is returned.
RETURN VALUE
On success, sd_bus_message_read_basic() returns 0 or a positive integer. On failure, it returns a
negative errno-style error code.
Errors
Returned errors may indicate the following problems:
-EINVAL
Specified type string is invalid or the message parameter is NULL.
-ENXIO
The message does not contain the specified type at current position.
-EBADMSG
The message cannot be parsed.
SEE ALSO
systemd(1), sd-bus(3), sd_bus_message_append_basic(3), sd_bus_message_skip(3), sd_bus_message_read(3)
NOTES
1. D-Bus Specification
https://dbus.freedesktop.org/doc/dbus-specification.html