dbus-tool is a multipurpose command line utility for the DBus interprocess communication system. Using dbus-tool we can inspect services, get/set property values, listen for signals, send signals, call methods, and more.
dbus-tool by default connects to the session bus and performs the requested command. Normal output is printed to standard output, errors are printed to standard error. On errors, dbus-tool exits with exit code 1, and on success the exit code is 0.
Synopsis: dbus-tool [COMMON-OPTIONS...] COMMAND [command arguments...]
Option | Description |
---|---|
-y , --system |
Connect to the system bus instead of the session bus. |
-b , --bus=ADDRESS |
Connect to a specific bus address. Ignoring parameter -y . |
-t , --timeout=MILLISECONDS |
Set a specific timeout when waiting for message replies. |
-v , --version |
Print version information and exit. |
-h , --help |
Print help and exit. |
dbus-tool [COMMON_OPTIONS] list [OPTIONS]
List the services (bus names) on this connection.
Options | Description |
---|---|
-a , --all |
Also include unique bus names. |
-x , --activatable |
Instead of already connected names, list all names that can be activated on the bus. |
dbus-tool [COMMON_OPTIONS] introspect [OPTIONS] <service> [object_path]
Print introspect data for a specific object path in a DBus service.
If the object_path
arguments is omitted, the root object /
is used.
Options | Description |
---|---|
-r , --raw |
Don't parse the introspect data, print it "as is". |
dbus-tool [COMMON_OPTIONS] get [OPTIONS] <service> <object_path> <interface> [property]
Get the property of an object in a DBus service.
If argument property
is omitted, the names and values of all properties are printed to standard output.
Options | Description |
---|---|
-s , --signature |
Also print the DBus signature of the properties. |
dbus-tool [COMMON_OPTIONS] set <service> <object_path> <interface> <property> [signature] <value>
Set the property of an object in a DBus service. The signature of the value can omitted if the value is a boolean(true|false), string, or a signed integer.
dbus-tool [COMMON_OPTIONS] call [OPTIONS] <service> <object_path> <interface> <method> [signature argument...]
Call a specific method in an object/interface in a DBus service. Any returned argument from the method is printed to standard output. Arguments to the method begins with a DBus signature, followed by the argument value. If there is only a single argument, the signature can be omitted if the argument is a boolean(true|false), string, or a signed integer.
Options | Description |
---|---|
-s , --signature |
When printing the reply arguments, also print the DBus signature of the arguments. |
dbus-tool [COMMON_OPTIONS] signal <service> <object_path> <interface> <signal-name> [signature argument...]
Acquire a service name and send a DBus signal from that service. This command will connect to the DBus and acquire the specified service name. Then it will send a signal with the specified object path and interface. Arguments to the signal begins with a DBus signature, then the argument value. If there is only a single argument, the signature can be omitted if the argument is a boolean(true|false), string, or a signed integer.
dbus-tool [COMMON_OPTIONS] listen [OPTIONS] <service> <object_path> <interface> [signal]
Listen for DBus signals from the specified object path using the specified interface. If a signal name is specified, only that signal will be caught. If no signal name is specified, all signals from that object path and interface will be caught. The signals will be printed to standard output. Stop listening and exit the program by pressing Ctrl-C.
Options | Description |
---|---|
-s , --signature |
When printing the signal arguments, also print the DBus signature of the arguments. |
dbus-tool [COMMON_OPTIONS] monitor
Monitor messages on the message bus and display them on standard output. Stop and exit by pressing Ctrl-C.
dbus-tool [COMMON_OPTIONS] ping [OPTIONS] <service>
Ping a service on the bus and print the response time in milliseconds.
Options | Description |
---|---|
-q , --quiet |
Suppress normal output, exit with 0 on success and 1 on failure. |
dbus-tool [COMMON_OPTIONS] owner <service>
Print the unique bus name of the primary owner of the service name.
dbus-tool [COMMON_OPTIONS] names <bus-name>
Print the names acquired by the specified bus connection.
dbus-tool [COMMON_OPTIONS] start [OPTIONS] <service>
Try to launch the executable associated with a service name.
Options | Description |
---|---|
-q , --quiet |
Suppress normal output, exit with 0 on success and 1 on failure. |
When using commands set, call, and signal, there is an option to send arguments to the commands. All DBus arguments must be of a specific type. There are 13 primitive types and 4 container types in the DBus protocol. All types has what is called a signature that tells what type it is. So when sending DBus arguments, first type the signature of the argument, and then the argument itself. This sequence is repeated for all arguments sent with the command. An example:
$ dbus-tool call some.interface /an/object/path an.interface Method i 42 b true
In this example, i 42 b true
are the two arguments sent to the method we call. The first argument has signature i
(a 32-bit signed integer) and value 42
. The second argument has signature b
(boolean) and value true
.
Here is a list of the 13 primitive types and their signatures:
Signature | Type | Description |
---|---|---|
y |
byte | Unsigned 8-bit integer. |
b |
boolean | A boolean value. Can be written as 0 , 1 , false , or true . |
n |
int16 | Signed 16-bit integer. |
q |
uint16 | Unsigned 16-bit integer. |
i |
int32 | Signed 32-bit integer. |
u |
uint32 | Unsigned 32-bit integer. |
x |
int64 | Signed 64-bit integer. |
t |
uint64 | Signed 64-bit integer. |
d |
double | IEEE 754 double-precision floating point. |
h |
unix_fd | Unix file descriptor. A signed 32-bit integer. |
s |
string | A string. When passing string values, they must be enclosed by either double quotes " or single quotes ' . |
o |
object_path | An object path (string). |
g |
signature | A DBus signature (string). |
And here are the 4 container types and their signatures:
Signature | Type | Description |
---|---|---|
a... |
array | An array. The a is followed by the signature of the array element type. |
(...) |
struct | A struct. Within the parenthesis are the signatures of the struct attributes. |
{...} |
dict_entry | A dict entry is a key-value pair. Within the brackets are the signatures of the key and the value. The key must be a primitive type. A dict entry is a type that can only be found as an array element. |
v |
variant | A variant. A variant means that the value can be of any DBus type. |
Signature examples:
- An unsigned 32-bit integer:
u
- An array with signed 16-bit integers:
an
- A struct containing a boolean and a string:
(bs)
- An array of structs containing boolean and a string:
a(bs)
- An array of key-value pairs where the key is a signed 32-bit integer and the value is a string:
a{is}
- A struct with a boolean, an array of key-value pairs as above, and an object path:
(ba{is}o)
After the signature of the DBus argument comes the actual value of the argument.
Numeric values are written as normal numerical values.
Example: 42
Boolean values are written as 0
, 1
, false
, or true
.
Example: false
Example: 1
String values are written as UTF-8 strings enclosed by single or double quotes. Some special characters must be escaped within the string:
Character | Escape sequence | Comment |
---|---|---|
carriage return | \r |
|
line feed | \n |
|
form feed | \f |
|
tab | \t |
|
backspace | \b |
|
reverse solidus | \\ |
|
double quote | \" |
Only required when the string is enclosed by double quotes. |
single quote | \' |
Only required when the string is enclosed by single quotes. |
Example: "Hello World!"
Example: 'First line.\nSecond line.'
Example: "This is a \"quoted\" word in a string."
Important Note!
When entering a string on the command line in a shell, the string command line argument needs to be enclosed by (double)quotes, or special characters escaped. So, on the command line in a bash shell, a DBus string value would be written as:
'"Hello World!"'
or:
"'Hello World!'"
or:
\"Hello\ World!\"
Array values are written as a sequence of item values separated by comma(,
) and enclosed by [
and ]
.
Example: [0,1,2,3]
Example: [false,true,false,false,false,true]
Example: ["Array","of","strings"]
Struct values are written as a sequence of attribute values separated by comma(,
) and enclosed by {
and }
.
Example (a struct with a string and an integer):
{"Answer",42}
Example (a struct with a boolean, an integer and a string):
{true,42,"Hello World!"}
A dict entry value written as a key and value separated by comma(,
) enclosed by (
and )
.
Since a dice entry type is only permitted as an element type of an array, they can only written as array values.
Example (the key is an integer and the value a string): [(1,"first"),(2,"second")]
Example (the key is a string and the value a boolean): [("array",true),("struct",false),("dict-entry",true)]
A variant is a special DBus type that can hold a value of any other DBus type. But since the dbus-tool must know what DBus type we are to send as the variant value, we must specify what value type we are sending. In order to do that we enter a prefix to the value. The prefix is the signature of the value followed by an underscore _
.
So in order to send a signed 32-bit integer as a variant value we write the value like this: i_42
.
Example (we are sending a 32-bit signed integer as a variant value): i_42
Example (a string as variant value): s_"Hello World!"
Example (an array of 32-bit unsigned integers as variant value): au_[1,2,3,4]
Example (an array of variants as variant value): av_[i_42,s_"string",b_true]
An example of a dbus-tool command that sends DBus arguments can look like this:
$ dbus-tool call my.example.service /object/path my.example.interface Method i 42
In the examples bellow we will, for clarity, shorten the part my.example.service /object/path my.example.interface Method
to ...
.
Pass an integer from a bash shell:
$ dbus-tool call ... i 42
Pass a string from a bash shell:
$ dbus-tool call ... s '"Hello World"'
Pass an integer and a string from a bash shell:
$ dbus-tool call ... i 42 s '"Hello World"'
Pass an array of 32-bit signed integers from a bash shell:
$ dbus-tool cal ... ai [1,2,3,4]
Pass a struct with an unsigned integer and a string from a bash shell:
$ dbus-tool call ... '(us)' '{42,"Answer"}'
Pass a booelan, a signed integer, and a struct with an unsigned integer and a string as attributes from a bash shell:
$ dbus-tool call ... b false i 32 '(us)' '{42,"Answer"}'
Pass an array of structs with a string and a boolean as attributes from a bash shell:
$ dbus-tool call ... 'a(sb)' '["First",true,"Second",true,"Third",false]'
Pass an array of arrays of integers from a bash shell:
$ dbus-tool call ... aai [[0,1,2,3],[42,32],[3489,2343,23543,52326]]
Pass an array of dict entries with strings as keys and booleans as values from a bash shell:
$ dbus-tool call ... a{sb} '[("On",true),("Off",false),("Other",false)]'
Pass an array of dict entries with integers as keys and variants as values from a bash shell:
$ dbus-tool call ... a{iv} '[(0,i_42),(1,s_"Hello\nLine 2"),(2,ai_[1,2,3])]'
The following examples were executed in a bash shell window running in an Ubuntu Linux system.
$ dbus-tool list
org.freedesktop.DBus
org.freedesktop.IBus
org.freedesktop.IBus.Panel.Extension.Gtk3
org.freedesktop.Notifications
org.freedesktop.PackageKit
org.freedesktop.ScreenSaver
org.freedesktop.systemd1
...
$ dbus-tool ping org.freedesktop.DBus
0.493 ms
Get the unique bus name of the DBus service "org.freedesktop.Notifications", then list all service names registered by that DBus connection:
$ dbus-tool owner org.freedesktop.Notifications
:1.50
$ dbus-tool names :1.50
:1.50
org.freedesktop.Notifications
org.gnome.Shell.Notifications
When using command names, the argument doesn't have to be a unique name:
$ dbus-tool names org.freedesktop.Notifications
:1.50
org.freedesktop.Notifications
org.gnome.Shell.Notifications
$ dbus-tool introspect org.freedesktop.Notifications
Service: org.freedesktop.Notifications
Object path: /
Interfaces:
Nodes:
org
$ dbus-tool introspect org.freedesktop.Notifications /org
Service: org.freedesktop.Notifications
Object path: /org
Interfaces:
Nodes:
freedesktop
$ dbus-tool introspect org.freedesktop.Notifications /org/freedesktop
Service: org.freedesktop.Notifications
Object path: /org/freedesktop
Interfaces:
Nodes:
Notifications
$ dbus-tool introspect org.freedesktop.Notifications /org/freedesktop/Notifications
Service: org.freedesktop.Notifications
Object path: /org/freedesktop/Notifications
Interfaces:
org.freedesktop.DBus.Properties
Methods:
Get
IN: interface_name(s), property_name(s)
OUT: value(v)
GetAll
IN: interface_name(s)
OUT: properties(a{sv})
Set
IN: interface_name(s), property_name(s), value(v)
Signals:
PropertiesChanged
ARG: interface_name(s), changed_properties(a{sv}), invalidated_properties(as)
org.freedesktop.DBus.Introspectable
Methods:
Introspect
OUT: xml_data(s)
org.freedesktop.DBus.Peer
Methods:
Ping
GetMachineId
OUT: machine_uuid(s)
org.freedesktop.Notifications
Methods:
Notify
IN: arg_0(s), arg_1(u), arg_2(s), arg_3(s), arg_4(s), arg_5(as), arg_6(a{sv}), arg_7(i)
OUT: arg_8(u)
CloseNotification
IN: arg_0(u)
GetCapabilities
OUT: arg_0(as)
GetServerInformation
OUT: arg_3(s)
Signals:
NotificationClosed
ARG: arg_0(u), arg_1(u)
ActionInvoked
ARG: arg_0(u), arg_1(s)
$ dbus-tool introspect --raw org.freedesktop.Notifications /org/freedesktop/Notifications
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<!-- GDBus 2.72.4 -->
<node>
<interface name="org.freedesktop.DBus.Properties">
<method name="Get">
<arg type="s" name="interface_name" direction="in"/>
<arg type="s" name="property_name" direction="in"/>
<arg type="v" name="value" direction="out"/>
</method>
<method name="GetAll">
<arg type="s" name="interface_name" direction="in"/>
<arg type="a{sv}" name="properties" direction="out"/>
</method>
<method name="Set">
<arg type="s" name="interface_name" direction="in"/>
<arg type="s" name="property_name" direction="in"/>
<arg type="v" name="value" direction="in"/>
</method>
<signal name="PropertiesChanged">
<arg type="s" name="interface_name"/>
<arg type="a{sv}" name="changed_properties"/>
<arg type="as" name="invalidated_properties"/>
</signal>
</interface>
<interface name="org.freedesktop.DBus.Introspectable">
<method name="Introspect">
<arg type="s" name="xml_data" direction="out"/>
</method>
</interface>
<interface name="org.freedesktop.DBus.Peer">
<method name="Ping"/>
<method name="GetMachineId">
<arg type="s" name="machine_uuid" direction="out"/>
</method>
</interface>
<interface name="org.freedesktop.Notifications">
<method name="Notify">
<arg type="s" name="arg_0" direction="in">
</arg>
<arg type="u" name="arg_1" direction="in">
</arg>
<arg type="s" name="arg_2" direction="in">
</arg>
<arg type="s" name="arg_3" direction="in">
</arg>
<arg type="s" name="arg_4" direction="in">
</arg>
<arg type="as" name="arg_5" direction="in">
</arg>
<arg type="a{sv}" name="arg_6" direction="in">
</arg>
<arg type="i" name="arg_7" direction="in">
</arg>
<arg type="u" name="arg_8" direction="out">
</arg>
</method>
<method name="CloseNotification">
<arg type="u" name="arg_0" direction="in">
</arg>
</method>
<method name="GetCapabilities">
<arg type="as" name="arg_0" direction="out">
</arg>
</method>
<method name="GetServerInformation">
<arg type="s" name="arg_0" direction="out">
</arg>
<arg type="s" name="arg_1" direction="out">
</arg>
<arg type="s" name="arg_2" direction="out">
</arg>
<arg type="s" name="arg_3" direction="out">
</arg>
</method>
<signal name="NotificationClosed">
<arg type="u" name="arg_0">
</arg>
<arg type="u" name="arg_1">
</arg>
</signal>
<signal name="ActionInvoked">
<arg type="u" name="arg_0">
</arg>
<arg type="s" name="arg_1">
</arg>
</signal>
</interface>
</node>
$ dbus-tool call org.freedesktop.Notifications /org/freedesktop/Notifications org.freedesktop.Notifications Notify s '"dbus-tool"' u 0 s '"applications-utilities"' s '"Example Notification"' s '"This is an example of a notification sent from dbus-tool."' as [] a{sv} [] i 3000
Get the brightness of the screen by reading property "Brightness" of interface "org.gnome.SettingsDaemon.Power.Screen" at object path "/org/gnome/SettingsDaemon/Power" in service "org.gnome.SettingsDaemon.Power":
$ dbus-tool get org.gnome.SettingsDaemon.Power /org/gnome/SettingsDaemon/Power org.gnome.SettingsDaemon.Power.Screen Brightness
41
Set the brightness of the screen by setting property "Brightness" of interface "org.gnome.SettingsDaemon.Power.Screen" at object path "/org/gnome/SettingsDaemon/Power" in service "org.gnome.SettingsDaemon.Power":
(Since the property value is a single signed 32-bit integer, we don't have to specify the DBus signature of the argument)
$ dbus-tool set org.gnome.SettingsDaemon.Power /org/gnome/SettingsDaemon/Power org.gnome.SettingsDaemon.Power.Screen Brightness 60
(option -s is used to see the DBus signature of the arguments)
$ dbus-tool listen -s org.gnome.SettingsDaemon.Power /org/gnome/SettingsDaemon/Power org.freedesktop.DBus.Properties PropertiesChanged
Got signal: PropertiesChanged
Interface: org.freedesktop.DBus.Properties
Arguments:
s org.gnome.SettingsDaemon.Power.Keyboard
a{sv} [(Brightness,50)]
as []
Got signal: PropertiesChanged
Interface: org.freedesktop.DBus.Properties
Arguments:
s org.gnome.SettingsDaemon.Power.Screen
a{sv} [(Brightness,55)]
as []
Got signal: PropertiesChanged
Interface: org.freedesktop.DBus.Properties
Arguments:
s org.gnome.SettingsDaemon.Power.Screen
a{sv} [(Brightness,60)]
as []
^C$
This example makes a connections to the session bus, registers service name "se.ultramarin.ultrabus" and then sends a signal named "TestSignal" using interface "se.ultramarin.ultrabus.example" and object path "/se/ultramarin/ultrabus/example". The signal is sent with three arguments. The first argument is a boolean. The second argument is a string. And the third argument is an array of variants. The array of variants has three elements, one signed 32-bit integer, one string, and finally one array of unsigned 32-bit integers.
$ dbus-tool signal se.ultramarin.ultrabus /se/ultramarin/ultrabus/example se.ultramarin.ultrabus.example TestSignal b true s '"Hello World!"' av [i_42,s_\"Hello\",au_[1,2,3]]
To se the signal, first open another window with a shell and use dbus-tool to listen for signals from object path "/se/ultramarin/ultrabus/example" in service "se.ultramarin.ultrabus" (option -s is used to see the DBus signature of the arguments):
$ dbus-tool listen -s se.ultramarin.ultrabus /se/ultramarin/ultrabus/example "" ""
Got signal: TestSignal
Interface: se.ultramarin.ultrabus.example
Arguments:
b true
s Hello World!
av [42,Hello,[1,2,3]]
^C$