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);