Page:Xlib - C Language X Interface.pdf/8

 Input events (for example, a key pressed or the pointer moved) arrive asynchronously from the server and are queued until they are requested by an explicit call (for example, XNextEvent or XWindowEvent). In addition, some library functions (for example, XRaiseWindow) generate Expose and ConfigureRequest events. These events also arrive asynchronously, but the client may wish to explicitly wait for them by calling XSync after calling a function that can cause the server to generate events.

1.2. Errors

Some functions return Status, an integer error indication. If the function fails, it returns a zero. If the function returns a status of zero, it has not updated the return arguments. Because C does not provide multiple return values, many functions must return their results by writing into clientpassed storage. By default, errors are handled either by a standard library function or by one that you provide. Functions that return pointers to strings return NULL pointers if the string does not exist.

The X server reports protocol errors at the time that it detects them. If more than one error could be generated for a given request, the server can report any of them.

Because Xlib usually does not transmit requests to the server immediately (that is, it buffers them), errors can be reported much later than they actually occur. For debugging purposes, however, Xlib provides a mechanism for forcing synchronous behavior (see section 11.8.1). When synchronization is enabled, errors are reported as they are generated.

When Xlib detects an error, it calls an error handler, which your program can provide. If you do not provide an error handler, the error is printed, and your program terminates.

1.3. Standard Header Files

The following include files are part of the Xlib standard:


 * 
 * This is the main header file for Xlib. The majority of all Xlib symbols are declared by including this file. This file also contains the preprocessor symbol XlibSpecificationRelease. This symbol is defined to have the 6 in this release of the standard. (Release 5 of Xlib was the first release to have this symbol.)


 * 
 * This file declares types and constants for the X protocol that are to be used by applications. It is included automatically from , so application code should never need to reference this file directly.


 * 
 * This file contains symbols for much of the color management facilities described in chapter 6. All functions, types, and symbols with the prefix "Xcms", plus the Color Conversion Contexts macros, are declared in this file.  must be included before including this file.


 * 
 * This file declares various functions, types, and symbols used for inter-client communication and application utility functions, which are described in chapters 14 and 16.  must be included before including this file.


 * 
 * This file declares all functions, types, and symbols for the resource manager facilities, which are described in chapter 15.  must be included before including this