SD_BUS_MESSAGE_READ_BASIC(3)                         sd_bus_message_read_basic

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
       message's lifetime. Similarly, during the lifetime of such a pointer,
       the message must not be modified. If type is 'h' (UNIX file
       descriptor), the descriptor is not duplicated by this call and the
       returned descriptor remains in possession of the message object, and
       needs to be duplicated by the caller in order to keep an open reference
       to it after the message object is freed (for example by calling
       "fcntl(fd, FD_DUPFD_CLOEXEC, 3)"). 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        | 8-bit unsigned  | uint8_t *       |
       |          |                         | integer         |                 |
       +----------+-------------------------+-----------------+-----------------+
       |"b"       | SD_BUS_TYPE_BOOLEAN     | boolean         | int * (NB: not  |
       |          |                         |                 | bool *)         |
       +----------+-------------------------+-----------------+-----------------+
       |"n"       | SD_BUS_TYPE_INT16       | 16-bit signed   | int16_t *       |
       |          |                         | integer         |                 |
       +----------+-------------------------+-----------------+-----------------+
       |"q"       | SD_BUS_TYPE_UINT16      | 16-bit unsigned | uint16_t *      |
       |          |                         | integer         |                 |
       +----------+-------------------------+-----------------+-----------------+
       |"i"       | SD_BUS_TYPE_INT32       | 32-bit signed   | int32_t *       |
       |          |                         | integer         |                 |
       +----------+-------------------------+-----------------+-----------------+
       |"u"       | SD_BUS_TYPE_UINT32      | 32-bit unsigned | uint32_t *      |
       |          |                         | integer         |                 |
       +----------+-------------------------+-----------------+-----------------+
       |"x"       | SD_BUS_TYPE_INT64       | 64-bit signed   | int64_t *       |
       |          |                         | integer         |                 |
       +----------+-------------------------+-----------------+-----------------+
       |"t"       | SD_BUS_TYPE_UINT64      | 64-bit unsigned | uint64_t *      |
       |          |                         | integer         |                 |
       +----------+-------------------------+-----------------+-----------------+
       |"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    | const char **   |
       |          |                         | path string     |                 |
       +----------+-------------------------+-----------------+-----------------+
       |"g"       | SD_BUS_TYPE_SIGNATURE   | D-Bus signature | const char **   |
       |          |                         | string          |                 |
       +----------+-------------------------+-----------------+-----------------+
       |"h"       | SD_BUS_TYPE_UNIX_FD     | UNIX file       | int *           |
       |          |                         | descriptor      |                 |
       +----------+-------------------------+-----------------+-----------------+

       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 a positive integer. If
       the end of the currently opened array has been reached, it returns 0.
       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.

NOTES
       Functions described here are available as a shared library, which can
       be compiled against and linked to with the libsystemd pkg-config(1)
       file.

       All functions listed here are thread-agnostic and only a single thread
       may operate on a given object at any given time. Different threads may
       access the same object at different times. Multiple independent objects
       may be used from different threads in parallel.

       The code described here uses getenv(3), which is declared to be not
       multi-thread-safe. This means that the code calling the functions
       described here must not call setenv(3) from a parallel thread. It is
       recommended to only do calls to setenv() from an early phase of the
       program when no other threads have been started.

HISTORY
       sd_bus_message_read_basic() was added in version 221.

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

systemd 261.2                                     SD_BUS_MESSAGE_READ_BASIC(3)