SD_BUS_ME...READ_ARRAY(3)

💅 sd_bus_message_read_array(3) — the manual page, bestie edition

okay so this is the page for sd_bus_message_read_array, from the sd_bus_message_read_array manual family (yes the header truncates it to SD_BUS_ME...READ_ARRAY(3), iconic abbreviation behaviour honestly). sit down, grab a strawberry drink 🍓, and let's get into it.

---

✨ NAME ✨

sd_bus_message_read_array — get your hands on an array of elements hanging out inside a message 🫶

---

🎀 SYNOPSIS 🎀

#include <systemd/sd-bus.h>

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

like, that's the whole vibe. three things in, one int out 💖

---

🦋 DESCRIPTION 🦋

sd_bus_message_read_array() gives you access to an array of elements inside the bus message m. the "read pointer" in the message has to be right before an array of type type — like, it must be positioned exactly there, no skipping ahead 🙈.

special case alert 🚨: type may be NUL, and in that case any trivial type is acceptable. flexible queen behaviour.

a pointer to the array data comes back in the ptr parameter, and the size of the array data (in bytes, bytes bestie) comes back in the size parameter.

⚠️ if the returned size parameter is 0, a valid non-null pointer will still be returned as ptr — but you may not dereference it. it's giving decorative. look, don't touch 💅

the data is aligned as appropriate for the data type. the data is part of the message — so:

• it may not be modified 🚫
• it's only valid as long as the message is referenced ⏳

after this function returns, the "read pointer" points at the next element after the array. moving on up ⬆️✨

💀 heads up: this function only supports arrays of trivial types — arrays of booleans, the various integer types, and floating point numbers. it may not be used for arrays of strings, structures or anything similar. so no string arrays, no struct arrays, none of that. don't even try it, i'm serious 😭

---

🔥 RETURN VALUE 🔥

on success, and when an array was actually read, sd_bus_message_read_array() returns an integer greater than zero. slay ✅

if it's invoked while inside a container element (like an array — for example when you're operating on an array of arrays, yes that's a thing) and the final element of the outer container has already been read, so the read pointer is now behind the last element of the outer container — the call returns 0. and in that case the returned pointer will be NULL and the size will be 0. empty. void. nothing left. 🫠

on failure, it returns a negative errno-style error code. boo. 💀

🌸 Errors 🌸

the errors that can come back mean the following, respectively:

• -EINVAL — the specified type is invalid or not a trivial type (see above 👀), or the message parameter or one of the output parameters are NULL. basically something's missing or wrong-typed, check yourself bestie.
• -EOPNOTSUPP — the byte order in the message is different than native byte order. not compatible, not today 🙅‍♀️
• -EPERM — the message is not sealed. no seal, no deal 🔒
• -EBADMSG — the message cannot be parsed. it's corrupted, we can't read it, it's over 😭

---

💜 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. standard icon behaviour 🎀
• 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... share the object, but take turns. be polite ✨
• the code described here uses getenv(3), which is declared to be not multi-thread-safe. this means that code calling the functions described here must not call setenv(3) from a parallel thread. the recommendation is to only do calls to setenv() from an early phase of the program, when no other threads have been started. front-load it, bestie, get it done before the party starts 🧚

---

⭐ HISTORY ⭐

sd_bus_message_read_array() was added in version 240. vintage but still iconic 👑

---

🌈 SEE ALSO 🌈

systemd(1), sd-bus(3), sd_bus_message_read(3), sd_bus_message_read_strv(3) — go read those too, iykyk 💅

---

and that's the page!! 🫶 brought to you by systemd 261.3 — mwah, love you, go read your arrays responsibly 💖✨🎀