<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">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>

  <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>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>

      <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>

<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>

</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>