XCB

This article relies excessively on references to primary sources. Please improve this article by adding secondary or tertiary sources. Find sources: "XCB" – news · newspapers · books · scholar · JSTOR (November 2009) (Learn how and when to remove this message)

XCB
Original author	Bart Massey
Developers	Jamey Sharp, Josh Triplett, Bart Massey
Release	2001; 25 years ago (2001)
Stable release	1.17.0  / 15 April 2024; 2 years ago (15 April 2024)
Written in	C
Operating system	POSIX
Type	X11 client library
License	MIT License
Website	xcb.freedesktop.org
Repository	gitlab.freedesktop.org/xorg/lib/libxcb

XCB (X protocol C-language Binding) is a library implementing the client side of the X11 display server protocol. XCB is written in the C programming language and distributed under the MIT License. The project was started in 2001 by Bart Massey and aims to replace Xlib.

Overview

XCB was designed as a smaller, modernized replacement for Xlib, previously the primary C library for communicating with the X window system, coinciding with a more complete overhaul of the X implementation that took place during the early 2000s. The main goals of XCB are to:

• reduce library size and complexity
• provide direct access to the X11 protocol

The required size reduction is achieved primarily by restricting XCB's scope to handling the X protocol and omitting Xlib functionality such as its extensive utility library, much of which saw little use by applications. This results in a factor thirty reduction of the compiled library size (as of 2004). Secondary goals include making the C interface asynchronous, facilitating better multithreading and making it easier to implement extensions (via XML protocol descriptions).

The core and extension protocol descriptions are in XML, with a program written in Python creating the C bindings. (Previous versions used XSLT and M4.)

A further goal is to be able to use these protocol descriptions to create protocol documentation, more language bindings, and server-side stubs.

Massey and others have worked to prove key portions of XCB formally correct using Z notation. (Xlib has long been known to contain errors.)

Example

// Simple XCB application for opening a window and drawing a box in it

// To compile it using GNU, use:
// gcc x.c -lxcb

#include <stdio.h>
#include <stdlib.h>
#include <xcb/xcb.h>

int main(void)
{
  xcb_connection_t    *connection;
  xcb_screen_t        *screen;
  xcb_window_t         window;
  xcb_gcontext_t       context;
  xcb_generic_event_t *event;
  uint32_t             mask;
  uint32_t             values[2];
  int                  done = 0;
  xcb_rectangle_t      r = { 20, 20, 60, 60 };

  // open connection to the server
  connection = xcb_connect(NULL, NULL);
  if (xcb_connection_has_error(connection)) {
    printf("Cannot open display\n");
    exit(EXIT_FAILURE);
  }
  // get the first screen
  screen = xcb_setup_roots_iterator( xcb_get_setup(connection) ).data;

  // create black graphics context
  context = xcb_generate_id(connection);
  window = screen->root;
  mask = XCB_GC_FOREGROUND | XCB_GC_GRAPHICS_EXPOSURES;
  values[0] = screen->black_pixel;
  values[1] = 0;
  xcb_create_gc(connection, context, window, mask, values);

  // create window
  window = xcb_generate_id(connection);
  mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK;
  values[0] = screen->white_pixel;
  values[1] = XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_KEY_PRESS;
  xcb_create_window(connection, screen->root_depth, window, screen->root,
                    10, 10, 100, 100, 1,
                    XCB_WINDOW_CLASS_INPUT_OUTPUT, screen->root_visual,
                    mask, values);

  // map (show) the window
  xcb_map_window(connection, window);

  xcb_flush(connection);

  // event loop
  while (!done && (event = xcb_wait_for_event(connection))) {

    switch (event->response_type & ~0x80) {
    case XCB_EXPOSE:    // draw or redraw the window
      xcb_poly_fill_rectangle(connection, window, context,  1, &r);
      xcb_flush(connection);
      break;
    case XCB_KEY_PRESS:  // exit on key press
      done = 1;
      break;
    }
    free(event);
  }
  // close connection to server
  xcb_disconnect(connection);

  exit(EXIT_SUCCESS);
}

The bitwise and operation a->response_type & ~0x80 removes a bit that indicates where the event came from.

XCB has a comparable, but slightly lower-level API than Xlib, as can be seen with this example.

Protocol description

Creators of XCB have invented a specialized interface description language to model X11 protocol in language-neutral way and facilitate generation of bindings to other programming languages.^{[dubious – discuss]} libxcb itself is implemented as a code generator and a tiny C stub of utility functions.

An example:

<xcb header="bigreq" extension-xname="BIG-REQUESTS"
    extension-name="BigRequests" extension-multiword="true"
    major-version="0" minor-version="0">

  <request name="Enable" opcode="0">
    <reply>
      <pad bytes="1" />
      <field type="CARD32" name="maximum_request_length" />
    </reply>
  </request>
</xcb>

Logo

The XCB logo was produced by Gearóid Molloy, author of the web comic Neko the Kitty, and donated to the project.

Other language bindings

• XCB.pm - Perl module implementing bindings to XCB.
• xpyb - The Python binding to the X Window System using XCB. As of June 2013, it does not support Python 3. Provided by freedesktop.org.
• xcffib - Another Python binding which supports Python 2 & 3 as well as several more X extensions than xpyb.
• guile-xcb - Guile module implementing a language to treat the xcb definition as source code.