sd_bus_message_read_basic(3) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | HISTORY | SEE ALSO | NOTES | COLOPHON

SD_BUS_M...EAD_BASIC(3) sd_bus_message_read_basicSD_BUS_M...EAD_BASIC(3)

NAME         top

       sd_bus_message_read_basic - Read a basic type from a message

SYNOPSIS         top

       #include <systemd/sd-bus.h>

       int sd_bus_message_read_basic(sd_bus_message *m, char type,
                                     void *p);

DESCRIPTION         top

       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         │ uint16_t *     │
       │           │                         │ unsigned       │                │
       │           │                         │ integer        │                │
       ├───────────┼─────────────────────────┼────────────────┼────────────────┤
       │ "i"       │ SD_BUS_TYPE_INT32       │ 32-bit signed  │ int32_t *      │
       │           │                         │ integer        │                │
       ├───────────┼─────────────────────────┼────────────────┼────────────────┤
       │ "u"       │ SD_BUS_TYPE_UINT32      │ 32-bit         │ uint32_t *     │
       │           │                         │ unsigned       │                │
       │           │                         │ integer        │                │
       ├───────────┼─────────────────────────┼────────────────┼────────────────┤
       │ "x"       │ SD_BUS_TYPE_INT64       │ 64-bit signed  │ int64_t *      │
       │           │                         │ integer        │                │
       ├───────────┼─────────────────────────┼────────────────┼────────────────┤
       │ "t"       │ SD_BUS_TYPE_UINT64      │ 64-bit         │ uint64_t *     │
       │           │                         │ unsigned       │                │
       │           │                         │ 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          │ const char **  │
       │           │                         │ signature      │                │
       │           │                         │ 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         top

       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.

HISTORY         top

       sd_bus_message_read_basic() was added in version 221.

SEE ALSO         top

       systemd(1), sd-bus(3), sd_bus_message_append_basic(3),
       sd_bus_message_skip(3), sd_bus_message_read(3)

NOTES         top

        1. D-Bus Specification
           https://dbus.freedesktop.org/doc/dbus-specification.html

COLOPHON         top

       This page is part of the systemd (systemd system and service
       manager) project.  Information about the project can be found at
       ⟨http://www.freedesktop.org/wiki/Software/systemd⟩.  If you have
       a bug report for this manual page, see
       ⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
       This page was obtained from the project's upstream Git repository
       ⟨https://github.com/systemd/systemd.git⟩ on 2024-06-14.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2024-06-13.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       [email protected]

systemd 257~devel                                SD_BUS_M...EAD_BASIC(3)

Pages that refer to this page: sd-bus(3)sd_bus_message_append_basic(3)sd_bus_message_read(3)sd_bus_message_skip(3)systemd.directives(7)systemd.index(7)