SD_BUS_MESSAGE_APPEND_STRING_MEMFD(3)

📦
version 261.3 · 17 versions
, in ubuntu stonking

💖 SD_BUS_MESSAGE_APPEND_STRING_IOVEC(3) — the manual page, but make it make sense 💖

okay so real talk: this is the section-3 manual page for sd_bus_message_append_string_memfd, sd_bus_message_append_string_iovec and sd_bus_message_append_string_space. bestie, the title only yells about one of them and honestly? main character energy, we respect it. 💅 the trio is here to shove a string into a D-Bus message and they are all gonna slay in slightly different ways.

✨ NAME ✨

sd_bus_message_append_string_memfd, sd_bus_message_append_string_iovec, sd_bus_message_append_string_space — attach a string to a message. that's the whole gig, no cap. 🎀

🌸 SYNOPSIS 🌸

#include <systemd/sd-bus.h>

int sd_bus_message_append_string_memfd(sd_bus_message *m, int memfd);

int sd_bus_message_append_string_iovec(sd_bus_message *m,
                                       const struct iovec *iov,
                                       unsigned n);

int sd_bus_message_append_string_space(sd_bus_message *m, size_t size,
                                       char **s);

look at them. iconic. 🦋

💫 DESCRIPTION 💫

so sd_bus_message_append_string_memfd() and sd_bus_message_append_string_iovec() are your girls for appending a single string — item of type "s" — to message m. one string. singular. she's not doing a whole array, okay?

  • sd_bus_message_append_string_memfd() — the contents of memfd are the string. and they must satisfy the same constraints as described for the "s" type in sd_bus_message_append_basic(3). same rules, no exceptions. 🙈
  • sd_bus_message_append_string_iovec() — the payload of iov is the string. it also must satisfy the same constraints as described for the "s" type in sd_bus_message_append_basic(3). yes, the exact same ones. iykyk. 💜

and here's the tea on iov: the iov argument must point to n struct iovec structures. each one gets to choose its own destiny:

  • if the structure has the iov_base field set, the memory pointed to gets copied into the message. 💚
  • if iov_base is unset, then a block of spaces (ASCII 32) of length iov_len gets inserted instead. free padding, we love a shortcut. ✨

also important: the memory pointed at by iov may be changed after this call. so like, don't think you can keep a grudge hold on it, it's the message's data now. 🫶

then there's sd_bus_message_append_string_space(), which appends space for a string to message m. she behaves similar to sd_bus_message_append_basic() with type "s", except instead of copying a string into the message she hands you back a pointer to the destination area in pointer p. so you fill it in yourself. DIY queen. 👑

and the space she allocates is for a string of length size plus the terminating NUL. both. you get both. 🎀

🔥 RETURN VALUE 🔥

on success, those calls return 0 or a positive integer. slay. 💖

on failure, they return a negative errno-style error code. not slay, but at least it's informative. 😭

💀 Errors 💀

the errors you might get back mean the following, and yes these are the exact ones, no embellishment:

  • -EINVAL — specified parameter is invalid. check your args bestie, something in there is not it.
  • -EPERM — message has been sealed. sealed. done. locked. she is not taking new guests. 🔒
  • -ESTALE — message is in invalid state. stale, like last week's vibe. 🌫️
  • -ENXIO — message cannot be appended to. nope. not happening. 🙅
  • -ENOMEM — memory allocation failed. the malloc said no. 😭

🧚 NOTES 🧚

okay admin stuff, but it matters:

  • functions described here are available as a shared library, which can be compiled against and linked to with the libsystemd pkg-config(1) file. link it properly, please. 🔗
  • 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. and multiple independent objects may be used from different threads in parallel. so like… one thread per object at a time, but parallel objects are totally fine. 🌈
  • 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 is recommended to only do calls to setenv() from an early phase of the program when no other threads have been started. so do your env stuff first, before the crowd shows up. 🫶
ngl the getenv(3) / setenv(3) thing is the one people forget and then spend three hours debugging. don't be that girl. 💀

🦋 SEE ALSO 🦋

🔖 NOTES (the footnote one) 🔖

  1. The D-Bus specification https://dbus.freedesktop.org/doc/dbus-specification.html

okay that's the whole page, bestie — and per the footer at the bottom, this is systemd 261.3 territory, manual section 3, so go forth and append strings responsibly. 💜🎀✨

📦 where this page comes from