SD_BUS_ME...READ_BASIC(3)

📦
version 261.3 · 17 versions
, in ubuntu stonking

💅 SD_BUS_MESSAGE_READ_BASIC(3) — sd_bus_message_read_basic 🎀

okay bestie, sit down, because this one is a little gem from the sd-bus crew, and I promise it's not scary. it lives in the manual pages, section 3, and yes the title is hyphenated weirdly on purpose, iykyk 💖

✨ NAME ✨

sd_bus_message_read_basic — literally just reads a basic type out of a message and moves on with its life 🦋

✨ SYNOPSIS ✨

#include <systemd/sd-bus.h>

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

that's it. that's the whole vibe. 🌸

✨ DESCRIPTION ✨

so sd_bus_message_read_basic() reads a basic type from a message and advances the read position in the message. like, it grabs the thing at the cursor and then the cursor slides forward, no take-backs 💅

the set of basic types and their ascii codes that get passed in type are described in the D-Bus Specification (that's footnote [1] down at the bottom, don't worry, I got you 🫶).

now the important bit, bestie, listen up — 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 **
⚠️ borrowed, not yours to keep: 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. no cap, that one bites people 😭

and for 'h' (UNIX file descriptor): the descriptor is not duplicated by this call, and the returned descriptor remains in possession of the message object. so you need to duplicate it yourself if you want to keep an open reference after the message object is freed — for example by calling "fcntl(fd, FD_DUPFD_CLOEXEC, 3)". 💀 (yes the manpage really has quotes around that, iconic honestly)

see the table below for a complete list of allowed types 👑

🎀 Table 1. Item type specifiers 🎀

  • "y" — SD_BUS_TYPE_BYTE — 8-bit unsigned integer — expected C type: uint8_t *
  • "b" — SD_BUS_TYPE_BOOLEAN — boolean — expected C type: int * (NB: not bool *) 🙈
  • "n" — SD_BUS_TYPE_INT16 — 16-bit signed integer — expected C type: int16_t *
  • "q" — SD_BUS_TYPE_UINT16 — 16-bit unsigned integer — expected C type: uint16_t *
  • "i" — SD_BUS_TYPE_INT32 — 32-bit signed integer — expected C type: int32_t *
  • "u" — SD_BUS_TYPE_UINT32 — 32-bit unsigned integer — expected C type: uint32_t *
  • "x" — SD_BUS_TYPE_INT64 — 64-bit signed integer — expected C type: int64_t *
  • "t" — SD_BUS_TYPE_UINT64 — 64-bit unsigned integer — expected C type: uint64_t *
  • "d" — SD_BUS_TYPE_DOUBLE — IEEE 754 double precision floating-point — expected C type: double *
  • "s" — SD_BUS_TYPE_STRING — UTF-8 string — expected C type: const char **
  • "o" — SD_BUS_TYPE_OBJECT_PATH — D-Bus object path string — expected C type: const char **
  • "g" — SD_BUS_TYPE_SIGNATURE — D-Bus signature string — expected C type: const char **
  • "h" — SD_BUS_TYPE_UNIX_FD — UNIX file descriptor — expected C type: int *

and if there is no object of the specified type at the current position in the message — boom, error returned. vibe check: failed 🧚

✨ 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 — the specified type string is invalid, or the message parameter is NULL.
  • -ENXIO — the message does not contain the specified type at the 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. slay 🫶

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. i.e. share the object, not the moment 💅

the code described here uses getenv(3), which is declared to be not multi-thread-safe. this means the code calling the functions described here must not call setenv(3) from a parallel thread. it's recommended to only do calls to setenv() from an early phase of the program when no other threads have been started. do your env setup first, party later 🎀

✨ HISTORY ✨

sd_bus_message_read_basic() was added in version 221. a true icon of its era 👑

✨ SEE ALSO ✨

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

✨ NOTES (the footnote one) ✨

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

and that's the whole page, bestie 💜 sign-off time: this gorgeousness is from systemd 261.3, sitting pretty under the SD_BUS_ME...READ_BASIC(3) header. go read your messages. periodt. 🌟

📦 where this page comes from