xcb-dl

This rust crate contains bindings for libxcb, libxcb-xinput, etc. Symbols are loaded dynamically at runtime, linking at compile time is not supported.

Hacking

Almost all code in this crate is auto-generated using the generate.py python script. Run generate-all to re-generate all code.

generate.py takes as input an xml file from the xcbproto project. For consistency, these files are vendored in the xcbproto directory. The current version is 1.14.1.

The python script a heavily modified version of the c_client.py script in the libxcb source code.

License

X11

lib.rs:

This crate contains bindings for libxcb, libxcb-xinput, etc. Symbols are loaded dynamically at runtime; linking at compile time is not supported.

Features

Only bindings for libxcb are available by default. Enable the appropriately named features to enable bindings for libxcb-xinput etc.

Handling Missing Symbols

Symbols are loaded lazily when they are accessed. If this fails, we panic. Enable the has_symbol feature to handle missing symbols more gracefully. This enables methods of the form has_X that return whether a symbol can be loaded.

let lib = xcb_dl::Xcb::load().unwrap();
if !lib.has_xcb_total_written() {
    eprintln!("Cannot monitor total number of bytes written.");
}

Constructing Structs

Future versions of this crate might add new fields to structs or remove padding fields. This is not considered a breaking change. Construct objects using Default::default() to ensure that your code remains valid:

let format = xcb_dl::ffi::xcb_format_t {
    depth: 0,
    bits_per_pixel: 0,
    scanline_pad: 0,
    ..Default::default()
};

Semantic Documentation

This crate contains almost no semantic documentation. Documentation of the X core protocol and extensions is available at freedesktop and x.org. Documentation of the libxcb functions that are not auto-generated from the protocols is available in the libxcb repository. Check src/xcb.h and src/xcbext.h.

libxcb Architecture

This sections provides a brief overview of the auto-generated functions in libxcb. Consult the libxcb documentation for more details.

The terminology in this section is not the official libxcb terminology.

libxcb sends requests to and receives messages from the X server. There are three types of messages:

• value replies: A success message sent in response to a request.
• error replies: An error sent in response to a request.
• events: An event such as a key press.

The code that sends a request can specify that replies should automatically be discarded by calling xcb_discard_reply.

libxcb maintains two queues for incoming messages:

• the event queue: Contains messages that can be retrieved via xcb_poll_for_event etc.
• the reply queue: Contains messages that can only be retrieved by the code that sent the request.

Events are always placed in the event queue.

Value replies are placed in the reply queue unless they are being discarded.

Each request has two variants:

• checked: Error replies are placed in the reply queue unless they are being discarded.
• unchecked: Error replies are placed in the event queue unless they are being discarded.

There are two types of requests:

• void requests: These do not generate value replies but can generate error replies.
• value requests: These can generate either value replies or error replies.

The default variant of void requests is unchecked. For each such request libxcb provides a function with the suffix _checked that uses the checked variant.

The default variant of value requests is checked. For each such request libxcb provides a function with the suffix _unchecked that uses the unchecked variant.

Messages placed in the reply queue must be retrieved by the user. Otherwise they will never be discarded.

For void requests, error replies can be retrieved by calling xcb_request_check.

For every value request libxcb provides a function with the suffix _reply that can be used to retrieve the value or error reply.

Memory Management

libxcb never takes ownership of memory passed to it.

The functions that return messages pass ownership of the message to the caller. These messages can be freed with libc::free.

Non-homogeneous Requests

Some requests contain variably sized data and possibly non-homogeneous arrays. To simplify creating such requests, libxcb provides auxiliary functions with the suffix _aux. These functions take fixed-sized arguments and internally create a serialized request.

Non-homogeneous Replies

Some replies contain variably sized data and possibly non-homogeneous arrays.

The data structures of libxcb do not contain fields for this data. Instead, libxcb provides accessor functions to retrieve pointers to these fields.

If the fields are non-homogeneous arrays, these accessor functions return iterators. The pointer in these iterators can be advanced by calling an appropriately named _next function.

If the fields are homogeneous arrays, libxcb provides _length functions that return the number of elements in the array.

In some cases these accessor functions return *mut c_void. In these cases libxcb usually provides an _unpack function that deserializes the data into a struct.