1<refentry id="gdbus" lang="en"> 2 3<refentryinfo> 4 <title>gdbus</title> 5 <productname>GIO</productname> 6 <authorgroup> 7 <author> 8 <contrib>Developer</contrib> 9 <firstname>David</firstname> 10 <surname>Zeuthen</surname> 11 <email>zeuthen@gmail.com</email> 12 </author> 13 </authorgroup> 14</refentryinfo> 15 16<refmeta> 17 <refentrytitle>gdbus</refentrytitle> 18 <manvolnum>1</manvolnum> 19 <refmiscinfo class="manual">User Commands</refmiscinfo> 20</refmeta> 21 22<refnamediv> 23 <refname>gdbus</refname> 24 <refpurpose>Tool for working with D-Bus objects</refpurpose> 25</refnamediv> 26 27<refsynopsisdiv> 28 <cmdsynopsis> 29 <command>gdbus</command> 30 <arg choice="plain">introspect</arg> 31 <group> 32 <arg choice="plain">--system</arg> 33 <arg choice="plain">--session</arg> 34 <arg choice="plain">--address <replaceable>address</replaceable></arg> 35 </group> 36 <arg choice="plain">--dest <replaceable>bus_name</replaceable></arg> 37 <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg> 38 <group> 39 <arg choice="plain">--xml</arg> 40 </group> 41 <group> 42 <arg choice="plain">--recurse</arg> 43 </group> 44 <group> 45 <arg choice="plain">--only-properties</arg> 46 </group> 47 </cmdsynopsis> 48 <cmdsynopsis> 49 <command>gdbus</command> 50 <arg choice="plain">monitor</arg> 51 <group> 52 <arg choice="plain">--system</arg> 53 <arg choice="plain">--session</arg> 54 <arg choice="plain">--address <replaceable>address</replaceable></arg> 55 </group> 56 <arg choice="plain">--dest <replaceable>bus_name</replaceable></arg> 57 <group> 58 <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg> 59 </group> 60 </cmdsynopsis> 61 <cmdsynopsis> 62 <command>gdbus</command> 63 <arg choice="plain">call</arg> 64 <group> 65 <arg choice="plain">--system</arg> 66 <arg choice="plain">--session</arg> 67 <arg choice="plain">--address <replaceable>address</replaceable></arg> 68 </group> 69 <arg choice="plain">--dest <replaceable>bus_name</replaceable></arg> 70 <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg> 71 <arg choice="plain">--method <replaceable>org.project.InterfaceName.MethodName</replaceable></arg> 72 <group> 73 <arg choice="plain">--timeout <replaceable>seconds</replaceable></arg> 74 </group> 75 <arg choice="plain">ARG1</arg> 76 <arg choice="plain" rep="repeat">ARG2</arg> 77 </cmdsynopsis> 78 <cmdsynopsis> 79 <command>gdbus</command> 80 <arg choice="plain">emit</arg> 81 <group> 82 <arg choice="plain">--system</arg> 83 <arg choice="plain">--session</arg> 84 <arg choice="plain">--address <replaceable>address</replaceable></arg> 85 </group> 86 <arg choice="plain">--object-path <replaceable>/path/to/object</replaceable></arg> 87 <arg choice="plain">--signal <replaceable>org.project.InterfaceName.SignalName</replaceable></arg> 88 <group> 89 <arg choice="plain">--dest <replaceable>unique_bus_name</replaceable></arg> 90 </group> 91 <arg choice="plain">ARG1</arg> 92 <arg choice="plain" rep="repeat">ARG2</arg> 93 </cmdsynopsis> 94 <cmdsynopsis> 95 <command>gdbus</command> 96 <arg choice="plain">wait</arg> 97 <group> 98 <arg choice="plain">--system</arg> 99 <arg choice="plain">--session</arg> 100 <arg choice="plain">--address <replaceable>address</replaceable></arg> 101 </group> 102 <arg choice="plain">--activate <replaceable>bus_name</replaceable></arg> 103 <group> 104 <arg choice="plain">--timeout <replaceable>seconds</replaceable></arg> 105 </group> 106 <arg choice="plain"><replaceable>bus_name</replaceable></arg> 107 </cmdsynopsis> 108 <cmdsynopsis> 109 <command>gdbus</command> 110 <arg choice="plain">help</arg> 111 </cmdsynopsis> 112</refsynopsisdiv> 113 114<refsect1> 115 <title>Description</title> 116 <para> 117 <command>gdbus</command> is a simple tool for working with D-Bus objects. 118 </para> 119</refsect1> 120<refsect1> 121 <title>Commands</title> 122 <variablelist> 123 <varlistentry> 124 <term><option>introspect</option></term> 125 <listitem><para> 126 Prints out interfaces and property values for a remote object. 127 For this to work, the owner of the object needs to implement the 128 <literal>org.freedesktop.DBus.Introspectable</literal> interface. 129 If the <option>--xml</option> option is used, the returned 130 introspection XML is printed, otherwise a parsed pretty 131 representation is printed. 132 The <option>--recurse</option> option can be used to 133 introspect children (and their children and so on) and the 134 <option>--only-properties</option> option can be used to 135 only print the interfaces with properties. 136 </para></listitem> 137 </varlistentry> 138 <varlistentry> 139 <term><option>monitor</option></term> 140 <listitem><para> 141 Monitors one or all objects owned by the owner of 142 <replaceable>bus_name</replaceable>. 143 </para></listitem> 144 </varlistentry> 145 <varlistentry> 146 <term><option>call</option></term> 147 <listitem><para> 148 Invokes a method on a remote object. Each argument to pass to the 149 method must be specified as a serialized 150 <link linkend="GVariant"><type>GVariant</type></link> except that strings do 151 not need explicit quotes. The return values are printed out as 152 serialized <link linkend="GVariant"><type>GVariant</type></link> 153 values. 154 </para></listitem> 155 </varlistentry> 156 <varlistentry> 157 <term><option>emit</option></term> 158 <listitem><para> 159 Emits a signal. Each argument to include in the signal must be specified as a serialized 160 <link linkend="GVariant"><type>GVariant</type></link> except that strings do 161 not need explicit quotes. 162 </para></listitem> 163 </varlistentry> 164 <varlistentry> 165 <term><option>wait</option></term> 166 <listitem><para> 167 Waits until <replaceable>bus_name</replaceable> is owned by some 168 process on the bus. If the <option>--activate</option> is specified, 169 that bus name will be auto-started first. It may be the same as the 170 bus name being waited for, or different. 171 </para></listitem> 172 </varlistentry> 173 <varlistentry> 174 <term><option>help</option></term> 175 <listitem><para> 176 Prints help and exit. 177 </para></listitem> 178 </varlistentry> 179 </variablelist> 180</refsect1> 181 182<refsect1> 183 <title>Bash Completion</title> 184 <para> 185 <command>gdbus</command> ships with a bash completion script to 186 complete commands, destinations, bus names, object paths and 187 interface/method names. 188 </para> 189</refsect1> 190 191<refsect1> 192 <title>Examples</title> 193 This shows how to introspect an object - note that the value of each 194 property is displayed: 195<programlisting> 196$ gdbus introspect --system \ 197 --dest org.freedesktop.NetworkManager \ 198 --object-path /org/freedesktop/NetworkManager/Devices/0 199node /org/freedesktop/NetworkManager/Devices/0 { 200 interface org.freedesktop.DBus.Introspectable { 201 methods: 202 Introspect(out s data); 203 }; 204 interface org.freedesktop.DBus.Properties { 205 methods: 206 Get(in s interface, 207 in s propname, 208 out v value); 209 Set(in s interface, 210 in s propname, 211 in v value); 212 GetAll(in s interface, 213 out a{sv} props); 214 }; 215 interface org.freedesktop.NetworkManager.Device.Wired { 216 signals: 217 PropertiesChanged(a{sv} arg_0); 218 properties: 219 readonly b Carrier = false; 220 readonly u Speed = 0; 221 readonly s HwAddress = '00:1D:72:88:BE:97'; 222 }; 223 interface org.freedesktop.NetworkManager.Device { 224 methods: 225 Disconnect(); 226 signals: 227 StateChanged(u arg_0, 228 u arg_1, 229 u arg_2); 230 properties: 231 readonly u DeviceType = 1; 232 readonly b Managed = true; 233 readwrite o Ip6Config = '/'; 234 readwrite o Dhcp4Config = '/'; 235 readwrite o Ip4Config = '/'; 236 readonly u State = 2; 237 readwrite u Ip4Address = 0; 238 readonly u Capabilities = 3; 239 readonly s Driver = 'e1000e'; 240 readwrite s Interface = 'eth0'; 241 readonly s Udi = '/sys/devices/pci0000:00/0000:00:19.0/net/eth0'; 242 }; 243}; 244</programlisting> 245<para> 246 The <option>--recurse</option> and <option>--only-properties</option> options can be useful when wanting to inspect all objects owned by a particular process: 247</para> 248<programlisting> 249$ gdbus introspect --system --dest org.freedesktop.UPower --object-path / --recurse --only-properties 250node / { 251 node /org { 252 node /org/freedesktop { 253 node /org/freedesktop/UPower { 254 interface org.freedesktop.UPower { 255 properties: 256 readonly b IsDocked = true; 257 readonly b LidForceSleep = false; 258 readonly b LidIsPresent = false; 259 readonly b LidIsClosed = false; 260 readonly b OnLowBattery = false; 261 readonly b OnBattery = false; 262 readonly b CanHibernate = true; 263 readonly b CanSuspend = true; 264 readonly s DaemonVersion = '0.9.10'; 265 }; 266 node /org/freedesktop/UPower/Policy { 267 }; 268 node /org/freedesktop/UPower/Wakeups { 269 interface org.freedesktop.UPower.Wakeups { 270 properties: 271 readonly b HasCapability = true; 272 }; 273 }; 274 }; 275 }; 276 }; 277}; 278</programlisting> 279<para> 280 In a similar fashion, the <option>introspect</option> command can be 281 used to learn details about the <literal>Notify</literal> method: 282</para> 283<programlisting> 284[...] 285 interface org.freedesktop.Notifications { 286 methods: 287 GetServerInformation(out s return_name, 288 out s return_vendor, 289 out s return_version, 290 out s return_spec_version); 291 GetCapabilities(out as return_caps); 292 CloseNotification(in u id); 293 Notify(in s app_name, 294 in u id, 295 in s icon, 296 in s summary, 297 in s body, 298 in as actions, 299 in a{sv} hints, 300 in i timeout, 301 out u return_id); 302 }; 303[...] 304</programlisting> 305<para> 306 With this information, it's easy to use the <option>call</option> 307 command to display a notification 308</para> 309<programlisting> 310$ gdbus call --session \ 311 --dest org.freedesktop.Notifications \ 312 --object-path /org/freedesktop/Notifications \ 313 --method org.freedesktop.Notifications.Notify \ 314 my_app_name \ 315 42 \ 316 gtk-dialog-info \ 317 "The Summary" \ 318 "Here's the body of the notification" \ 319 [] \ 320 {} \ 321 5000 322(uint32 12,) 323</programlisting> 324<para> 325 Call a method with file handle argument: 326</para> 327<programlisting> 328$ gdbus call --session \ 329 --dest org.example.foo \ 330 --object-path /org/example/foo \ 331 --method SendFDs \ 332 1 \ 333 10 \ 334 10<file.foo 335</programlisting> 336<para> 337 Monitoring all objects on a service: 338</para> 339<programlisting> 340$ gdbus monitor --system --dest org.freedesktop.ConsoleKit 341Monitoring signals from all objects owned by org.freedesktop.ConsoleKit 342The name org.freedesktop.ConsoleKit is owned by :1.15 343/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (false,) 344/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('',) 345/org/freedesktop/ConsoleKit/Session2: org.freedesktop.ConsoleKit.Session.ActiveChanged (true,) 346/org/freedesktop/ConsoleKit/Seat1: org.freedesktop.ConsoleKit.Seat.ActiveSessionChanged ('/org/freedesktop/ConsoleKit/Session2',) 347</programlisting> 348<para> 349 Monitoring a single object on a service: 350</para> 351<programlisting> 352$ gdbus monitor --system --dest org.freedesktop.NetworkManager --object-path /org/freedesktop/NetworkManager/AccessPoint/4141 353Monitoring signals on object /org/freedesktop/NetworkManager/AccessPoint/4141 owned by org.freedesktop.NetworkManager 354The name org.freedesktop.NetworkManager is owned by :1.5 355/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x5c>},) 356/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x64>},) 357/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x5e>},) 358/org/freedesktop/NetworkManager/AccessPoint/4141: org.freedesktop.NetworkManager.AccessPoint.PropertiesChanged ({'Strength': <byte 0x64>},) 359</programlisting> 360 361<para> 362 Emitting a signal: 363</para> 364<programlisting> 365$ gdbus emit --session --object-path /foo --signal org.bar.Foo "['foo', 'bar', 'baz']" 366</programlisting> 367 368<para> 369 Emitting a signal to a specific process: 370</para> 371<programlisting> 372$ gdbus emit --session --object-path /bar --signal org.bar.Bar someString --dest :1.42 373</programlisting> 374 375<para> 376 Waiting for a well-known name to be owned on the bus; this will 377 <emphasis>not</emphasis> auto-start the service: 378</para> 379<programlisting> 380$ gdbus wait --session org.bar.SomeName 381</programlisting> 382 383<para> 384 Auto-starting then waiting for a well-known name to be owned on the bus: 385</para> 386<programlisting> 387$ gdbus wait --session --activate org.bar.SomeName 388</programlisting> 389 390<para> 391 Auto-starting a different service, then waiting for a well-known name to be 392 owned on the bus. This is useful in situations where 393 <replaceable>SomeName</replaceable> is not directly activatable: 394</para> 395<programlisting> 396$ gdbus wait --session --activate org.bar.PrerequisiteName org.bar.SomeName 397</programlisting> 398 399<para> 400 Waiting for a well-known name and giving up after 30 seconds. By default, 401 the timeout is disabled; or set <option>--timeout</option> to 0 to disable it: 402</para> 403<programlisting> 404$ gdbus wait --session --timeout 30 org.bar.SomeName 405</programlisting> 406 407</refsect1> 408 409<refsect1> 410 <title>Bugs</title> 411 <para> 412 Please send bug reports to either the distribution bug tracker 413 or the upstream bug tracker at 414 <ulink url="https://gitlab.gnome.org/GNOME/glib/issues/new"/>. 415 </para> 416</refsect1> 417 418<refsect1> 419 <title>See Also</title> 420 <para> 421 <citerefentry> 422 <refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum> 423 </citerefentry> 424 </para> 425</refsect1> 426 427</refentry> 428 429