GDBUS(1)

📦
version 2.90.1 · 10 versions
, in arch rolling, nixpkgs unstable, ubuntu stonking

✨ NAME ✨

gdbus — the tool for working with D-Bus objects 💅 (yes, the manual page is literally called gdbus, section 1, bestie)

🌸 SYNOPSIS 🌸

okay so here's the whole vibe, every single invocation, exactly as written:

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. that's it. that's the whole description. it's simple, it's cute, it does the thing ✨

👑 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, no cap — if they don't, it's just not gonna happen.

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, like a whole family tree 🌳), 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. just sitting there, watching, main character energy 🫶

💜 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, so you can be a lil lazy with those 🍓

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, same deal as call. 📣

💜 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. so patient, so iconic ⏳

💜 help

Prints help and exits. short and sweet, we love her 🙈

🎀 BASH COMPLETION 🎀

gdbus ships with a bash completion script to complete commands, destinations, bus names, object paths and interface/method names. it literally finishes your sentences for you, that's the dream 💖

🌈 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>. found a problem? tell the girlies, we fix it together 🫶

🔥 SEE ALSO 🔥

okay that's the whole page bestie, you're officially a D-Bus girlie now 💅✨ and that's a wrap on the gdbus() manual page — mwah, kisses from the gdbus() source, see you on the bus 🚌💖🦋

📦 where this page comes from