| .. _gdbus(1): | |
| .. meta:: | |
| :copyright: Copyright 2010, 2011, 2012, 2020 Red Hat, Inc. | |
| :copyright: Copyright 2015 Collabora, Ltd. | |
| :copyright: Copyright 2021 Endless OS Foundation, LLC | |
| :license: LGPL-2.1-or-later | |
| .. | |
| This has to be duplicated from above to make it machine-readable by `reuse`: | |
| SPDX-FileCopyrightText: 2010, 2011, 2012, 2020 Red Hat, Inc. | |
| SPDX-FileCopyrightText: 2015 Collabora, Ltd. | |
| SPDX-FileCopyrightText: 2021 Endless OS Foundation, LLC | |
| SPDX-License-Identifier: LGPL-2.1-or-later | |
| ===== | |
| gdbus | |
| ===== | |
| ----------------------------------- | |
| Tool for working with D-Bus objects | |
| ----------------------------------- | |
| SYNOPSIS | |
| -------- | |
| | **gdbus** introspect [--system | --session | --address *address*] --dest *bus_name* --object-path */path/to/object* [--xml] [--recurse] [--only-properties] | |
| | **gdbus** monitor [--system | --session | --address *address*] --dest *bus_name* [--object-path */path/to/object*] | |
| | **gdbus** call [--system | --session | --address *address*] --dest *bus_name* --object-path */path/to/object* --method *org.project.InterfaceName.MethodName* [--timeout *seconds* | --interactive] [*ARG*…] | |
| | **gdbus** emit [--system | --session | --address *address*] --object-path */path/to/object* --signal *org.project.InterfaceName.SignalName* [--dest *unique_bus_name*] [*ARG*…] | |
| | **gdbus** wait [--system | --session | --address *address*] --activate *bus_name* [--timeout *seconds*] *bus_name* | |
| | **gdbus** help | |
| DESCRIPTION | |
| ----------- | |
| ``gdbus`` is a simple tool for working with D-Bus objects. | |
| COMMANDS | |
| -------- | |
| ``introspect`` | |
| Prints out interfaces and property values for a remote object. For this to | |
| work, the owner of the object needs to implement the | |
| ``org.freedesktop.DBus.Introspectable`` interface. If the ``--xml`` option is | |
| used, the returned introspection XML is printed, otherwise a parsed pretty | |
| representation is printed. The ``--recurse`` option can be used to introspect | |
| children (and their children and so on) and the ``--only-properties`` option | |
| can be used to only print the interfaces with properties. | |
| ``monitor`` | |
| Monitors one or all objects owned by the owner of ``bus_name``. | |
| ``call`` | |
| Invokes a method on a remote object. Each argument to pass to the method must | |
| be specified as a serialized ``GVariant`` except that strings do not need | |
| explicit quotes. The return values are printed out as serialized ``GVariant`` | |
| values. | |
| ``emit`` | |
| Emits a signal. Each argument to include in the signal must be specified as a | |
| serialized ``GVariant`` except that strings do not need explicit quotes. | |
| ``wait`` | |
| Waits until ``bus_name`` is owned by some process on the bus. If the | |
| ``--activate`` is specified, that bus name will be auto-started first. It may | |
| be the same as the bus name being waited for, or different. | |
| ``help`` | |
| Prints help and exits. | |
| BASH COMPLETION | |
| --------------- | |
| ``gdbus`` ships with a bash completion script to complete commands, | |
| destinations, bus names, object paths and interface/method names. | |
| EXAMPLES | |
| -------- | |
| This shows how to introspect an object — note that the value of each property is | |
| displayed:: | |
| $ 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'; | |
| }; | |
| }; | |
| The ``--recurse`` and ``--only-properties`` options can be useful when wanting | |
| to inspect all objects owned by a particular process:: | |
| $ 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; | |
| }; | |
| }; | |
| }; | |
| }; | |
| }; | |
| }; | |
| In a similar fashion, the ``introspect`` command can be used to learn details | |
| about the ``Notify`` method:: | |
| […] | |
| 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); | |
| }; | |
| […] | |
| With this information, it’s easy to use the ``call`` command to display a | |
| notification:: | |
| $ 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,) | |
| Call a method with file handle argument:: | |
| $ gdbus call --session \ | |
| --dest org.example.foo \ | |
| --object-path /org/example/foo \ | |
| --method SendFDs \ | |
| 1 \ | |
| 10 \ | |
| 10<file.foo | |
| Monitoring all objects on a service:: | |
| $ 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',) | |
| Monitoring a single object on a service:: | |
| $ 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>},) | |
| Emitting a signal:: | |
| $ gdbus emit --session --object-path /foo --signal org.bar.Foo "['foo', 'bar', 'baz']" | |
| Emitting a signal to a specific process:: | |
| $ gdbus emit --session --object-path /bar --signal org.bar.Bar someString --dest :1.42 | |
| Waiting for a well-known name to be owned on the bus; this will *not* auto-start | |
| the service:: | |
| $ gdbus wait --session org.bar.SomeName | |
| Auto-starting then waiting for a well-known name to be owned on the bus:: | |
| $ gdbus wait --session --activate org.bar.SomeName | |
| Auto-starting a different service, then waiting for a well-known name to be | |
| owned on the bus. This is useful in situations where ``SomeName`` is not | |
| directly activatable:: | |
| $ gdbus wait --session --activate org.bar.PrerequisiteName org.bar.SomeName | |
| Waiting for a well-known name and giving up after 30 seconds. By default, the | |
| timeout is disabled; or set ``--timeout`` to ``0`` to disable it:: | |
| $ gdbus wait --session --timeout 30 org.bar.SomeName | |
| BUGS | |
| ---- | |
| Please send bug reports to either the distribution bug tracker or the | |
| `upstream bug tracker <https://gitlab.gnome.org/GNOME/glib/issues/new>`_. | |
| SEE ALSO | |
| -------- | |
| `dbus-send(1) <man:dbus-send(1)>`_ |