1 <?xml version="1.0" standalone="no"?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
9 <title>D-Bus FAQ</title>
10 <releaseinfo>Version 0.2</releaseinfo>
11 <date>07 November 2006</date>
14 <firstname>Havoc</firstname>
15 <surname>Pennington</surname>
17 <orgname>Red Hat, Inc.</orgname>
19 <email>hp@pobox.com</email>
24 <firstname>David</firstname>
25 <othername role="mi">A</othername>
26 <surname>Wheeler</surname>
41 This is probably best answered by reading the D-Bus <ulink url="dbus-tutorial.html">tutorial</ulink> or
42 the introduction to the <ulink url="dbus-specification.html">specification</ulink>. In
43 short, it is a system consisting of 1) a wire protocol for exposing a
44 typical object-oriented language/framework to other applications; and
45 2) a bus daemon that allows applications to find and monitor one another.
46 Phrased differently, D-Bus is 1) an interprocess communication (IPC) system and 2) some higher-level
47 structure (lifecycle tracking, service activation, security policy) provided by two bus daemons,
48 one systemwide and one per-user-session.
56 Is D-Bus stable/finished?
61 The low-level library "libdbus" and the protocol specification are considered
62 ABI stable. The <ulink url="README">README</ulink>
63 file has a discussion of the API/ABI stability guarantees.
64 Higher-level bindings (such as those for Qt, GLib, Python, Java, C#) each
65 have their own release schedules and degree of maturity, not linked to
66 the low-level library and bus daemon release. Check the project page for
67 the binding you're considering to understand that project's policies.
75 How is the reference implementation licensed? Can I use it in
76 proprietary applications?
81 The short answer is yes, you can use it in proprietary applications.
82 You should read the <ulink url="COPYING">COPYING</ulink> file, which
83 offers you the choice of two licenses. These are the GPL and the
84 AFL. The GPL requires that your application be licensed under the GPL
85 as well. The AFL is an "X-style" or "BSD-style" license compatible
86 with proprietary licensing, but it does have some requirements; in
87 particular it prohibits you from filing a lawsuit alleging that the
88 D-Bus software infringes your patents <emphasis>while you continue to
89 use D-Bus</emphasis>. If you're going to sue, you have to stop using
90 the software. Read the licenses to determine their meaning, this FAQ
91 entry is not intended to change the meaning or terms of the licenses.
99 What is the difference between a bus name, and object path,
105 If you imagine a C++ program that implements a network service, then
106 the bus name is the hostname of the computer running this C++ program,
107 the object path is a C++ object instance pointer, and an interface is
108 a C++ class (a pure virtual or abstract class, to be exact).
111 In Java terms, the object path is an object reference,
112 and an interface is a Java interface.
115 People get confused because if they write an application
116 with a single object instance and a single interface,
117 then the bus name, object path, and interface look
118 redundant. For example, you might have a text editor
119 that uses the bus name <literal>org.freedesktop.TextEditor</literal>,
120 has a global singleton object called
121 <literal>/org/freedesktop/TextEditor</literal>, and
122 that singleton object could implement the interface
123 <literal>org.freedesktop.TextEditor</literal>.
126 However, a text editor application could as easily own multiple bus
127 names (for example, <literal>org.kde.KWrite</literal> in addition to
128 generic <literal>TextEditor</literal>), have multiple objects (maybe
129 <literal>/org/kde/documents/4352</literal> where the number changes
130 according to the document), and each object could implement multiple
131 interfaces, such as <literal>org.freedesktop.DBus.Introspectable</literal>,
132 <literal>org.freedesktop.BasicTextField</literal>,
133 <literal>org.kde.RichTextDocument</literal>.
139 <qandaentry id="service">
147 A service is a program that can be launched by the bus daemon
148 to provide some functionality to other programs. Services
149 are normally launched according to the bus name they will
153 People often misuse the word "service" for any
154 bus name, but this tends to be ambiguous and confusing so is discouraged.
155 In the D-Bus docs we try to use "service" only when talking about
156 programs the bus knows how to launch, i.e. a service always has a
162 <qandaentry id="components">
165 Is D-Bus a "component system"?
170 It helps to keep these concepts separate in your mind:
174 Object/component system
179 GUI control/widget embedding interfaces
184 Interprocess communication system or wire protocol
190 D-Bus is not a component system. "Component system" was originally
191 defined by COM, and was essentially a workaround for the limitations
192 of the C++ object system (adding introspection, runtime location of
193 objects, ABI guarantees, and so forth). With the C# language and CLR,
194 Microsoft added these features to the primary object system, leaving
195 COM obsolete. Similarly, Java has much less need for something like
196 COM than C++ did. Even QObject (from Qt) and GObject (from GLib) offer
197 some of the same features found in COM.
200 Component systems are not about GUI control embedding. Embedding
201 a spreadsheet in a word processor document is a matter of defining
202 some specific <emphasis>interfaces</emphasis> that objects
203 can implement. These interfaces provide methods related to
204 GUI controls. So an object implementing those interfaces
208 The word "component" just means "object with some fancy features" and
209 in modern languages all objects are effectively "components."
212 So components are fancy objects, and some objects are GUI controls.
215 A third, unrelated feature is interprocess communication or IPC.
216 D-Bus is an IPC system. Given an object (or "component" if you must),
217 you can expose the functionality of that object over an IPC system.
218 Examples of IPC systems are DCOM, CORBA, SOAP, XML-RPC, and D-Bus.
219 You can use any of these IPC systems with any object/component system,
220 though some of them are "tuned" for specific object systems.
221 You can think of an IPC system primarily as a wire protocol.
224 If you combine an IPC system with a set of GUI control interfaces,
225 then you can have an out-of-process or dynamically-loaded GUI control.
228 Another related concept is the <firstterm>plugin</firstterm> or
229 <firstterm>extension</firstterm>. Generic plugin systems such as the
230 <ulink url="http://eclipse.org">Eclipse</ulink> system are not so different
231 from component/object systems, though perhaps a "plugin" tends to be a
232 bundle of objects with a user-visible name and can be
233 downloaded/packaged as a unit.
238 <qandaentry id="speed">
241 How fast is the D-Bus reference implementation?
246 Of course it depends a bit on what you're doing.
247 <ulink url="http://lists.freedesktop.org/pipermail/dbus/2004-November/001779.html">
248 This mail</ulink> contains some benchmarking. At the time of that
249 benchmark, D-Bus one-to-one communication was about 2.5x slower than
250 simply pushing the data raw over a socket. After the recent rewrite of
251 the marshaling code, D-Bus is slower than that because a lot of
252 optimization work was lost. But it can probably be sped up again.
255 D-Bus communication with the intermediate bus daemon should be
256 (and as last profiled, was) about twice as slow as one-to-one
257 mode, because a round trip involves four socket reads/writes rather
258 than two socket reads/writes.
261 The overhead comes from a couple of places; part of it is simply
262 "abstraction penalty" (there are layers of code to support
263 multiple main loops, multiple transport types, security, etc.).
264 Probably the largest part comes from data validation
265 (because the reference implementation does not trust incoming data).
266 It would be simple to add a "no validation" mode, but probably
267 not a good idea all things considered.
270 Raw bandwidth isn't the only concern; D-Bus is designed to
271 enable asynchronous communication and avoid round trips.
272 This is frequently a more important performance issue
279 <qandaentry id="size">
282 How large is the D-Bus reference implementation?
287 A production build (with assertions, unit tests, and verbose logging
288 disabled) is on the order of a 150K shared library.
291 A much, much smaller implementation would be possible by omitting out
292 of memory handling, hardcoding a main loop (or always using blocking
293 I/O), skipping validation, and otherwise simplifying things.
298 <qandaentry id="other-ipc">
301 How does D-Bus differ from other interprocess communication
302 or networking protocols?
307 The best place to start is to read the D-Bus <ulink url="dbus-tutorial.html">tutorial</ulink>, so
308 you have a concrete idea what D-Bus actually is. If you
309 understand other protocols on a wire format level, you
310 may also want to read the D-Bus <ulink url="dbus-specification.html">specification</ulink> to see what
311 D-Bus looks like on a low level.
314 As the <ulink url="dbus-tutorial.html">tutorial</ulink> and <ulink url="dbus-specification.html">specification</ulink> both explain, D-Bus is tuned
315 for some specific use cases. Thus, it probably isn't tuned
316 for what you want to do, unless you are doing the things
317 D-Bus was designed for. Don't make the mistake of thinking
318 that any system labeled "IPC" is the same thing.
321 The D-Bus authors would not recommend using D-Bus
322 for applications where it doesn't make sense.
323 The following questions compare D-Bus to some other
324 protocols primarily to help you understand D-Bus
325 and decide whether it's appropriate; D-Bus is neither intended
326 nor claimed to be the right choice for every application.
329 It should be possible to bridge D-Bus to other IPC systems,
330 just as D-Bus can be bridged to object systems.
333 Note: the D-Bus mailing list subscribers are <emphasis>very much not
334 interested</emphasis> in debating which IPC system is the One True
335 System. So if you want to discuss that, please use another forum.
341 <qandaentry id="corba">
344 How does D-Bus differ from CORBA?
349 Start by reading <xref linkend="other-ipc"/>.
352 <ulink url="http://www.omg.org">CORBA</ulink> is designed to support
353 object-oriented IPC between objects, automatically marshalling
354 parameters as necessary. CORBA is strongly supported by the <ulink
355 url="http://www.omg.org">Open Management Group (OMG)</ulink>, which
356 produces various standards and supporting documents for CORBA and has
357 the backing of many large organizations. There are many CORBA ORBs
358 available, both proprietary ORBs and free / open source software ORBs
359 (the latter include <ulink
360 url="http://orbit-resource.sourceforge.net/">ORBit</ulink>, <ulink
361 url="http://www.mico.org/">MICO</ulink>, and <ulink
362 url="http://www.theaceorb.com/">The ACE Orb (TAO)</ulink>). Many
363 organizations continue to use CORBA ORBs for various kinds of IPC.
366 Both GNOME and KDE have used CORBA and then moved away from it. KDE
367 had more success with a system called DCOP, and GNOME layered a system
368 called Bonobo on top of CORBA. Without custom extensions, CORBA does
369 not support many of the things one wants to do in a desktop
370 environment with the GNOME/KDE architecture.
373 CORBA on the other hand has a number of features of interest for
374 enterprise and web application development, though XML systems such as
375 SOAP are the latest fad.
378 Like D-Bus, CORBA uses a fast binary protocol (IIOP). Both systems
379 work in terms of objects and methods, and have concepts such as
380 "oneway" calls. Only D-Bus has direct support for "signals" as in
381 GLib/Qt (or Java listeners, or C# delegates).
384 D-Bus hardcodes and specifies a lot of things that CORBA leaves open-ended,
385 because CORBA is more generic and D-Bus has two specific use-cases in mind.
386 This makes D-Bus a bit simpler.
389 However, unlike CORBA D-Bus does <emphasis>not</emphasis> specify the
390 API for the language bindings. Instead, "native" bindings adapted
391 specifically to the conventions of a framework such as QObject,
392 GObject, C#, Java, Python, etc. are encouraged. The libdbus reference
393 implementation is designed to be a backend for bindings of this
394 nature, rather than to be used directly. The rationale is that an IPC
395 system API should not "leak" all over a program; it should come into
396 play only just before data goes over the wire. As an aside, OMG is
397 apparently working on a simpler C++ binding for CORBA.
400 Many CORBA implementations such as ORBit are faster than the libdbus
401 reference implementation. One reason is that D-Bus considers data
402 from the other end of the connection to be untrusted and extensively
403 validates it. But generally speaking other priorities were placed
404 ahead of raw speed in the libdbus implementation. A fast D-Bus
405 implementation along the lines of ORBit should be possible, of course.
408 On a more trivial note, D-Bus involves substantially fewer acronyms
415 <qandaentry id="xmlrpcsoap">
418 How does D-Bus differ from XML-RPC and SOAP?
423 Start by reading <xref linkend="other-ipc"/>.
426 In <ulink url="http://www.w3.org/TR/SOAP/">SOAP</ulink> and <ulink
427 url="http://www.xmlrpc.com">XML-RPC</ulink>, RPC calls are transformed
428 into an XML-based format, then sent over the wire (typically using the
429 HTTP protocol), where they are processed and returned. XML-RPC is the
430 simple protocol (its spec is only a page or two), and SOAP is the
431 full-featured protocol.
434 XML-RPC and SOAP impose XML parsing overhead that is normally
435 irrelevant in the context of the Internet, but significant for
436 constant fine-grained IPC among applications in a desktop session.
439 D-Bus offers persistent connections and with the bus daemon
440 supports lifecycle tracking of other applications connected
441 to the bus. With XML-RPC and SOAP, typically each method call
442 exists in isolation and has its own HTTP connection.
447 <qandaentry id="dce">
450 How does D-Bus differ from DCE?
455 Start by reading <xref linkend="other-ipc"/>.
458 <ulink url="http://www.opengroup.org/dce/">Distributed Computing
459 Environment (DCE)</ulink> is an industry-standard vendor-neutral
460 standard that includes an IPC mechanism. <ulink
461 url="http://www.opengroup.org/comm/press/05-01-12.htm">The Open Group
462 has released an implementation as open source software</ulink>. DCE
463 is quite capable, and includes a vast amount of functionality such as
464 a distributed time service. As the name implies, DCE is intended for
465 use in a large, multi-computer distributed application. D-Bus would
466 not be well-suited for this.
472 <qandaentry id="dcom">
475 How does D-Bus differ from DCOM and COM?
480 Start by reading <xref linkend="other-ipc"/>.
483 Comparing D-Bus to COM is apples and oranges;
484 see <xref linkend="components"/>.
487 DCOM (distributed COM) is a Windows IPC system designed for use with
488 the COM object system. It's similar in some ways to DCE and CORBA.
493 <qandaentry id="internet-communications-engine">
496 How does D-Bus differ from ZeroC's Internet Communications Engine (Ice)
501 Start by reading <xref linkend="other-ipc"/>.
504 The <ulink url="http://www.zeroc.com/ice.html"> Internet
505 Communications Engine (Ice)</ulink> is a powerful IPC mechanism more
506 on the level of SOAP or CORBA than D-Bus. Ice has a "dual-license"
507 business around it; i.e. you can use it under the GPL, or pay for a
513 <qandaentry id="inter-client-exchange">
516 How does D-Bus differ from Inter-Client Exchange (ICE)?
521 <ulink url="http://www.x.org/X11R6.8.1/docs/ICE/ice.pdf">ICE</ulink>
522 was developed for the X Session Management protocol (XSMP), as part of
523 the X Window System (X11R6.1). The idea was to allow desktop sessions
524 to contain nongraphical clients in addition to X clients.
527 ICE is a binary protocol designed for desktop use, and KDE's DCOP
528 builds on ICE. ICE is substantially simpler than D-Bus (in contrast
529 to most of the other IPC systems mentioned here, which are more
530 complex). ICE doesn't really define a mapping to objects and methods
531 (DCOP adds that layer). The reference implementation of ICE (libICE)
532 is often considered to be horrible (and horribly insecure).
535 DCOP and XSMP are the only two widely-used applications of ICE,
536 and both could in principle be replaced by D-Bus. (Though whether
537 GNOME and KDE will bother is an open question.)
544 <qandaentry id="dcop">
547 How does D-Bus differ from DCOP?
552 Start by reading <xref linkend="other-ipc"/>.
555 D-Bus is intentionally pretty similar to <ulink
556 url="http://developer.kde.org/documentation/library/kdeqt/dcop.html">DCOP</ulink>,
557 and can be thought of as a "DCOP the next generation" suitable for
558 sharing between the various open source desktop projects.
561 D-Bus is a bit more complex than DCOP, though the Qt binding for D-Bus
562 should not be more complex for programmers. The additional complexity
563 of D-Bus arises from its separation of object references vs. bus names
564 vs. interfaces as distinct concepts, and its support for one-to-one
565 connections in addition to connections over the bus. The libdbus
566 reference implementation has a lot of API to support multiple bindings
567 and main loops, and performs data validation and out-of-memory handling
568 in order to support secure applications such as the systemwide bus.
571 D-Bus is probably somewhat slower than DCOP due to data validation
572 and more "layers" in the reference implementation. A comparison
573 hasn't been posted to the list though.
576 At this time, KDE has not committed to using D-Bus, but there have
577 been discussions of KDE bridging D-Bus and DCOP, or even changing
578 DCOP's implementation to use D-Bus internally (so that GNOME and KDE
579 would end up using exactly the same bus). See the KDE mailing list
580 archives for some of these discussions.
586 <qandaentry id="yet-more-ipc">
589 How does D-Bus differ from [yet more IPC mechanisms]?
594 Start by reading <xref linkend="other-ipc"/>.
597 There are countless uses of network sockets in the world. <ulink
598 url="http://www.mbus.org/">MBUS</ulink>, Sun ONC/RPC, Jabber/XMPP,
599 SIP, are some we can think of quickly.
605 <qandaentry id="which-ipc">
608 Which IPC mechanism should I use?
613 Start by reading <xref linkend="other-ipc"/>.
616 If you're writing an Internet or Intranet application, XML-RPC or SOAP
617 work for many people. These are standard, available for most
618 languages, simple to debug and easy to use.
621 If you're writing a desktop application for UNIX,
622 then D-Bus is of course our recommendation for
623 talking to other parts of the desktop session.
624 (With the caveat that you should use a stable release
625 of D-Bus; until we reach 1.0, there isn't a stable release.)
628 If you're doing something complicated such as clustering,
629 distributed swarms, peer-to-peer, or whatever then
630 the authors of this FAQ don't have expertise in these
631 areas and you should ask someone else or try a search engine.
634 Note: the D-Bus mailing list is probably not the place to
635 discuss which system is appropriate for your application,
636 though you are welcome to ask specific questions about
637 D-Bus <emphasis>after reading this FAQ, the tutorial, and
638 searching the list archives</emphasis>. The best way
639 to search the list archives is probably to use
640 an Internet engine such as Google. On Google,
641 include "site:freedesktop.org" in your search.
650 How can I submit a bug or patch?
655 The D-Bus <ulink url="http://dbus.freedesktop.org">web site</ulink>
656 has a link to the bug tracker, which is the best place to store
657 patches. You can also post them to the list, especially if you want
658 to discuss the patch or get feedback.