Debian Codegraph @

doc/dbus-test-tool.1.xml.in

raw
1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
3 <refentry id="dbus-test-tool.1">
4 <refentryinfo>
5 <copyright>
6 <year>2015</year>
7 <holder>Collabora Ltd.</holder>
8 </copyright>
9 <legalnotice>
10 <!--
11 Copyright 2015 Collabora Ltd.
12 SPDX-License-Identifier: GPL-2.0-or-later
13 -->
14 <para>This man page is distributed under the same terms as
15 dbus-test-tool (GPL-2+). There is NO WARRANTY, to the extent
16 permitted by law.</para>
17 </legalnotice>
18 </refentryinfo>
19
20 <refmeta>
21 <refentrytitle>dbus-test-tool</refentrytitle>
22 <manvolnum>1</manvolnum>
23 <refmiscinfo class="manual">User Commands</refmiscinfo>
24 <refmiscinfo class="source">D-Bus</refmiscinfo>
25 <refmiscinfo class="version">@DBUS_VERSION@</refmiscinfo>
26 </refmeta>
27 <refnamediv>
28 <refname>dbus-test-tool</refname>
29 <refpurpose>D-Bus traffic generator and test tool</refpurpose>
30 </refnamediv>
31
32 <refsynopsisdiv id="synopsis">
33 <cmdsynopsis>
34 <command>dbus-test-tool</command>
35 <arg choice="plain">black-hole</arg>
36 <group choice="opt">
37 <arg choice="plain">--session</arg>
38 <arg choice="plain">--system</arg>
39 </group>
40 <arg choice="opt">--name=<replaceable>NAME</replaceable></arg>
41 <arg choice="opt">--no-read</arg>
42 </cmdsynopsis>
43
44 <cmdsynopsis>
45 <command>dbus-test-tool</command>
46 <arg choice="plain">echo</arg>
47 <group choice="opt">
48 <arg choice="plain">--session</arg>
49 <arg choice="plain">--system</arg>
50 </group>
51 <arg choice="opt">--name=<replaceable>NAME</replaceable></arg>
52 <arg choice="opt">--sleep-ms=<replaceable>MS</replaceable></arg>
53 </cmdsynopsis>
54
55 <cmdsynopsis>
56 <command>dbus-test-tool</command>
57 <arg choice="plain">spam</arg>
58 <group choice="opt">
59 <arg choice="plain">--session</arg>
60 <arg choice="plain">--system</arg>
61 </group>
62 <arg choice="opt">--dest=<replaceable>NAME</replaceable></arg>
63 <arg choice="opt">--count=<replaceable>N</replaceable></arg>
64 <arg choice="opt">--flood</arg>
65 <arg choice="opt">--ignore-errors</arg>
66 <arg choice="opt">--messages-per-conn=<replaceable>N</replaceable></arg>
67 <arg choice="opt">--no-reply</arg>
68 <arg choice="opt">--queue=<replaceable>N</replaceable></arg>
69 <arg choice="opt">--seed=<replaceable>SEED</replaceable></arg>
70 <group choice="opt">
71 <arg choice="plain">--string</arg>
72 <arg choice="plain">--bytes</arg>
73 <arg choice="plain">--empty</arg>
74 </group>
75 <group choice="opt">
76 <arg choice="plain">--payload=<replaceable>S</replaceable></arg>
77 <arg choice="plain">--stdin</arg>
78 <arg choice="plain">--message-stdin</arg>
79 <arg choice="plain">--random-size</arg>
80 </group>
81 </cmdsynopsis>
82 </refsynopsisdiv>
83
84 <refsect1 id="description">
85 <title>DESCRIPTION</title>
86 <para><command>dbus-test-tool</command> is a multi-purpose tool
87 for debugging and profiling D-Bus.</para>
88
89 <para><command>dbus-test-tool black-hole</command>
90 connects to D-Bus, optionally requests a name, then does not
91 reply to messages. It normally reads and discards messages from
92 its D-Bus socket, but can be configured to sleep forever without
93 reading.</para>
94
95 <para><command>dbus-test-tool echo</command>
96 connects to D-Bus, optionally requests a name, then sends back an
97 empty reply to every method call, after an optional delay.</para>
98
99 <para><command>dbus-test-tool spam</command>
100 connects to D-Bus and makes repeated method calls,
101 normally named <literal>com.example.Spam</literal>.</para>
102 </refsect1>
103
104 <refsect1 id="options">
105 <title>OPTIONS</title>
106 <refsect2>
107 <title>Common options</title>
108 <variablelist remap="TP">
109
110 <varlistentry>
111 <term><option>--session</option></term>
112 <listitem>
113 <para>Connect to the session bus. This is the default.</para>
114 </listitem>
115 </varlistentry>
116
117 <varlistentry>
118 <term><option>--system</option></term>
119 <listitem>
120 <para>Connect to the system bus.</para>
121 </listitem>
122 </varlistentry>
123
124 </variablelist>
125 </refsect2>
126
127 <refsect2>
128 <title>black-hole mode</title>
129 <variablelist remap="TP">
130
131 <varlistentry>
132 <term><option>--name=</option><replaceable>NAME</replaceable></term>
133 <listitem>
134 <para>Before proceeding, request ownership of the well-known
135 bus name <replaceable>NAME</replaceable>, for example
136 <literal>com.example.NoReply</literal>. By default,
137 no name is requested, and the tool can only be addressed by
138 a unique bus name such as <literal>:1.23</literal>.</para>
139 </listitem>
140 </varlistentry>
141
142 <varlistentry>
143 <term><option>--no-read</option></term>
144 <listitem>
145 <para>Do not read from the D-Bus socket.</para>
146 </listitem>
147 </varlistentry>
148
149 </variablelist>
150 </refsect2>
151
152 <refsect2>
153 <title>echo mode</title>
154 <variablelist remap="TP">
155
156 <varlistentry>
157 <term><option>--name=</option><replaceable>NAME</replaceable></term>
158 <listitem>
159 <para>Before proceeding, request ownership of the well-known
160 bus name <replaceable>NAME</replaceable>, for example
161 <literal>com.example.Echo</literal>. By default,
162 no name is requested, and the tool can only be addressed by
163 a unique bus name such as <literal>:1.23</literal>.</para>
164 </listitem>
165 </varlistentry>
166
167 <varlistentry>
168 <term><option>--sleep-ms=</option><replaceable>MS</replaceable></term>
169 <listitem>
170 <para>Block for <replaceable>MS</replaceable> milliseconds
171 before replying to a method call.</para>
172 </listitem>
173 </varlistentry>
174
175 </variablelist>
176 </refsect2>
177
178 <refsect2>
179 <title>spam mode</title>
180 <variablelist remap="TP">
181
182 <varlistentry>
183 <term><option>--dest=</option><replaceable>NAME</replaceable></term>
184 <listitem>
185 <para>Send method calls to the well-known or unique
186 bus name <replaceable>NAME</replaceable>.
187 The default is the dbus-daemon,
188 <literal>org.freedesktop.DBus</literal>.</para>
189 </listitem>
190 </varlistentry>
191
192 <varlistentry>
193 <term><option>--count=</option><replaceable>N</replaceable></term>
194 <listitem>
195 <para>Send <replaceable>N</replaceable> method calls in total.
196 The default is 1.</para>
197 </listitem>
198 </varlistentry>
199
200 <varlistentry>
201 <term><option>--queue=</option><replaceable>N</replaceable></term>
202 <listitem>
203 <para>Send <replaceable>N</replaceable> method calls before
204 waiting for any replies, then send one new call per reply
205 received, keeping <replaceable>N</replaceable> method calls
206 "in flight" at all times until the number of messages specified
207 with the <option>--count</option> option have been sent.
208 The default is 1, unless <option>--flood</option>
209 is used.</para>
210 </listitem>
211 </varlistentry>
212
213 <varlistentry>
214 <term><option>--flood</option></term>
215 <listitem>
216 <para>Send all messages without waiting for a reply,
217 equivalent to <option>--queue</option> with an arbitrarily
218 large <replaceable>N</replaceable>.</para>
219 </listitem>
220 </varlistentry>
221
222 <varlistentry>
223 <term><option>--no-reply</option></term>
224 <listitem>
225 <para>Set the "no reply desired" flag on the messages.
226 This implies <option>--flood</option>, since it disables
227 the replies that would be used for a finite
228 <option>--queue</option> length.</para>
229 </listitem>
230 </varlistentry>
231
232 <varlistentry>
233 <term><option>--messages-per-conn=</option><replaceable>N</replaceable></term>
234 <listitem>
235 <para>If given, send <replaceable>N</replaceable> method calls
236 on the same connection, then disconnect and reconnect.
237 The default is to use the same connection for all method
238 calls.</para>
239 </listitem>
240 </varlistentry>
241
242 <varlistentry>
243 <term><option>--string</option></term>
244 <listitem>
245 <para>The payload of each message is a UTF-8 string. This is the
246 default. The actual string used is given by the
247 <option>--payload</option> or <option>--stdin</option>
248 option, defaulting to "hello, world!".</para>
249 </listitem>
250 </varlistentry>
251
252 <varlistentry>
253 <term><option>--bytes</option></term>
254 <listitem>
255 <para>The payload of each message is a byte-array.
256 The actual bytes used are given by the
257 <option>--payload</option> or <option>--stdin</option>
258 option, defaulting to the ASCII encoding of
259 "hello, world!".</para>
260 </listitem>
261 </varlistentry>
262
263 <varlistentry>
264 <term><option>--empty</option></term>
265 <listitem>
266 <para>The messages have no payload.</para>
267 </listitem>
268 </varlistentry>
269
270 <varlistentry>
271 <term><option>--payload=</option><replaceable>S</replaceable></term>
272 <listitem>
273 <para>Use <replaceable>S</replaceable> as the
274 <option>--string</option> or <option>--bytes</option>
275 in the messages. The default is "hello, world!".</para>
276 </listitem>
277 </varlistentry>
278
279 <varlistentry>
280 <term><option>--stdin</option></term>
281 <listitem>
282 <para>Read from standard input until end-of-file is reached,
283 and use that as the <option>--string</option> or
284 <option>--bytes</option> in the messages.</para>
285 </listitem>
286 </varlistentry>
287
288 <varlistentry>
289 <term><option>--message-stdin</option></term>
290 <listitem>
291 <para>Read a complete binary D-Bus method call message from
292 standard input, and use that for each method call.</para>
293 </listitem>
294 </varlistentry>
295
296 <varlistentry>
297 <term><option>--random-size</option></term>
298 <listitem>
299 <para>Read whitespace-separated ASCII decimal numbers from
300 standard input, choose one at random for each message,
301 and send a message whose payload is a string of that
302 length.</para>
303 </listitem>
304 </varlistentry>
305
306 <varlistentry>
307 <term><option>--seed=</option><replaceable>SEED</replaceable></term>
308 <listitem>
309 <para>Use <replaceable>SEED</replaceable> as the seed
310 for the pseudorandom number generator, to have somewhat
311 repeatable sequences of random messages.</para>
312 </listitem>
313 </varlistentry>
314
315 </variablelist>
316 </refsect2>
317 </refsect1>
318
319 <refsect1 id="bugs">
320 <title>BUGS</title>
321 <para>Please send bug reports to the D-Bus bug tracker or mailing list.
322 See <ulink url="https://www.freedesktop.org/wiki/Software/dbus/">https://www.freedesktop.org/wiki/Software/dbus/</ulink>.</para>
323 </refsect1>
324
325 <refsect1 id='author'>
326 <title>AUTHOR</title>
327 <para>See <ulink url='https://dbus.freedesktop.org/doc/AUTHORS'>https://dbus.freedesktop.org/doc/AUTHORS</ulink></para>
328 </refsect1>
329
330 <refsect1 id="see_also">
331 <title>SEE ALSO</title>
332 <para><citerefentry><refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum></citerefentry></para>
333 </refsect1>
334 </refentry>