2010-05-07 01:39:16 +02:00
<refentry id= "gdbus" lang= "en" >
2012-08-03 00:36:25 +02:00
<refentryinfo >
<title > gdbus</title>
<productname > GIO</productname>
<authorgroup >
<author >
<contrib > Developer</contrib>
<firstname > David</firstname>
<surname > Zeuthen</surname>
<email > zeuthen@gmail.com</email>
</author>
</authorgroup>
</refentryinfo>
2010-05-07 01:39:16 +02:00
<refmeta >
<refentrytitle > gdbus</refentrytitle>
<manvolnum > 1</manvolnum>
<refmiscinfo class= "manual" > User Commands</refmiscinfo>
</refmeta>
<refnamediv >
<refname > gdbus</refname>
2011-06-04 18:33:39 +02:00
<refpurpose > Tool for working with D-Bus objects</refpurpose>
2010-05-07 01:39:16 +02:00
</refnamediv>
<refsynopsisdiv >
<cmdsynopsis >
<command > gdbus</command>
<arg choice= "plain" > introspect</arg>
<group >
<arg choice= "plain" > --system</arg>
<arg choice= "plain" > --session</arg>
<arg choice= "plain" > --address <replaceable > address</replaceable> </arg>
</group>
<arg choice= "plain" > --dest <replaceable > bus_name</replaceable> </arg>
<arg choice= "plain" > --object-path <replaceable > /path/to/object</replaceable> </arg>
2011-06-09 18:25:04 +02:00
<group >
<arg choice= "plain" > --xml</arg>
</group>
2011-06-09 19:22:18 +02:00
<group >
<arg choice= "plain" > --recurse</arg>
</group>
<group >
<arg choice= "plain" > --only-properties</arg>
</group>
2010-05-07 01:39:16 +02:00
</cmdsynopsis>
2010-05-13 05:12:14 +02:00
<cmdsynopsis >
<command > gdbus</command>
<arg choice= "plain" > monitor</arg>
<group >
<arg choice= "plain" > --system</arg>
<arg choice= "plain" > --session</arg>
<arg choice= "plain" > --address <replaceable > address</replaceable> </arg>
</group>
<arg choice= "plain" > --dest <replaceable > bus_name</replaceable> </arg>
<group >
<arg choice= "plain" > --object-path <replaceable > /path/to/object</replaceable> </arg>
</group>
</cmdsynopsis>
2010-05-07 01:39:16 +02:00
<cmdsynopsis >
<command > gdbus</command>
<arg choice= "plain" > call</arg>
<group >
<arg choice= "plain" > --system</arg>
<arg choice= "plain" > --session</arg>
<arg choice= "plain" > --address <replaceable > address</replaceable> </arg>
</group>
<arg choice= "plain" > --dest <replaceable > bus_name</replaceable> </arg>
<arg choice= "plain" > --object-path <replaceable > /path/to/object</replaceable> </arg>
<arg choice= "plain" > --method <replaceable > org.project.InterfaceName.MethodName</replaceable> </arg>
2011-05-06 21:25:49 +02:00
<group >
<arg choice= "plain" > --timeout <replaceable > seconds</replaceable> </arg>
2021-11-11 11:37:43 +01:00
<arg choice= "plain" > --interactive</arg>
2011-05-06 21:25:49 +02:00
</group>
2010-05-07 01:39:16 +02:00
<arg choice= "plain" > ARG1</arg>
<arg choice= "plain" rep= "repeat" > ARG2</arg>
</cmdsynopsis>
2011-06-04 18:33:39 +02:00
<cmdsynopsis >
<command > gdbus</command>
<arg choice= "plain" > emit</arg>
<group >
<arg choice= "plain" > --system</arg>
<arg choice= "plain" > --session</arg>
<arg choice= "plain" > --address <replaceable > address</replaceable> </arg>
</group>
<arg choice= "plain" > --object-path <replaceable > /path/to/object</replaceable> </arg>
<arg choice= "plain" > --signal <replaceable > org.project.InterfaceName.SignalName</replaceable> </arg>
<group >
<arg choice= "plain" > --dest <replaceable > unique_bus_name</replaceable> </arg>
</group>
<arg choice= "plain" > ARG1</arg>
<arg choice= "plain" rep= "repeat" > ARG2</arg>
</cmdsynopsis>
2015-03-10 16:01:13 +01:00
<cmdsynopsis >
<command > gdbus</command>
<arg choice= "plain" > wait</arg>
<group >
<arg choice= "plain" > --system</arg>
<arg choice= "plain" > --session</arg>
<arg choice= "plain" > --address <replaceable > address</replaceable> </arg>
</group>
<arg choice= "plain" > --activate <replaceable > bus_name</replaceable> </arg>
<group >
<arg choice= "plain" > --timeout <replaceable > seconds</replaceable> </arg>
</group>
<arg choice= "plain" > <replaceable > bus_name</replaceable> </arg>
</cmdsynopsis>
2010-05-07 01:39:16 +02:00
<cmdsynopsis >
<command > gdbus</command>
<arg choice= "plain" > help</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 >
<title > Description</title>
<para >
2011-06-04 18:33:39 +02:00
<command > gdbus</command> is a simple tool for working with D-Bus objects.
2010-05-07 01:39:16 +02:00
</para>
2012-08-03 00:36:25 +02:00
</refsect1>
<refsect1 >
2010-05-07 01:39:16 +02:00
<title > Commands</title>
<variablelist >
<varlistentry >
<term > <option > introspect</option> </term>
<listitem > <para >
Prints out interfaces and property values for a remote object.
For this to work, the owner of the object needs to implement the
<literal > org.freedesktop.DBus.Introspectable</literal> interface.
2011-06-09 18:25:04 +02:00
If the <option > --xml</option> option is used, the returned
introspection XML is printed, otherwise a parsed pretty
2011-06-09 19:22:18 +02:00
representation is printed.
The <option > --recurse</option> option can be used to
introspect children (and their children and so on) and the
<option > --only-properties</option> option can be used to
only print the interfaces with properties.
</para> </listitem>
2010-05-07 01:39:16 +02:00
</varlistentry>
2010-05-13 05:12:14 +02:00
<varlistentry >
<term > <option > monitor</option> </term>
<listitem > <para >
2010-05-14 00:19:16 +02:00
Monitors one or all objects owned by the owner of
2010-05-13 05:12:14 +02:00
<replaceable > bus_name</replaceable> .
</para> </listitem>
</varlistentry>
2010-05-07 01:39:16 +02:00
<varlistentry >
<term > <option > call</option> </term>
<listitem > <para >
Invokes a method on a remote object. Each argument to pass to the
method must be specified as a serialized
<link linkend= "GVariant" > <type > GVariant</type> </link> except that strings do
not need explicit quotes. The return values are printed out as
serialized <link linkend= "GVariant" > <type > GVariant</type> </link>
values.
</para> </listitem>
</varlistentry>
2011-06-04 18:33:39 +02:00
<varlistentry >
<term > <option > emit</option> </term>
<listitem > <para >
Emits a signal. Each argument to include in the signal must be specified as a serialized
<link linkend= "GVariant" > <type > GVariant</type> </link> except that strings do
not need explicit quotes.
</para> </listitem>
</varlistentry>
2015-03-10 16:01:13 +01:00
<varlistentry >
<term > <option > wait</option> </term>
<listitem > <para >
Waits until <replaceable > bus_name</replaceable> is owned by some
process on the bus. If the <option > --activate</option> is specified,
that bus name will be auto-started first. It may be the same as the
bus name being waited for, or different.
</para> </listitem>
</varlistentry>
2010-05-07 01:39:16 +02:00
<varlistentry >
<term > <option > help</option> </term>
<listitem > <para >
Prints help and exit.
</para> </listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 >
<title > Bash Completion</title>
<para >
<command > gdbus</command> ships with a bash completion script to
complete commands, destinations, bus names, object paths and
interface/method names.
</para>
</refsect1>
<refsect1 >
<title > Examples</title>
This shows how to introspect an object - note that the value of each
property is displayed:
<programlisting >
$ gdbus introspect --system \
--dest org.freedesktop.NetworkManager \
--object-path /org/freedesktop/NetworkManager/Devices/0
node /org/freedesktop/NetworkManager/Devices/0 {
interface org.freedesktop.DBus.Introspectable {
methods:
Introspect(out s data);
};
interface org.freedesktop.DBus.Properties {
methods:
Get(in s interface,
in s propname,
out v value);
Set(in s interface,
in s propname,
in v value);
GetAll(in s interface,
out a{sv} props);
};
interface org.freedesktop.NetworkManager.Device.Wired {
signals:
PropertiesChanged(a{sv} arg_0);
properties:
readonly b Carrier = false;
readonly u Speed = 0;
readonly s HwAddress = '00:1D:72:88:BE:97';
};
interface org.freedesktop.NetworkManager.Device {
methods:
Disconnect();
signals:
StateChanged(u arg_0,
u arg_1,
u arg_2);
properties:
readonly u DeviceType = 1;
readonly b Managed = true;
readwrite o Ip6Config = '/';
readwrite o Dhcp4Config = '/';
readwrite o Ip4Config = '/';
readonly u State = 2;
readwrite u Ip4Address = 0;
readonly u Capabilities = 3;
readonly s Driver = 'e1000e';
readwrite s Interface = 'eth0';
readonly s Udi = '/sys/devices/pci0000:00/0000:00:19.0/net/eth0';
};
};
</programlisting>
2011-06-09 19:22:18 +02:00
<para >
The <option > --recurse</option> and <option > --only-properties</option> options can be useful when wanting to inspect all objects owned by a particular process:
</para>
<programlisting >
$ gdbus introspect --system --dest org.freedesktop.UPower --object-path / --recurse --only-properties
node / {
node /org {
node /org/freedesktop {
node /org/freedesktop/UPower {
interface org.freedesktop.UPower {
properties:
readonly b IsDocked = true;
readonly b LidForceSleep = false;
readonly b LidIsPresent = false;
readonly b LidIsClosed = false;
readonly b OnLowBattery = false;
readonly b OnBattery = false;
readonly b CanHibernate = true;
readonly b CanSuspend = true;
readonly s DaemonVersion = '0.9.10';
};
node /org/freedesktop/UPower/Policy {
};
node /org/freedesktop/UPower/Wakeups {
interface org.freedesktop.UPower.Wakeups {
properties:
readonly b HasCapability = true;
};
};
};
};
};
};
</programlisting>
2010-05-07 01:39:16 +02:00
<para >
In a similar fashion, the <option > introspect</option> command can be
used to learn details about the <literal > Notify</literal> method:
</para>
<programlisting >
[...]
interface org.freedesktop.Notifications {
methods:
GetServerInformation(out s return_name,
out s return_vendor,
out s return_version,
out s return_spec_version);
GetCapabilities(out as return_caps);
CloseNotification(in u id);
Notify(in s app_name,
in u id,
in s icon,
in s summary,
in s body,
in as actions,
in a{sv} hints,
in i timeout,
out u return_id);
};
[...]
</programlisting>
<para >
With this information, it's easy to use the <option > call</option>
command to display a notification
</para>
<programlisting >
$ gdbus call --session \
--dest org.freedesktop.Notifications \
--object-path /org/freedesktop/Notifications \
--method org.freedesktop.Notifications.Notify \
my_app_name \
42 \
gtk-dialog-info \
"The Summary" \
"Here's the body of the notification" \
[] \
{} \
5000
(uint32 12,)
</programlisting>
2020-11-06 18:19:27 +01:00
<para >
Call a method with file handle argument:
</para>
<programlisting >
$ gdbus call --session \
--dest org.example.foo \
--object-path /org/example/foo \
--method SendFDs \
1 \
10 \
10< file.foo
</programlisting>
2010-05-13 05:12:14 +02:00
<para >
Monitoring all objects on a service:
</para>
<programlisting >
$ gdbus monitor --system --dest org.freedesktop.ConsoleKit
Monitoring signals from all objects owned by org.freedesktop.ConsoleKit
The name org.freedesktop.ConsoleKit is owned by :1.15
/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (false,)
/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('',)
/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (true,)
/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('/org/freedesktop/ConsoleKit/Session2',)
</programlisting>
<para >
Monitoring a single object on a service:
</para>
<programlisting >
2010-05-14 00:19:16 +02:00
$ gdbus monitor --system --dest org.freedesktop.NetworkManager --object-path /org/freedesktop/NetworkManager/AccessPoint/4141
Monitoring signals on object /org/freedesktop/NetworkManager/AccessPoint/4141 owned by org.freedesktop.NetworkManager
The name org.freedesktop.NetworkManager is owned by :1.5
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': < byte 0x5c> },)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': < byte 0x64> },)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': < byte 0x5e> },)
/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': < byte 0x64> },)
2010-05-13 05:12:14 +02:00
</programlisting>
2011-06-04 18:33:39 +02:00
<para >
Emitting a signal:
</para>
<programlisting >
2011-06-04 18:43:00 +02:00
$ gdbus emit --session --object-path /foo --signal org.bar.Foo "['foo', 'bar', 'baz']"
2011-06-04 18:33:39 +02:00
</programlisting>
<para >
Emitting a signal to a specific process:
</para>
<programlisting >
2011-06-04 18:43:00 +02:00
$ gdbus emit --session --object-path /bar --signal org.bar.Bar someString --dest :1.42
2011-06-04 18:33:39 +02:00
</programlisting>
2015-03-10 16:01:13 +01:00
<para >
Waiting for a well-known name to be owned on the bus; this will
<emphasis > not</emphasis> auto-start the service:
</para>
<programlisting >
$ gdbus wait --session org.bar.SomeName
</programlisting>
<para >
Auto-starting then waiting for a well-known name to be owned on the bus:
</para>
<programlisting >
$ gdbus wait --session --activate org.bar.SomeName
</programlisting>
<para >
Auto-starting a different service, then waiting for a well-known name to be
owned on the bus. This is useful in situations where
<replaceable > SomeName</replaceable> is not directly activatable:
</para>
<programlisting >
$ gdbus wait --session --activate org.bar.PrerequisiteName org.bar.SomeName
</programlisting>
<para >
Waiting for a well-known name and giving up after 30 seconds. By default,
the timeout is disabled; or set <option > --timeout</option> to 0 to disable it:
</para>
<programlisting >
$ gdbus wait --session --timeout 30 org.bar.SomeName
</programlisting>
2010-05-07 01:39:16 +02:00
</refsect1>
<refsect1 >
2012-08-03 00:36:25 +02:00
<title > Bugs</title>
2010-05-07 01:39:16 +02:00
<para >
Please send bug reports to either the distribution bug tracker
or the upstream bug tracker at
2018-05-31 23:44:02 +02:00
<ulink url= "https://gitlab.gnome.org/GNOME/glib/issues/new" /> .
2010-05-07 01:39:16 +02:00
</para>
</refsect1>
<refsect1 >
2012-08-03 00:36:25 +02:00
<title > See Also</title>
2010-05-07 01:39:16 +02:00
<para >
<citerefentry >
<refentrytitle > dbus-send</refentrytitle> <manvolnum > 1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>
