path: root/XcbApi.mdwn

[[toc levels="6"]]

This is the API for [[XCB]]. At this moment the code does not reflect the API described here, which is undergoing what I hope will be the last publically-visible changes (aside from any future additions). Entries where the documentation does not agree with current CVS are marked with this symbol: [!] . If you have any comments, now is the time: they will be welcomed.

Each function and data structure documents the source file containing its declaration, in addition to the usual sorts of documentation.

# Public API

These functions are declared in xcb.h.

<a name="XCBConnection"></a>

## XCBConnection

(xcbint.h)

`typedef struct XCBConnection XCBConnection`

An XCBConnection is an opaque structure containing all data that [[XCB]] needs to communicate with an X server.

<a name="XCBExtension"></a>

## XCBExtension

(xcb.h)

`typedef struct XCBExtension XCBExtension`

An XCBExtension is an opaque structure used as key for [XCBGetExtensionData](#XCBGetExtensionData).

<a name="XCBAuthInfoHost"></a>

## XCBAuthInfoHost

(xcb.h [!] )

    typedef struct XCBAuthInfoHost {
             unsigned short family;
             unsigned short addresslen;
             char *address;
             unsigned short displaylen;
             char *display;
    } XCBAuthInfoHost;

Identifier for an X server.

<dl>
  <dt>family</dt>
  <dd>
    <p>one of the families defined in X.h or Xauth.h; usually [[FamilyInternet]] or [[FamilyLocal]].</p>
  </dd>
  <dt>address</dt>
  <dd>
    <p>interpreted in a family-specific manner; for [[FamilyInternet]], a <tt>struct in_addr</tt> (see ip(7)).</p>
  </dd>
  <dt>display</dt>
  <dd>string containing the display number.</dd>
</dl>

<a name="XCBAuthInfo"></a>

## XCBAuthInfo

(xcb.h)

    typedef struct XCBAuthInfo {
             int namelen;
             char *name;
             int datalen;
             char *data;
    } XCBAuthInfo;

A container for authorization information to be sent to the X server.

<dl>
  <dt>name</dt>
  <dd>string containing the authentication protocol name, such as &quot;MIT-MAGIC-COOKIE-1&quot; or &quot;XDM-AUTHORIZATION-1&quot;.</dd>
  <dt>data</dt>
  <dd>interpreted in a protocol-specific manner.</dd>
</dl>

<a name="XCBConnect"></a>

## XCBConnect

(xcb\_util.c [!] )

`XCBConnection *XCBConnect(const char *display, int *screen)`

Connects to the X server specified by `display`. If `display` is null, uses the value of the DISPLAY environment variable. If a particular screen on that server is preferred, the int pointed to by `screen` (if non-null) will be set to that screen; otherwise the screen will be set to 0.

Calls:

- [XCBGetFDFromDisplay](#XCBGetFDFromDisplay)
- [XCBGetAuthInfo](#XCBGetAuthInfo)
- [XCBConnectToFD](#XCBConnectToFD)

<a name="XCBConnectToDisplayWithAuthInfo"></a>

## XCBConnectToDisplayWithAuthInfo

(xcb\_util.c [!] )

`XCBConnection *XCBConnectToDisplayWithAuthInfo(const char *display, XCBAuthInfo *auth, int *screen)`

Connects to the X server specified by `display`, using the given authorization information. If a particular screen on that server is preferred, the int pointed to by `screen` (if non-null) will be set to that screen; otherwise the screen will be set to 0.

Calls:

- [XCBGetFDFromDisplay](#XCBGetFDFromDisplay)
- [XCBConnectToFD](#XCBConnectToFD)

<a name="XCBConnectToFD"></a>

## XCBConnectToFD

(xcb\_conn.c [!] )

`XCBConnection *XCBConnectToFD(int fd, XCBAuthInfo *auth_info)`

Connects to an X server, given an open socket and a suitable [XCBAuthInfo](http://xcb.freedesktop.org/wiki/).

<dl>
  <dt>fd</dt>
  <dd>
    <p>a file descriptor bidirectionally connected to an X server. <a href="#XCBGetTCPFD">XCBGetTCPFD</a> and <a href="#XCBGetUnixFD">XCBGetUnixFD</a> return appropriate file descriptors.</p>
  </dd>
  <dt>auth_info</dt>
  <dd>
    <p>authentication data, or 0 if the connection should be unauthenticated. <a href="#XCBGetAuthInfo">XCBGetAuthInfo</a> returns appropriate authentication data.</p>
  </dd>
  <dt>Returns</dt>
  <dd>
    <p>an <a href="#XCBConnection">XCBConnection</a>, or 0 on failure.</p>
  </dd>
</dl>

See also [XCBConnect](#XCBConnect).

<a name="XCBDisconnect"></a>

## XCBDisconnect

(xcb\_conn.c)

`void XCBDisconnect(XCBConnection *c)`

Closes the file descriptor and frees all memory associated with the connection.

<dl>
  <dt>c</dt>
  <dd>
    <p>a connection previously returned by <a href="#XCBConnect">XCBConnect</a> and not previously passed to XCBDisconnect.</p>
  </dd>
</dl>

<a name="XCBGetFDFromDisplay"></a>

## XCBGetFDFromDisplay

(xcb\_util.c [!] )

`int XCBGetFDFromDisplay(const char *name, int *screenp, XCBAuthInfoHost *host)`

Calls:

- [XCBParseDisplay](#XCBParseDisplay)
- [XCBGetTCPFD](#XCBGetTCPFD) or [XCBGetUnixFD](#XCBGetUnixFD)

<a name="XCBParseDisplay"></a>

## XCBParseDisplay

(xcb\_util.c)

`int XCBParseDisplay(const char *name, char **host, int *display, int *screen)`

Parses a display string `name` in the form documented by X(7x). Has no side effects on failure.

- name\*: the display name to parse. host\*: a non-null pointer to a pointer which will be set to a malloc'd copy of the hostname. display\*: a non-null pointer to an int which will be set to the display number. screen\*: a (possibly null) pointer to an int which will be set to the preferred screen number, or set to 0 if the display string does not contain a screen number. Returns\*: 0 on failure (perhaps `name` was null or unparsable); non-zero on success.

<a name="XCBGetTCPFD"></a>

## XCBGetTCPFD

(xcb\_util.c [!] )

`int XCBGetTCPFD(const char *hostname, unsigned short display, XCBAuthInfoHost *host)`

Opens a TCP socket to the given `hostname`. The destination port is `display` plus 6000. If `host` is not null, it is filled in with values appropriate for passing to [XCBGetAuthInfo](#XCBGetAuthInfo).

<a name="XCBGetUnixFD"></a>

## XCBGetUnixFD

(xcb\_util.c [!] )

`int XCBGetUnixFD(unsigned short display, XCBAuthInfoHost *host)`

Opens a Unix-domain socket. The filename is "/tmp/.X11-unix/X" plus `display`. If `host` is not null, it is filled in with values appropriate for passing to [XCBGetAuthInfo](#XCBGetAuthInfo).

<a name="XCBGetAuthInfo"></a>

## XCBGetAuthInfo

(xcb\_auth.c [!] )

`int XCBGetAuthInfo(XCBAuthInfoHost *host, XCBAuthInfo *info)`

Looks up the best available authorization data for the given host.

The current implementation is a wrapper around the Xau library, which looks up hosts in the file specified by the environment variable XAUTHORITY, or the file $HOME/.Xauthority if the first fails. To manipulate this file, see xauth(1x).

<a name="XCBGetSetupData"></a>

## XCBGetSetupData

(xcb\_conn.c [!] )

`XCBConnSetupSuccessRep *XCBGetSetupData(XCBConnection *c)`

Accessor for the data returned by the server when the [XCBConnection](#XCBConnection) was initialized.

This data includes

- the server's required format for images,
- a list of available visuals,
- a list of available screens,
- the server's maximum request length (in the absence of the BIG-REQUESTS extension),
- and other assorted information.

See the X protocol specification for more details.

<a name="XCBGetFileDescriptor"></a>

## XCBGetFileDescriptor

(xcb\_conn.c)

`int XCBGetFileDescriptor(XCBConnection *c)`

Accessor for the file descriptor that was passed to the [XCBConnectToFD](#XCBConnectToFD) call that returned `c`.

<a name="XCBGetMaximumRequestLength"></a>

## XCBGetMaximumRequestLength

(xcb\_conn.c)

`CARD32 XCBGetMaximumRequestLength(XCBConnection *c)`

In the absence of the BIG-REQUESTS extension, returns the maximum_request_length field from the connection setup data, which may be as much as 65535. If the server supports BIG-REQUESTS, then the maximum_request_length field from the reply to the [[BigRequestsEnable]] request will be returned instead.

Note that this length is measured in four-byte units, making the theoretical maximum lengths roughly 256kB without BIG-REQUESTS and 16GB with.

<a name="XCBWaitForEvent"></a>

## XCBWaitForEvent

(xcb\_in.c [!] )

`XCBGenericEvent *XCBWaitForEvent(XCBConnection *c)`

Returns the next event or error from the server, or returns null in the event of an I/O error. Blocks until either an event or error arrive, or an I/O error occurs.

<a name="XCBPollForEvent"></a>

## XCBPollForEvent

(xcb\_in.c)

`XCBGenericEvent *XCBPollForEvent(XCBConnection *c, int *error)`

Returns the next event or error from the server, if one is available, or returns null otherwise. If no event is available, that might be because an I/O error like connection close occurred while attempting to read the next event.

- error\*: pointer to an int to be filled in with the I/O error status of the operation. If \*error\* is null, terminates the application when an I/O error occurs.

<a name="XCBFlush"></a>

## XCBFlush

(xcb\_out.c)

`int XCBFlush(XCBConnection *c)`

Forces any buffered output to be written to the server. Blocks until the write is complete.

<a name="XCBSync"></a>

## XCBSync

(xcb\_util.c)

`int XCBSync(XCBConnection *c, XCBGenericError **e)`

Blocks the calling thread for the duration of one round trip to the server, ensuring that all events and errors caused by previous requests are available to XCB.

<a name="XCBGetExtensionData"></a>

## XCBGetExtensionData

(xcb\_ext.c)

`const XCBQueryExtensionRep *XCBGetExtensionData(XCBConnection *c, XCBExtension *ext)`

This function is the primary interface to the "extension cache", which caches reply information from [[QueryExtension]] requests. Invoking this function may cause a call to XCBQueryExtension to retrieve extension information from the server, and may block until extension data is received from the server.

Do not free the returned XCBQueryExtensionRep - this storage is managed by the cache itself.

<a name="XCBPrefetchExtensionData"></a>

## XCBPrefetchExtensionData

(xcb\_ext.c)

`void XCBPrefetchExtensionData(XCBConnection *c, XCBExtension *ext)`

This function allows a "prefetch" of extension data into the extension cache. Invoking the function may cause a call to XCBQueryExtension, but will not block waiting for the reply. [XCBGetExtensionData](#XCBGetExtensionData) will return the prefetched data after possibly blocking while it is retrieved.

# Protocol Stub API

These are not single functions or types, but rather naming conventions intended to be used in the core protocol API and the public API for all extensions. All declarations associated with the core protocol are in xcb.h, while each extension provides all of its declarations in its own header file.

One of the design goals of this API is that users should be able to learn these conventions, then read documentation on the binary encoding of the core protocol or any extension, and immediately determine the correct function name and argument list to generate the desired request.

## Extensions

### XCB"&lt;Extension&gt;"Id

`[#XCBExtension XCBExtension] XCB"<Extension>"Id`

A unique object identifying this extension for [XCBGetExtensionData](#XCBGetExtensionData).

## Fields

Several conventions apply to field names.

- Fields have underscore-separated lower-case names.
- Where a field represents an object in an X protocol specification document, the name is formed by replacing dash ("-") and space (" ") characters with underscores ("\_").
- Where a field holds the length of field "foo", its name is "foo\_len".

## Types

The C name for the X type with name "Name" is XCB&lt;"Name"&gt;. If the type is from an extension, then "Name" is composed by prefixing the extension name onto the type name.

[!] _**TODO:**Links to XCBProtocolLanguage should be changed to point to appropriate [[XmlXcb]] documentation._

Types are declared using the [[STRUCT|XCBProtocolLanguage]], [[UNION|XCBProtocolLanguage]], [[XIDTYPE|XCBProtocolLanguage]], [[ENUM|XCBProtocolLanguage]], and ["XCBProtocolLanguage#TYPEDEF: TYPEDEF] protocol description macros.

<a name="XCBNameIter"></a>

### XCB&lt;Name&gt;Iter

    typedef struct {
             XCB<Name>; *data;
             int rem;
             int index;
    } XCB<Name>Iter;

An iterator may only be created for types declared using the [[STRUCT|XCBProtocolLanguage]] and [[XIDTYPE|XCBProtocolLanguage]] protocol description macros.

A special iterator type, XCBGenericIter, is declared in xcb.h.

### XCB&lt;Name&gt;Next

`void XCB&<"Name">Next(XCB<"Name">Iter *i)`

Every [iterator](#XCBNameIter) has a XCB&lt;"Name"&gt;Next function.

### XCB&lt;Name&gt;End

`XCBGenericIter XCB<Name">End(XCB<"Name">Iter i)`

Every [iterator](#XCBNameIter) has a XCB&lt;"Name"&gt;End function.

### XCB&lt;TypeName&gt;&lt;Field&gt;Iter

`XCB<"BaseType">Iter XCB<"TypeName"><"Field">Iter(XCB<"TypeName"> *R)`

Declared by the [[LISTFIELD|XCBProtocolLanguage]] protocol description macro.

### XCB&lt;TypeName&gt;&lt;Field&gt;

`<"BaseType"> *XCB<"TypeName"><"Field">(XCB<"TypeName"> *R)`

Declared by the [[LISTFIELD|XCBProtocolLanguage]] protocol description macro.

### XCB&lt;TypeName&gt;&lt;Field&gt;Length

`int XCB<"TypeName"><"Field">Length(XCB<"TypeName"> *R)`

Declared by the [[LISTFIELD|XCBProtocolLanguage]] protocol description macro.

### XCB&lt;TypeName&gt;&lt;Field&gt;End

`XCBGenericIter XCB<"TypeName"><"Field">End(XCB<"TypeName"> *R)`

Declared by the [[LISTFIELD|XCBProtocolLanguage]] protocol description macro.

### XCB&lt;Name&gt;New

`XCB<"Name"> XCB<"Name">New(XCBConnection *c)`

Allocate a new XID of the appropriate kind.

Declared by the [[XIDTYPE|XCBProtocolLanguage]] protocol description macro.

## Requests

Every request declared using the [[REQUEST|XCBProtocolLanguage]] or [[VOIDREQUEST|XCBProtocolLanguage]] protocol description macros generates an assortment of types and functions.

The base C name for all types and functions related to the X request with name "Name" is XCB&lt;"Name"&gt;. If the request is from an extension, then "Name" is composed by prefixing the extension name onto the request name.

<a name="XCBNameCookie"></a>

### XCB&lt;Name&gt;Cookie

    typedef struct {
             unsigned int sequence;
    } XCB<Name>Cookie;

A special cookie type, XCBVoidCookie, is declared in xcb.h. See [XCB&lt;Name&gt;](#XCBName).

### XCB&lt;Name&gt;Req

    typedef struct {
             CARD8 major_opcode;
             /* first single-byte field, CARD8 minor_opcode, or one byte of padding */
             CARD16 length;
             ...
    } XCB<Name>Req;

### XCB&lt;Name&gt;Rep

    typedef struct {
             BYTE response_type;
             /* first single-byte field or one byte of padding */
             CARD16 sequence;
             CARD32 length;
             ...
             /* padding to 32 bytes */
    } XCB<Name>Rep;

`response_type` always equals 1 in a reply.

A special reply type, XCBGenericRep, is declared in xcb.h. It contains only the fields common to all replies.

<a name="XCBName"></a>

### XCB&lt;Name&gt;

`XCB<"Name">VoidCookie XCB<"Name">(XCBConnection *c, ...)`

Delivers a request with the specified arguments to the X server.

If the request will cause a reply to be generated, then an [XCB&lt;"Name"&gt;Cookie](#XCBNameCookie) will be returned and the [XCB&lt;Name&gt;Reply](#XCBNameReply) function should be used to obtain the actual reply.

Otherwise, an [XCBVoidCookie](#XCBNameCookie) will be returned, and no [XCB&lt;Name&gt;Reply](#XCBNameReply) function will be provided.

<a name="XCBNameReply"></a>

### XCB&lt;Name&gt;Reply

`XCB<"Name">Rep *XCB<"Name">Reply(XCBConnection *c, XCB<"Name">Cookie cookie, XCBGenericError **e)`

### XCB&lt;Name&gt;&lt;Field&gt;Iter

`XCB<"BaseType">Iter XCB<"Name"><"Field">Iter(XCB<"Name">Rep *R)`

### XCB&lt;Name&gt;&lt;Field&gt;

`<"BaseType"> *XCB<"Name"><"Field">(XCB<"Name">Rep *R)`

### XCB&lt;Name&gt;&lt;Field&gt;Length

`int XCB<"Name"><"Field">Length(XCB<"Name">Rep *R)`

### XCB&lt;Name&gt;&lt;Field&gt;End

`XCBGenericIter XCB<"Name"><"Field">End(XCB<"Name">Rep *R)`

## Events and Errors

### XCB&lt;EventName&gt;Event

    typedef struct {
             BYTE response_type;
             /* first single-byte field or one byte of padding */
             CARD16 sequence;
             ...
             /* padding to 32 bytes */
    } XCB<EventName>Event;

`response_type` equals the event number. See [XCB&lt;EventName&gt;](#XCBEventName).

A special event type, XCBGenericEvent, is declared in xcb.h. It contains only the fields common to all events.

<a name="XCBEventName"></a>

### XCB&lt;EventName&gt;

`#define XCB<EventName> <number>`

### XCB&lt;ErrorName&gt;Error

    typedef struct {
             BYTE response_type;
             BYTE error_code;
             CARD16 sequence;
             ...
             /* padding to 32 bytes */
    } XCB<ErrorName>Error;

`response_type` always equals 0 for errors.

`error_code` equals the error number. See [XCB&lt;ErrorName&gt;](#XCBErrorName).

A special event type, XCBGenericEvent, is declared in xcb.h. It contains only the fields common to all errors.

<a name="XCBErrorName"></a>

### XCB&lt;ErrorName&gt;

`#define XCB<ErrorName> <number>`

# Protocol Extension API

These functions are expected to be useful only to X protocol extension implementations built on XCB. They are declared in xcbext.h.

Care is required when calling these functions, as they generally do not have the type-safety properties of the public API functions.

## struct XCBExtension

    struct XCBExtension {
             const char *name;
             int global_id;
    };

- name\*: the X name of this extension, stored as a null-terminated string. global\_id\*: a small integer unique across all extensions in the current process.

## XCBProtocolRequest

    typedef struct {
             size_t count;
             XCBExtension *ext;
             CARD8 opcode;
             BOOL isvoid;
    } XCBProtocolRequest;

Values for a particular request that are always constant.

<dl>
  <dt>count</dt>
  <dd>number of elements in the iovec array.</dd>
  <dt>ext</dt>
  <dd>extension identifier, or null for the core protocol.</dd>
  <dt>opcode</dt>
  <dd>major opcode of the request for the core protocol, or minor opcode for an extension.</dd>
  <dt>isvoid</dt>
  <dd>zero if this request will return a reply; non-zero otherwise.</dd>
</dl>

## XCBSendRequest

(xcb\_out.c)

`int XCBSendRequest(XCBConnection *c, unsigned int *sequence, struct iovec *vector, const XCBProtocolRequest *request)`

## XCBWaitForReply

(xcb\_in.c)

`void *XCBWaitForReply(XCBConnection *c, unsigned int request, XCBGenericError **e)`

## XCBGenerateID

(xcb\_xid.c)

`CARD32 XCBGenerateID(XCBConnection *c)`

## XCBPopcount

(xcb\_util.c)

`int XCBPopcount(CARD32 mask)`

Returns the number of bits in the binary representation of `mask` that are equal to 1. This is also called a "population count".

# Xlib/XCB API

Xlib currently uses undocumented parts of XCB from xcbint.h. This interface may change without notice and must not be used: ask for a new API on the mailing list if there's some functionality that you would find useful. At some point in the future, we will design and publish an interface for Xlib, and we'd love to make it as generally useful as possible. Note that when the new API is available, xcbint.h will no longer be installed.

# Tips and Tricks

## Lists and Replies

All replies must be freed after they are used to prevent memory leaks. Please note that when a reply is allocated it includes any lists that are returned. Therefore if the list needs to be used after the reply has been freed it must be copied before any use of free() occurs.

    /* Get the reply */
    XCBGlxReadPixelsRep *reply = XCBGlxReadPixelsReply(c, XCBGlxReadPixels(c, ...), NULL);

    /* The data list must be copied to (GLvoid *) pixels, for later use. */
    (void)memcpy(pixels, XCBGlxReadPixelsData(reply), XCBGlxReadPixelsDataLength(reply) * sizeof(GLvoid));

    /* free the reply */
    free(reply);