XCB

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.{{cite conference |last1=Gettys |first1=James |first2=Keith |last2=Packard |title=The (Re) Architecture of the X Window System |conference=Proc. Linux Symposium |volume=1 |year=2004 |url=https://keithp.com/~keithp/talks/xarch_ols2004/xarch_ols2004.pdf}} 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).{{cite conference |first=Jamey |last=Sharp |title=How Xlib is Implemented (And What We're Doing About It) |conference=Proc. Usenix Annual Techn. Conf., Freenix Track |year=2004 |url=http://www.freedesktop.org/software/xcb/xlib_impl.pdf}}

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.Massey and Bauer, 2002. (Xlib has long been known to contain errors.Sharp and Massey, 2002, §2.4. "While Xlib was designed to support threaded applications, and while that support is not unusable, there are known race conditions that cannot be eliminated without changing the Xlib interface.")

Xlib/XCB provides application binary interface compatibility with both Xlib and XCB, providing an incremental porting path.{{cite book |last1=Maloney |first1=Ross J. |title=Low Level X Window Programming: An Introduction by Examples |date=31 March 2018 |publisher=Springer |isbn=978-3-319-74250-2 |pages=225–244 |url=https://books.google.com/books?id=8r1TDwAAQBAJ&dq=XCB+library&pg=PA225 |access-date=17 May 2022 |language=en}} Xlib/XCB uses the protocol layer of Xlib, but replaces the Xlib transport layer with XCB, and provides access to the underlying XCB connection for direct use of XCB. Xlib/XCB allows an application to open a single connection to the X display server and use both XCB and Xlib, possibly through a mixture of libraries designed for one or the other.{{cite web |url=http://xcb.freedesktop.org/XlibXcb/ |title=Xlib/XCB: Xlib with XCB transport |date=2008-01-11 |access-date=2009-09-11}}{{cite mailing list |author=Jamey Sharp and Josh Triplett |url=http://lists.debian.org/debian-devel-announce/2006/11/msg00010.html |mailing-list=debian-devel-announce |title=libx11 with Xlib/XCB now in experimental; please test with your packages |date=2006-11-26 |access-date=2009-09-11}}

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

// To compile it using GNU, use:

// gcc x.c -lxcb

1. include
2. include
3. include

int main(void)

{

xcb_connection_t *c;

xcb_screen_t *s;

xcb_window_t w;

xcb_gcontext_t g;

xcb_generic_event_t *e;

uint32_t mask;

uint32_t values[2];

int done = 0;

xcb_rectangle_t r = { 20, 20, 60, 60 };

// open connection to the server

c = xcb_connect(NULL, NULL);

if (xcb_connection_has_error(c)) {

printf("Cannot open display\n");

exit(EXIT_FAILURE);

}

// get the first screen

s = xcb_setup_roots_iterator( xcb_get_setup(c) ).data;

// create black graphics context

g = xcb_generate_id(c);

w = s->root;

mask = XCB_GC_FOREGROUND | XCB_GC_GRAPHICS_EXPOSURES;

values[0] = s->black_pixel;

values[1] = 0;

xcb_create_gc(c, g, w, mask, values);

// create window

w = xcb_generate_id(c);

mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK;

values[0] = s->white_pixel;

values[1] = XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_KEY_PRESS;

xcb_create_window(c, s->root_depth, w, s->root,

10, 10, 100, 100, 1,

XCB_WINDOW_CLASS_INPUT_OUTPUT, s->root_visual,

mask, values);

// map (show) the window

xcb_map_window(c, w);

xcb_flush(c);

// event loop

while (!done && (e = xcb_wait_for_event(c))) {

switch (e->response_type & ~0x80) {

case XCB_EXPOSE: // draw or redraw the window

xcb_poly_fill_rectangle(c, w, g, 1, &r);

xcb_flush(c);

break;

case XCB_KEY_PRESS: // exit on key press

done = 1;

break;

}

free(e);

}

// close connection to server

xcb_disconnect(c);

exit(EXIT_SUCCESS);

}

The bitwise and operation a->response_type & ~0x80 removes a bit that indicates where the event came from.{{cite web |title=X Window System Protocol |url=https://www.x.org/releases/current/doc/xproto/x11protocol.html#event_format |website=X.Org |access-date=22 March 2024 |location=Chapter 1. Protocol Formats |quote=Every event contains an 8-bit type code. The most significant bit in this code is set if the event was generated from a SendEvent request.}}

XCB has a comparable, but slightly lower-level API than Xlib,{{citation |url=https://www.usenix.org/legacy/event/usenix02/tech/freenix/full_papers/sharp/sharp_html/ |title=XCL : An Xlib Compatibility Layer For XCB |author1=Jamey Sharp |author2=Bart Massey |publisher=USENIX 2002 Annual Technical Conference, Freenix Track |year=2002}} as can be seen with this example.

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|xml dialect is not an invention|date=March 2024}} libxcb itself is implemented as a code generator and a tiny C stub of utility functions.

An example:

extension-name="BigRequests" extension-multiword="true"

major-version="0" minor-version="0">

The XCB logo was produced by Gearóid Molloy, author of the web comic Neko the Kitty, and donated to the project.[http://xcb.freedesktop.org/KittyLogo/ KittyLogo] (xcb.freedesktop.org)

• [http://search.cpan.org/dist/X11-XCB/lib/X11/XCB.pm XCB.pm] - Perl module implementing bindings to XCB.
• [http://xcb.freedesktop.org/XcbPythonBinding/ 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.
• [https://github.com/tych0/xcffib/ xcffib] - Another Python binding which supports Python 2 & 3 as well as several more X extensions than xpyb.

{{Reflist}}

• {{cite conference

| author1 = Massey, Bart

| author2 = Sharp, Jamey

| title = XCB: An X Protocol C Binding

| book-title = Proceedings of the XFree86 Technical Conference

| publisher = USENIX

| date = 2001-09-19

| location = Oakland, California

| url = http://static.usenix.org/publications/library/proceedings/als01/full_papers/massey/massey.pdf

| access-date = 2012-03-12}}

• {{cite conference

| author1 = Massey, Bart

| author2 = Bauer, Robert

| title = X Meets Z: Verifying Correctness In The Presence Of POSIX Threads

| book-title = Proceedings of the FREENIX Track: 2002 USENIX Annual Technical Conference

| pages = 221–234

| publisher = USENIX

| year = 2002

| location = Monterey, California

| url = http://www.usenix.org/events/usenix02/tech/freenix/full_papers/massey/massey_html/index.html

| access-date = 2008-11-07

| ref = refMasseyBauer2002}}

• {{cite conference

| author1 = Sharp, Jamey

| author2 = Massey, Bart

| title = XCL: A Compatibility Layer For XCB

| book-title = Proceedings of the FREENIX Track: 2002 USENIX Annual Technical Conference

| pages = 71–83

| publisher = USENIX

| year = 2002

| location = Monterey, California

| url = http://www.usenix.org/events/usenix02/tech/freenix/full_papers/sharp/sharp_html/index.html

| access-date = 2008-11-07

| ref = refSharpMassey2002}}

{{Portal|Free Software}}

• [http://xcb.freedesktop.org/ XCB wiki] (freedesktop.org)
• [http://xcb.freedesktop.org/XcbApi/ XCB API reference], [http://xcb.freedesktop.org/tutorial/ tutorial]
• [http://www.x.org/releases/current/doc/libxcb/tutorial/index.html libxcb tutorial]
• [http://xcb.freedesktop.org/Publications Further publications]
• [http://xorg.freedesktop.org/wiki/guide/xlib-and-xcb/ The X New Developer’s Guide: Xlib and XCB]

{{freedesktop.org}}

{{XWinSys}}

{{Widget toolkits}}

{{DEFAULTSORT:Xcb}}

Category:C (programming language) libraries

Category:Freedesktop.org

Category:Freedesktop.org libraries

Category:Software using the MIT license

Category:X Window System