Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_message_dump.3

raw
1 '\" t
2 .TH "SD_BUS_MESSAGE_DUMP" "3" "" "systemd 261~rc3" "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, sd_bus_message_dump_json \- 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 .HP \w'int\ sd_bus_message_dump_json('u
34 .BI "int sd_bus_message_dump_json(sd_bus_message\ *" "m" ", uint64_t\ " "flags" ", sd_json_variant\ **" "ret" ");"
35 .SH "DESCRIPTION"
36 .PP
37 The
38 \fBsd_bus_message_dump()\fR
39 function writes a textual representation of the message
40 \fIm\fR
41 to the stream
42 \fIf\fR\&. If
43 \fIf\fR
44 is
45 \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\&.
46 .PP
47 The
48 \fBsd_bus_message_dump_json()\fR
49 function converts the DBus message
50 \fIm\fR
51 to a JSON variant and stores it in
52 \fIret\fR\&. The caller should call
53 \fBsd_json_variant_unref()\fR
54 for the acquired JSON variant after use\&. Unlike
55 \fBsd_bus_message_dump()\fR, the function itself does not print anything\&. To print the DBus message in the JSON format, please pass the returned JSON variant to
56 \fBsd_json_variant_dump()\fR\&.
57 .PP
58 The
59 \fIflags\fR
60 parameter may be used to modify the output, and is a combination of zero or more of the following flags:
61 .PP
62 \fBSD_BUS_MESSAGE_DUMP_WITH_HEADER\fR
63 .RS 4
64 The header of the message that specifies the message type, flags, and several more additional metadata will be printed or included in the resulting JSON object\&.
65 .RE
66 .PP
67 \fBSD_BUS_MESSAGE_DUMP_SUBTREE_ONLY\fR
68 .RS 4
69 Only the current container will be printed or converted\&. When the flag is
70 \fInot\fR
71 specified, the contents of the whole message will be printed or converted\&.
72 .RE
73 .PP
74 Note that these functions move the read pointer of the message\&. It may be necessary to reset the position afterwards, for example with
75 \fBsd_bus_message_rewind\fR(3)\&.
76 .SH "EXAMPLES"
77 .PP
78 Output for a signal message (with
79 \fBSD_BUS_MESSAGE_DUMP_WITH_HEADER\fR):
80 .sp
81 .if n \{\
82 .RS 4
83 .\}
84 .nf
85 >\& Type=signal Endian=l Flags=1 Version=1 Cookie=22
86 Path=/value/a Interface=org\&.freedesktop\&.DBus\&.Properties Member=PropertiesChanged
87 MESSAGE "sa{sv}as" {
88 STRING "org\&.freedesktop\&.systemd\&.ValueTest";
89 ARRAY "{sv}" {
90 DICT_ENTRY "sv" {
91 STRING "Value";
92 VARIANT "s" {
93 STRING "object 0x1e, path /value/a";
94 };
95 };
96 };
97 ARRAY "s" {
98 STRING "Value2";
99 STRING "AnExplicitProperty";
100 };
101 };
102 .fi
103 .if n \{\
104 .RE
105 .\}
106 .sp
107 .SH "RETURN VALUE"
108 .PP
109 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\&.
110 .SH "NOTES"
111 .PP
112 Functions described here are available as a shared library, which can be compiled against and linked to with the
113 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
114 file\&.
115 .PP
116 The code described here uses
117 \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
118 \fBsetenv\fR(3)
119 from a parallel thread\&. It is recommended to only do calls to
120 \fBsetenv()\fR
121 from an early phase of the program when no other threads have been started\&.
122 .SH "SEE ALSO"
123 .PP
124 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd-json\fR(3)