diff options
author | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2015-02-11 16:59:42 +0000 |
---|---|---|
committer | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2015-02-12 14:13:03 +0000 |
commit | 15506779a70d8ac38c2bb302ab83d2c1924aea6d (patch) | |
tree | f151a45f45bcfbe62e9239d8c27bec428228c50d /doc | |
parent | e161ec72143d58aff1243d1d88f11907eed0becb (diff) | |
download | dbus-15506779a70d8ac38c2bb302ab83d2c1924aea6d.tar.gz |
Document dbus-test-tool
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=89086
Reviewed-by: Philip Withnall <philip.withnall@collabora.co.uk>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/Makefile.am | 1 | ||||
-rw-r--r-- | doc/dbus-test-tool.1.xml.in | 325 |
2 files changed, 326 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index b9a4c106..3879a614 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -7,6 +7,7 @@ man_pages = \ dbus-monitor.1 \ dbus-run-session.1 \ dbus-send.1 \ + dbus-test-tool.1 \ dbus-uuidgen.1 \ $(NULL) diff --git a/doc/dbus-test-tool.1.xml.in b/doc/dbus-test-tool.1.xml.in new file mode 100644 index 00000000..091dee14 --- /dev/null +++ b/doc/dbus-test-tool.1.xml.in @@ -0,0 +1,325 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> +<refentry id="dbus-test-tool.1"> + <refentryinfo> + <copyright> + <year>2015</year> + <holder>Collabora Ltd.</holder> + </copyright> + <legalnotice> + <para>This man page is distributed under the same terms as + dbus-test-tool (GPL-2+). There is NO WARRANTY, to the extent + permitted by law.</para> + </legalnotice> + </refentryinfo> + + <refmeta> + <refentrytitle>dbus-test-tool</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="manual">User Commands</refmiscinfo> + <refmiscinfo class="source">D-Bus</refmiscinfo> + <refmiscinfo class="version">@DBUS_VERSION@</refmiscinfo> + </refmeta> + <refnamediv> + <refname>dbus-test-tool</refname> + <refpurpose>D-Bus traffic generator and test tool</refpurpose> + </refnamediv> + + <refsynopsisdiv id="synopsis"> + <cmdsynopsis> + <command>dbus-test-tool</command> + <arg choice="plain">black-hole</arg> + <group choice="opt"> + <arg choice="plain">--session</arg> + <arg choice="plain">--system</arg> + </group> + <arg choice="opt">--name=<replaceable>NAME</replaceable></arg> + <arg choice="opt">--no-read</arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>dbus-test-tool</command> + <arg choice="plain">echo</arg> + <group choice="opt"> + <arg choice="plain">--session</arg> + <arg choice="plain">--system</arg> + </group> + <arg choice="opt">--name=<replaceable>NAME</replaceable></arg> + <arg choice="opt">--sleep=<replaceable>MS</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>dbus-test-tool</command> + <arg choice="plain">spam</arg> + <group choice="opt"> + <arg choice="plain">--session</arg> + <arg choice="plain">--system</arg> + </group> + <arg choice="opt">--dest=<replaceable>NAME</replaceable></arg> + <arg choice="opt">--count=<replaceable>N</replaceable></arg> + <arg choice="opt">--flood</arg> + <arg choice="opt">--ignore-errors</arg> + <arg choice="opt">--messages-per-conn=<replaceable>N</replaceable></arg> + <arg choice="opt">--no-reply</arg> + <arg choice="opt">--queue=<replaceable>N</replaceable></arg> + <arg choice="opt">--seed=<replaceable>SEED</replaceable></arg> + <group choice="opt"> + <arg choice="plain">--string</arg> + <arg choice="plain">--bytes</arg> + <arg choice="plain">--empty</arg> + </group> + <group choice="opt"> + <arg choice="plain">--payload=<replaceable>S</replaceable></arg> + <arg choice="plain">--stdin</arg> + <arg choice="plain">--message-stdin</arg> + <arg choice="plain">--random-size</arg> + </group> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1 id="description"> + <title>DESCRIPTION</title> + <para><command>dbus-test-tool</command> is a multi-purpose tool + for debugging and profiling D-Bus.</para> + + <para><command>dbus-test-tool black-hole</command> + connects to D-Bus, optionally requests a name, then does not + reply to messages. It normally reads and discards messages from + its D-Bus socket, but can be configured to sleep forever without + reading.</para> + + <para><command>dbus-test-tool echo</command> + connects to D-Bus, optionally requests a name, then sends back an + empty reply to every method call, after an optional delay.</para> + + <para><command>dbus-test-tool spam</command> + connects to D-Bus and makes repeated method calls, + normally named <literal>com.example.Spam</literal>.</para> + </refsect1> + + <refsect1 id="options"> + <title>OPTIONS</title> + <refsect2> + <title>Common options</title> + <variablelist remap="TP"> + + <varlistentry> + <term><option>--session</option></term> + <listitem> + <para>Connect to the session bus. This is the default.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--system</option></term> + <listitem> + <para>Connect to the system bus.</para> + </listitem> + </varlistentry> + + </variablelist> + </refsect2> + + <refsect2> + <title>black-hole mode</title> + <variablelist remap="TP"> + + <varlistentry> + <term><option>--name=</option><replaceable>NAME</replaceable></term> + <listitem> + <para>Before proceeding, request ownership of the well-known + bus name <replaceable>NAME</replaceable>, for example + <literal>com.example.NoReply</literal>. By default, + no name is requested, and the tool can only be addressed by + a unique bus name such as <literal>:1.23</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-read</option></term> + <listitem> + <para>Do not read from the D-Bus socket.</para> + </listitem> + </varlistentry> + + </variablelist> + </refsect2> + + <refsect2> + <title>echo mode</title> + <variablelist remap="TP"> + + <varlistentry> + <term><option>--name=</option><replaceable>NAME</replaceable></term> + <listitem> + <para>Before proceeding, request ownership of the well-known + bus name <replaceable>NAME</replaceable>, for example + <literal>com.example.Echo</literal>. By default, + no name is requested, and the tool can only be addressed by + a unique bus name such as <literal>:1.23</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--sleep=</option><replaceable>MS</replaceable></term> + <listitem> + <para>Block for <replaceable>MS</replaceable> milliseconds + before replying to a method call.</para> + </listitem> + </varlistentry> + + </variablelist> + </refsect2> + + <refsect2> + <title>spam mode</title> + <variablelist remap="TP"> + + <varlistentry> + <term><option>--dest=</option><replaceable>NAME</replaceable></term> + <listitem> + <para>Send method calls to the well-known or unique + bus name <replaceable>NAME</replaceable>. + The default is the dbus-daemon, + <literal>org.freedesktop.DBus</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--count=</option><replaceable>N</replaceable></term> + <listitem> + <para>Send <replaceable>N</replaceable> method calls in total. + The default is 1.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--queue=</option><replaceable>N</replaceable></term> + <listitem> + <para>Send <replaceable>N</replaceable> method calls before + waiting for any replies, then send one new call per reply + received, keeping <replaceable>N</replaceable> method calls + "in flight" at all times until the number of messages specified + with the <option>--count</option> option have been sent. + The default is 1, unless <option>--flood</option> + is used.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--flood</option></term> + <listitem> + <para>Send all messages without waiting for a reply, + equivalent to <option>--queue</option> with an arbitrarily + large <replaceable>N</replaceable>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-reply</option></term> + <listitem> + <para>Set the "no reply desired" flag on the messages. + This implies <option>--flood</option>, since it disables + the replies that would be used for a finite + <option>--queue</option> length.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--messages-per-conn=</option><replaceable>N</replaceable></term> + <listitem> + <para>If given, send <replaceable>N</replaceable> method calls + on the same connection, then disconnect and reconnect. + The default is to use the same connection for all method + calls.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--string</option></term> + <listitem> + <para>The payload of each message is a UTF-8 string. This is the + default. The actual string used is given by the + <option>--payload</option> or <option>--stdin</option> + option, defaulting to "hello, world!".</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--bytes</option></term> + <listitem> + <para>The payload of each message is a byte-array. + The actual bytes used are given by the + <option>--payload</option> or <option>--stdin</option> + option, defaulting to the ASCII encoding of + "hello, world!".</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--empty</option></term> + <listitem> + <para>The messages have no payload.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--payload=</option><replaceable>S</replaceable></term> + <listitem> + <para>Use <replaceable>S</replaceable> as the + <option>--string</option> or <option>--bytes</option> + in the messages. The default is "hello, world!".</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--stdin</option></term> + <listitem> + <para>Read from standard input until end-of-file is reached, + and use that as the <option>--string</option> or + <option>--bytes</option> in the messages.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--message-stdin</option></term> + <listitem> + <para>Read a complete binary D-Bus method call message from + standard input, and use that for each method call.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--random-size</option></term> + <listitem> + <para>Read whitespace-separated ASCII decimal numbers from + standard input, choose one at random for each message, + and send a message whose payload is a string of that + length.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--seed=</option><replaceable>SEED</replaceable></term> + <listitem> + <para>Use <replaceable>SEED</replaceable> as the seed + for the pseudorandom number generator, to have somewhat + repeatable sequences of random messages.</para> + </listitem> + </varlistentry> + + </variablelist> + </refsect2> + </refsect1> + + <refsect1 id="bugs"> + <title>BUGS</title> + <para>Please send bug reports to the D-Bus bug tracker or mailing list. + See <ulink url="http://www.freedesktop.org/software/dbus/">http://www.freedesktop.org/software/dbus/</ulink>.</para> + </refsect1> + + <refsect1 id="see_also"> + <title>SEE ALSO</title> + <para><citerefentry><refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum></citerefentry></para> + </refsect1> +</refentry> |