Debian Codegraph @

upstream/debian-trixie/man3/sd_bus_message_dump.3

raw
1 '\" t
2 .TH "SD_BUS_MESSAGE_DUMP" "3" "" "systemd 257.13" "sd_bus_message_dump"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_bus_message_dump \- Produce a string representation of a message for debugging purposes
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-bus\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_bus_message_dump('u
32 .BI "int sd_bus_message_dump(sd_bus_message\ *" "m" ", FILE\ *" "f" ", uint64_t\ " "flags" ");"
33 .PP
34 \fBSD_BUS_MESSAGE_DUMP_WITH_HEADER\fR,
35 \fBSD_BUS_MESSAGE_DUMP_SUBTREE_ONLY\fR
36 .SH "DESCRIPTION"
37 .PP
38 The
39 \fBsd_bus_message_dump()\fR
40 function writes a textual representation of the message
41 \fIm\fR
42 to the stream
43 \fIf\fR\&. If
44 \fIf\fR
45 is
46 \fBNULL\fR, standard output (\fBstdio\fR) will be used\&. This function is intended to be used for debugging purposes, and the output is neither stable nor designed to be machine readable\&.
47 .PP
48 The
49 \fIflags\fR
50 parameter may be used to modify the output\&. With
51 \fBSD_BUS_MESSAGE_DUMP_WITH_HEADER\fR, a header that specifies the message type and flags and some additional metadata is printed\&. When
52 \fBSD_BUS_MESSAGE_DUMP_SUBTREE_ONLY\fR
53 is not passed, the contents of the whole message are printed\&. When it
54 \fIis\fR
55 passed, only the current container in printed\&.
56 .PP
57 Note that this function moves the read pointer of the message\&. It may be necessary to reset the position afterwards, for example with
58 \fBsd_bus_message_rewind\fR(3)\&.
59 .SH "EXAMPLES"
60 .PP
61 Output for a signal message (with
62 \fBSD_BUS_MESSAGE_DUMP_WITH_HEADER\fR):
63 .sp
64 .if n \{\
65 .RS 4
66 .\}
67 .nf
68 >\& Type=signal Endian=l Flags=1 Version=1 Cookie=22
69 Path=/value/a Interface=org\&.freedesktop\&.DBus\&.Properties Member=PropertiesChanged
70 MESSAGE "sa{sv}as" {
71 STRING "org\&.freedesktop\&.systemd\&.ValueTest";
72 ARRAY "{sv}" {
73 DICT_ENTRY "sv" {
74 STRING "Value";
75 VARIANT "s" {
76 STRING "object 0x1e, path /value/a";
77 };
78 };
79 };
80 ARRAY "s" {
81 STRING "Value2";
82 STRING "AnExplicitProperty";
83 };
84 };
85 .fi
86 .if n \{\
87 .RE
88 .\}
89 .sp
90 .SH "RETURN VALUE"
91 .PP
92 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\&.
93 .SH "NOTES"
94 .PP
95 Functions described here are available as a shared library, which can be compiled against and linked to with the
96 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
97 file\&.
98 .PP
99 The code described here uses
100 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
101 \fBsetenv\fR(3)
102 from a parallel thread\&. It is recommended to only do calls to
103 \fBsetenv()\fR
104 from an early phase of the program when no other threads have been started\&.
105 .SH "SEE ALSO"
106 .PP
107 \fBsystemd\fR(1), \fBsd-bus\fR(3)