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.1</releaseinfo>
11 <date>22 January 2005</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>. In
42 short, it is a system consisting of 1) a wire protocol for exposing a
43 typical object-oriented language/framework to other applications; and
44 2) a bus daemon that allows applications to find and monitor one another.
52 Is D-BUS stable/finished?
57 D-BUS has not yet reached 1.0. The <ulink url="README">README</ulink>
58 file has a discussion of the API/ABI stability guarantees before and
59 after 1.0. In short, there are no guarantees before 1.0, and stability
60 of both protocol and reference library will be maintained after 1.0.
61 As of January 2005 we don't expect major protocol or API changes prior
62 to the 1.0 release, but anything is possible.
70 How is the reference implementation licensed? Can I use it in
71 proprietary applications?
76 The short answer is yes, you can use it in proprietary applications.
77 You should read the <ulink url="COPYING">COPYING</ulink> file, which
78 offers you the choice of two licenses. These are the GPL and the
79 AFL. The GPL requires that your application be licensed under the GPL
80 as well. The AFL is an "X-style" or "BSD-style" license compatible
81 with proprietary licensing, but it does have some requirements; in
82 particular it prohibits you from filing a lawsuit alleging that the
83 D-BUS software infringes your patents <emphasis>while you continue to
84 use D-BUS</emphasis>. If you're going to sue, you have to stop using
85 the software. Read the licenses to determine their meaning, this FAQ
86 entry is not intended to change the meaning or terms of the licenses.
94 What is the difference between a bus name, and object path,
100 If you imagine a C++ program that implements a network service, then
101 the bus name is the hostname of the computer running this C++ program,
102 the object path is a C++ object instance pointer, and an interface is
103 a C++ class (a pure virtual or abstract class, to be exact).
106 In Java terms, the object path is an object reference,
107 and an interface is a Java interface.
110 People get confused because if they write an application
111 with a single object instance and a single interface,
112 then the bus name, object path, and interface look
113 redundant. For example, you might have a text editor
114 that uses the bus name <literal>org.freedesktop.TextEditor</literal>,
115 has a global singleton object called
116 <literal>/org/freedesktop/TextEditor</literal>, and
117 that singleton object could implement the interface
118 <literal>org.freedesktop.TextEditor</literal>.
121 However, a text editor application could as easily own multiple bus
122 names (for example, <literal>org.kde.KWrite</literal> in addition to
123 generic <literal>TextEditor</literal>), have multiple objects (maybe
124 <literal>/org/kde/documents/4352</literal> where the number changes
125 according to the document), and each object could implement multiple
126 interfaces, such as <literal>org.freedesktop.DBus.Introspectable</literal>,
127 <literal>org.freedesktop.BasicTextField</literal>,
128 <literal>org.kde.RichTextDocument</literal>.
134 <qandaentry id="service">
142 A service is a program that can be launched by the bus daemon
143 to provide some functionality to other programs. Services
144 are normally launched according to the bus name they will
150 <qandaentry id="components">
153 Is D-BUS a "component system"?
158 D-BUS is not a component system. "Component system" was originally
159 defined by COM, and was essentially a workaround for the limitations
160 of the C++ object system (adding introspection, runtime location of
161 objects, ABI guarantees, and so forth). With the C# language and CLR,
162 Microsoft added these features to the primary object system, leaving
163 COM obsolete. Similarly, Java has much less need for something like
164 COM than C++ did. Even QObject (from Qt) and GObject (from GLib) offer
165 some of the same features found in COM.
168 Component systems are not about GUI control embedding. Embedding
169 a spreadsheet in a word processor document is a matter of defining
170 some specific <emphasis>interfaces</emphasis> that objects
171 can implement. These interfaces provide methods related to
172 GUI controls. So an object implementing those interfaces
176 The word "component" just means "object with some fancy features" and
177 in modern languages all objects are effectively "components."
180 A third, orthogonal feature is interprocess communication or IPC.
181 D-BUS is an IPC system. Given an object (or "component" if you must),
182 you can expose the functionality of that object over an IPC system.
183 Examples of IPC systems are DCOM, CORBA, SOAP, XML-RPC, and D-BUS.
184 You can use any of these IPC systems with any object/component system,
185 though some of them are "tuned" for specific object systems.
186 You can think of an IPC system primarily as a wire protocol.
189 If you combine an IPC system with a set of GUI control interfaces,
190 then you can have an out-of-process or dynamically-loaded GUI control.
193 Summarizing, there are three orthogonal things:
197 Object/component system
202 Control embedding interfaces
207 Interprocess communication system or wire protocol
213 Another related concept is the <firstterm>plugin</firstterm> or
214 <firstterm>extension</firstterm>. Generic plugin systems such as the
215 <ulink url="http://eclipse.org">Eclipse</ulink> system are not so different
216 from component/object systems, though perhaps a "plugin" tends to be a
217 bundle of objects with a user-visible name and can be
218 downloaded/packaged as a unit.
223 <qandaentry id="speed">
226 How fast is the D-BUS reference implementation?
231 Of course it depends a bit on what you're doing.
232 <ulink url="http://lists.freedesktop.org/pipermail/dbus/2004-November/001779.html">
233 This mail</ulink> contains some benchmarking. At the time of that
234 benchmark, D-BUS one-to-one communication was about 2.5x slower than
235 simply pushing the data raw over a socket. After the recent rewrite of
236 the marshaling code, D-BUS is slower than that because a lot of
237 optimization work was lost. But it can probably be sped up again.
240 D-BUS communication with the intermediate bus daemon should be
241 (and as last profiled, was) about twice as slow as one-to-one
242 mode, because a round trip involves four socket reads/writes rather
243 than two socket reads/writes.
246 The overhead comes from a couple of places; part of it is simply
247 "abstraction penalty" (there are layers of code to support
248 multiple main loops, multiple transport types, security, etc.).
249 Probably the largest part comes from data validation
250 (because the reference implementation does not trust incoming data).
251 It would be simple to add a "no validation" mode, but probably
252 not a good idea all things considered.
255 Raw bandwidth isn't the only concern; D-BUS is designed to
256 enable asynchronous communication and avoid round trips.
257 This is frequently a more important performance issue
264 <qandaentry id="size">
267 How large is the D-BUS reference implementation?
272 A production build (with assertions, unit tests, and verbose logging
273 disabled) is on the order of a 150K shared library.
276 A much, much smaller implementation would be possible by omitting out
277 of memory handling, hardcoding a main loop (or always using blocking
278 I/O), skipping validation, and otherwise simplifying things.
283 <qandaentry id="other-ipc">
286 How does D-BUS differ from other interprocess communication
287 or networking protocols?
292 The best place to start is to read the D-BUS <ulink url="dbus-tutorial.html">tutorial</ulink>, so
293 you have a concrete idea what D-BUS actually is. If you
294 understand other protocols on a wire format level, you
295 may also want to read the D-BUS <ulink url="dbus-specification.html">specification</ulink> to see what
296 D-BUS looks like on a low level.
299 As the <ulink url="dbus-tutorial.html">tutorial</ulink> and <ulink url="dbus-specification.html">specification</ulink> both explain, D-BUS is tuned
300 for some specific use cases. Thus, it probably isn't tuned
301 for what you want to do, unless you are doing the things
302 D-BUS was designed for. Don't make the mistake of thinking
303 that any system labeled "IPC" is the same thing.
306 The D-BUS authors would not recommend using D-BUS
307 for applications where it doesn't make sense.
308 The following questions compare D-BUS to some other
309 protocols primarily to help you understand D-BUS
310 and decide whether it's appropriate; D-BUS is neither intended
311 nor claimed to be the right choice for every application.
314 It should be possible to bridge D-BUS to other IPC systems,
315 just as D-BUS can be bridged to object systems.
318 Note: the D-BUS mailing list subscribers are <emphasis>very much not
319 interested</emphasis> in debating which IPC system is the One True
320 System. So if you want to discuss that, please use another forum.
326 <qandaentry id="corba">
329 How does D-BUS differ from CORBA?
334 Start by reading <xref linkend="other-ipc"/>.
337 <ulink url="http://www.omg.org">CORBA</ulink> is designed to support
338 object-oriented IPC between objects, automatically marshalling
339 parameters as necessary. CORBA is strongly supported by the <ulink
340 url="http://www.omg.org">Open Management Group (OMG)</ulink>, which
341 produces various standards and supporting documents for CORBA and has
342 the backing of many large organizations. There are many CORBA ORBs
343 available, both proprietary ORBs and free / open source software ORBs
344 (the latter include <ulink
345 url="http://orbit-resource.sourceforge.net/">ORBit</ulink>, <ulink
346 url="http://www.mico.org/">MICO</ulink>, and <ulink
347 url="http://www.theaceorb.com/">The ACE Orb (TAO)</ulink>). Many
348 organizations continue to use CORBA ORBs for various kinds of IPC.
351 Both GNOME and KDE have used CORBA and then moved away from it. KDE
352 had more success with a system called DCOP, and GNOME layered a system
353 called Bonobo on top of CORBA. Without custom extensions, CORBA does
354 not support many of the things one wants to do in a desktop
355 environment with the GNOME/KDE architecture.
358 CORBA on the other hand has a number of features of interest for
359 enterprise and web application development, though XML systems such as
360 SOAP are the latest fad.
363 Like D-BUS, CORBA uses a fast binary protocol (IIOP). Both systems
364 work in terms of objects and methods, and have concepts such as
365 "oneway" calls. Only D-BUS has direct support for "signals" as in
366 GLib/Qt (or Java listeners, or C# delegates).
369 D-BUS hardcodes and specifies a lot of things that CORBA leaves open-ended,
370 because CORBA is more generic and D-BUS has two specific use-cases in mind.
371 This makes D-BUS a bit simpler.
374 However, unlike CORBA D-BUS does <emphasis>not</emphasis> specify the
375 API for the language bindings. Instead, "native" bindings adapted
376 specifically to the conventions of a framework such as QObject,
377 GObject, C#, Java, Python, etc. are encouraged. The libdbus reference
378 implementation is designed to be a backend for bindings of this
379 nature, rather than to be used directly. The rationale is that an IPC
380 system API should not "leak" all over a program; it should come into
381 play only just before data goes over the wire. As an aside, OMG is
382 apparently working on a simpler C++ binding for CORBA.
385 Many CORBA implementations such as ORBit are faster than the libdbus
386 reference implementation. One reason is that D-BUS considers data
387 from the other end of the connection to be untrusted and extensively
388 validates it. But generally speaking other priorities were placed
389 ahead of raw speed in the libdbus implementation. A fast D-BUS
390 implementation along the lines of ORBit should be possible, of course.
393 On a more trivial note, D-BUS involves substantially fewer acronyms
400 <qandaentry id="xmlrpcsoap">
403 How does D-BUS differ from XML-RPC and SOAP?
408 Start by reading <xref linkend="other-ipc"/>.
411 In <ulink url="http://www.w3.org/TR/SOAP/">SOAP</ulink> and <ulink
412 url="http://www.xmlrpc.com">XML-RPC</ulink>, RPC calls are transformed
413 into an XML-based format, then sent over the wire (typically using the
414 HTTP protocol), where they are processed and returned. XML-RPC is the
415 simple protocol (its spec is only a page or two), and SOAP is the
416 full-featured protocol.
419 XML-RPC and SOAP impose XML parsing overhead that is normally
420 irrelevant in the context of the Internet, but significant for
421 constant fine-grained IPC among applications in a desktop session.
424 D-BUS offers persistent connections and with the bus daemon
425 supports lifecycle tracking of other applications connected
426 to the bus. With XML-RPC and SOAP, typically each method call
427 exists in isolation and has its own HTTP connection.
432 <qandaentry id="dce">
435 How does D-BUS differ from DCE?
440 Start by reading <xref linkend="other-ipc"/>.
443 <ulink url="http://www.opengroup.org/dce/">Distributed Computing
444 Environment (DCE)</ulink> is an industry-standard vendor-neutral
445 standard that includes an IPC mechanism. <ulink
446 url="http://www.opengroup.org/comm/press/05-01-12.htm">The Open Group
447 has released an implementation as open source software</ulink>. DCE
448 is quite capable, and includes a vast amount of functionality such as
449 a distributed time service. As the name implies, DCE is intended for
450 use in a large, multi-computer distributed application. D-BUS would
451 not be well-suited for this.
457 <qandaentry id="dcom">
460 How does D-BUS differ from DCOM and COM?
465 Start by reading <xref linkend="other-ipc"/>.
468 Comparing D-BUS to COM is apples and oranges;
469 see <xref linkend="components"/>.
472 DCOM (distributed COM) is a Windows IPC system designed for use with
473 the COM object system. It's similar in some ways to DCE and CORBA.
478 <qandaentry id="internet-communications-engine">
481 How does D-BUS differ from ZeroC's Internet Communications Engine (Ice)
486 Start by reading <xref linkend="other-ipc"/>.
489 The <ulink url="http://www.zeroc.com/ice.html"> Internet
490 Communications Engine (Ice)</ulink> is a powerful IPC mechanism more
491 on the level of SOAP or CORBA than D-BUS. Ice has a "dual-license"
492 business around it; i.e. you can use it under the GPL, or pay for a
498 <qandaentry id="inter-client-exchange">
501 How does D-BUS differ from Inter-Client Exchange (ICE)?
506 <ulink url="http://www.x.org/X11R6.8.1/docs/ICE/ice.pdf">ICE</ulink>
507 was developed for the X Session Management protocol (XSMP), as part of
508 the X Window System (X11R6.1). The idea was to allow desktop sessions
509 to contain nongraphical clients in addition to X clients.
512 ICE is a binary protocol designed for desktop use, and KDE's DCOP
513 builds on ICE. ICE is substantially simpler than D-BUS (in contrast
514 to most of the other IPC systems mentioned here, which are more
515 complex). ICE doesn't really define a mapping to objects and methods
516 (DCOP adds that layer). The reference implementation of ICE (libICE)
517 is often considered to be horrible (and horribly insecure).
520 DCOP and XSMP are the only two widely-used applications of ICE,
521 and both could in principle be replaced by D-BUS. (Though whether
522 GNOME and KDE will bother is an open question.)
529 <qandaentry id="dcop">
532 How does D-BUS differ from DCOP?
537 Start by reading <xref linkend="other-ipc"/>.
540 D-BUS is intentionally pretty similar to <ulink
541 url="http://developer.kde.org/documentation/library/kdeqt/dcop.html">DCOP</ulink>,
542 and can be thought of as a "DCOP the next generation" suitable for
543 sharing between the various open source desktop projects.
546 D-BUS is a bit more complex than DCOP, though the Qt binding for D-BUS
547 should not be more complex for programmers. The additional complexity
548 of D-BUS arises from its separation of object references vs. bus names
549 vs. interfaces as distinct concepts, and its support for one-to-one
550 connections in addition to connections over the bus. The libdbus
551 reference implementation has a lot of API to support multiple bindings
552 and main loops, and performs data validation and out-of-memory handling
553 in order to support secure applications such as the systemwide bus.
556 D-BUS is probably somewhat slower than DCOP due to data validation
557 and more "layers" in the reference implementation. A comparison
558 hasn't been posted to the list though.
561 At this time, KDE has not committed to using D-BUS, but there have
562 been discussions of KDE bridging D-BUS and DCOP, or even changing
563 DCOP's implementation to use D-BUS internally (so that GNOME and KDE
564 would end up using exactly the same bus). See the KDE mailing list
565 archives for some of these discussions.
571 <qandaentry id="yet-more-ipc">
574 How does D-BUS differ from [yet more IPC mechanisms]?
579 Start by reading <xref linkend="other-ipc"/>.
582 There are countless uses of network sockets in the world. <ulink
583 url="http://www.mbus.org/">MBUS</ulink>, Sun ONC/RPC, Jabber/XMPP,
584 SIP, are some we can think of quickly.
590 <qandaentry id="which-ipc">
593 Which IPC mechanism should I use?
598 Start by reading <xref linkend="other-ipc"/>.
601 If you're writing an Internet or Intranet application, XML-RPC or SOAP
602 work for many people. These are standard, available for most
603 languages, simple to debug and easy to use.
606 If you're writing a desktop application for UNIX,
607 then D-BUS is of course our recommendation for
608 talking to other parts of the desktop session.
609 (With the caveat that you should use a stable release
610 of D-BUS; until we reach 1.0, there isn't a stable release.)
613 If you're doing something complicated such as clustering,
614 distributed swarms, peer-to-peer, or whatever then
615 the authors of this FAQ don't have expertise in these
616 areas and you should ask someone else or try a search engine.
619 Note: the D-BUS mailing list is probably not the place to
620 discuss which system is appropriate for your application,
621 though you are welcome to ask specific questions about
622 D-BUS <emphasis>after reading this FAQ, the tutorial, and
623 searching the list archives</emphasis>. The best way
624 to search the list archives is probably to use
625 an Internet engine such as Google. On Google,
626 include "site:freedesktop.org" in your search.
635 How can I submit a bug or patch?
640 The D-BUS <ulink url="http://dbus.freedesktop.org">web site</ulink>
641 has a link to the bug tracker, which is the best place to store
642 patches. You can also post them to the list, especially if you want
643 to discuss the patch or get feedback.