<refentry id="gdbus" lang="en"> <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> <refmeta> <refentrytitle>gdbus</refentrytitle> <manvolnum>1</manvolnum> <refmiscinfo class="manual">User Commands</refmiscinfo> </refmeta> <refnamediv> <refname>gdbus</refname> <refpurpose>Tool for working with D-Bus objects</refpurpose> </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> <group> <arg choice="plain">--xml</arg> </group> <group> <arg choice="plain">--recurse</arg> </group> <group> <arg choice="plain">--only-properties</arg> </group> </cmdsynopsis> <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> <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> <group> <arg choice="plain">--timeout <replaceable>seconds</replaceable></arg> </group> <arg choice="plain">ARG1</arg> <arg choice="plain" rep="repeat">ARG2</arg> </cmdsynopsis> <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> <cmdsynopsis> <command>gdbus</command> <arg choice="plain">help</arg> </cmdsynopsis> </refsynopsisdiv> <refsect1> <title>Description</title> <para> <command>gdbus</command> is a simple tool for working with D-Bus objects. </para> </refsect1> <refsect1> <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. If the <option>--xml</option> option is used, the returned introspection XML is printed, otherwise a parsed pretty 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> </varlistentry> <varlistentry> <term><option>monitor</option></term> <listitem><para> Monitors one or all objects owned by the owner of <replaceable>bus_name</replaceable>. </para></listitem> </varlistentry> <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> <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> <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> <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> <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> <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> $ 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>},) </programlisting> <para> Emitting a signal: </para> <programlisting> $ gdbus emit --session --object-path /foo --signal org.bar.Foo "['foo', 'bar', 'baz']" </programlisting> <para> Emitting a signal to a specific process: </para> <programlisting> $ gdbus emit --session --object-path /bar --signal org.bar.Bar someString --dest :1.42 </programlisting> </refsect1> <refsect1> <title>Bugs</title> <para> Please send bug reports to either the distribution bug tracker or the upstream bug tracker at <ulink url="https://bugzilla.gnome.org/enter_bug.cgi?product=glib"/>. </para> </refsect1> <refsect1> <title>See Also</title> <para> <citerefentry> <refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum> </citerefentry> </para> </refsect1> </refentry>