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

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