diff options
author | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2020-01-23 18:49:50 +0100 |
---|---|---|
committer | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2020-01-30 14:33:05 +0100 |
commit | f770b7e084d6c2d1ac04d9e723cd793ec52187d9 (patch) | |
tree | 6dcc66e6417f7b9684443dbfeb54ec84f90b91e5 | |
parent | 2b4a65b66813b01aa56e6f11643017d3fef55b06 (diff) | |
download | systemd-f770b7e084d6c2d1ac04d9e723cd793ec52187d9.tar.gz |
man: document man/sd_bus_message_dump.xml
-rw-r--r-- | man/rules/meson.build | 1 | ||||
-rw-r--r-- | man/sd-bus.xml | 1 | ||||
-rw-r--r-- | man/sd_bus_message_dump.xml | 107 |
3 files changed, 109 insertions, 0 deletions
diff --git a/man/rules/meson.build b/man/rules/meson.build index 90376da775..58c1f61241 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -230,6 +230,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 @@ <citerefentry><refentrytitle>sd_bus_message_append_string_memfd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_append_strv</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_copy</refentrytitle><manvolnum>3</manvolnum></citerefentry>, +<citerefentry><refentrytitle>sd_bus_message_dump</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_get_cookie</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_get_signature</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 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 @@ +<?xml version='1.0'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="sd_bus_message_dump" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_message_dump</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_dump</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_dump</refname> + + <refpurpose>Produce a string representation of a message for debugging purposes</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int sd_bus_message_dump</funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>FILE *<parameter>f</parameter></paramdef> + <paramdef>uint64_t <parameter>flags</parameter></paramdef> + </funcprototype> + </funcsynopsis> + + <para> + <constant>SD_BUS_MESSAGE_DUMP_WITH_HEADER</constant>, + <constant>SD_BUS_MESSAGE_DUMP_SUBTREE_ONLY</constant> + </para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <function>sd_bus_message_dump()</function> function writes a textual representation of the + message <parameter>m</parameter> to the stream <parameter>f</parameter>. This function is intended to be + used for debugging purposes, and the output is neither stable nor designed to be machine readable. + </para> + + <para>The <parameter>flags</parameter> parameter may be used to modify the output. With + <constant>SD_BUS_MESSAGE_DUMP_WITH_HEADER</constant>, a header that specifies the message type and flags + and some additional metadata is printed. When <constant>SD_BUS_MESSAGE_DUMP_SUBTREE_ONLY</constant> is + not passed, the contents of the whole message are printed. When it <emphasis>is</emphasis> passed, + only the current container in printed.</para> + + <para>Note that this function moves the read pointer of the message. It may be necessary to reset the + position afterwards, for example with + <citerefentry><refentrytitle>sd_bus_message_rewind</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>Output for a signal message (with <constant>SD_BUS_MESSAGE_DUMP_WITH_HEADER</constant>): + <programlisting> +‣ 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"; + }; + }; + </programlisting> + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>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.</para> + </refsect1> + + <xi:include href="libsystemd-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |