SD_BUS_MESSAGE_READ_STRV(3)

💅 SD_BUS_MESSAGE_READ_STRV — bestie's guide to strv reading

okay so this whole page lives in the sd-bus manual family (that's the (3) part, iykyk), and it's all about two little functions that scoop an array of strings out of a D-Bus message. sound niche? it is. is it gonna slay your whole afternoon? maybe! let's go 🎀

---

✨ NAME ✨

sd_bus_message_read_strv, sd_bus_message_read_strv_extend — literally just here to give you access to an array of strings inside a message 💖

---

✨ SYNOPSIS ✨

#include <systemd/sd-bus.h>

int sd_bus_message_read_strv(sd_bus_message *m, char ***l);

int sd_bus_message_read_strv_extend(sd_bus_message *m, char ***l);

---

🌸 DESCRIPTION 🌸

So sd_bus_message_read_strv() reads an array of string-like items out of the message m. the way that the "read pointer" in the message has to be sitting right before an array of strings (D-Bus type "as"), object paths (D-Bus type "ao"), or signatures (D-Bus type "ag"), okay? no skipping ahead bestie. on success, you get a pointer to a NULL-terminated array of strings (a strv) in the output parameter l. 🦋

and here's the part where you gotta pay attention: ownership of this array is transferred to the caller. so that's on you now, bestie — you're responsible for freeing this array and its contents. main character responsibility, honestly. 😭

also, tiny optimization note (not me forgetting it, i would never): if an empty array is encountered, a NULL pointer might be returned here, and you should consider that equivalent to an array with zero entries. so don't panic when you see NULL, it's giving "empty, but make it fashion." 🫶

---

sd_bus_message_read_strv_extend() is the sibling, and it's similar — but the second parameter is an input-output parameter. so:

• if *l is NULL, it behaves identically to sd_bus_message_read_strv() (twins!)
• otherwise, *l must point to a strv, and that strv will be reallocated and extended with additional strings ✨

this one is particularly useful when you're combining multiple lists of strings across a message or messages into a single array of strings. like gluing your playlists together. iconic behavior. 🎧

---

🔥 RETURN VALUE 🔥

on success, these functions return a non-negative integer 💚 on failure, they return a negative errno-style error code 💀

😭 Errors

the errors you might get back mean the following, so let's vibe check them one by one:

• -EINVAL — m or l are NULL. (you forgot something, bestie.)

Added in version 246.

• -EPERM — the message is not sealed. 🔒 (no seal, no deal.)

Added in version 246.

• -EBADMSG — the message cannot be parsed. (it's giving gibberish.)

Added in version 246.

• -ENXIO — the message "read pointer" is not right before an array of the appropriate type. (wrong spot, wrong vibe.)

Added in version 248.

---

🧚 NOTES 🧚

the functions described here are available as a shared library, which you can compile against and link 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, share the object, but not at the same time, okay? scheduling is everything. 💅

⚠️ okay this one matters: the code described here uses getenv(3), which is declared to be not multi-thread-safe. that 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. early-phase setenv() only, periodt. 🙈

---

👑 HISTORY 👑

• sd_bus_message_read_strv() was added in version 246.
• sd_bus_message_read_strv_extend() was added in version 252.

(so extend is the younger sibling, and honestly it ate. ⭐)

---

🌈 SEE ALSO 🌈

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

---

and that's the page, bestie! 🍓 this is from systemd 261.3, so if anyone asks, that's the version you're repping. go forth, read those strvs, free your memory, and don't call setenv() from a parallel thread — mwah 💜✨