diff --git a/man/rules/meson.build b/man/rules/meson.build
index e55538be9c..591d7c48b5 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -233,6 +233,7 @@ manpages = [
''],
['sd_bus_message_append_strv', '3', [], ''],
['sd_bus_message_copy', '3', [], ''],
+ ['sd_bus_message_dump', '3', [], ''],
['sd_bus_message_get_cookie', '3', ['sd_bus_message_get_reply_cookie'], ''],
['sd_bus_message_get_monotonic_usec',
'3',
diff --git a/man/sd-bus.xml b/man/sd-bus.xml
index e9a66d87dd..76865e1f8e 100644
--- a/man/sd-bus.xml
+++ b/man/sd-bus.xml
@@ -58,6 +58,7 @@
sd_bus_message_append_string_memfd3,
sd_bus_message_append_strv3,
sd_bus_message_copy3,
+sd_bus_message_dump3,
sd_bus_message_get_cookie3,
sd_bus_message_get_monotonic_usec3,
sd_bus_message_get_signature3,
diff --git a/man/sd_bus_message_dump.xml b/man/sd_bus_message_dump.xml
new file mode 100644
index 0000000000..db9e46d991
--- /dev/null
+++ b/man/sd_bus_message_dump.xml
@@ -0,0 +1,107 @@
+
+
+
+
+
+
+
+ sd_bus_message_dump
+ systemd
+
+
+
+ sd_bus_message_dump
+ 3
+
+
+
+ sd_bus_message_dump
+
+ Produce a string representation of a message for debugging purposes
+
+
+
+
+ #include <systemd/sd-bus.h>
+
+
+ int sd_bus_message_dump
+ sd_bus_message *m
+ FILE *f
+ uint64_t flags
+
+
+
+
+ SD_BUS_MESSAGE_DUMP_WITH_HEADER,
+ SD_BUS_MESSAGE_DUMP_SUBTREE_ONLY
+
+
+
+
+ Description
+
+ The sd_bus_message_dump() function writes a textual representation of the
+ message m to the stream f. This function is intended to be
+ used for debugging purposes, and the output is neither stable nor designed to be machine readable.
+
+
+ The flags parameter may be used to modify the output. With
+ SD_BUS_MESSAGE_DUMP_WITH_HEADER, a header that specifies the message type and flags
+ and some additional metadata is printed. When SD_BUS_MESSAGE_DUMP_SUBTREE_ONLY is
+ not passed, the contents of the whole message are printed. When it is passed,
+ only the current container in printed.
+
+ Note that this function moves the read pointer of the message. It may be necessary to reset the
+ position afterwards, for example with
+ sd_bus_message_rewind3.
+
+
+
+
+ Examples
+
+ Output for a signal message (with SD_BUS_MESSAGE_DUMP_WITH_HEADER):
+
+‣ Type=signal Endian=l Flags=1 Version=1 Priority=0 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";
+ };
+ };
+
+
+
+
+
+ Return Value
+
+ On success, this function returns 0 or a positive integer. On failure, it returns a negative
+ errno-style error code. No error codes are currently defined.
+
+
+
+
+
+ See Also
+
+
+ systemd1,
+ sd-bus3
+
+
+
+
diff --git a/src/busctl/busctl.c b/src/busctl/busctl.c
index 659621256b..5f3d5ddf39 100644
--- a/src/busctl/busctl.c
+++ b/src/busctl/busctl.c
@@ -1158,7 +1158,7 @@ static int introspect(int argc, char **argv, void *userdata) {
}
static int message_dump(sd_bus_message *m, FILE *f) {
- return bus_message_dump(m, f, BUS_MESSAGE_DUMP_WITH_HEADER);
+ return sd_bus_message_dump(m, f, SD_BUS_MESSAGE_DUMP_WITH_HEADER);
}
static int message_pcap(sd_bus_message *m, FILE *f) {
@@ -2052,7 +2052,7 @@ static int call(int argc, char **argv, void *userdata) {
} else if (arg_verbose) {
(void) pager_open(arg_pager_flags);
- r = bus_message_dump(reply, stdout, 0);
+ r = sd_bus_message_dump(reply, stdout, 0);
if (r < 0)
return r;
} else {
@@ -2158,7 +2158,7 @@ static int get_property(int argc, char **argv, void *userdata) {
} else if (arg_verbose) {
(void) pager_open(arg_pager_flags);
- r = bus_message_dump(reply, stdout, BUS_MESSAGE_DUMP_SUBTREE_ONLY);
+ r = sd_bus_message_dump(reply, stdout, SD_BUS_MESSAGE_DUMP_SUBTREE_ONLY);
if (r < 0)
return r;
} else {
diff --git a/src/fuzz/fuzz-bus-message.c b/src/fuzz/fuzz-bus-message.c
index aca82edad9..3d1ac7e68a 100644
--- a/src/fuzz/fuzz-bus-message.c
+++ b/src/fuzz/fuzz-bus-message.c
@@ -36,7 +36,7 @@ int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
if (getenv_bool("SYSTEMD_FUZZ_OUTPUT") <= 0)
assert_se(g = open_memstream_unlocked(&out, &out_size));
- bus_message_dump(m, g ?: stdout, BUS_MESSAGE_DUMP_WITH_HEADER);
+ sd_bus_message_dump(m, g ?: stdout, SD_BUS_MESSAGE_DUMP_WITH_HEADER);
r = sd_bus_message_rewind(m, true);
assert_se(r >= 0);
diff --git a/src/libsystemd/libsystemd.sym b/src/libsystemd/libsystemd.sym
index 17a39e1d0f..ccc23e1257 100644
--- a/src/libsystemd/libsystemd.sym
+++ b/src/libsystemd/libsystemd.sym
@@ -685,6 +685,7 @@ global:
LIBSYSTEMD_245 {
global:
+ sd_bus_message_dump;
sd_bus_message_sensitive;
sd_event_add_child_pidfd;
sd_event_source_get_child_pidfd;
diff --git a/src/libsystemd/sd-bus/bus-dump.c b/src/libsystemd/sd-bus/bus-dump.c
index 9a6a81d7aa..caab5e5ebe 100644
--- a/src/libsystemd/sd-bus/bus-dump.c
+++ b/src/libsystemd/sd-bus/bus-dump.c
@@ -18,23 +18,23 @@
#include "terminal-util.h"
#include "util.h"
-static char *indent(unsigned level, unsigned flags) {
+static char *indent(unsigned level, uint64_t flags) {
char *p;
unsigned n, i = 0;
n = 0;
- if (flags & BUS_MESSAGE_DUMP_SUBTREE_ONLY && level > 0)
+ if (flags & SD_BUS_MESSAGE_DUMP_SUBTREE_ONLY && level > 0)
level -= 1;
- if (flags & BUS_MESSAGE_DUMP_WITH_HEADER)
+ if (flags & SD_BUS_MESSAGE_DUMP_WITH_HEADER)
n += 2;
p = new(char, n + level*8 + 1);
if (!p)
return NULL;
- if (flags & BUS_MESSAGE_DUMP_WITH_HEADER) {
+ if (flags & SD_BUS_MESSAGE_DUMP_WITH_HEADER) {
p[i++] = ' ';
p[i++] = ' ';
}
@@ -45,7 +45,7 @@ static char *indent(unsigned level, unsigned flags) {
return p;
}
-int bus_message_dump(sd_bus_message *m, FILE *f, unsigned flags) {
+_public_ int sd_bus_message_dump(sd_bus_message *m, FILE *f, uint64_t flags) {
unsigned level = 1;
int r;
@@ -54,7 +54,7 @@ int bus_message_dump(sd_bus_message *m, FILE *f, unsigned flags) {
if (!f)
f = stdout;
- if (flags & BUS_MESSAGE_DUMP_WITH_HEADER) {
+ if (flags & SD_BUS_MESSAGE_DUMP_WITH_HEADER) {
fprintf(f,
"%s%s%s Type=%s%s%s Endian=%c Flags=%u Version=%u Priority=%"PRIi64,
m->header->type == SD_BUS_MESSAGE_METHOD_ERROR ? ansi_highlight_red() :
@@ -118,11 +118,11 @@ int bus_message_dump(sd_bus_message *m, FILE *f, unsigned flags) {
bus_creds_dump(&m->creds, f, true);
}
- r = sd_bus_message_rewind(m, !(flags & BUS_MESSAGE_DUMP_SUBTREE_ONLY));
+ r = sd_bus_message_rewind(m, !(flags & SD_BUS_MESSAGE_DUMP_SUBTREE_ONLY));
if (r < 0)
return log_error_errno(r, "Failed to rewind: %m");
- if (!(flags & BUS_MESSAGE_DUMP_SUBTREE_ONLY)) {
+ if (!(flags & SD_BUS_MESSAGE_DUMP_SUBTREE_ONLY)) {
_cleanup_free_ char *prefix = NULL;
prefix = indent(0, flags);
@@ -259,7 +259,7 @@ int bus_message_dump(sd_bus_message *m, FILE *f, unsigned flags) {
}
}
- if (!(flags & BUS_MESSAGE_DUMP_SUBTREE_ONLY)) {
+ if (!(flags & SD_BUS_MESSAGE_DUMP_SUBTREE_ONLY)) {
_cleanup_free_ char *prefix = NULL;
prefix = indent(0, flags);
diff --git a/src/libsystemd/sd-bus/bus-dump.h b/src/libsystemd/sd-bus/bus-dump.h
index a1b67c6b14..f138791c04 100644
--- a/src/libsystemd/sd-bus/bus-dump.h
+++ b/src/libsystemd/sd-bus/bus-dump.h
@@ -6,13 +6,6 @@
#include "sd-bus.h"
-enum {
- BUS_MESSAGE_DUMP_WITH_HEADER = 1 << 0,
- BUS_MESSAGE_DUMP_SUBTREE_ONLY = 1 << 1,
-};
-
-int bus_message_dump(sd_bus_message *m, FILE *f, unsigned flags);
-
int bus_creds_dump(sd_bus_creds *c, FILE *f, bool terse);
int bus_pcap_header(size_t snaplen, FILE *f);
diff --git a/src/libsystemd/sd-bus/test-bus-chat.c b/src/libsystemd/sd-bus/test-bus-chat.c
index d9716ae745..05127f0e0c 100644
--- a/src/libsystemd/sd-bus/test-bus-chat.c
+++ b/src/libsystemd/sd-bus/test-bus-chat.c
@@ -145,7 +145,7 @@ static int server(sd_bus *bus) {
strna(sd_bus_message_get_member(m)),
pid,
strna(label));
- /* bus_message_dump(m); */
+ /* sd_bus_message_dump(m); */
/* sd_bus_message_rewind(m, true); */
if (sd_bus_message_is_method_call(m, "org.freedesktop.systemd.test", "LowerCase")) {
diff --git a/src/libsystemd/sd-bus/test-bus-gvariant.c b/src/libsystemd/sd-bus/test-bus-gvariant.c
index 1a9a35d56b..d248bd4da1 100644
--- a/src/libsystemd/sd-bus/test-bus-gvariant.c
+++ b/src/libsystemd/sd-bus/test-bus-gvariant.c
@@ -175,7 +175,7 @@ static int test_marshal(void) {
}
#endif
- assert_se(bus_message_dump(m, NULL, BUS_MESSAGE_DUMP_WITH_HEADER) >= 0);
+ assert_se(sd_bus_message_dump(m, NULL, SD_BUS_MESSAGE_DUMP_WITH_HEADER) >= 0);
assert_se(bus_message_get_blob(m, &blob, &sz) >= 0);
@@ -196,7 +196,7 @@ static int test_marshal(void) {
assert_se(bus_message_from_malloc(bus, blob, sz, NULL, 0, NULL, &n) >= 0);
blob = NULL;
- assert_se(bus_message_dump(n, NULL, BUS_MESSAGE_DUMP_WITH_HEADER) >= 0);
+ assert_se(sd_bus_message_dump(n, NULL, SD_BUS_MESSAGE_DUMP_WITH_HEADER) >= 0);
m = sd_bus_message_unref(m);
@@ -205,7 +205,7 @@ static int test_marshal(void) {
assert_se(sd_bus_message_append(m, "as", 0) >= 0);
assert_se(sd_bus_message_seal(m, 4712, 0) >= 0);
- assert_se(bus_message_dump(m, NULL, BUS_MESSAGE_DUMP_WITH_HEADER) >= 0);
+ assert_se(sd_bus_message_dump(m, NULL, SD_BUS_MESSAGE_DUMP_WITH_HEADER) >= 0);
return EXIT_SUCCESS;
}
diff --git a/src/libsystemd/sd-bus/test-bus-marshal.c b/src/libsystemd/sd-bus/test-bus-marshal.c
index d7d51ba950..107eea390e 100644
--- a/src/libsystemd/sd-bus/test-bus-marshal.c
+++ b/src/libsystemd/sd-bus/test-bus-marshal.c
@@ -188,10 +188,10 @@ int main(int argc, char *argv[]) {
r = sd_bus_message_seal(m, 4711, 0);
assert_se(r >= 0);
- bus_message_dump(m, stdout, BUS_MESSAGE_DUMP_WITH_HEADER);
+ sd_bus_message_dump(m, stdout, SD_BUS_MESSAGE_DUMP_WITH_HEADER);
ms = open_memstream_unlocked(&first, &first_size);
- bus_message_dump(m, ms, 0);
+ sd_bus_message_dump(m, ms, 0);
fflush(ms);
assert_se(!ferror(ms));
@@ -244,11 +244,11 @@ int main(int argc, char *argv[]) {
r = bus_message_from_malloc(bus, buffer, sz, NULL, 0, NULL, &m);
assert_se(r >= 0);
- bus_message_dump(m, stdout, BUS_MESSAGE_DUMP_WITH_HEADER);
+ sd_bus_message_dump(m, stdout, SD_BUS_MESSAGE_DUMP_WITH_HEADER);
fclose(ms);
ms = open_memstream_unlocked(&second, &second_size);
- bus_message_dump(m, ms, 0);
+ sd_bus_message_dump(m, ms, 0);
fflush(ms);
assert_se(!ferror(ms));
assert_se(first_size == second_size);
@@ -354,7 +354,7 @@ int main(int argc, char *argv[]) {
fclose(ms);
ms = open_memstream_unlocked(&third, &third_size);
- bus_message_dump(copy, ms, 0);
+ sd_bus_message_dump(copy, ms, 0);
fflush(ms);
assert_se(!ferror(ms));
diff --git a/src/libsystemd/sd-bus/test-bus-objects.c b/src/libsystemd/sd-bus/test-bus-objects.c
index 3c5bb88f4e..41cf8c1670 100644
--- a/src/libsystemd/sd-bus/test-bus-objects.c
+++ b/src/libsystemd/sd-bus/test-bus-objects.c
@@ -399,7 +399,7 @@ static int client(struct context *c) {
r = sd_bus_call_method(bus, "org.freedesktop.systemd.test", "/foo", "org.freedesktop.DBus.Properties", "GetAll", &error, &reply, "s", "");
assert_se(r >= 0);
- bus_message_dump(reply, stdout, BUS_MESSAGE_DUMP_WITH_HEADER);
+ sd_bus_message_dump(reply, stdout, SD_BUS_MESSAGE_DUMP_WITH_HEADER);
sd_bus_message_unref(reply);
reply = NULL;
@@ -417,7 +417,7 @@ static int client(struct context *c) {
r = sd_bus_call_method(bus, "org.freedesktop.systemd.test", "/value", "org.freedesktop.DBus.ObjectManager", "GetManagedObjects", &error, &reply, "");
assert_se(r >= 0);
- bus_message_dump(reply, stdout, BUS_MESSAGE_DUMP_WITH_HEADER);
+ sd_bus_message_dump(reply, stdout, SD_BUS_MESSAGE_DUMP_WITH_HEADER);
sd_bus_message_unref(reply);
reply = NULL;
@@ -429,7 +429,7 @@ static int client(struct context *c) {
assert_se(r > 0);
assert_se(sd_bus_message_is_signal(reply, "org.freedesktop.DBus.Properties", "PropertiesChanged"));
- bus_message_dump(reply, stdout, BUS_MESSAGE_DUMP_WITH_HEADER);
+ sd_bus_message_dump(reply, stdout, SD_BUS_MESSAGE_DUMP_WITH_HEADER);
sd_bus_message_unref(reply);
reply = NULL;
@@ -441,7 +441,7 @@ static int client(struct context *c) {
assert_se(r > 0);
assert_se(sd_bus_message_is_signal(reply, "org.freedesktop.DBus.Properties", "PropertiesChanged"));
- bus_message_dump(reply, stdout, BUS_MESSAGE_DUMP_WITH_HEADER);
+ sd_bus_message_dump(reply, stdout, SD_BUS_MESSAGE_DUMP_WITH_HEADER);
sd_bus_message_unref(reply);
reply = NULL;
@@ -453,7 +453,7 @@ static int client(struct context *c) {
assert_se(r > 0);
assert_se(sd_bus_message_is_signal(reply, "org.freedesktop.DBus.ObjectManager", "InterfacesAdded"));
- bus_message_dump(reply, stdout, BUS_MESSAGE_DUMP_WITH_HEADER);
+ sd_bus_message_dump(reply, stdout, SD_BUS_MESSAGE_DUMP_WITH_HEADER);
sd_bus_message_unref(reply);
reply = NULL;
@@ -465,7 +465,7 @@ static int client(struct context *c) {
assert_se(r > 0);
assert_se(sd_bus_message_is_signal(reply, "org.freedesktop.DBus.ObjectManager", "InterfacesRemoved"));
- bus_message_dump(reply, stdout, BUS_MESSAGE_DUMP_WITH_HEADER);
+ sd_bus_message_dump(reply, stdout, SD_BUS_MESSAGE_DUMP_WITH_HEADER);
sd_bus_message_unref(reply);
reply = NULL;
@@ -477,7 +477,7 @@ static int client(struct context *c) {
assert_se(r > 0);
assert_se(sd_bus_message_is_signal(reply, "org.freedesktop.DBus.ObjectManager", "InterfacesAdded"));
- bus_message_dump(reply, stdout, BUS_MESSAGE_DUMP_WITH_HEADER);
+ sd_bus_message_dump(reply, stdout, SD_BUS_MESSAGE_DUMP_WITH_HEADER);
sd_bus_message_unref(reply);
reply = NULL;
@@ -489,7 +489,7 @@ static int client(struct context *c) {
assert_se(r > 0);
assert_se(sd_bus_message_is_signal(reply, "org.freedesktop.DBus.ObjectManager", "InterfacesRemoved"));
- bus_message_dump(reply, stdout, BUS_MESSAGE_DUMP_WITH_HEADER);
+ sd_bus_message_dump(reply, stdout, SD_BUS_MESSAGE_DUMP_WITH_HEADER);
sd_bus_message_unref(reply);
reply = NULL;
diff --git a/src/systemd/sd-bus.h b/src/systemd/sd-bus.h
index 3c9792e497..ff2c0e9ef0 100644
--- a/src/systemd/sd-bus.h
+++ b/src/systemd/sd-bus.h
@@ -19,6 +19,7 @@
#include
#include
+#include
#include
#include
@@ -105,6 +106,11 @@ enum {
SD_BUS_NAME_QUEUE = 1ULL << 2
};
+enum {
+ SD_BUS_MESSAGE_DUMP_WITH_HEADER = 1ULL << 0,
+ SD_BUS_MESSAGE_DUMP_SUBTREE_ONLY = 1ULL << 1,
+};
+
/* Callbacks */
typedef int (*sd_bus_message_handler_t)(sd_bus_message *m, void *userdata, sd_bus_error *ret_error);
@@ -330,6 +336,8 @@ int sd_bus_message_at_end(sd_bus_message *m, int complete);
int sd_bus_message_rewind(sd_bus_message *m, int complete);
int sd_bus_message_sensitive(sd_bus_message *m);
+int sd_bus_message_dump(sd_bus_message *m, FILE *f, uint64_t flags);
+
/* Bus management */
int sd_bus_get_unique_name(sd_bus *bus, const char **unique);