HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
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)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, chartype,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 intype are described in theD-BusSpecification[1]. Ifp is notNULL, it should contain a pointer to an appropriate object. For example, iftype is'y', the object passed inp should have typeuint8_t *. Iftype is's', the object passed inp should have typeconst 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. Iftype 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.
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 isNULL.-ENXIO The message does not contain the specified type at current position.-EBADMSG The message cannot be parsed.
sd_bus_message_read_basic()was added in version 221.
systemd(1),sd-bus(3),sd_bus_message_append_basic(3),sd_bus_message_skip(3),sd_bus_message_read(3)
1. D-Bus Specificationhttps://dbus.freedesktop.org/doc/dbus-specification.html
This page is part of thesystemd (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 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-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 isnot part of the original manual page), send a mail to man-pages@man7.orgsystemd 258~rc2SD_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)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |