|
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | SEE ALSO | NOTES | COLOPHON |
SD_BUS_MESSAGE_READ_BASIC(3)_bus_message_read_basicBUS_MESSAGE_READ_BASIC(3)
sd_bus_message_read_basic - Read a basic type from a message
#include <systemd/sd-bus.h>
int sd_bus_message_read_basic(sd_bus_message *m, char type, void *p);
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.
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.
systemd(1), sd-bus(3), sd_bus_message_append_basic(3),
sd_bus_message_skip(3), sd_bus_message_read(3)
1. D-Bus Specification
https://dbus.freedesktop.org/doc/dbus-specification.html
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-08-13. (At that
time, the date of the most recent commit that was found in the repos‐
itory was 2020-08-11.) 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 246 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)