• D-Bus is low-latency because it is designed to avoid round trips and allow asynchronous operation, much like the X protocol.

• D-Bus is low-overhead because it uses a binary protocol, and does not have to convert to and from a text format such as XML. Because D-Bus is intended for potentially high-resolution same-machine IPC, not primarily for Internet IPC, this is an interesting optimization.

• D-Bus is easy to use because it works in terms of messages rather than byte streams, and automatically handles a lot of the hard IPC issues. Also, the D-Bus library is designed to be wrapped in a way that lets developers use their framework's existing object/type system, rather than learning a new one specifically for IPC.

• A "system bus" for notifications from the system to user sessions, and to allow the system to request input from user sessions.

• A "session bus" used to implement desktop environments such as GNOME and KDE.

The D-Bus protocol is frozen (only compatible extensions are allowed) as of November 8, 2006. However, this specification could still use a fair bit of work to make interoperable reimplementation possible without reference to the D-Bus reference implementation. Thus, this specification is not marked 1.0. To mark it 1.0, we'd like to see someone invest significant effort in clarifying the specification language, and growing the specification to cover more aspects of the reference implementation's behavior.

Until this work is complete, any attempt to reimplement D-Bus will probably require looking at the reference implementation and/or asking questions on the D-Bus mailing list about intended behavior. Questions on the list are very welcome.

Nonetheless, this document should be a useful starting point and is to our knowledge accurate, though incomplete.

The D-Bus protocol does not include type tags in the marshaled data; a block of marshaled values must have a known type signature. The type signature is made up of type codes. A type code is an ASCII character representing the type of a value. Because ASCII characters are used, the type signature will always form a valid ASCII string. A simple string compare determines whether two type signatures are equivalent.

As a simple example, the type code for 32-bit integer (INT32) is the ASCII character 'i'. So the signature for a block of values containing a single INT32 would be:

          "i"
        

A block of values containing two INT32 would have this signature:

          "ii"
        

All basic types work like INT32 in this example. To marshal and unmarshal basic types, you simply read one value from the data block corresponding to each type code in the signature. In addition to basic types, there are four container types: STRUCT, ARRAY, VARIANT, and DICT_ENTRY.

STRUCT has a type code, ASCII character 'r', but this type code does not appear in signatures. Instead, ASCII characters '(' and ')' are used to mark the beginning and end of the struct. So for example, a struct containing two integers would have this signature:

          "(ii)"
        

Structs can be nested, so for example a struct containing an integer and another struct:

          "(i(ii))"
        

The value block storing that struct would contain three integers; the type signature allows you to distinguish "(i(ii))" from "((ii)i)" or "(iii)" or "iii".

The STRUCT type code 'r' is not currently used in the D-Bus protocol, but is useful in code that implements the protocol. This type code is specified to allow such code to interoperate in non-protocol contexts.

Empty structures are not allowed; there must be at least one type code between the parentheses.

ARRAY has ASCII character 'a' as type code. The array type code must be followed by a single complete type. The single complete type following the array is the type of each array element. So the simple example is:

          "ai"
        

which is an array of 32-bit integers. But an array can be of any type, such as this array-of-struct-with-two-int32-fields:

          "a(ii)"
        

Or this array of array of integer:

          "aai"
        

The phrase single complete type deserves some definition. A single complete type is a basic type code, a variant type code, an array with its element type, or a struct with its fields. So the following signatures are not single complete types:

          "aa"
        

          "(ii"
        

          "ii)"
        

And the following signatures contain multiple complete types:

          "ii"
        

          "aiai"
        

          "(ii)(ii)"
        

Note however that a single complete type may contain multiple other single complete types.

VARIANT has ASCII character 'v' as its type code. A marshaled value of type VARIANT will have the signature of a single complete type as part of the value. This signature will be followed by a marshaled value of that type.

A DICT_ENTRY works exactly like a struct, but rather than parentheses it uses curly braces, and it has more restrictions. The restrictions are: it occurs only as an array element type; it has exactly two single complete types inside the curly braces; the first single complete type (the "key") must be a basic type rather than a container type. Implementations must not accept dict entries outside of arrays, must not accept dict entries with zero, one, or more than two fields, and must not accept dict entries with non-basic-typed keys. A dict entry is always a key-value pair.

The first field in the DICT_ENTRY is always the key. A message is considered corrupt if the same key occurs twice in the same array of DICT_ENTRY. However, for performance reasons implementations are not required to reject dicts with duplicate keys.

In most languages, an array of dict entry would be represented as a map, hash table, or dict object.

The following table summarizes the D-Bus types.

Given a type signature, a block of bytes can be converted into typed values. This section describes the format of the block of bytes. Byte order and alignment issues are handled uniformly for all D-Bus types.

A block of bytes has an associated byte order. The byte order has to be discovered in some way; for D-Bus messages, the byte order is part of the message header as described in the section called “Message Format”. For now, assume that the byte order is known to be either little endian or big endian.

Each value in a block of bytes is aligned "naturally," for example 4-byte values are aligned to a 4-byte boundary, and 8-byte values to an 8-byte boundary. To properly align a value, alignment padding may be necessary. The alignment padding must always be the minimum required padding to properly align the following value; and it must always be made up of nul bytes. The alignment padding must not be left uninitialized (it can't contain garbage), and more padding than required must not be used.

Given all this, the types are marshaled on the wire as follows:

A message consists of a header and a body. The header is a block of values with a fixed signature and meaning. The body is a separate block of values, with a signature specified in the header.

The length of the header must be a multiple of 8, allowing the body to begin on an 8-byte boundary when storing the entire message in a single buffer. If the header does not naturally end on an 8-byte boundary up to 7 bytes of nul-initialized alignment padding must be added.

The message body need not end on an 8-byte boundary.

The maximum length of a message, including header, header alignment padding, and body is 2 to the 27th power or 134217728. Implementations must not send or accept messages exceeding this size.

The signature of the header is:

          "yyyyuua(yv)"
        

Written out more readably, this is:

          BYTE, BYTE, BYTE, BYTE, UINT32, UINT32, ARRAY of STRUCT of (BYTE,VARIANT)
        

These values have the following meanings:

Message types that can appear in the second byte of the header are:

Flags that can appear in the third byte of the header: