-<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<!--
- SPDX-License-Identifier: LGPL-2.1+
-
- This file is part of systemd.
-
- Copyright 2014 Zbigniew Jędrzejewski-Szmek
--->
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="busctl"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>busctl</title>
<productname>systemd</productname>
-
- <authorgroup>
- <author>
- <contrib>A monkey with a typewriter</contrib>
- <firstname>Zbigniew</firstname>
- <surname>Jędrzejewski-Szmek</surname>
- <email>zbyszek@in.waw.pl</email>
- </author>
- </authorgroup>
</refentryinfo>
<refmeta>
introspect and monitor the D-Bus bus.</para>
</refsect1>
+ <refsect1>
+ <title>Commands</title>
+
+ <para>The following commands are understood:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><command>list</command></term>
+
+ <listitem><para>Show all peers on the bus, by their service
+ names. By default, shows both unique and well-known names, but
+ this may be changed with the <option>--unique</option> and
+ <option>--acquired</option> switches. This is the default
+ operation if no command is specified.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>status</command> <arg choice="opt"><replaceable>SERVICE</replaceable></arg></term>
+
+ <listitem><para>Show process information and credentials of a
+ bus service (if one is specified by its unique or well-known
+ name), a process (if one is specified by its numeric PID), or
+ the owner of the bus (if no parameter is
+ specified).</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>monitor</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
+
+ <listitem><para>Dump messages being exchanged. If
+ <replaceable>SERVICE</replaceable> is specified, show messages
+ to or from this peer, identified by its well-known or unique
+ name. Otherwise, show all messages on the bus. Use
+ <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>
+ to terminate the dump.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>capture</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
+
+ <listitem><para>Similar to <command>monitor</command> but
+ writes the output in pcap format (for details, see the <ulink
+ url="https://wiki.wireshark.org/Development/LibpcapFileFormat">Libpcap
+ File Format</ulink> description). Make sure to redirect
+ standard output to a file. Tools like
+ <citerefentry project='die-net'><refentrytitle>wireshark</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ may be used to dissect and view the resulting
+ files.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>tree</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
+
+ <listitem><para>Shows an object tree of one or more
+ services. If <replaceable>SERVICE</replaceable> is specified,
+ show object tree of the specified services only. Otherwise,
+ show all object trees of all services on the bus that acquired
+ at least one well-known name.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>introspect</command> <arg choice="plain"><replaceable>SERVICE</replaceable></arg> <arg choice="plain"><replaceable>OBJECT</replaceable></arg> <arg choice="opt"><replaceable>INTERFACE</replaceable></arg></term>
+
+ <listitem><para>Show interfaces, methods, properties and
+ signals of the specified object (identified by its path) on
+ the specified service. If the interface argument is passed, the
+ output is limited to members of the specified
+ interface.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>call</command> <arg choice="plain"><replaceable>SERVICE</replaceable></arg> <arg choice="plain"><replaceable>OBJECT</replaceable></arg> <arg choice="plain"><replaceable>INTERFACE</replaceable></arg> <arg choice="plain"><replaceable>METHOD</replaceable></arg> <arg choice="opt"><replaceable>SIGNATURE</replaceable> <arg choice="opt" rep="repeat"><replaceable>ARGUMENT</replaceable></arg></arg></term>
+
+ <listitem><para>Invoke a method and show the response. Takes a
+ service name, object path, interface name and method name. If
+ parameters shall be passed to the method call, a signature
+ string is required, followed by the arguments, individually
+ formatted as strings. For details on the formatting used, see
+ below. To suppress output of the returned data, use the
+ <option>--quiet</option> option.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>emit</command> <arg choice="plain"><replaceable>OBJECT</replaceable></arg> <arg choice="plain"><replaceable>INTERFACE</replaceable></arg> <arg choice="plain"><replaceable>SIGNAL</replaceable></arg> <arg choice="opt"><replaceable>SIGNATURE</replaceable> <arg choice="opt" rep="repeat"><replaceable>ARGUMENT</replaceable></arg></arg></term>
+
+ <listitem><para>Emit a signal. Takes a object path, interface name and method name. If parameters
+ shall be passed, a signature string is required, followed by the arguments, individually formatted as
+ strings. For details on the formatting used, see below. To specify the destination of the signal,
+ use the <option>--destination=</option> option.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>get-property</command> <arg choice="plain"><replaceable>SERVICE</replaceable></arg> <arg choice="plain"><replaceable>OBJECT</replaceable></arg> <arg choice="plain"><replaceable>INTERFACE</replaceable></arg> <arg choice="plain" rep="repeat"><replaceable>PROPERTY</replaceable></arg></term>
+
+ <listitem><para>Retrieve the current value of one or more
+ object properties. Takes a service name, object path,
+ interface name and property name. Multiple properties may be
+ specified at once, in which case their values will be shown one
+ after the other, separated by newlines. The output is, by
+ default, in terse format. Use <option>--verbose</option> for a
+ more elaborate output format.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>set-property</command> <arg choice="plain"><replaceable>SERVICE</replaceable></arg> <arg choice="plain"><replaceable>OBJECT</replaceable></arg> <arg choice="plain"><replaceable>INTERFACE</replaceable></arg> <arg choice="plain"><replaceable>PROPERTY</replaceable></arg> <arg choice="plain"><replaceable>SIGNATURE</replaceable></arg> <arg choice="plain" rep="repeat"><replaceable>ARGUMENT</replaceable></arg></term>
+
+ <listitem><para>Set the current value of an object
+ property. Takes a service name, object path, interface name,
+ property name, property signature, followed by a list of
+ parameters formatted as strings.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>help</command></term>
+
+ <listitem><para>Show command syntax help.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
<refsect1>
<title>Options</title>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>--xml-interface</option></term>
+
+ <listitem>
+ <para>When used with the <command>introspect</command> call, dump the XML description received from
+ the D-Bus <constant>org.freedesktop.DBus.Introspectable.Introspect</constant> call instead of the
+ normal output.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--json=</option><replaceable>MODE</replaceable></term>
+
+ <listitem>
+ <para>When used with the <command>call</command> or <command>get-property</command> command, shows output
+ formatted as JSON. Expects one of <literal>short</literal> (for the shortest possible output without any
+ redundant whitespace or line breaks) or <literal>pretty</literal> (for a pretty version of the same, with
+ indentation and line breaks). Note that transformation from D-Bus marshalling to JSON is done in a loss-less
+ way, which means type information is embedded into the JSON object tree.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-j</option></term>
+
+ <listitem>
+ <para>Equivalent to <option>--json=pretty</option> when invoked interactively from a terminal. Otherwise
+ equivalent to <option>--json=short</option>, in particular when the output is piped to some other
+ program.</para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>--expect-reply=</option><replaceable>BOOL</replaceable></term>
<term><option>--auto-start=</option><replaceable>BOOL</replaceable></term>
<listitem>
- <para>When used with the <command>call</command> command, specifies
+ <para>When used with the <command>call</command> or <command>emit</command> command, specifies
whether the method call should implicitly activate the
called service, should it not be running yet but is
configured to be auto-started. Defaults to
</listitem>
</varlistentry>
- <xi:include href="user-system-options.xml" xpointer="user" />
- <xi:include href="user-system-options.xml" xpointer="system" />
- <xi:include href="user-system-options.xml" xpointer="host" />
- <xi:include href="user-system-options.xml" xpointer="machine" />
-
- <xi:include href="standard-options.xml" xpointer="no-pager" />
- <xi:include href="standard-options.xml" xpointer="no-legend" />
- <xi:include href="standard-options.xml" xpointer="help" />
- <xi:include href="standard-options.xml" xpointer="version" />
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Commands</title>
-
- <para>The following commands are understood:</para>
-
- <variablelist>
- <varlistentry>
- <term><command>list</command></term>
-
- <listitem><para>Show all peers on the bus, by their service
- names. By default, shows both unique and well-known names, but
- this may be changed with the <option>--unique</option> and
- <option>--acquired</option> switches. This is the default
- operation if no command is specified.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><command>status</command> <arg choice="opt"><replaceable>SERVICE</replaceable></arg></term>
-
- <listitem><para>Show process information and credentials of a
- bus service (if one is specified by its unique or well-known
- name), a process (if one is specified by its numeric PID), or
- the owner of the bus (if no parameter is
- specified).</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><command>monitor</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
-
- <listitem><para>Dump messages being exchanged. If
- <replaceable>SERVICE</replaceable> is specified, show messages
- to or from this peer, identified by its well-known or unique
- name. Otherwise, show all messages on the bus. Use Ctrl-C to
- terminate the dump.</para></listitem>
- </varlistentry>
-
<varlistentry>
- <term><command>capture</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
-
- <listitem><para>Similar to <command>monitor</command> but
- writes the output in pcap format (for details, see the <ulink
- url="https://wiki.wireshark.org/Development/LibpcapFileFormat">Libpcap
- File Format</ulink> description). Make sure to redirect
- standard output to a file. Tools like
- <citerefentry project='die-net'><refentrytitle>wireshark</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- may be used to dissect and view the resulting
- files.</para></listitem>
- </varlistentry>
+ <term><option>--destination=</option><replaceable>SERVICE</replaceable></term>
- <varlistentry>
- <term><command>tree</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
-
- <listitem><para>Shows an object tree of one or more
- services. If <replaceable>SERVICE</replaceable> is specified,
- show object tree of the specified services only. Otherwise,
- show all object trees of all services on the bus that acquired
- at least one well-known name.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><command>introspect</command> <arg choice="plain"><replaceable>SERVICE</replaceable></arg> <arg choice="plain"><replaceable>OBJECT</replaceable></arg> <arg choice="opt"><replaceable>INTERFACE</replaceable></arg></term>
-
- <listitem><para>Show interfaces, methods, properties and
- signals of the specified object (identified by its path) on
- the specified service. If the interface argument is passed, the
- output is limited to members of the specified
- interface.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><command>call</command> <arg choice="plain"><replaceable>SERVICE</replaceable></arg> <arg choice="plain"><replaceable>OBJECT</replaceable></arg> <arg choice="plain"><replaceable>INTERFACE</replaceable></arg> <arg choice="plain"><replaceable>METHOD</replaceable></arg> <arg choice="opt"><replaceable>SIGNATURE</replaceable> <arg choice="opt" rep="repeat"><replaceable>ARGUMENT</replaceable></arg></arg></term>
-
- <listitem><para>Invoke a method and show the response. Takes a
- service name, object path, interface name and method name. If
- parameters shall be passed to the method call, a signature
- string is required, followed by the arguments, individually
- formatted as strings. For details on the formatting used, see
- below. To suppress output of the returned data, use the
- <option>--quiet</option> option.</para></listitem>
+ <listitem>
+ <para>Takes a service name. When used with the <command>emit</command> command, a signal is
+ emitted to the specified service.</para>
+ </listitem>
</varlistentry>
- <varlistentry>
- <term><command>get-property</command> <arg choice="plain"><replaceable>SERVICE</replaceable></arg> <arg choice="plain"><replaceable>OBJECT</replaceable></arg> <arg choice="plain"><replaceable>INTERFACE</replaceable></arg> <arg choice="plain" rep="repeat"><replaceable>PROPERTY</replaceable></arg></term>
-
- <listitem><para>Retrieve the current value of one or more
- object properties. Takes a service name, object path,
- interface name and property name. Multiple properties may be
- specified at once, in which case their values will be shown one
- after the other, separated by newlines. The output is, by
- default, in terse format. Use <option>--verbose</option> for a
- more elaborate output format.</para></listitem>
- </varlistentry>
+ <xi:include href="user-system-options.xml" xpointer="user" />
+ <xi:include href="user-system-options.xml" xpointer="system" />
+ <xi:include href="user-system-options.xml" xpointer="host" />
+ <xi:include href="user-system-options.xml" xpointer="machine" />
<varlistentry>
- <term><command>set-property</command> <arg choice="plain"><replaceable>SERVICE</replaceable></arg> <arg choice="plain"><replaceable>OBJECT</replaceable></arg> <arg choice="plain"><replaceable>INTERFACE</replaceable></arg> <arg choice="plain"><replaceable>PROPERTY</replaceable></arg> <arg choice="plain"><replaceable>SIGNATURE</replaceable></arg> <arg choice="plain" rep="repeat"><replaceable>ARGUMENT</replaceable></arg></term>
+ <term><option>-l</option></term>
+ <term><option>--full</option></term>
- <listitem><para>Set the current value of an object
- property. Takes a service name, object path, interface name,
- property name, property signature, followed by a list of
- parameters formatted as strings.</para></listitem>
+ <listitem>
+ <para>Do not ellipsize the output in <command>list</command> command.</para>
+ </listitem>
</varlistentry>
- <varlistentry>
- <term><command>help</command></term>
-
- <listitem><para>Show command syntax help.</para></listitem>
- </varlistentry>
+ <xi:include href="standard-options.xml" xpointer="no-pager" />
+ <xi:include href="standard-options.xml" xpointer="no-legend" />
+ <xi:include href="standard-options.xml" xpointer="help" />
+ <xi:include href="standard-options.xml" xpointer="version" />
</variablelist>
</refsect1>