SD_BUS_ME...PEND_ARRAY(3)

📦
version 261.3 · 18 versions
, in ubuntu stonking

🌸 SD_BUS_ME...PEND_ARRAY(3) — aka the sd_bus_message_append_array family 🌸

okay so bestie, welcome to the <pink>SD_BUS_ME...PEND_ARRAY(3)</pink> page 💅 this is the manual for the whole sd_bus_message_append_array squad — yes the title gets squished like that, no I did not do it, it's just how the man formatter vibes on this one. grab a boba, we're appending arrays to D-Bus messages 🧚✨

💖 NAME 💖

sd_bus_message_append_array, sd_bus_message_append_array_memfd, sd_bus_message_append_array_iovec, sd_bus_message_append_array_space — append an array of fields to a D-Bus message 🫶

✨ SYNOPSIS ✨

#include <systemd/sd-bus.h>

int sd_bus_message_append_array(sd_bus_message *m, char type,
                                const void *ptr, size_t size);

int sd_bus_message_append_array_memfd(sd_bus_message *m, char type,
                                      int memfd, uint64_t offset,
                                      uint64_t size);

int sd_bus_message_append_array_iovec(sd_bus_message *m, char type,
                                      const struct iovec *iov,
                                      unsigned n);

int sd_bus_message_append_array_space(sd_bus_message *m, char type,
                                      size_t size, void **ptr);

like, four whole functions, one header, we love a cohesive little family 😭💜

🎀 DESCRIPTION 🎀

🌈 the classic: sd_bus_message_append_array()

so sd_bus_message_append_array() appends an array to a D-Bus message m. literally a whole array, boom, in it goes. a container gets opened, the array contents get appended, and then the container gets closed — open, fill, close, slay ✨

the parameter type tells the function how the pointer p should be interpreted 👀 and type has got to be one of the "trivial" types: "y", "n", "q", "i", "u", "x", "t", "d" — but not "b", okay? not "b". those are defined in the Basic D-Bus Types[1] section of the D-Bus specification, and they're also listed in sd_bus_message_append_basic(3) (go look, iykyk).

pointer p must point to an array of size bytes containing items of the respective type. and size must be a multiple of the size of the type type — do the math bestie, the type system will not do it for you 💀

special case tho: p may be NULL, if size is 0. cute.

the memory pointed to by p gets copied into the memory area containing the message, and it stays in the possession of the caller — so you can freely change the data after this call and the message you appended the array to won't even notice, no cap 🫶

🦋 the zero-copy one: sd_bus_message_append_array_memfd()

sd_bus_message_append_array_memfd() appends an array of a trivial type to message m, similar to sd_bus_message_append_array(). but instead of a plain pointer, the contents of the memory file descriptor memfd, starting at the specified offset and of the specified size, is used as the contents of the array 👑

offset and size must be a multiple of the size of the type type. however — special exception alert 🚨 — if offset is specified as zero and size specified as UINT64_MAX, then the full memory file descriptor contents is used. the whole thing. all of it.

⚠️ the memory file descriptor is sealed by this call if it has not been sealed yet, and cannot be modified after this call. like, at all. sealed means sealed. see memfd_create(2) for details about memory file descriptors.

appending arrays with memory file descriptors enables efficient zero-copy data transfer ✨ because the memory file descriptor may be passed as-is to the destination, without copying the memory in it to the destination process. iconic behaviour, honestly.

but — not all protocol transports support passing memory file descriptors between participants, in which case this call will automatically fall back to copying. also, since memory file descriptor passing is inefficient for smaller amounts of data, copying might still be enforced even where memory file descriptor passing is supported. so like, it's giving "sometimes zero-copy, sometimes not" — the function handles it, don't stress 💅

🍓 the scatter-gather one: sd_bus_message_append_array_iovec()

sd_bus_message_append_array_iovec() appends an array of a trivial type to the message m, similar to sd_bus_message_append_array(). contents of the I/O vector array iov are used as the contents of the array 🎀

the total size of iov payload (that's the sum of the iov_len fields) must be a multiple of the size of the type type. and iov must point to n I/O vector structures.

each structure may have the iov_base field set — in which case the memory pointed to will be copied into the message — or unset (set to zero) — in which case a block of zeros of length iov_len bytes will be inserted. zeros. free real estate 🌈

the memory pointed at by iov may be changed after this call. yes bestie, after. you're free 💜

🧚 the "you write it" one: sd_bus_message_append_array_space()

sd_bus_message_append_array_space() appends space for an array of a trivial type to message m. it behaves the same as sd_bus_message_append_array(), but instead of copying items to the message, it returns a pointer to the destination area to the caller in pointer p. so you get to write the array contents into that memory yourself. main character energy, you're doing the filling 👑

⚠️ modifications to the memory pointed to should only occur until the next operation on the bus message is invoked. most importantly, the memory should not be altered anymore when another field has been added to the message or the message has been sealed. that's when it's over, bestie, hands off 🛑

⭐ RETURN VALUE ⭐

on success, these calls return 0 or a positive integer 🎉 on failure, they return a negative errno-style error code 😭

💀 Errors

returned errors may indicate the following problems:

  • -EINVAL — specified parameter is invalid. check ur args bestie.
  • -EPERM — message has been sealed. yeah, sealed. it's done. move on.
  • -ESTALE — message is in invalid state. not a vibe.
  • -ENXIO — message cannot be appended to. it said no 💅
  • -ENOMEM — memory allocation failed. the RAM said not today.

🔥 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 🫶

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. so like, one object = one thread at a time, but time-slicing is fine, and separate objects can absolutely be living their parallel lives 🌈

⚠️ the code described here uses getenv(3), which is declared to be not multi-thread-safe. this means that the code calling the functions described here must not call setenv(3) from a parallel thread. it is recommended to only do calls to setenv() from an early phase of the program when no other threads have been started. basically: set your env early, before the threads wake up 😭🙈

🌟 SEE ALSO 🌟

systemd(1), sd-bus(3), sd_bus_message_append(3), sd_bus_message_append_basic(3), memfd_create(2), The D-Bus specification[2]

📚 NOTES (the footnote ones, yes there are two NOTES sections, don't @ me) 📚

  1. Basic D-Bus Types — https://dbus.freedesktop.org/doc/dbus-specification.html#basic-types
  2. The D-Bus specification — https://dbus.freedesktop.org/doc/dbus-specification.html

aaaand that's the page 🎀 this absolutely iconic piece of documentation is from systemd 261.3, and it's the <pink>SD_BUS_ME...PEND_ARRAY(3)</pink> page — that's the source, that's the version, that's the whole footer vibe. go append some arrays, bestie, you've got this 💅✨🦋💖

📦 where this page comes from