View source for XCB

{{Short description|X protocol C language binding library}}
{{Primary sources|date=November 2009}}

{{Infobox software
| name                   = XCB
| title                  = 
| logo                   = Xcb logo.svg
| logo size              = 200px
| logo caption           = 
| screenshot             = <!-- [[File: ]] -->
| caption                = 
| collapsible            = 
| author                 = Bart Massey
| developer              = Jamey Sharp, Josh Triplett, Bart Massey
| released               = {{Start date and age|2001}}
| discontinued           = 
| latest release version = {{wikidata|property|preferred|references|edit|P348|P548=Q2804309}}                                             | latest release date    = {{Start date and age|{{wikidata|qualifier|preferred|single|P348|P548=Q2804309|P577}}|df=yes}}
| latest preview version = 
| latest preview date    = <!-- {{Start date and age|YYYY|MM|DD|df=yes/no}} -->
| programming language   = [[C (programming language)|C]]
| operating system       = [[POSIX]]
| platform               = 
| size                   = 
| genre                  = [[X Window System core protocol|X11 client library]]
| license                = [[MIT License]]
| website                = {{URL|https://xcb.freedesktop.org}}
}}

[[File:X11 display server protocol.svg|thumb|X11-clients use XCB to communicate with the [[display server|X server]].]]
[[File:Linux Graphics Stack 2013.svg|thumb|A more complete view of the [[Linux]] graphics stack]]
[[File:Xlib and XCB in the X Window System graphics stack.svg|thumb|Programs often use [[GTK]] or [[FLTK]] or [[Qt (software)|Qt]] for their [[GUI widget]]s.]]
[[File:Free and open-source-software display servers and UI toolkits.svg|thumb|A more complete view of the components of an operating system for home computers.]]

'''XCB''' (''X protocol C-language Binding'') is a [[library (computer science)|library]] implementing the client side of the [[X Window System core protocol|X11]] display server protocol. XCB is written in the [[C (programming language)|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.<ref>{{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}}</ref> The main goals of XCB are to:
* reduce library size and complexity
* provide direct access to the [[X Window core protocol|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).<ref>{{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}}</ref>
Secondary goals include making the C interface [[Asynchronous communication|asynchronous]], facilitating better [[thread (computing)|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 (programming language)|Python]] creating the C bindings. (Previous versions used [[XSLT]] and [[m4 (computer language)|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 [[Formal verification|formally correct]] using [[Z notation]].<ref>[[#refMasseyBauer2002|Massey and Bauer, 2002]].</ref> (Xlib has long been known to contain errors.<ref>[[#refSharpMassey2002|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."</ref>)

===Xlib compatibility===
''Xlib/XCB'' provides [[application binary interface]] compatibility with both Xlib and XCB, providing an incremental porting path.<ref name="Maloney2018">{{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}}</ref> 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.<ref>{{cite web |url=http://xcb.freedesktop.org/XlibXcb/ |title=Xlib/XCB: Xlib with XCB transport |date=2008-01-11 |access-date=2009-09-11}}</ref><ref>{{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}}</ref>

==Example==
<syntaxhighlight lang="c">
// 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    *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);
}
</syntaxhighlight>

The [[Bitwise_operations_in_C#Bitwise_AND_&|bitwise and]] operation <syntaxhighlight lang="C" inline>a->response_type & ~0x80</syntaxhighlight> removes a bit that indicates where the event came from.<ref>{{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.}}</ref>

XCB has a comparable, but slightly lower-level API than [[Xlib#Example|Xlib]],<ref>{{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}}</ref> 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|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:
<syntaxhighlight lang="xml">
<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>
</syntaxhighlight>

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

==Other language bindings==
* [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.<!--
* Version 1.9.1 has Python 3 support.<ref name="release" />

No, don't confuse; you need python to build libxcb, and libxcb itself is a C binding. The cited mail says 1.9.1 has a bugfix to use python-3 to build libxcb.

-->

==Notes==
{{Reflist}}

==References==
* {{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&ndash;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&ndash;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}}

==External links==
{{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]]