'\" t .\" Title: gdbus .\" Author: David Zeuthen .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 02/15/2024 .\" Manual: User Commands .\" Source: GIO .\" Language: English .\" .TH "GDBUS" "1" "" "GIO" "User Commands" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" gdbus \- Tool for working with D\-Bus objects .SH "SYNOPSIS" .HP \w'\fBgdbus\fR\ 'u \fBgdbus\fR introspect [\-\-system | \-\-session | \-\-address\ \fIaddress\fR] \-\-dest\ \fIbus_name\fR \-\-object\-path\ \fI/path/to/object\fR [\-\-xml] [\-\-recurse] [\-\-only\-properties] .HP \w'\fBgdbus\fR\ 'u \fBgdbus\fR monitor [\-\-system | \-\-session | \-\-address\ \fIaddress\fR] \-\-dest\ \fIbus_name\fR [\-\-object\-path\ \fI/path/to/object\fR] .HP \w'\fBgdbus\fR\ 'u \fBgdbus\fR call [\-\-system | \-\-session | \-\-address\ \fIaddress\fR] \-\-dest\ \fIbus_name\fR \-\-object\-path\ \fI/path/to/object\fR \-\-method\ \fIorg\&.project\&.InterfaceName\&.MethodName\fR [\-\-timeout\ \fIseconds\fR | \-\-interactive] ARG1 ARG2... .HP \w'\fBgdbus\fR\ 'u \fBgdbus\fR emit [\-\-system | \-\-session | \-\-address\ \fIaddress\fR] \-\-object\-path\ \fI/path/to/object\fR \-\-signal\ \fIorg\&.project\&.InterfaceName\&.SignalName\fR [\-\-dest\ \fIunique_bus_name\fR] ARG1 ARG2... .HP \w'\fBgdbus\fR\ 'u \fBgdbus\fR wait [\-\-system | \-\-session | \-\-address\ \fIaddress\fR] \-\-activate\ \fIbus_name\fR [\-\-timeout\ \fIseconds\fR] \fIbus_name\fR .HP \w'\fBgdbus\fR\ 'u \fBgdbus\fR help .SH "DESCRIPTION" .PP \fBgdbus\fR is a simple tool for working with D\-Bus objects\&. .SH "COMMANDS" .PP \fBintrospect\fR .RS 4 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 \fB\-\-xml\fR option is used, the returned introspection XML is printed, otherwise a parsed pretty representation is printed\&. The \fB\-\-recurse\fR option can be used to introspect children (and their children and so on) and the \fB\-\-only\-properties\fR option can be used to only print the interfaces with properties\&. .RE .PP \fBmonitor\fR .RS 4 Monitors one or all objects owned by the owner of \fIbus_name\fR\&. .RE .PP \fBcall\fR .RS 4 Invokes a method on a remote object\&. Each argument to pass to the method must be specified as a serialized \fBGVariant\fR except that strings do not need explicit quotes\&. The return values are printed out as serialized \fBGVariant\fR values\&. .RE .PP \fBemit\fR .RS 4 Emits a signal\&. Each argument to include in the signal must be specified as a serialized \fBGVariant\fR except that strings do not need explicit quotes\&. .RE .PP \fBwait\fR .RS 4 Waits until \fIbus_name\fR is owned by some process on the bus\&. If the \fB\-\-activate\fR is specified, that bus name will be auto\-started first\&. It may be the same as the bus name being waited for, or different\&. .RE .PP \fBhelp\fR .RS 4 Prints help and exit\&. .RE .SH "BASH COMPLETION" .PP \fBgdbus\fR ships with a bash completion script to complete commands, destinations, bus names, object paths and interface/method names\&. .SH "EXAMPLES" This shows how to introspect an object \- note that the value of each property is displayed: .sp .if n \{\ .RS 4 .\} .nf $ gdbus introspect \-\-system \e \-\-dest org\&.freedesktop\&.NetworkManager \e \-\-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 = \*(Aq00:1D:72:88:BE:97\*(Aq; }; 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 = \*(Aq/\*(Aq; readwrite o Dhcp4Config = \*(Aq/\*(Aq; readwrite o Ip4Config = \*(Aq/\*(Aq; readonly u State = 2; readwrite u Ip4Address = 0; readonly u Capabilities = 3; readonly s Driver = \*(Aqe1000e\*(Aq; readwrite s Interface = \*(Aqeth0\*(Aq; readonly s Udi = \*(Aq/sys/devices/pci0000:00/0000:00:19\&.0/net/eth0\*(Aq; }; }; .fi .if n \{\ .RE .\} .PP The \fB\-\-recurse\fR and \fB\-\-only\-properties\fR options can be useful when wanting to inspect all objects owned by a particular process: .sp .if n \{\ .RS 4 .\} .nf $ 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 = \*(Aq0\&.9\&.10\*(Aq; }; node /org/freedesktop/UPower/Policy { }; node /org/freedesktop/UPower/Wakeups { interface org\&.freedesktop\&.UPower\&.Wakeups { properties: readonly b HasCapability = true; }; }; }; }; }; }; .fi .if n \{\ .RE .\} .PP In a similar fashion, the \fBintrospect\fR command can be used to learn details about the Notify method: .sp .if n \{\ .RS 4 .\} .nf [\&.\&.\&.] 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); }; [\&.\&.\&.] .fi .if n \{\ .RE .\} .PP With this information, it\*(Aqs easy to use the \fBcall\fR command to display a notification .sp .if n \{\ .RS 4 .\} .nf $ gdbus call \-\-session \e \-\-dest org\&.freedesktop\&.Notifications \e \-\-object\-path /org/freedesktop/Notifications \e \-\-method org\&.freedesktop\&.Notifications\&.Notify \e my_app_name \e 42 \e gtk\-dialog\-info \e "The Summary" \e "Here\*(Aqs the body of the notification" \e [] \e {} \e 5000 (uint32 12,) .fi .if n \{\ .RE .\} .PP Call a method with file handle argument: .sp .if n \{\ .RS 4 .\} .nf $ gdbus call \-\-session \e \-\-dest org\&.example\&.foo \e \-\-object\-path /org/example/foo \e \-\-method SendFDs \e 1 \e 10 \e 10},) /org/freedesktop/NetworkManager/AccessPoint/4141: org\&.freedesktop\&.NetworkManager\&.AccessPoint\&.PropertiesChanged ({\*(AqStrength\*(Aq: },) /org/freedesktop/NetworkManager/AccessPoint/4141: org\&.freedesktop\&.NetworkManager\&.AccessPoint\&.PropertiesChanged ({\*(AqStrength\*(Aq: },) /org/freedesktop/NetworkManager/AccessPoint/4141: org\&.freedesktop\&.NetworkManager\&.AccessPoint\&.PropertiesChanged ({\*(AqStrength\*(Aq: },) .fi .if n \{\ .RE .\} .PP Emitting a signal: .sp .if n \{\ .RS 4 .\} .nf $ gdbus emit \-\-session \-\-object\-path /foo \-\-signal org\&.bar\&.Foo "[\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq]" .fi .if n \{\ .RE .\} .PP Emitting a signal to a specific process: .sp .if n \{\ .RS 4 .\} .nf $ gdbus emit \-\-session \-\-object\-path /bar \-\-signal org\&.bar\&.Bar someString \-\-dest :1\&.42 .fi .if n \{\ .RE .\} .PP Waiting for a well\-known name to be owned on the bus; this will \fInot\fR auto\-start the service: .sp .if n \{\ .RS 4 .\} .nf $ gdbus wait \-\-session org\&.bar\&.SomeName .fi .if n \{\ .RE .\} .PP Auto\-starting then waiting for a well\-known name to be owned on the bus: .sp .if n \{\ .RS 4 .\} .nf $ gdbus wait \-\-session \-\-activate org\&.bar\&.SomeName .fi .if n \{\ .RE .\} .PP Auto\-starting a different service, then waiting for a well\-known name to be owned on the bus\&. This is useful in situations where \fISomeName\fR is not directly activatable: .sp .if n \{\ .RS 4 .\} .nf $ gdbus wait \-\-session \-\-activate org\&.bar\&.PrerequisiteName org\&.bar\&.SomeName .fi .if n \{\ .RE .\} .PP Waiting for a well\-known name and giving up after 30 seconds\&. By default, the timeout is disabled; or set \fB\-\-timeout\fR to 0 to disable it: .sp .if n \{\ .RS 4 .\} .nf $ gdbus wait \-\-session \-\-timeout 30 org\&.bar\&.SomeName .fi .if n \{\ .RE .\} .SH "BUGS" .PP Please send bug reports to either the distribution bug tracker or the upstream bug tracker at \m[blue]\fB\%https://gitlab.gnome.org/GNOME/glib/issues/new\fR\m[]\&. .SH "SEE ALSO" .PP \fBdbus-send\fR(1)