XCB  1.12
Data Structures | Macros | Typedefs | Functions
XCB Core API

Core API of the XCB library. More...

Data Structures

struct  xcb_generic_iterator_t
 Generic iterator. More...
 
struct  xcb_generic_reply_t
 Generic reply. More...
 
struct  xcb_generic_event_t
 Generic event. More...
 
struct  xcb_ge_event_t
 GE event. More...
 
struct  xcb_generic_error_t
 Generic error. More...
 
struct  xcb_void_cookie_t
 Generic cookie. More...
 
struct  xcb_auth_info_t
 Container for authorization information. More...
 

Macros

#define X_PROTOCOL   11
 
#define X_PROTOCOL_REVISION   0
 
#define X_TCP_PORT   6000
 
#define XCB_CONN_ERROR   1
 
#define XCB_CONN_CLOSED_EXT_NOTSUPPORTED   2
 
#define XCB_CONN_CLOSED_MEM_INSUFFICIENT   3
 
#define XCB_CONN_CLOSED_REQ_LEN_EXCEED   4
 
#define XCB_CONN_CLOSED_PARSE_ERR   5
 
#define XCB_CONN_CLOSED_INVALID_SCREEN   6
 
#define XCB_CONN_CLOSED_FDPASSING_FAILED   7
 
#define XCB_TYPE_PAD(T, I)   (-(I) & (sizeof(T) > 4 ? 3 : sizeof(T) - 1))
 
#define XCB_NONE   0L
 
#define XCB_COPY_FROM_PARENT   0L
 
#define XCB_CURRENT_TIME   0L
 
#define XCB_NO_SYMBOL   0L
 

Typedefs

typedef struct xcb_connection_t xcb_connection_t
 XCB Connection structure. More...
 
typedef struct xcb_auth_info_t xcb_auth_info_t
 Container for authorization information. More...
 
typedef struct xcb_special_event xcb_special_event_t
 
typedef struct xcb_extension_t xcb_extension_t
 

Functions

int xcb_flush (xcb_connection_t *c)
 Forces any buffered output to be written to the server. More...
 
uint32_t xcb_get_maximum_request_length (xcb_connection_t *c)
 Returns the maximum request length that this server accepts. More...
 
void xcb_prefetch_maximum_request_length (xcb_connection_t *c)
 Prefetch the maximum request length without blocking. More...
 
xcb_generic_event_txcb_wait_for_event (xcb_connection_t *c)
 Returns the next event or error from the server. More...
 
xcb_generic_event_txcb_poll_for_event (xcb_connection_t *c)
 Returns the next event or error from the server. More...
 
xcb_generic_event_txcb_poll_for_queued_event (xcb_connection_t *c)
 Returns the next event without reading from the connection. More...
 
xcb_generic_event_txcb_poll_for_special_event (xcb_connection_t *c, xcb_special_event_t *se)
 Returns the next event from a special queue.
 
xcb_generic_event_txcb_wait_for_special_event (xcb_connection_t *c, xcb_special_event_t *se)
 Returns the next event from a special queue, blocking until one arrives.
 
xcb_special_event_txcb_register_for_special_xge (xcb_connection_t *c, xcb_extension_t *ext, uint32_t eid, uint32_t *stamp)
 Listen for a special event.
 
void xcb_unregister_for_special_event (xcb_connection_t *c, xcb_special_event_t *se)
 Stop listening for a special event.
 
xcb_generic_error_txcb_request_check (xcb_connection_t *c, xcb_void_cookie_t cookie)
 Return the error for a request, or NULL if none can ever arrive. More...
 
void xcb_discard_reply (xcb_connection_t *c, unsigned int sequence)
 Discards the reply for a request. More...
 
void xcb_discard_reply64 (xcb_connection_t *c, uint64_t sequence)
 Discards the reply for a request, given by a 64bit sequence number. More...
 
const struct xcb_query_extension_reply_txcb_get_extension_data (xcb_connection_t *c, xcb_extension_t *ext)
 Caches reply information from QueryExtension requests. More...
 
void xcb_prefetch_extension_data (xcb_connection_t *c, xcb_extension_t *ext)
 Prefetch of extension data into the extension cache. More...
 
const struct xcb_setup_txcb_get_setup (xcb_connection_t *c)
 Access the data returned by the server. More...
 
int xcb_get_file_descriptor (xcb_connection_t *c)
 Access the file descriptor of the connection. More...
 
int xcb_connection_has_error (xcb_connection_t *c)
 Test whether the connection has shut down due to a fatal error. More...
 
xcb_connection_txcb_connect_to_fd (int fd, xcb_auth_info_t *auth_info)
 Connects to the X server. More...
 
void xcb_disconnect (xcb_connection_t *c)
 Closes the connection. More...
 
int xcb_parse_display (const char *name, char **host, int *display, int *screen)
 Parses a display string name in the form documented by X(7x). More...
 
xcb_connection_txcb_connect (const char *displayname, int *screenp)
 Connects to the X server. More...
 
xcb_connection_txcb_connect_to_display_with_auth_info (const char *display, xcb_auth_info_t *auth, int *screen)
 Connects to the X server, using an authorization information. More...
 
uint32_t xcb_generate_id (xcb_connection_t *c)
 Allocates an XID for a new object. More...
 

Detailed Description

Core API of the XCB library.

Macro Definition Documentation

#define X_PROTOCOL   11

Current protocol version

#define X_PROTOCOL_REVISION   0

Current minor version

#define X_TCP_PORT   6000

X_TCP_PORT + display number = server port for TCP transport

Referenced by xcb_parse_display().

#define XCB_CONN_CLOSED_EXT_NOTSUPPORTED   2

xcb connection shutdown because of extension not supported

Referenced by xcb_get_maximum_request_length().

#define XCB_CONN_CLOSED_FDPASSING_FAILED   7

Connection closed because some FD passing operation failed

Referenced by xcb_unregister_for_special_event().

#define XCB_CONN_CLOSED_INVALID_SCREEN   6

Connection closed because the server does not have a screen matching the display.

Referenced by xcb_connect_to_display_with_auth_info(), and xcb_disconnect().

#define XCB_CONN_CLOSED_MEM_INSUFFICIENT   3

malloc(), calloc() and realloc() error upon failure, for eg ENOMEM

Referenced by xcb_connect_to_fd(), xcb_disconnect(), and xcb_unregister_for_special_event().

#define XCB_CONN_CLOSED_PARSE_ERR   5

Connection closed, error during parsing display string.

Referenced by xcb_connect_to_display_with_auth_info(), and xcb_disconnect().

#define XCB_CONN_CLOSED_REQ_LEN_EXCEED   4

Connection closed, exceeding request length that server accepts.

Referenced by xcb_get_maximum_request_length().

#define XCB_CONN_ERROR   1

xcb connection errors because of socket, pipe and other stream errors.

Referenced by xcb_connect_to_display_with_auth_info(), xcb_connect_to_fd(), xcb_disconnect(), and xcb_unregister_for_special_event().

#define XCB_COPY_FROM_PARENT   0L

XCB_COPY_FROM_PARENT can be used for many xcb_create_window parameters

#define XCB_CURRENT_TIME   0L

XCB_CURRENT_TIME can be used in most requests that take an xcb_timestamp_t

#define XCB_NO_SYMBOL   0L

XCB_NO_SYMBOL fills in unused entries in xcb_keysym_t tables

#define XCB_NONE   0L

XCB_NONE is the universal null resource or null atom parameter value for many core X requests

Typedef Documentation

Container for authorization information.

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

XCB Connection structure.

A structure that contain all data that XCB needs to communicate with an X server.Opaque structure containing all data that XCB needs to communicate with an X server.

Opaque structure used as key for xcb_get_extension_data_t.

Function Documentation

xcb_connection_t* xcb_connect ( const char *  displayname,
int *  screenp 
)

Connects to the X server.

Parameters
displaynameThe name of the display.
screenpA pointer to a preferred screen number.
Returns
A newly allocated xcb_connection_t structure.

Connects to the X server specified by displayname. If displayname is NULL, uses the value of the DISPLAY environment variable. If a particular screen on that server is preferred, the int pointed to by screenp (if not NULL) will be set to that screen; otherwise the screen will be set to 0.

Always returns a non-NULL pointer to a xcb_connection_t, even on failure. Callers need to use xcb_connection_has_error() to check for failure. When finished, use xcb_disconnect() to close the connection and free the structure.

References xcb_connect_to_display_with_auth_info().

xcb_connection_t* xcb_connect_to_display_with_auth_info ( const char *  display,
xcb_auth_info_t auth,
int *  screen 
)

Connects to the X server, using an authorization information.

Parameters
displayThe name of the display.
authThe authorization information.
screenA pointer to a preferred screen number.
Returns
A newly allocated xcb_connection_t structure.

Connects to the X server specified by displayname, using the authorization auth. If a particular screen on that server is preferred, the int pointed to by screenp (if not NULL) will be set to that screen; otherwise screenp will be set to 0.

Always returns a non-NULL pointer to a xcb_connection_t, even on failure. Callers need to use xcb_connection_has_error() to check for failure. When finished, use xcb_disconnect() to close the connection and free the structure.

References xcb_auth_info_t::data, xcb_auth_info_t::name, XCB_CONN_CLOSED_INVALID_SCREEN, XCB_CONN_CLOSED_PARSE_ERR, XCB_CONN_ERROR, xcb_connect_to_fd(), and xcb_disconnect().

Referenced by xcb_connect().

xcb_connection_t* xcb_connect_to_fd ( int  fd,
xcb_auth_info_t auth_info 
)

Connects to the X server.

Parameters
fdThe file descriptor.
auth_infoAuthentication data.
Returns
A newly allocated xcb_connection_t structure.

Connects to an X server, given the open socket fd and the xcb_auth_info_t auth_info. The file descriptor fd is bidirectionally connected to an X server. If the connection should be unauthenticated, auth_info must be NULL.

Always returns a non-NULL pointer to a xcb_connection_t, even on failure. Callers need to use xcb_connection_has_error() to check for failure. When finished, use xcb_disconnect() to close the connection and free the structure.

References XCB_CONN_CLOSED_MEM_INSUFFICIENT, XCB_CONN_ERROR, and xcb_disconnect().

Referenced by xcb_connect_to_display_with_auth_info().

int xcb_connection_has_error ( xcb_connection_t c)

Test whether the connection has shut down due to a fatal error.

Parameters
cThe connection.
Returns
> 0 if the connection is in an error state; 0 otherwise.

Some errors that occur in the context of an xcb_connection_t are unrecoverable. When such an error occurs, the connection is shut down and further operations on the xcb_connection_t have no effect, but memory will not be freed until xcb_disconnect() is called on the xcb_connection_t.

Returns
XCB_CONN_ERROR, because of socket errors, pipe errors or other stream errors.
XCB_CONN_CLOSED_EXT_NOTSUPPORTED, when extension not supported.
XCB_CONN_CLOSED_MEM_INSUFFICIENT, when memory not available.
XCB_CONN_CLOSED_REQ_LEN_EXCEED, exceeding request length that server accepts.
XCB_CONN_CLOSED_PARSE_ERR, error during parsing display string.
XCB_CONN_CLOSED_INVALID_SCREEN, because the server does not have a screen matching the display.
void xcb_discard_reply ( xcb_connection_t c,
unsigned int  sequence 
)

Discards the reply for a request.

Parameters
cThe connection to the X server.
sequenceThe request sequence number from a cookie.

Discards the reply for a request. Additionally, any error generated by the request is also discarded (unless it was an _unchecked request and the error has already arrived).

This function will not block even if the reply is not yet available.

Note that the sequence really does have to come from an xcb cookie; this function is not designed to operate on socket-handoff replies.

void xcb_discard_reply64 ( xcb_connection_t c,
uint64_t  sequence 
)

Discards the reply for a request, given by a 64bit sequence number.

Parameters
cThe connection to the X server.
sequence64-bit sequence number as returned by xcb_send_request64().

Discards the reply for a request. Additionally, any error generated by the request is also discarded (unless it was an _unchecked request and the error has already arrived).

This function will not block even if the reply is not yet available.

Note that the sequence really does have to come from xcb_send_request64(); the cookie sequence number is defined as "unsigned" int and therefore not 64-bit on all platforms. This function is not designed to operate on socket-handoff replies.

Unlike its xcb_discard_reply() counterpart, the given sequence number is not automatically "widened" to 64-bit.

void xcb_disconnect ( xcb_connection_t c)

Closes the connection.

Parameters
cThe connection.

Closes the file descriptor and frees all memory associated with the connection c. If c is NULL, nothing is done.

References XCB_CONN_CLOSED_INVALID_SCREEN, XCB_CONN_CLOSED_MEM_INSUFFICIENT, XCB_CONN_CLOSED_PARSE_ERR, and XCB_CONN_ERROR.

Referenced by xcb_connect_to_display_with_auth_info(), and xcb_connect_to_fd().

int xcb_flush ( xcb_connection_t c)

Forces any buffered output to be written to the server.

Parameters
cThe connection to the X server.
Returns
> 0 on success, <= 0 otherwise.

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

uint32_t xcb_generate_id ( xcb_connection_t c)

Allocates an XID for a new object.

Parameters
cThe connection.
Returns
A newly allocated XID.

Allocates an XID for a new object. Typically used just prior to various object creation functions, such as xcb_create_window.

References xcb_get_extension_data(), xcb_xc_misc_get_xid_range(), and xcb_xc_misc_get_xid_range_reply().

const struct xcb_query_extension_reply_t* xcb_get_extension_data ( xcb_connection_t c,
xcb_extension_t ext 
)

Caches reply information from QueryExtension requests.

Parameters
cThe connection.
extThe extension data.
Returns
A pointer to the xcb_query_extension_reply_t for the extension.

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 xcb_query_extension to retrieve extension information from the server, and may block until extension data is received from the server.

The result must not be freed. This storage is managed by the cache itself.

References xcb_query_extension_reply().

Referenced by xcb_generate_id(), xcb_get_maximum_request_length(), xcb_prefetch_maximum_request_length(), and xcb_register_for_special_xge().

int xcb_get_file_descriptor ( xcb_connection_t c)

Access the file descriptor of the connection.

Parameters
cThe connection.
Returns
The file descriptor.

Accessor for the file descriptor that was passed to the xcb_connect_to_fd call that returned c or for the file descriptor that was opened internally.

uint32_t xcb_get_maximum_request_length ( xcb_connection_t c)

Returns the maximum request length that this server accepts.

Parameters
cThe connection to the X server.
Returns
The maximum request length field.

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.

References xcb_big_requests_enable_reply(), XCB_CONN_CLOSED_EXT_NOTSUPPORTED, XCB_CONN_CLOSED_REQ_LEN_EXCEED, xcb_get_extension_data(), and xcb_prefetch_maximum_request_length().

const struct xcb_setup_t* xcb_get_setup ( xcb_connection_t c)

Access the data returned by the server.

Parameters
cThe connection.
Returns
A pointer to an xcb_setup_t structure.

Accessor for the data returned by the server when the xcb_connection_t 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.

The result must not be freed.

int xcb_parse_display ( const char *  name,
char **  host,
int *  display,
int *  screen 
)

Parses a display string name in the form documented by X(7x).

Parameters
nameThe name of the display.
hostA pointer to a malloc'd copy of the hostname.
displayA pointer to the display number.
screenA pointer to the screen number.
Returns
0 on failure, non 0 otherwise.

Parses the display string name display_name in the form documented by X(7x). Has no side effects on failure. If displayname is NULL or empty, it uses the environment variable DISPLAY. hostp is a pointer to a newly allocated string that contain the host name. displayp is set to the display number and screenp to the preferred screen number. screenp can be NULL. If displayname does not contain a screen number, it is set to 0.

References X_TCP_PORT.

xcb_generic_event_t* xcb_poll_for_event ( xcb_connection_t c)

Returns the next event or error from the server.

Parameters
cThe connection to the X server.
Returns
The next event from the server.

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, in which case the connection is shut down when this function returns.

xcb_generic_event_t* xcb_poll_for_queued_event ( xcb_connection_t c)

Returns the next event without reading from the connection.

Parameters
cThe connection to the X server.
Returns
The next already queued event from the server.

This is a version of xcb_poll_for_event that only examines the event queue for new events. The function doesn't try to read new events from the connection if no queued events are found.

This function is useful for callers that know in advance that all interesting events have already been read from the connection. For example, callers might use xcb_wait_for_reply and be interested only of events that preceded a specific reply.

void xcb_prefetch_extension_data ( xcb_connection_t c,
xcb_extension_t ext 
)

Prefetch of extension data into the extension cache.

Parameters
cThe connection.
extThe extension data.

This function allows a "prefetch" of extension data into the extension cache. Invoking the function may cause a call to xcb_query_extension, but will not block waiting for the reply. xcb_get_extension_data will return the prefetched data after possibly blocking while it is retrieved.

void xcb_prefetch_maximum_request_length ( xcb_connection_t c)

Prefetch the maximum request length without blocking.

Parameters
cThe connection to the X server.

Without blocking, does as much work as possible toward computing the maximum request length accepted by the X server.

Invoking this function may cause a call to xcb_big_requests_enable, but will not block waiting for the reply. xcb_get_maximum_request_length will return the prefetched data after possibly blocking while the reply is retrieved.

Note that in order for this function to be fully non-blocking, the application must previously have called xcb_prefetch_extension_data(c, &xcb_big_requests_id) and the reply must have already arrived.

References xcb_big_requests_enable(), and xcb_get_extension_data().

Referenced by xcb_get_maximum_request_length().

xcb_generic_error_t* xcb_request_check ( xcb_connection_t c,
xcb_void_cookie_t  cookie 
)

Return the error for a request, or NULL if none can ever arrive.

Parameters
cThe connection to the X server.
cookieThe request cookie.
Returns
The error for the request, or NULL if none can ever arrive.

The xcb_void_cookie_t cookie supplied to this function must have resulted from a call to xcb_[request_name]_checked(). This function will block until one of two conditions happens. If an error is received, it will be returned. If a reply to a subsequent request has already arrived, no error can arrive for this request, so this function will return NULL.

Note that this function will perform a sync if needed to ensure that the sequence number will advance beyond that provided in cookie; this is a convenience to avoid races in determining whether the sync is needed.

References xcb_void_cookie_t::sequence.

xcb_generic_event_t* xcb_wait_for_event ( xcb_connection_t c)

Returns the next event or error from the server.

Parameters
cThe connection to the X server.
Returns
The next event from the server.

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.