SD_BUS_MESSAGE_DUMP(3)

💖 SD_BUS_MESSAGE_DUMP(3) 💖

hi bestie!! welcome to the sd_bus_message_dump page (that's the manual name right there, SD_BUS_MESSAGE_DUMP(3), iykyk) — it's all about turning a D-Bus message into something you can actually look at when you're debugging. no cap, it's giving "print it and stare at it" energy. 💅

---

✨ NAME ✨

sd_bus_message_dump, sd_bus_message_dump_json — produce a string representation of a message for debugging purposes

like, that's the whole vibe: you got a message, you wanna see it. 🦋

---

🫶 SYNOPSIS 🫶

#include <systemd/sd-bus.h>

int sd_bus_message_dump(sd_bus_message *m, FILE *f, uint64_t flags);

int sd_bus_message_dump_json(sd_bus_message *m, uint64_t flags,
                             sd_json_variant **ret);

---

🌸 DESCRIPTION 🌸

okay so first up, sd_bus_message_dump() — it writes a textual representation of the message m into the stream f. and if f is NULL? it just uses standard output (stdio), iconic behavior honestly. 🌈

heads up bestie: this function is for debugging purposes only. the output is neither stable nor designed to be machine readable. do not parse it. do not build your whole pipeline on it. it's a vibe, not a contract. 💀

then there's sd_bus_message_dump_json() — this one converts the D-Bus message m to a JSON variant and stashes it in ret. you, the caller, are responsible for calling sd_json_variant_unref() on that JSON variant once you're done with it (yes, clean up after yourself, we love a responsible queen 👑). and unlike sd_bus_message_dump(), this function doesn't print anything itself. so if you want the D-Bus message printed in JSON format, you pass the returned JSON variant to sd_json_variant_dump(). that's the whole recipe. 🍓

the flags parameter is how you tweak the output — it's a combination of zero or more of these bad boys:

• SD_BUS_MESSAGE_DUMP_WITH_HEADER — the header of the message, which specifies the message type, flags, and several more additional metadata, gets printed (or included in the resulting JSON object). main character energy for your metadata fr fr ✨
• SD_BUS_MESSAGE_DUMP_SUBTREE_ONLY — only the current container gets printed or converted. leave this flag off and the contents of the whole entire message get printed or converted. so like, do you want the whole tree or just this branch? your call. 🌳

IMPORTANT: these functions move the read pointer of the message. so you might need to reset the position afterwards, for example with sd_bus_message_rewind(3). don't say I didn't warn you 😭

---

🎀 EXAMPLES 🎀

here's what the output looks like for a signal message (with SD_BUS_MESSAGE_DUMP_WITH_HEADER) — obsessed with how pretty this is ngl:

> Type=signal  Endian=l  Flags=1  Version=1  Cookie=22
  Path=/value/a  Interface=org.freedesktop.DBus.Properties  Member=PropertiesChanged
  MESSAGE "sa{sv}as" {
          STRING "org.freedesktop.systemd.ValueTest";
          ARRAY "{sv}" {
                  DICT_ENTRY "sv" {
                          STRING "Value";
                          VARIANT "s" {
                                  STRING "object 0x1e, path /value/a";
                          };
                  };
          };
          ARRAY "s" {
                  STRING "Value2";
                  STRING "AnExplicitProperty";
          };
  };

see?? nested and everything. ate. 💅

---

🔥 RETURN VALUE 🔥

on success, this function returns 0 or a positive integer. on failure, it returns a negative errno-style error code. and get this — no error codes are currently defined. so like, it fails in theory but there's nothing specific to tell you about it yet. 🤷♀️

---

💜 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, and multiple independent objects may be used from different threads in parallel. so like, share the object nicely, one thread at a time, periodt. 🧚
• 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 your setenv() calls in an early phase of the program, when no other threads have been started yet. do it early, bestie, and then never touch it again 🙈

---

👑 SEE ALSO 👑

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

---

and that's the page!! 💖 stay hydrated, rewind your read pointers, and go dump some messages. this has been SD_BUS_MESSAGE_DUMP(3) from systemd 262.1 — mwah, ily, bye bestie 🌸✨🎀