sd_bus_message_read_basic(3) — Linux manual page

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

SD_BUS_MESSAGE_READ_BASIC(3)_bus_message_read_basicBUS_MESSAGE_READ_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 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   │ uint8_t *       │
       │          │                         │ integer         │                 │
       ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
       │"b"       │ SD_BUS_TYPE_BOOLEAN     │ boolean         │ int * (NB: not  │
       │          │                         │                 │ bool *)         │
       ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
       │"n"       │ SD_BUS_TYPE_INT16       │ 16bit signed    │ int16_t *       │
       │          │                         │ integer         │                 │
       ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
       │"q"       │ SD_BUS_TYPE_UINT16      │ 16bit unsigned  │ uint16_t *      │
       │          │                         │ integer         │                 │
       ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
       │"i"       │ SD_BUS_TYPE_INT32       │ 32bit signed    │ int32_t *       │
       │          │                         │ integer         │                 │
       ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
       │"u"       │ SD_BUS_TYPE_UINT32      │ 32bit unsigned  │ uint32_t *      │
       │          │                         │ integer         │                 │
       ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
       │"x"       │ SD_BUS_TYPE_INT64       │ 64bit signed    │ int64_t *       │
       │          │                         │ integer         │                 │
       ├──────────┼─────────────────────────┼─────────────────┼─────────────────┤
       │"t"       │ SD_BUS_TYPE_UINT64      │ 64bit 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         top

       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         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 2020-06-09.  (At that
       time, the date of the most recent commit that was found in the repos‐
       itory was 2020-06-09.)  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 man-pages@man7.org

systemd 245                                     SD_BUS_MESSAGE_READ_BASIC(3)

Pages that refer to this page: sd-bus(3)sd_bus_message_append_basic(3)sd_bus_message_peek_type(3)sd_bus_message_read(3)sd_bus_message_readv(3)sd_bus_message_skip(3)30-systemd-environment-d-generator(7)systemd.directives(7)systemd.index(7)