'\" t
.\" Title: gdbus
.\" Author: David Zeuthen <zeuthen@gmail.com>
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\" Date: 04/07/2018
.\" 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] 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
Monitoring all objects on a service:
.sp
.if n \{\
.RS 4
.\}
.nf
$ 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 (\*(Aq\*(Aq,)
/org/freedesktop/ConsoleKit/Session2: org\&.freedesktop\&.ConsoleKit\&.Session\&.ActiveChanged (true,)
/org/freedesktop/ConsoleKit/Seat1: org\&.freedesktop\&.ConsoleKit\&.Seat\&.ActiveSessionChanged (\*(Aq/org/freedesktop/ConsoleKit/Session2\*(Aq,)
.fi
.if n \{\
.RE
.\}
.PP
Monitoring a single object on a service:
.sp
.if n \{\
.RS 4
.\}
.nf
$ 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 ({\*(AqStrength\*(Aq: <byte 0x5c>},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org\&.freedesktop\&.NetworkManager\&.AccessPoint\&.PropertiesChanged ({\*(AqStrength\*(Aq: <byte 0x64>},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org\&.freedesktop\&.NetworkManager\&.AccessPoint\&.PropertiesChanged ({\*(AqStrength\*(Aq: <byte 0x5e>},)
/org/freedesktop/NetworkManager/AccessPoint/4141: org\&.freedesktop\&.NetworkManager\&.AccessPoint\&.PropertiesChanged ({\*(AqStrength\*(Aq: <byte 0x64>},)
.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://bugzilla.gnome.org/enter_bug.cgi?product=glib\fR\m[]\&.
.SH "SEE ALSO"
.PP
\fBdbus-send\fR(1)