1 files changed, 2542 insertions, 2542 deletions

diff --git a/libX11/specs/libX11/CH11.xml b/libX11/specs/libX11/CH11.xml
index c8031649a..df8a9630a 100644
--- a/libX11/specs/libX11/CH11.xml
+++ b/libX11/specs/libX11/CH11.xml
@@ -1,2542 +1,2542 @@
-<?xml version="1.0" encoding="UTF-8" ?>

-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"

-	  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">

-<chapter id="event_handling_functions">

-<title>Event Handling Functions</title>

-

-<para>

-This chapter discusses the Xlib functions you can use to:

-</para>

-<itemizedlist>

-  <listitem><para>Select events</para></listitem>

-  <listitem><para>Handle the output buffer and the event queue</para></listitem>

-  <listitem><para>Select events from the event queue</para></listitem>

-  <listitem><para>Send and get events</para></listitem>

-  <listitem><para>Handle protocol errors</para></listitem>

-</itemizedlist>

-<note><para>

-Some toolkits use their own event-handling functions and do not allow you to

-interchange these event-handling functions with those in Xlib. For further

-information, see the documentation supplied with the toolkit.

-</para></note>

-

-<para>

-Most applications simply are event loops: they wait for an event, decide what to do with it,

-execute some amount of code that results in changes to the display, and then wait for the next

-event.

-</para>

-

-<sect1 id="Selecting_Events">

-<title>Selecting Events</title>

-<!-- .XS -->

-<!-- (SN Selecting Events  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-There are two ways to select the events you want reported to your client

-application.

-One way is to set the event_mask member of the

-<structname>XSetWindowAttributes</structname>

-structure when you call

-<function>XCreateWindow</function>

-and

-<function>XChangeWindowAttributes</function>.

-Another way is to use

-<function>XSelectInput</function>.

-<indexterm significance="preferred"><primary>XSelectInput</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSelectInput</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>long<parameter> event_mask</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN	 -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi whose events you are interested in -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event mask.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XSelectInput</function>

-function requests that the X server report the events associated with the 

-specified event mask.

-Initially, X will not report any of these events.

-Events are reported relative to a window.

-If a window is not interested in a device event, it usually propagates to

-the closest ancestor that is interested,

-unless the do_not_propagate mask prohibits it.

-<indexterm><primary>Event</primary><secondary>propagation</secondary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-Setting the event-mask attribute of a window overrides any previous call

-for the same window but not for other clients.

-Multiple clients can select for the same events on the same window

-with the following restrictions:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Multiple clients can select events on the same window because their event masks

-are disjoint.

-When the X server generates an event, it reports it

-to all interested clients.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Only one client at a time can select

-<symbol>CirculateRequest</symbol>,

-<symbol>ConfigureRequest</symbol>,

-or

-<symbol>MapRequest</symbol>

-events, which are associated with

-the event mask

-<symbol>SubstructureRedirectMask</symbol>.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Only one client at a time can select

-a

-<symbol>ResizeRequest</symbol>

-event, which is associated with

-the event mask

-<symbol>ResizeRedirectMask</symbol>.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Only one client at a time can select a 

-<symbol>ButtonPress</symbol>

-event, which is associated with

-the event mask

-<symbol>ButtonPressMask</symbol>.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The server reports the event to all interested clients.

-</para>

-<para>

-<!-- .LP -->

-<function>XSelectInput</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect1>

-<sect1 id="Handling_the_Output_Buffer">

-<title>Handling the Output Buffer</title>

-<!-- .XS -->

-<!-- (SN Handling the Output Buffer -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The output buffer is an area used by Xlib to store requests.

-The functions described in this section flush the output buffer

-if the function would block or not return an event.

-That is, all requests residing in the output buffer that

-have not yet been sent are transmitted to the X server.

-These functions differ in the additional tasks they might perform.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To flush the output buffer, use 

-<function>XFlush</function>.

-<indexterm significance="preferred"><primary>XFlush</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XFlush</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XFlush</function>

-function

-flushes the output buffer.

-Most client applications need not use this function because the output

-buffer is automatically flushed as needed by calls to

-<function>XPending</function>,

-<function>XNextEvent</function>,

-and

-<function>XWindowEvent</function>.

-<indexterm><primary>XPending</primary></indexterm>

-<indexterm><primary>XNextEvent</primary></indexterm>

-<indexterm><primary>XWindowEvent</primary></indexterm>

-Events generated by the server may be enqueued into the library's event queue.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To flush the output buffer and then wait until all requests have been processed,

-use 

-<function>XSync</function>.

-<indexterm significance="preferred"><primary>XSync</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSync</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Bool<parameter> discard</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>discard</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a Boolean value that indicates whether 

-<function>XSync</function>

-discards all events on the event queue.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSync</function>

-function

-flushes the output buffer and then waits until all requests have been received

-and processed by the X server.

-Any errors generated must be handled by the error handler.

-For each protocol error received by Xlib,

-<function>XSync</function>

-calls the client application's error handling routine (see section 11.8.2).

-Any events generated by the server are enqueued into the library's 

-event queue.

-</para>

-<para>

-<!-- .LP -->

-Finally, if you passed 

-<symbol>False</symbol>,

-<function>XSync</function>

-does not discard the events in the queue.

-If you passed 

-<symbol>True</symbol>,

-<function>XSync</function>

-discards all events in the queue,

-including those events that were on the queue before

-<function>XSync</function>

-was called.

-Client applications seldom need to call

-<function>XSync</function>.

-</para>

-</sect1>

-<sect1 id="Event_Queue_Management">

-<title>Event Queue Management</title>

-<!-- .XS -->

-<!-- (SN Event Queue Management -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib maintains an event queue.

-However, the operating system also may be buffering data 

-in its network connection that is not yet read into the event queue.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To check the number of events in the event queue, use

-<function>XEventsQueued</function>.

-<indexterm significance="preferred"><primary>XEventsQueued</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XEventsQueued</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> mode</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the mode.

-You can pass

-<symbol>QueuedAlready</symbol>,

-<symbol>QueuedAfterFlush</symbol>,

-or

-<symbol>QueuedAfterReading</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If mode is 

-<symbol>QueuedAlready</symbol>,

-<function>XEventsQueued</function>

-returns the number of events

-already in the event queue (and never performs a system call).

-If mode is 

-<symbol>QueuedAfterFlush</symbol>,

-<function>XEventsQueued</function>

-returns the number of events already in the queue if the number is nonzero.

-If there are no events in the queue, 

-<function>XEventsQueued</function>

-flushes the output buffer, 

-attempts to read more events out of the application's connection,

-and returns the number read.

-If mode is 

-<symbol>QueuedAfterReading</symbol>,

-<function>XEventsQueued</function>

-returns the number of events already in the queue if the number is nonzero. 

-If there are no events in the queue, 

-<function>XEventsQueued</function>

-attempts to read more events out of the application's connection 

-without flushing the output buffer and returns the number read.

-</para>

-<para>

-<!-- .LP -->

-<function>XEventsQueued</function>

-always returns immediately without I/O if there are events already in the

-queue.

-<function>XEventsQueued</function>

-with mode 

-<symbol>QueuedAfterFlush</symbol>

-is identical in behavior to

-<function>XPending</function>.

-<function>XEventsQueued</function>

-with mode

-<symbol>QueuedAlready</symbol>

-is identical to the

-<function>XQLength</function>

-function.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To return the number of events that are pending, use 

-<function>XPending</function>.

-<indexterm significance="preferred"><primary>XPending</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XPending</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN	 -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XPending</function>

-function returns the number of events that have been received from the

-X server but have not been removed from the event queue.

-<function>XPending</function>

-is identical to

-<function>XEventsQueued</function>

-with the mode

-<symbol>QueuedAfterFlush</symbol>

-specified.

-</para>

-</sect1>

-<sect1 id="Manipulating_the_Event_Queue">

-<title>Manipulating the Event Queue</title>

-<!-- .XS -->

-<!-- (SN Manipulating the Event Queue  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that let you manipulate the event queue.

-This section discusses how to:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Obtain events, in order, and remove them from the queue

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Peek at events in the queue without removing them

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Obtain events that match the event mask or the arbitrary

-predicate procedures that you provide

-    </para>

-  </listitem>

-</itemizedlist>

-<sect2 id="Returning_the_Next_Event">

-<title>Returning the Next Event</title>

-<!-- .XS -->

-<!-- (SN Returning the Next Event -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To get the next event and remove it from the queue, use

-<function>XNextEvent</function>.

-<indexterm significance="preferred"><primary>XNextEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XNextEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the next event in the queue.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XNextEvent</function>

-function copies the first event from the event queue into the specified

-<structname>XEvent</structname>

-structure and then removes it from the queue.

-If the event queue is empty,

-<function>XNextEvent</function>

-flushes the output buffer and blocks until an event is received.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To peek at the event queue, use

-<function>XPeekEvent</function>.

-<indexterm significance="preferred"><primary>XPeekEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XPeekEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns a copy of the matched event's associated structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XPeekEvent</function>

-function returns the first event from the event queue,

-but it does not remove the event from the queue.

-If the queue is empty,

-<function>XPeekEvent</function>

-flushes the output buffer and blocks until an event is received.

-It then copies the event into the client-supplied

-<structname>XEvent</structname>

-structure without removing it from the event queue.

-</para>

-</sect2>

-<sect2 id="Selecting_Events_Using_a_Predicate_Procedure">

-<title>Selecting Events Using a Predicate Procedure</title>

-<!-- .XS -->

-<!-- (SN Selecting Events Using a Predicate Procedure -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Each of the functions discussed in this section requires you to

-pass a predicate procedure that determines if an event matches 

-what you want.

-Your predicate procedure must decide if the event is useful

-without calling any Xlib functions.

-If the predicate directly or indirectly causes the state of the event queue

-to change, the result is not defined.

-If Xlib has been initialized for threads, the predicate is called with

-the display locked and the result of a call by the predicate to any

-Xlib function that locks the display is not defined unless the caller

-has first called

-<function>XLockDisplay</function>.

-</para>

-<para>

-<!-- .LP -->

-The predicate procedure and its associated arguments are:

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><type>Bool</type></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event</parameter></paramdef>

-  <paramdef>XPointer<parameter> arg</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the

-<structname>XEvent</structname>

-structure.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>arg</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the argument passed in from the 

-<function>XIfEvent</function>,

-<function>XCheckIfEvent</function>,

-or

-<function>XPeekIfEvent</function>

-function.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The predicate procedure is called once for each

-event in the queue until it finds a match. 

-After finding a match, the predicate procedure must return 

-<symbol>True</symbol>.

-If it did not find a match, it must return

-<symbol>False</symbol>.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To check the event queue for a matching event

-and, if found, remove the event from the queue, use

-<function>XIfEvent</function>.

-<indexterm significance="preferred"><primary>XIfEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XIfEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-  <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>

-  <paramdef>XPointer<parameter> arg</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the matched event's associated structure.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>predicate</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure that is to be called to determine

-if the next event in the queue matches what you want.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>arg</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the user-supplied argument that will be passed to the predicate procedure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XIfEvent</function>

-function completes only when the specified predicate

-procedure returns 

-<symbol>True</symbol>

-for an event, 

-which indicates an event in the queue matches.

-<function>XIfEvent</function>

-flushes the output buffer if it blocks waiting for additional events.

-<function>XIfEvent</function>

-removes the matching event from the queue 

-and copies the structure into the client-supplied

-<structname>XEvent</structname>

-structure.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To check the event queue for a matching event without blocking, use

-<function>XCheckIfEvent</function>.

-<indexterm significance="preferred"><primary>XCheckIfEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XCheckIfEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-  <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>

-  <paramdef>XPointer<parameter> arg</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns a copy of the matched event's associated structure.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>predicate</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure that is to be called to determine

-if the next event in the queue matches what you want.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>arg</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the user-supplied argument that will be passed to the predicate procedure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-When the predicate procedure finds a match,

-<function>XCheckIfEvent</function>

-copies the matched event into the client-supplied

-<structname>XEvent</structname>

-structure and returns 

-<symbol>True</symbol>.

-(This event is removed from the queue.)

-If the predicate procedure finds no match,

-<function>XCheckIfEvent</function>

-returns

-<symbol>False</symbol>,

-and the output buffer will have been flushed.

-All earlier events stored in the queue are not discarded.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To check the event queue for a matching event

-without removing the event from the queue, use

-<function>XPeekIfEvent</function>.

-<indexterm significance="preferred"><primary>XPeekIfEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XPeekIfEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-  <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>

-  <paramdef>XPointer<parameter> arg</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns a copy of the matched event's associated structure.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>predicate</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure that is to be called to determine

-if the next event in the queue matches what you want.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>arg</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the user-supplied argument that will be passed to the predicate procedure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XPeekIfEvent</function>

-function returns only when the specified predicate

-procedure returns 

-<symbol>True</symbol>

-for an event.

-After the predicate procedure finds a match,

-<function>XPeekIfEvent</function>

-copies the matched event into the client-supplied

-<structname>XEvent</structname>

-structure without removing the event from the queue.

-<function>XPeekIfEvent</function>

-flushes the output buffer if it blocks waiting for additional events.

-</para>

-</sect2>

-<sect2 id="Selecting_Events_Using_a_Window_or_Event_Mask">

-<title>Selecting Events Using a Window or Event Mask</title>

-<!-- .XS -->

-<!-- (SN Selecting Events Using a Window or Event Mask -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-The functions discussed in this section let you select events by window 

-or event types, allowing you to process events out of order.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To remove the next event that matches both a window and an event mask, use

-<function>XWindowEvent</function>.

-<indexterm significance="preferred"><primary>XWindowEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XWindowEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>long<parameter> event_mask</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi whose events you are interested in -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event mask.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the matched event's associated structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XWindowEvent</function>

-function searches the event queue for an event that matches both the specified

-window and event mask.

-When it finds a match,

-<function>XWindowEvent</function>

-removes that event from the queue and copies it into the specified

-<structname>XEvent</structname>

-structure.

-The other events stored in the queue are not discarded.

-If a matching event is not in the queue,

-<function>XWindowEvent</function>

-flushes the output buffer and blocks until one is received.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To remove the next event that matches both a window and an event mask (if any),

-use

-<function>XCheckWindowEvent</function>.

-<indexterm><primary>XCheckWindowEvent</primary></indexterm>

-This function is similar to

-<function>XWindowEvent</function>

-except that it never blocks and it returns a 

-<type>Bool</type>

-indicating if the event was returned.

-<indexterm significance="preferred"><primary>XCheckWindowEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XCheckWindowEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>long<parameter> event_mask</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi whose events you are interested in -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event mask.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the matched event's associated structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCheckWindowEvent</function>

-function searches the event queue and then the events available 

-on the server connection for the first event that matches the specified window

-and event mask.

-If it finds a match,

-<function>XCheckWindowEvent</function>

-removes that event, copies it into the specified

-<structname>XEvent</structname>

-structure, and returns

-<symbol>True</symbol>.

-The other events stored in the queue are not discarded.

-If the event you requested is not available,

-<function>XCheckWindowEvent</function>

-returns

-<symbol>False</symbol>,

-and the output buffer will have been flushed.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To remove the next event that matches an event mask, use

-<function>XMaskEvent</function>.

-<indexterm significance="preferred"><primary>XMaskEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XMaskEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>long<parameter> event_mask</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event mask.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the matched event's associated structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XMaskEvent</function>

-function searches the event queue for the events associated with the 

-specified mask.

-When it finds a match,

-<function>XMaskEvent</function>

-removes that event and copies it into the specified

-<structname>XEvent</structname>

-structure.

-The other events stored in the queue are not discarded.

-If the event you requested is not in the queue,

-<function>XMaskEvent</function>

-flushes the output buffer and blocks until one is received.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To return and remove the next event that matches an event mask (if any), use

-<function>XCheckMaskEvent</function>.

-This function is similar to 

-<function>XMaskEvent</function>

-except that it never blocks and it returns a 

-<type>Bool</type>

-indicating if the event was returned.

-<indexterm significance="preferred"><primary>XCheckMaskEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XCheckMaskEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>long<parameter> event_mask</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event mask.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the matched event's associated structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCheckMaskEvent</function>

-function searches the event queue and then any events available on the

-server connection for the first event that matches the specified mask.

-If it finds a match,

-<function>XCheckMaskEvent</function>

-removes that event, copies it into the specified

-<structname>XEvent</structname>

-structure, and returns

-<symbol>True</symbol>.

-The other events stored in the queue are not discarded.

-If the event you requested is not available,

-<function>XCheckMaskEvent</function>

-returns

-<symbol>False</symbol>,

-and the output buffer will have been flushed.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp  -->

-To return and remove the next event in the queue that matches an event type, use

-<function>XCheckTypedEvent</function>.

-<indexterm significance="preferred"><primary>XCheckTypedEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XCheckTypedEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> event_type</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_type</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event type to be compared.

-

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the matched event's associated structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCheckTypedEvent</function>

-function searches the event queue and then any events available  

-on the server connection for the first event that matches the specified type.

-If it finds a match,

-<function>XCheckTypedEvent</function>

-removes that event, copies it into the specified

-<structname>XEvent</structname>

-structure, and returns

-<symbol>True</symbol>.

-The other events in the queue are not discarded.

-If the event is not available,

-<function>XCheckTypedEvent</function>

-returns

-<symbol>False</symbol>,

-and the output buffer will have been flushed.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To return and remove the next event in the queue that matches an event type 

-and a window, use

-<function>XCheckTypedWindowEvent</function>.

-<indexterm significance="preferred"><primary>XCheckTypedWindowEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XCheckTypedWindowEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>int<parameter> event_type</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_type</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event type to be compared.

-

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the matched event's associated structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XCheckTypedWindowEvent</function>

-function searches the event queue and then any events available  

-on the server connection for the first event that matches the specified

-type and window.

-If it finds a match,

-<function>XCheckTypedWindowEvent</function>

-removes the event from the queue, copies it into the specified

-<structname>XEvent</structname>

-structure, and returns

-<symbol>True</symbol>.

-The other events in the queue are not discarded.

-If the event is not available,

-<function>XCheckTypedWindowEvent</function>

-returns

-<symbol>False</symbol>,

-and the output buffer will have been flushed.

-</para>

-</sect2>

-</sect1>

-<sect1 id="Putting_an_Event_Back_into_the_Queue">

-<title>Putting an Event Back into the Queue</title>

-<!-- .XS -->

-<!-- (SN Putting an Event Back into the Queue  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To push an event back into the event queue, use

-<function>XPutBackEvent</function>.

-<indexterm significance="preferred"><primary>XPutBackEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XPutBackEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XPutBackEvent</function>

-function pushes an event back onto the head of the display's event queue

-by copying the event into the queue.

-This can be useful if you read an event and then decide that you

-would rather deal with it later.

-There is no limit to the number of times in succession that you can call

-<function>XPutBackEvent</function>.

-</para>

-</sect1>

-<sect1 id="Sending_Events_to_Other_Applications">

-<title>Sending Events to Other Applications</title>

-<!-- .XS -->

-<!-- (SN Sending Events to Other Applications -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-To send an event to a specified window, use

-<function>XSendEvent</function>.

-<indexterm><primary>XSendEvent</primary></indexterm>

-This function is often used in selection processing.

-For example, the owner of a selection should use

-<function>XSendEvent</function>

-to send a

-<symbol>SelectionNotify</symbol>

-event to a requestor when a selection has been converted 

-and stored as a property.

-<indexterm significance="preferred"><primary>XSendEvent</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XSendEvent</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Bool<parameter> propagate</parameter></paramdef>

-  <paramdef>long<parameter> event_mask</parameter></paramdef>

-  <paramdef>XEvent<parameter> *event_send</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window the event is to be sent to, or

-<symbol>PointerWindow</symbol>,

-or

-<symbol>InputFocus</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>propagate</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a Boolean value.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_mask</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event mask.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>event_send</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the event that is to be sent.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSendEvent</function>

-function identifies the destination window, 

-determines which clients should receive the specified events, 

-and ignores any active grabs.

-This function requires you to pass an event mask.

-For a discussion of the valid event mask names,

-see section 10.3.

-This function uses the w argument to identify the destination window as follows:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-If w is

-<symbol>PointerWindow</symbol>,

-the destination window is the window that contains the pointer.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If w is

-<symbol>InputFocus</symbol>

-and if the focus window contains the pointer, 

-the destination window is the window that contains the pointer; 

-otherwise, the destination window is the focus window.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-To determine which clients should receive the specified events,

-<function>XSendEvent</function>

-uses the propagate argument as follows:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-If event_mask is the empty set,

-the event is sent to the client that created the destination window.

-If that client no longer exists,

-no event is sent.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If propagate is 

-<symbol>False</symbol>,

-the event is sent to every client selecting on destination any of the event

-types in the event_mask argument.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If propagate is 

-<symbol>True</symbol>

-and no clients have selected on destination any of

-the event types in event-mask, the destination is replaced with the

-closest ancestor of destination for which some client has selected a

-type in event-mask and for which no intervening window has that type in its

-do-not-propagate-mask. 

-If no such window exists or if the window is

-an ancestor of the focus window and 

-<symbol>InputFocus</symbol>

-was originally specified

-as the destination, the event is not sent to any clients.

-Otherwise, the event is reported to every client selecting on the final

-destination any of the types specified in event_mask.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The event in the

-<structname>XEvent</structname>

-structure must be one of the core events or one of the events

-defined by an extension (or a 

-<errorname>BadValue</errorname>

-error results) so that the X server can correctly byte-swap 

-the contents as necessary.  

-The contents of the event are

-otherwise unaltered and unchecked by the X server except to force send_event to

-<symbol>True</symbol>

-in the forwarded event and to set the serial number in the event correctly;

-therefore these fields

-and the display field are ignored by

-<function>XSendEvent</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XSendEvent</function>

-returns zero if the conversion to wire protocol format failed

-and returns nonzero otherwise.

-</para>

-<para>

-<!-- .LP -->

-<function>XSendEvent</function>

-can generate

-<errorname>BadValue</errorname>

-and 

-<errorname>BadWindow</errorname>

-errors.

-</para>

-</sect1>

-<sect1 id="Getting_Pointer_Motion_History">

-<title>Getting Pointer Motion History</title>

-<!-- .XS -->

-<!-- (SN Getting Pointer Motion History -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Some X server implementations will maintain a more complete

-history of pointer motion than is reported by event notification.

-The pointer position at each pointer hardware interrupt may be

-stored in a buffer for later retrieval.

-This buffer is called the motion history buffer.

-For example, a few applications, such as paint programs,

-want to have a precise history of where the pointer

-traveled. 

-However, this historical information is highly excessive for most applications.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To determine the approximate maximum number of elements in the motion buffer, 

-use

-<function>XDisplayMotionBufferSize</function>.

-<indexterm significance="preferred"><primary>XDisplayMotionBufferSize</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>unsigned <type>long</type></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The server may retain the recent history of the pointer motion

-and do so to a finer granularity than is reported by

-<symbol>MotionNotify</symbol>

-events.

-The

-<function>XGetMotionEvents</function>

-function makes this history available.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To get the motion history for a specified window and time, use

-<function>XGetMotionEvents</function>.

-<indexterm significance="preferred"><primary>XGetMotionEvents</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>XTimeCoord *<function>XGetMotionEvents</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Timestart,<parameter> stop</parameter></paramdef>

-  <paramdef>int<parameter> *nevents_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>start</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>stop</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the time interval in which the events are returned from the motion

-history buffer.

-You can pass a timestamp or

-<symbol>CurrentTime</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nevents_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of events from the motion history buffer.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetMotionEvents</function>

-function returns all events in the motion history buffer that fall between the

-specified start and stop times, inclusive, and that have coordinates

-that lie within the specified window (including its borders) at its present

-placement.

-If the server does not support motion history, 

-if the start time is later than the stop time,

-or if the start time is in the future, 

-no events are returned;

-<function>XGetMotionEvents</function>

-returns NULL.

-If the stop time is in the future, it is equivalent to specifying

-<symbol>CurrentTime</symbol>.

-The return type for this function is a structure defined as follows:

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XTimeCoord</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i -->

-<!-- .ta .5i -->

-typedef struct {

-	Time time;

-	short x, y;

-} XTimeCoord;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The time member is set to the time, in milliseconds. 

-The x and y members are set to the coordinates of the pointer and

-are reported relative to the origin

-of the specified window.

-To free the data returned from this call, use

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetMotionEvents</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect1>

-<sect1 id="Handling_Protocol_Errors">

-<title>Handling Protocol Errors</title>

-<!-- .XS -->

-<!-- (SN Handling Protocol Errors -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to enable or disable synchronization

-and to use the default error handlers.

-</para>

-<sect2 id="Enabling_or_Disabling_Synchronization">

-<title>Enabling or Disabling Synchronization</title>

-<!-- .XS -->

-<!-- (SN Enabling or Disabling Synchronization  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-When debugging X applications, 

-it often is very convenient to require Xlib to behave synchronously

-so that errors are reported as they occur.

-The following function lets you disable or enable synchronous behavior.

-Note that graphics may occur 30 or more times more slowly when 

-synchronization is enabled.

-<indexterm><primary>_Xdebug</primary></indexterm>

-On <acronym>POSIX</acronym>-conformant systems,

-there is also a global variable 

-<varname>_Xdebug</varname>

-that, if set to nonzero before starting a program under a debugger, will force

-synchronous library behavior.

-</para>

-<para>

-<!-- .LP -->

-After completing their work,

-all Xlib functions that generate protocol requests call what is known as

-an after function.

-<function>XSetAfterFunction</function>

-sets which function is to be called.

-<indexterm significance="preferred"><primary>XSetAfterFunction</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><type>int</type></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> (*procedure)()</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>procedure</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the procedure to be called.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The specified procedure is called with only a display pointer.

-<function>XSetAfterFunction</function>

-returns the previous after function.

-</para>

-<para>

-<!-- .LP -->

-To enable or disable synchronization, use 

-<function>XSynchronize</function>.

-<indexterm><primary>Debugging</primary><secondary>synchronous mode</secondary></indexterm>

-<indexterm significance="preferred"><primary>XSynchronize</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><type>int</type></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Bool<parameter> onoff</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>onoff</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a Boolean value that indicates whether to enable 

-or disable synchronization.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSynchronize</function>

-function returns 

-the previous after function.

-If onoff is 

-<symbol>True</symbol>,

-<function>XSynchronize</function>

-turns on synchronous behavior.

-If onoff is

-<symbol>False</symbol>,

-<function>XSynchronize</function>

-turns off synchronous behavior.

-</para>

-</sect2>

-<sect2 id="Using_the_Default_Error_Handlers">

-<title>Using the Default Error Handlers</title>

-<!-- .XS -->

-<!-- (SN Using the Default Error Handlers  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm><primary>Debugging</primary><secondary>error handlers</secondary></indexterm>

-<indexterm><primary>Error</primary><secondary>handlers</secondary></indexterm>

-There are two default error handlers in Xlib: 

-one to handle typically fatal conditions (for example, 

-the connection to a display server dying because a machine crashed) 

-and one to handle protocol errors from the X server.

-These error handlers can be changed to user-supplied routines if you

-prefer your own error handling and can be changed as often as you like.

-If either function is passed a NULL pointer, it will

-reinvoke the default handler.

-The action of the default handlers is to print an explanatory

-message and exit.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the error handler, use

-<function>XSetErrorHandler</function>.

-<indexterm significance="preferred"><primary>XSetErrorHandler</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int *<function>XSetErrorHandler</function></funcdef>

-  <paramdef>int <parameter> *handler</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>handler</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the program's supplied error handler.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-Xlib generally calls the program's

-supplied error handler whenever an error is received.

-It is not called on

-<errorname>BadName</errorname>

-errors from

-<systemitem>OpenFont</systemitem>,

-<systemitem>LookupColor</systemitem>,

-or

-<systemitem>AllocNamedColor</systemitem>

-protocol requests or on

-<errorname>BadFont</errorname>

-errors from a

-<systemitem>QueryFont</systemitem>

-protocol request.

-These errors generally are reflected back to the program through the

-procedural interface.

-Because this condition is not assumed to be fatal, 

-it is acceptable for your error handler to return;

-the returned value is ignored.

-However, the error handler should not

-call any functions (directly or indirectly) on the display

-that will generate protocol requests or that will look for input events.

-The previous error handler is returned.

-</para>

-<para>

-<!-- .LP -->

-The 

-<structname>XErrorEvent</structname>

-structure contains:

-<indexterm><primary>Debugging</primary><secondary>error event</secondary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XErrorEvent</primary></indexterm>

-<literallayout class="monospaced">

-<!-- .TA .5i 2.5i -->

-<!-- .ta .5i 2.5i -->

-typedef struct {

-	int type;

-	Display *display;	/* Display the event was read from */

-	unsigned long serial;		/* serial number of failed request */

-	unsigned char error_code;	/* error code of failed request */

-	unsigned char request_code;	/* Major op-code of failed request */

-	unsigned char minor_code;	/* Minor op-code of failed request */

-	XID resourceid;		/* resource id */

-} XErrorEvent;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<indexterm><primary>Serial Number</primary></indexterm>

-The serial member is the number of requests, starting from one, 

-sent over the network connection since it was opened. 

-It is the number that was the value of 

-<function>NextRequest</function>

-immediately before the failing call was made.  

-The request_code member is a protocol request

-of the procedure that failed, as defined in 

-&lt; X11/Xproto.h .&gt;

-The following error codes can be returned by the functions described in this

-chapter:

-</para>

-<!-- .br -->

-<!-- .ne 13 -->

-<indexterm><primary>Debugging</primary><secondary>error numbers</secondary></indexterm>

-<indexterm><primary>Error</primary><secondary>codes</secondary></indexterm>

-<!-- .\".CP T 3 -->

-<!-- .\"Error Codes -->

-<indexterm significance="preferred"><primary>BadAccess</primary></indexterm>

-<indexterm significance="preferred"><primary>BadAlloc</primary></indexterm>

-<indexterm significance="preferred"><primary>BadAtom</primary></indexterm>

-<indexterm significance="preferred"><primary>BadColor</primary></indexterm>

-<indexterm significance="preferred"><primary>BadCursor</primary></indexterm>

-<indexterm significance="preferred"><primary>BadDrawable</primary></indexterm>

-<indexterm significance="preferred"><primary>BadFont</primary></indexterm>

-<indexterm significance="preferred"><primary>BadGC</primary></indexterm>

-<indexterm significance="preferred"><primary>BadIDChoice</primary></indexterm>

-<informaltable>

-  <tgroup cols='2' align='center'>

-  <colspec colname='c1'/>

-  <colspec colname='c2'/>

-  <thead>

-    <row>

-      <entry>Error Code</entry>

-      <entry>Description</entry>

-    </row>

-  </thead>

-  <tbody>

-    <row>

-      <entry><errorname>BadAccess</errorname></entry>

-      <entry>A client attempts to grab a key/button combination already grabbed

-      by another client.</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>A client attempts to free a colormap entry that it had not already allocated

-      or to free an entry in a colormap that was created with all entries writable.</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>A client attempts to store into a read-only or unallocated colormap entry.</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>A client attempts to modify the access control list from other than the local

-      (or otherwise authorized) host.</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>A client attempts to select an event type that another client

-      has already selected.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadAlloc</errorname></entry>

-      <entry>The server fails to allocate the requested resource.

-      Note that the explicit listing of

-      <errorname>BadAlloc</errorname>

-      errors in requests only covers allocation errors at a very coarse level

-      and is not intended to (nor can it in practice hope to) cover all cases of

-      a server running out of allocation space in the middle of service.

-      The semantics when a server runs out of allocation space are left unspecified,

-      but a server may generate a

-      <errorname>BadAlloc</errorname>

-      error on any request for this reason,

-      and clients should be prepared to receive such errors and handle or discard

-      them.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadAtom</errorname></entry>

-      <entry>A value for an atom argument does not name a defined atom.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadColor</errorname></entry>

-      <entry>A value for a colormap argument does not name a defined colormap.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadCursor</errorname></entry>

-      <entry>A value for a cursor argument does not name a defined cursor.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadDrawable</errorname></entry>

-      <entry>A value for a drawable argument does not name a defined window or pixmap.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadFont</errorname></entry>

-      <entry>A value for a font argument does not name a defined font (or, in some cases,

-      <type>GContext</type>).</entry>

-    </row>

-    <row>

-      <entry><errorname>BadGC</errorname></entry>

-      <entry>A value for a

-      <type>GContext</type>

-      argument does not name a defined 

-      <type>GContext</type>.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadIDChoice</errorname></entry>

-      <entry>The value chosen for a resource identifier either is not included in the

-      range assigned to the client or is already in use.

-      Under normal circumstances,

-      this cannot occur and should be considered a server or Xlib error.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadImplementation</errorname></entry>

-      <entry>The server does not implement some aspect of the request.

-      A server that generates this error for a core request is deficient.

-      As such, this error is not listed for any of the requests,

-      but clients should be prepared to receive such errors

-      and handle or discard them.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadLength</errorname></entry>

-      <entry>The length of a request is shorter or longer than that required to

-      contain the arguments.

-      This is an internal Xlib or server error.</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>

-      The length of a request exceeds the maximum length accepted by the server.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadMatch</errorname></entry>

-      <entry>In a graphics request,

-      the root and depth of the graphics context do not match those of the drawable.</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>An <symbol>InputOnly</symbol> window is used as a drawable.</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>

-      Some argument or pair of arguments has the correct type and range,

-      but it fails to match in some other way required by the request.</entry>

-    </row>

-    <row>

-      <entry></entry>

-      <entry>An <symbol>InputOnly</symbol>

-      window lacks this attribute.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadName</errorname></entry>

-      <entry>A font or color of the specified name does not exist.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadPixmap</errorname></entry>

-      <entry>A value for a pixmap argument does not name a defined pixmap.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadRequest</errorname></entry>

-      <entry>The major or minor opcode does not specify a valid request.

-      This usually is an Xlib or server error.</entry>

-    </row>

-    <row>

-      <entry><errorname>BadValue</errorname></entry>

-      <entry>Some numeric value falls outside of the range of values accepted

-      by the request.

-      Unless a specific range is specified for an argument,

-      the full range defined by the argument's type is accepted.

-      Any argument defined as a set of alternatives typically can generate

-      this error (due to the encoding).</entry>

-    </row>

-    <row>

-      <entry><errorname>BadWindow</errorname></entry>

-      <entry>A value for a window argument does not name a defined window.</entry>

-    </row>

-  </tbody>

-  </tgroup>

-</informaltable>

-

-<indexterm significance="preferred"><primary>BadImplementation</primary></indexterm>

-<indexterm significance="preferred"><primary>BadLength</primary></indexterm>

-<indexterm significance="preferred"><primary>BadMatch</primary></indexterm>

-<indexterm significance="preferred"><primary>BadName</primary></indexterm>

-<indexterm significance="preferred"><primary>BadPixmap</primary></indexterm>

-<indexterm significance="preferred"><primary>BadRequest</primary></indexterm>

-<indexterm significance="preferred"><primary>BadValue</primary></indexterm>

-<indexterm significance="preferred"><primary>BadWindow</primary></indexterm>

-<!-- .NT Note -->

-

-<note>

-<para>

-The 

-<errorname>BadAtom</errorname>,

-<errorname>BadColor</errorname>,

-<errorname>BadCursor</errorname>,

-<errorname>BadDrawable</errorname>,

-<errorname>BadFont</errorname>,

-<errorname>BadGC</errorname>,

-<errorname>BadPixmap</errorname>,

-and 

-<errorname>BadWindow</errorname>

-errors are also used when the argument type is extended by a set of

-fixed alternatives.

-</para>

-</note>

-

-<!-- .NE -->

-<!-- .sp -->

-<para>

-<!-- .LP -->

-To obtain textual descriptions of the specified error code, use 

-<function>XGetErrorText</function>.

-<indexterm significance="preferred"><primary>XGetErrorText</primary></indexterm>

-<indexterm><primary>Debugging</primary><secondary>error message strings</secondary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XGetErrorText</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>int<parameter> code</parameter></paramdef>

-  <paramdef>char<parameter> *buffer_return</parameter></paramdef>

-  <paramdef>int<parameter> length</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>code</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the error code for which you want to obtain a description.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>buffer_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the error description.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>length</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the size of the buffer.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM  -->

-The

-<function>XGetErrorText</function>

-function copies a null-terminated string describing the specified error code

-into the specified buffer.

-The returned text is in the encoding of the current locale.

-It is recommended that you use this function to obtain an error description

-because extensions to Xlib may define their own error codes

-and error strings.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain error messages from the error database, use

-<function>XGetErrorDatabaseText</function>.

-<indexterm significance="preferred"><primary>XGetErrorDatabaseText</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XGetErrorDatabaseText</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>char*name,<parameter> *message</parameter></paramdef>

-  <paramdef>char<parameter> *default_string</parameter></paramdef>

-  <paramdef>char<parameter> *buffer_return</parameter></paramdef>

-  <paramdef>int<parameter> length</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the name of the application.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>message</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the type of the error message.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>default_string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the default error message if none is found in the database.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>buffer_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the error description.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>length</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the size of the buffer.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetErrorDatabaseText</function>

-function returns a null-terminated message

-(or the default message) from the error message

-database.

-Xlib uses this function internally to look up its error messages.

-The text in the default_string argument is assumed

-to be in the encoding of the current locale,

-and the text stored in the buffer_return argument

-is in the encoding of the current locale.

-</para>

-<para>

-<!-- .LP -->

-The name argument should generally be the name of your application.

-The message argument should indicate which type of error message you want.

-If the name and message are not in the Host Portable Character Encoding,

-the result is implementation-dependent.

-Xlib uses three predefined ``application names'' to report errors.

-In these names,

-uppercase and lowercase matter.

-<variablelist>

-  <varlistentry>

-    <term>

-      XProtoError

-    </term>

-    <listitem>

-      <para>

-The protocol error number is used as a string for the message argument.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      XlibMessage

-    </term>

-    <listitem>

-      <para>

-These are the message strings that are used internally by the library.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      XRequest

-    </term>

-    <listitem>

-      <para>

-For a core protocol request,

-the major request protocol number is used for the message argument.

-For an extension request,

-the extension name (as given by

-<function>InitExtension</function>)

-followed by a period (.) and the minor request protocol number 

-is used for the message argument.

-If no string is found in the error database,

-the default_string is returned to the buffer argument.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To report an error to the user when the requested display does not exist, use

-<function>XDisplayName</function>.

-<indexterm significance="preferred"><primary>XDisplayName</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XDisplayName</function></funcdef>

-  <paramdef>char<parameter> *string</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>string</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the character string.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDisplayName</function>

-function returns the name of the display that 

-<function>XOpenDisplay</function>

-would attempt to use.

-If a NULL string is specified,

-<function>XDisplayName</function>

-looks in the environment for the display and returns the display name that

-<function>XOpenDisplay</function>

-would attempt to use.

-This makes it easier to report to the user precisely which display the

-program attempted to open when the initial connection attempt failed.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To handle fatal I/O errors, use

-<function>XSetIOErrorHandler</function>.

-<indexterm significance="preferred"><primary>XSetIOErrorHandler</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><type>int</type></funcdef>

-  <paramdef>int(*handler)(Display<parameter> *)</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>handler</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the program's supplied error handler.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetIOErrorHandler</function>

-sets the fatal I/O error handler.

-Xlib calls the program's supplied error handler if any sort of system call

-error occurs (for example, the connection to the server was lost).

-This is assumed to be a fatal condition,

-and the called routine should not return.

-If the I/O error handler does return,

-the client process exits.

-</para>

-<para>

-<!-- .LP -->

-Note that the previous error handler is returned.

-<!-- .bp -->

-

-</para>

-</sect2>

-</sect1>

-</chapter>

+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+	  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<chapter id="event_handling_functions">
+<title>Event Handling Functions</title>
+
+<para>
+This chapter discusses the Xlib functions you can use to:
+</para>
+<itemizedlist>
+  <listitem><para>Select events</para></listitem>
+  <listitem><para>Handle the output buffer and the event queue</para></listitem>
+  <listitem><para>Select events from the event queue</para></listitem>
+  <listitem><para>Send and get events</para></listitem>
+  <listitem><para>Handle protocol errors</para></listitem>
+</itemizedlist>
+<note><para>
+Some toolkits use their own event-handling functions and do not allow you to
+interchange these event-handling functions with those in Xlib. For further
+information, see the documentation supplied with the toolkit.
+</para></note>
+
+<para>
+Most applications simply are event loops: they wait for an event, decide what to do with it,
+execute some amount of code that results in changes to the display, and then wait for the next
+event.
+</para>
+
+<sect1 id="Selecting_Events">
+<title>Selecting Events</title>
+<!-- .XS -->
+<!-- (SN Selecting Events  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+There are two ways to select the events you want reported to your client
+application.
+One way is to set the event_mask member of the
+<structname>XSetWindowAttributes</structname>
+structure when you call
+<function>XCreateWindow</function>
+and
+<function>XChangeWindowAttributes</function>.
+Another way is to use
+<function>XSelectInput</function>.
+<indexterm significance="preferred"><primary>XSelectInput</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xselectinput'>
+<funcprototype>
+  <funcdef><function>XSelectInput</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>long<parameter> event_mask</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN	 -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose events you are interested in -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event mask.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XSelectInput</function>
+function requests that the X server report the events associated with the 
+specified event mask.
+Initially, X will not report any of these events.
+Events are reported relative to a window.
+If a window is not interested in a device event, it usually propagates to
+the closest ancestor that is interested,
+unless the do_not_propagate mask prohibits it.
+<indexterm><primary>Event</primary><secondary>propagation</secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+Setting the event-mask attribute of a window overrides any previous call
+for the same window but not for other clients.
+Multiple clients can select for the same events on the same window
+with the following restrictions:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Multiple clients can select events on the same window because their event masks
+are disjoint.
+When the X server generates an event, it reports it
+to all interested clients.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Only one client at a time can select
+<symbol>CirculateRequest</symbol>,
+<symbol>ConfigureRequest</symbol>,
+or
+<symbol>MapRequest</symbol>
+events, which are associated with
+the event mask
+<symbol>SubstructureRedirectMask</symbol>.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Only one client at a time can select
+a
+<symbol>ResizeRequest</symbol>
+event, which is associated with
+the event mask
+<symbol>ResizeRedirectMask</symbol>.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Only one client at a time can select a 
+<symbol>ButtonPress</symbol>
+event, which is associated with
+the event mask
+<symbol>ButtonPressMask</symbol>.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The server reports the event to all interested clients.
+</para>
+<para>
+<!-- .LP -->
+<function>XSelectInput</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Handling_the_Output_Buffer">
+<title>Handling the Output Buffer</title>
+<!-- .XS -->
+<!-- (SN Handling the Output Buffer -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The output buffer is an area used by Xlib to store requests.
+The functions described in this section flush the output buffer
+if the function would block or not return an event.
+That is, all requests residing in the output buffer that
+have not yet been sent are transmitted to the X server.
+These functions differ in the additional tasks they might perform.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To flush the output buffer, use 
+<function>XFlush</function>.
+<indexterm significance="preferred"><primary>XFlush</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xflush'>
+<funcprototype>
+  <funcdef><function>XFlush</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFlush</function>
+function
+flushes the output buffer.
+Most client applications need not use this function because the output
+buffer is automatically flushed as needed by calls to
+<function>XPending</function>,
+<function>XNextEvent</function>,
+and
+<function>XWindowEvent</function>.
+<indexterm><primary>XPending</primary></indexterm>
+<indexterm><primary>XNextEvent</primary></indexterm>
+<indexterm><primary>XWindowEvent</primary></indexterm>
+Events generated by the server may be enqueued into the library's event queue.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To flush the output buffer and then wait until all requests have been processed,
+use 
+<function>XSync</function>.
+<indexterm significance="preferred"><primary>XSync</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsync'>
+<funcprototype>
+  <funcdef><function>XSync</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Bool<parameter> discard</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>discard</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a Boolean value that indicates whether 
+<function>XSync</function>
+discards all events on the event queue.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSync</function>
+function
+flushes the output buffer and then waits until all requests have been received
+and processed by the X server.
+Any errors generated must be handled by the error handler.
+For each protocol error received by Xlib,
+<function>XSync</function>
+calls the client application's error handling routine (see section 11.8.2).
+Any events generated by the server are enqueued into the library's 
+event queue.
+</para>
+<para>
+<!-- .LP -->
+Finally, if you passed 
+<symbol>False</symbol>,
+<function>XSync</function>
+does not discard the events in the queue.
+If you passed 
+<symbol>True</symbol>,
+<function>XSync</function>
+discards all events in the queue,
+including those events that were on the queue before
+<function>XSync</function>
+was called.
+Client applications seldom need to call
+<function>XSync</function>.
+</para>
+</sect1>
+<sect1 id="Event_Queue_Management">
+<title>Event Queue Management</title>
+<!-- .XS -->
+<!-- (SN Event Queue Management -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib maintains an event queue.
+However, the operating system also may be buffering data 
+in its network connection that is not yet read into the event queue.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To check the number of events in the event queue, use
+<function>XEventsQueued</function>.
+<indexterm significance="preferred"><primary>XEventsQueued</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xeventsqueued'>
+<funcprototype>
+  <funcdef>int <function>XEventsQueued</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the mode.
+You can pass
+<symbol>QueuedAlready</symbol>,
+<symbol>QueuedAfterFlush</symbol>,
+or
+<symbol>QueuedAfterReading</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If mode is 
+<symbol>QueuedAlready</symbol>,
+<function>XEventsQueued</function>
+returns the number of events
+already in the event queue (and never performs a system call).
+If mode is 
+<symbol>QueuedAfterFlush</symbol>,
+<function>XEventsQueued</function>
+returns the number of events already in the queue if the number is nonzero.
+If there are no events in the queue, 
+<function>XEventsQueued</function>
+flushes the output buffer, 
+attempts to read more events out of the application's connection,
+and returns the number read.
+If mode is 
+<symbol>QueuedAfterReading</symbol>,
+<function>XEventsQueued</function>
+returns the number of events already in the queue if the number is nonzero. 
+If there are no events in the queue, 
+<function>XEventsQueued</function>
+attempts to read more events out of the application's connection 
+without flushing the output buffer and returns the number read.
+</para>
+<para>
+<!-- .LP -->
+<function>XEventsQueued</function>
+always returns immediately without I/O if there are events already in the
+queue.
+<function>XEventsQueued</function>
+with mode 
+<symbol>QueuedAfterFlush</symbol>
+is identical in behavior to
+<function>XPending</function>.
+<function>XEventsQueued</function>
+with mode
+<symbol>QueuedAlready</symbol>
+is identical to the
+<function>XQLength</function>
+function.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return the number of events that are pending, use 
+<function>XPending</function>.
+<indexterm significance="preferred"><primary>XPending</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xpending'>
+<funcprototype>
+  <funcdef>int <function>XPending</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN	 -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPending</function>
+function returns the number of events that have been received from the
+X server but have not been removed from the event queue.
+<function>XPending</function>
+is identical to
+<function>XEventsQueued</function>
+with the mode
+<symbol>QueuedAfterFlush</symbol>
+specified.
+</para>
+</sect1>
+<sect1 id="Manipulating_the_Event_Queue">
+<title>Manipulating the Event Queue</title>
+<!-- .XS -->
+<!-- (SN Manipulating the Event Queue  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that let you manipulate the event queue.
+This section discusses how to:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Obtain events, in order, and remove them from the queue
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Peek at events in the queue without removing them
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Obtain events that match the event mask or the arbitrary
+predicate procedures that you provide
+    </para>
+  </listitem>
+</itemizedlist>
+<sect2 id="Returning_the_Next_Event">
+<title>Returning the Next Event</title>
+<!-- .XS -->
+<!-- (SN Returning the Next Event -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To get the next event and remove it from the queue, use
+<function>XNextEvent</function>.
+<indexterm significance="preferred"><primary>XNextEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xnextevent'>
+<funcprototype>
+  <funcdef><function>XNextEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the next event in the queue.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XNextEvent</function>
+function copies the first event from the event queue into the specified
+<structname>XEvent</structname>
+structure and then removes it from the queue.
+If the event queue is empty,
+<function>XNextEvent</function>
+flushes the output buffer and blocks until an event is received.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To peek at the event queue, use
+<function>XPeekEvent</function>.
+<indexterm significance="preferred"><primary>XPeekEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xpeekevent'>
+<funcprototype>
+  <funcdef><function>XPeekEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns a copy of the matched event's associated structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPeekEvent</function>
+function returns the first event from the event queue,
+but it does not remove the event from the queue.
+If the queue is empty,
+<function>XPeekEvent</function>
+flushes the output buffer and blocks until an event is received.
+It then copies the event into the client-supplied
+<structname>XEvent</structname>
+structure without removing it from the event queue.
+</para>
+</sect2>
+<sect2 id="Selecting_Events_Using_a_Predicate_Procedure">
+<title>Selecting Events Using a Predicate Procedure</title>
+<!-- .XS -->
+<!-- (SN Selecting Events Using a Predicate Procedure -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Each of the functions discussed in this section requires you to
+pass a predicate procedure that determines if an event matches 
+what you want.
+Your predicate procedure must decide if the event is useful
+without calling any Xlib functions.
+If the predicate directly or indirectly causes the state of the event queue
+to change, the result is not defined.
+If Xlib has been initialized for threads, the predicate is called with
+the display locked and the result of a call by the predicate to any
+Xlib function that locks the display is not defined unless the caller
+has first called
+<function>XLockDisplay</function>.
+</para>
+<para>
+<!-- .LP -->
+The predicate procedure and its associated arguments are:
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef><type>Bool</type></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event</parameter></paramdef>
+  <paramdef>XPointer<parameter> arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the
+<structname>XEvent</structname>
+structure.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>arg</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the argument passed in from the 
+<function>XIfEvent</function>,
+<function>XCheckIfEvent</function>,
+or
+<function>XPeekIfEvent</function>
+function.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The predicate procedure is called once for each
+event in the queue until it finds a match. 
+After finding a match, the predicate procedure must return 
+<symbol>True</symbol>.
+If it did not find a match, it must return
+<symbol>False</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To check the event queue for a matching event
+and, if found, remove the event from the queue, use
+<function>XIfEvent</function>.
+<indexterm significance="preferred"><primary>XIfEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xifevent'>
+<funcprototype>
+  <funcdef><function>XIfEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+  <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>
+  <paramdef>XPointer<parameter> arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the matched event's associated structure.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>predicate</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure that is to be called to determine
+if the next event in the queue matches what you want.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>arg</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the user-supplied argument that will be passed to the predicate procedure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XIfEvent</function>
+function completes only when the specified predicate
+procedure returns 
+<symbol>True</symbol>
+for an event, 
+which indicates an event in the queue matches.
+<function>XIfEvent</function>
+flushes the output buffer if it blocks waiting for additional events.
+<function>XIfEvent</function>
+removes the matching event from the queue 
+and copies the structure into the client-supplied
+<structname>XEvent</structname>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To check the event queue for a matching event without blocking, use
+<function>XCheckIfEvent</function>.
+<indexterm significance="preferred"><primary>XCheckIfEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcheckifevent'>
+<funcprototype>
+  <funcdef>Bool <function>XCheckIfEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+  <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>
+  <paramdef>XPointer<parameter> arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns a copy of the matched event's associated structure.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>predicate</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure that is to be called to determine
+if the next event in the queue matches what you want.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>arg</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the user-supplied argument that will be passed to the predicate procedure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+When the predicate procedure finds a match,
+<function>XCheckIfEvent</function>
+copies the matched event into the client-supplied
+<structname>XEvent</structname>
+structure and returns 
+<symbol>True</symbol>.
+(This event is removed from the queue.)
+If the predicate procedure finds no match,
+<function>XCheckIfEvent</function>
+returns
+<symbol>False</symbol>,
+and the output buffer will have been flushed.
+All earlier events stored in the queue are not discarded.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To check the event queue for a matching event
+without removing the event from the queue, use
+<function>XPeekIfEvent</function>.
+<indexterm significance="preferred"><primary>XPeekIfEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xpeekifevent'>
+<funcprototype>
+  <funcdef><function>XPeekIfEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+  <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>
+  <paramdef>XPointer<parameter> arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns a copy of the matched event's associated structure.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>predicate</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure that is to be called to determine
+if the next event in the queue matches what you want.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>arg</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the user-supplied argument that will be passed to the predicate procedure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XPeekIfEvent</function>
+function returns only when the specified predicate
+procedure returns 
+<symbol>True</symbol>
+for an event.
+After the predicate procedure finds a match,
+<function>XPeekIfEvent</function>
+copies the matched event into the client-supplied
+<structname>XEvent</structname>
+structure without removing the event from the queue.
+<function>XPeekIfEvent</function>
+flushes the output buffer if it blocks waiting for additional events.
+</para>
+</sect2>
+<sect2 id="Selecting_Events_Using_a_Window_or_Event_Mask">
+<title>Selecting Events Using a Window or Event Mask</title>
+<!-- .XS -->
+<!-- (SN Selecting Events Using a Window or Event Mask -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The functions discussed in this section let you select events by window 
+or event types, allowing you to process events out of order.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove the next event that matches both a window and an event mask, use
+<function>XWindowEvent</function>.
+<indexterm significance="preferred"><primary>XWindowEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xwindowevent'>
+<funcprototype>
+  <funcdef><function>XWindowEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>long<parameter> event_mask</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose events you are interested in -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event mask.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the matched event's associated structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XWindowEvent</function>
+function searches the event queue for an event that matches both the specified
+window and event mask.
+When it finds a match,
+<function>XWindowEvent</function>
+removes that event from the queue and copies it into the specified
+<structname>XEvent</structname>
+structure.
+The other events stored in the queue are not discarded.
+If a matching event is not in the queue,
+<function>XWindowEvent</function>
+flushes the output buffer and blocks until one is received.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove the next event that matches both a window and an event mask (if any),
+use
+<function>XCheckWindowEvent</function>.
+<indexterm><primary>XCheckWindowEvent</primary></indexterm>
+This function is similar to
+<function>XWindowEvent</function>
+except that it never blocks and it returns a 
+<type>Bool</type>
+indicating if the event was returned.
+<indexterm significance="preferred"><primary>XCheckWindowEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcheckwindowevent'>
+<funcprototype>
+  <funcdef>Bool <function>XCheckWindowEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>long<parameter> event_mask</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose events you are interested in -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event mask.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the matched event's associated structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCheckWindowEvent</function>
+function searches the event queue and then the events available 
+on the server connection for the first event that matches the specified window
+and event mask.
+If it finds a match,
+<function>XCheckWindowEvent</function>
+removes that event, copies it into the specified
+<structname>XEvent</structname>
+structure, and returns
+<symbol>True</symbol>.
+The other events stored in the queue are not discarded.
+If the event you requested is not available,
+<function>XCheckWindowEvent</function>
+returns
+<symbol>False</symbol>,
+and the output buffer will have been flushed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To remove the next event that matches an event mask, use
+<function>XMaskEvent</function>.
+<indexterm significance="preferred"><primary>XMaskEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xmaskevent'>
+<funcprototype>
+  <funcdef><function>XMaskEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>long<parameter> event_mask</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event mask.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the matched event's associated structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XMaskEvent</function>
+function searches the event queue for the events associated with the 
+specified mask.
+When it finds a match,
+<function>XMaskEvent</function>
+removes that event and copies it into the specified
+<structname>XEvent</structname>
+structure.
+The other events stored in the queue are not discarded.
+If the event you requested is not in the queue,
+<function>XMaskEvent</function>
+flushes the output buffer and blocks until one is received.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return and remove the next event that matches an event mask (if any), use
+<function>XCheckMaskEvent</function>.
+This function is similar to 
+<function>XMaskEvent</function>
+except that it never blocks and it returns a 
+<type>Bool</type>
+indicating if the event was returned.
+<indexterm significance="preferred"><primary>XCheckMaskEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xcheckmaskevent'>
+<funcprototype>
+  <funcdef>Bool <function>XCheckMaskEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>long<parameter> event_mask</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event mask.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the matched event's associated structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCheckMaskEvent</function>
+function searches the event queue and then any events available on the
+server connection for the first event that matches the specified mask.
+If it finds a match,
+<function>XCheckMaskEvent</function>
+removes that event, copies it into the specified
+<structname>XEvent</structname>
+structure, and returns
+<symbol>True</symbol>.
+The other events stored in the queue are not discarded.
+If the event you requested is not available,
+<function>XCheckMaskEvent</function>
+returns
+<symbol>False</symbol>,
+and the output buffer will have been flushed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp  -->
+To return and remove the next event in the queue that matches an event type, use
+<function>XCheckTypedEvent</function>.
+<indexterm significance="preferred"><primary>XCheckTypedEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xchecktypedevent'>
+<funcprototype>
+  <funcdef>Bool <function>XCheckTypedEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> event_type</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_type</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event type to be compared.
+
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the matched event's associated structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCheckTypedEvent</function>
+function searches the event queue and then any events available  
+on the server connection for the first event that matches the specified type.
+If it finds a match,
+<function>XCheckTypedEvent</function>
+removes that event, copies it into the specified
+<structname>XEvent</structname>
+structure, and returns
+<symbol>True</symbol>.
+The other events in the queue are not discarded.
+If the event is not available,
+<function>XCheckTypedEvent</function>
+returns
+<symbol>False</symbol>,
+and the output buffer will have been flushed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return and remove the next event in the queue that matches an event type 
+and a window, use
+<function>XCheckTypedWindowEvent</function>.
+<indexterm significance="preferred"><primary>XCheckTypedWindowEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xchecktypedwindowevent'>
+<funcprototype>
+  <funcdef>Bool <function>XCheckTypedWindowEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>int<parameter> event_type</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_type</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event type to be compared.
+
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the matched event's associated structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCheckTypedWindowEvent</function>
+function searches the event queue and then any events available  
+on the server connection for the first event that matches the specified
+type and window.
+If it finds a match,
+<function>XCheckTypedWindowEvent</function>
+removes the event from the queue, copies it into the specified
+<structname>XEvent</structname>
+structure, and returns
+<symbol>True</symbol>.
+The other events in the queue are not discarded.
+If the event is not available,
+<function>XCheckTypedWindowEvent</function>
+returns
+<symbol>False</symbol>,
+and the output buffer will have been flushed.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Putting_an_Event_Back_into_the_Queue">
+<title>Putting an Event Back into the Queue</title>
+<!-- .XS -->
+<!-- (SN Putting an Event Back into the Queue  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To push an event back into the event queue, use
+<function>XPutBackEvent</function>.
+<indexterm significance="preferred"><primary>XPutBackEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xputbackevent'>
+<funcprototype>
+  <funcdef><function>XPutBackEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XPutBackEvent</function>
+function pushes an event back onto the head of the display's event queue
+by copying the event into the queue.
+This can be useful if you read an event and then decide that you
+would rather deal with it later.
+There is no limit to the number of times in succession that you can call
+<function>XPutBackEvent</function>.
+</para>
+</sect1>
+<sect1 id="Sending_Events_to_Other_Applications">
+<title>Sending Events to Other Applications</title>
+<!-- .XS -->
+<!-- (SN Sending Events to Other Applications -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To send an event to a specified window, use
+<function>XSendEvent</function>.
+<indexterm><primary>XSendEvent</primary></indexterm>
+This function is often used in selection processing.
+For example, the owner of a selection should use
+<function>XSendEvent</function>
+to send a
+<symbol>SelectionNotify</symbol>
+event to a requestor when a selection has been converted 
+and stored as a property.
+<indexterm significance="preferred"><primary>XSendEvent</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsendevent'>
+<funcprototype>
+  <funcdef>Status <function>XSendEvent</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Bool<parameter> propagate</parameter></paramdef>
+  <paramdef>long<parameter> event_mask</parameter></paramdef>
+  <paramdef>XEvent<parameter> *event_send</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window the event is to be sent to, or
+<symbol>PointerWindow</symbol>,
+or
+<symbol>InputFocus</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>propagate</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a Boolean value.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_mask</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event mask.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>event_send</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the event that is to be sent.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSendEvent</function>
+function identifies the destination window, 
+determines which clients should receive the specified events, 
+and ignores any active grabs.
+This function requires you to pass an event mask.
+For a discussion of the valid event mask names,
+see section 10.3.
+This function uses the w argument to identify the destination window as follows:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+If w is
+<symbol>PointerWindow</symbol>,
+the destination window is the window that contains the pointer.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If w is
+<symbol>InputFocus</symbol>
+and if the focus window contains the pointer, 
+the destination window is the window that contains the pointer; 
+otherwise, the destination window is the focus window.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+To determine which clients should receive the specified events,
+<function>XSendEvent</function>
+uses the propagate argument as follows:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+If event_mask is the empty set,
+the event is sent to the client that created the destination window.
+If that client no longer exists,
+no event is sent.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If propagate is 
+<symbol>False</symbol>,
+the event is sent to every client selecting on destination any of the event
+types in the event_mask argument.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If propagate is 
+<symbol>True</symbol>
+and no clients have selected on destination any of
+the event types in event-mask, the destination is replaced with the
+closest ancestor of destination for which some client has selected a
+type in event-mask and for which no intervening window has that type in its
+do-not-propagate-mask. 
+If no such window exists or if the window is
+an ancestor of the focus window and 
+<symbol>InputFocus</symbol>
+was originally specified
+as the destination, the event is not sent to any clients.
+Otherwise, the event is reported to every client selecting on the final
+destination any of the types specified in event_mask.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The event in the
+<structname>XEvent</structname>
+structure must be one of the core events or one of the events
+defined by an extension (or a 
+<errorname>BadValue</errorname>
+error results) so that the X server can correctly byte-swap 
+the contents as necessary.  
+The contents of the event are
+otherwise unaltered and unchecked by the X server except to force send_event to
+<symbol>True</symbol>
+in the forwarded event and to set the serial number in the event correctly;
+therefore these fields
+and the display field are ignored by
+<function>XSendEvent</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XSendEvent</function>
+returns zero if the conversion to wire protocol format failed
+and returns nonzero otherwise.
+</para>
+<para>
+<!-- .LP -->
+<function>XSendEvent</function>
+can generate
+<errorname>BadValue</errorname>
+and 
+<errorname>BadWindow</errorname>
+errors.
+</para>
+</sect1>
+<sect1 id="Getting_Pointer_Motion_History">
+<title>Getting Pointer Motion History</title>
+<!-- .XS -->
+<!-- (SN Getting Pointer Motion History -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Some X server implementations will maintain a more complete
+history of pointer motion than is reported by event notification.
+The pointer position at each pointer hardware interrupt may be
+stored in a buffer for later retrieval.
+This buffer is called the motion history buffer.
+For example, a few applications, such as paint programs,
+want to have a precise history of where the pointer
+traveled. 
+However, this historical information is highly excessive for most applications.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To determine the approximate maximum number of elements in the motion buffer, 
+use
+<function>XDisplayMotionBufferSize</function>.
+<indexterm significance="preferred"><primary>XDisplayMotionBufferSize</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdisplaymotionbuffersize'>
+<funcprototype>
+  <funcdef>unsigned <type>long</type></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The server may retain the recent history of the pointer motion
+and do so to a finer granularity than is reported by
+<symbol>MotionNotify</symbol>
+events.
+The
+<function>XGetMotionEvents</function>
+function makes this history available.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the motion history for a specified window and time, use
+<function>XGetMotionEvents</function>.
+<indexterm significance="preferred"><primary>XGetMotionEvents</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgetmotionevents'>
+<funcprototype>
+  <funcdef>XTimeCoord *<function>XGetMotionEvents</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Timestart,<parameter> stop</parameter></paramdef>
+  <paramdef>int<parameter> *nevents_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>start</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>stop</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the time interval in which the events are returned from the motion
+history buffer.
+You can pass a timestamp or
+<symbol>CurrentTime</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nevents_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of events from the motion history buffer.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetMotionEvents</function>
+function returns all events in the motion history buffer that fall between the
+specified start and stop times, inclusive, and that have coordinates
+that lie within the specified window (including its borders) at its present
+placement.
+If the server does not support motion history, 
+if the start time is later than the stop time,
+or if the start time is in the future, 
+no events are returned;
+<function>XGetMotionEvents</function>
+returns NULL.
+If the stop time is in the future, it is equivalent to specifying
+<symbol>CurrentTime</symbol>.
+The return type for this function is a structure defined as follows:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XTimeCoord</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+typedef struct {
+	Time time;
+	short x, y;
+} XTimeCoord;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The time member is set to the time, in milliseconds. 
+The x and y members are set to the coordinates of the pointer and
+are reported relative to the origin
+of the specified window.
+To free the data returned from this call, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetMotionEvents</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Handling_Protocol_Errors">
+<title>Handling Protocol Errors</title>
+<!-- .XS -->
+<!-- (SN Handling Protocol Errors -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to enable or disable synchronization
+and to use the default error handlers.
+</para>
+<sect2 id="Enabling_or_Disabling_Synchronization">
+<title>Enabling or Disabling Synchronization</title>
+<!-- .XS -->
+<!-- (SN Enabling or Disabling Synchronization  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+When debugging X applications, 
+it often is very convenient to require Xlib to behave synchronously
+so that errors are reported as they occur.
+The following function lets you disable or enable synchronous behavior.
+Note that graphics may occur 30 or more times more slowly when 
+synchronization is enabled.
+<indexterm><primary>_Xdebug</primary></indexterm>
+On <acronym>POSIX</acronym>-conformant systems,
+there is also a global variable 
+<varname>_Xdebug</varname>
+that, if set to nonzero before starting a program under a debugger, will force
+synchronous library behavior.
+</para>
+<para>
+<!-- .LP -->
+After completing their work,
+all Xlib functions that generate protocol requests call what is known as
+an after function.
+<function>XSetAfterFunction</function>
+sets which function is to be called.
+<indexterm significance="preferred"><primary>XSetAfterFunction</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetafterfunction'>
+<funcprototype>
+  <funcdef><type>int</type></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> (*procedure)()</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>procedure</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the procedure to be called.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The specified procedure is called with only a display pointer.
+<function>XSetAfterFunction</function>
+returns the previous after function.
+</para>
+<para>
+<!-- .LP -->
+To enable or disable synchronization, use 
+<function>XSynchronize</function>.
+<indexterm><primary>Debugging</primary><secondary>synchronous mode</secondary></indexterm>
+<indexterm significance="preferred"><primary>XSynchronize</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsynchronize'>
+<funcprototype>
+  <funcdef><type>int</type></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Bool<parameter> onoff</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>onoff</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a Boolean value that indicates whether to enable 
+or disable synchronization.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSynchronize</function>
+function returns 
+the previous after function.
+If onoff is 
+<symbol>True</symbol>,
+<function>XSynchronize</function>
+turns on synchronous behavior.
+If onoff is
+<symbol>False</symbol>,
+<function>XSynchronize</function>
+turns off synchronous behavior.
+</para>
+</sect2>
+<sect2 id="Using_the_Default_Error_Handlers">
+<title>Using the Default Error Handlers</title>
+<!-- .XS -->
+<!-- (SN Using the Default Error Handlers  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Debugging</primary><secondary>error handlers</secondary></indexterm>
+<indexterm><primary>Error</primary><secondary>handlers</secondary></indexterm>
+There are two default error handlers in Xlib: 
+one to handle typically fatal conditions (for example, 
+the connection to a display server dying because a machine crashed) 
+and one to handle protocol errors from the X server.
+These error handlers can be changed to user-supplied routines if you
+prefer your own error handling and can be changed as often as you like.
+If either function is passed a NULL pointer, it will
+reinvoke the default handler.
+The action of the default handlers is to print an explanatory
+message and exit.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the error handler, use
+<function>XSetErrorHandler</function>.
+<indexterm significance="preferred"><primary>XSetErrorHandler</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xseterrorhandler'>
+<funcprototype>
+  <funcdef>int *<function>XSetErrorHandler</function></funcdef>
+  <paramdef>int <parameter> *handler</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>handler</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the program's supplied error handler.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+Xlib generally calls the program's
+supplied error handler whenever an error is received.
+It is not called on
+<errorname>BadName</errorname>
+errors from
+<systemitem>OpenFont</systemitem>,
+<systemitem>LookupColor</systemitem>,
+or
+<systemitem>AllocNamedColor</systemitem>
+protocol requests or on
+<errorname>BadFont</errorname>
+errors from a
+<systemitem>QueryFont</systemitem>
+protocol request.
+These errors generally are reflected back to the program through the
+procedural interface.
+Because this condition is not assumed to be fatal, 
+it is acceptable for your error handler to return;
+the returned value is ignored.
+However, the error handler should not
+call any functions (directly or indirectly) on the display
+that will generate protocol requests or that will look for input events.
+The previous error handler is returned.
+</para>
+<para>
+<!-- .LP -->
+The 
+<structname>XErrorEvent</structname>
+structure contains:
+<indexterm><primary>Debugging</primary><secondary>error event</secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XErrorEvent</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+	int type;
+	Display *display;	/* Display the event was read from */
+	unsigned long serial;		/* serial number of failed request */
+	unsigned char error_code;	/* error code of failed request */
+	unsigned char request_code;	/* Major op-code of failed request */
+	unsigned char minor_code;	/* Minor op-code of failed request */
+	XID resourceid;		/* resource id */
+} XErrorEvent;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Serial Number</primary></indexterm>
+The serial member is the number of requests, starting from one, 
+sent over the network connection since it was opened. 
+It is the number that was the value of 
+<function>NextRequest</function>
+immediately before the failing call was made.  
+The request_code member is a protocol request
+of the procedure that failed, as defined in 
+&lt; X11/Xproto.h .&gt;
+The following error codes can be returned by the functions described in this
+chapter:
+</para>
+<!-- .br -->
+<!-- .ne 13 -->
+<indexterm><primary>Debugging</primary><secondary>error numbers</secondary></indexterm>
+<indexterm><primary>Error</primary><secondary>codes</secondary></indexterm>
+<!-- .\".CP T 3 -->
+<!-- .\"Error Codes -->
+<indexterm significance="preferred"><primary>BadAccess</primary></indexterm>
+<indexterm significance="preferred"><primary>BadAlloc</primary></indexterm>
+<indexterm significance="preferred"><primary>BadAtom</primary></indexterm>
+<indexterm significance="preferred"><primary>BadColor</primary></indexterm>
+<indexterm significance="preferred"><primary>BadCursor</primary></indexterm>
+<indexterm significance="preferred"><primary>BadDrawable</primary></indexterm>
+<indexterm significance="preferred"><primary>BadFont</primary></indexterm>
+<indexterm significance="preferred"><primary>BadGC</primary></indexterm>
+<indexterm significance="preferred"><primary>BadIDChoice</primary></indexterm>
+<informaltable>
+  <tgroup cols='2' align='center'>
+  <colspec colname='c1'/>
+  <colspec colname='c2'/>
+  <thead>
+    <row>
+      <entry>Error Code</entry>
+      <entry>Description</entry>
+    </row>
+  </thead>
+  <tbody>
+    <row>
+      <entry><errorname>BadAccess</errorname></entry>
+      <entry>A client attempts to grab a key/button combination already grabbed
+      by another client.</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>A client attempts to free a colormap entry that it had not already allocated
+      or to free an entry in a colormap that was created with all entries writable.</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>A client attempts to store into a read-only or unallocated colormap entry.</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>A client attempts to modify the access control list from other than the local
+      (or otherwise authorized) host.</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>A client attempts to select an event type that another client
+      has already selected.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadAlloc</errorname></entry>
+      <entry>The server fails to allocate the requested resource.
+      Note that the explicit listing of
+      <errorname>BadAlloc</errorname>
+      errors in requests only covers allocation errors at a very coarse level
+      and is not intended to (nor can it in practice hope to) cover all cases of
+      a server running out of allocation space in the middle of service.
+      The semantics when a server runs out of allocation space are left unspecified,
+      but a server may generate a
+      <errorname>BadAlloc</errorname>
+      error on any request for this reason,
+      and clients should be prepared to receive such errors and handle or discard
+      them.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadAtom</errorname></entry>
+      <entry>A value for an atom argument does not name a defined atom.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadColor</errorname></entry>
+      <entry>A value for a colormap argument does not name a defined colormap.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadCursor</errorname></entry>
+      <entry>A value for a cursor argument does not name a defined cursor.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadDrawable</errorname></entry>
+      <entry>A value for a drawable argument does not name a defined window or pixmap.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadFont</errorname></entry>
+      <entry>A value for a font argument does not name a defined font (or, in some cases,
+      <type>GContext</type>).</entry>
+    </row>
+    <row>
+      <entry><errorname>BadGC</errorname></entry>
+      <entry>A value for a
+      <type>GContext</type>
+      argument does not name a defined 
+      <type>GContext</type>.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadIDChoice</errorname></entry>
+      <entry>The value chosen for a resource identifier either is not included in the
+      range assigned to the client or is already in use.
+      Under normal circumstances,
+      this cannot occur and should be considered a server or Xlib error.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadImplementation</errorname></entry>
+      <entry>The server does not implement some aspect of the request.
+      A server that generates this error for a core request is deficient.
+      As such, this error is not listed for any of the requests,
+      but clients should be prepared to receive such errors
+      and handle or discard them.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadLength</errorname></entry>
+      <entry>The length of a request is shorter or longer than that required to
+      contain the arguments.
+      This is an internal Xlib or server error.</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>
+      The length of a request exceeds the maximum length accepted by the server.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadMatch</errorname></entry>
+      <entry>In a graphics request,
+      the root and depth of the graphics context do not match those of the drawable.</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>An <symbol>InputOnly</symbol> window is used as a drawable.</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>
+      Some argument or pair of arguments has the correct type and range,
+      but it fails to match in some other way required by the request.</entry>
+    </row>
+    <row>
+      <entry></entry>
+      <entry>An <symbol>InputOnly</symbol>
+      window lacks this attribute.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadName</errorname></entry>
+      <entry>A font or color of the specified name does not exist.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadPixmap</errorname></entry>
+      <entry>A value for a pixmap argument does not name a defined pixmap.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadRequest</errorname></entry>
+      <entry>The major or minor opcode does not specify a valid request.
+      This usually is an Xlib or server error.</entry>
+    </row>
+    <row>
+      <entry><errorname>BadValue</errorname></entry>
+      <entry>Some numeric value falls outside of the range of values accepted
+      by the request.
+      Unless a specific range is specified for an argument,
+      the full range defined by the argument's type is accepted.
+      Any argument defined as a set of alternatives typically can generate
+      this error (due to the encoding).</entry>
+    </row>
+    <row>
+      <entry><errorname>BadWindow</errorname></entry>
+      <entry>A value for a window argument does not name a defined window.</entry>
+    </row>
+  </tbody>
+  </tgroup>
+</informaltable>
+
+<indexterm significance="preferred"><primary>BadImplementation</primary></indexterm>
+<indexterm significance="preferred"><primary>BadLength</primary></indexterm>
+<indexterm significance="preferred"><primary>BadMatch</primary></indexterm>
+<indexterm significance="preferred"><primary>BadName</primary></indexterm>
+<indexterm significance="preferred"><primary>BadPixmap</primary></indexterm>
+<indexterm significance="preferred"><primary>BadRequest</primary></indexterm>
+<indexterm significance="preferred"><primary>BadValue</primary></indexterm>
+<indexterm significance="preferred"><primary>BadWindow</primary></indexterm>
+<!-- .NT Note -->
+
+<note>
+<para>
+The 
+<errorname>BadAtom</errorname>,
+<errorname>BadColor</errorname>,
+<errorname>BadCursor</errorname>,
+<errorname>BadDrawable</errorname>,
+<errorname>BadFont</errorname>,
+<errorname>BadGC</errorname>,
+<errorname>BadPixmap</errorname>,
+and 
+<errorname>BadWindow</errorname>
+errors are also used when the argument type is extended by a set of
+fixed alternatives.
+</para>
+</note>
+
+<!-- .NE -->
+<!-- .sp -->
+<para>
+<!-- .LP -->
+To obtain textual descriptions of the specified error code, use 
+<function>XGetErrorText</function>.
+<indexterm significance="preferred"><primary>XGetErrorText</primary></indexterm>
+<indexterm><primary>Debugging</primary><secondary>error message strings</secondary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgeterrortext'>
+<funcprototype>
+  <funcdef><function>XGetErrorText</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>int<parameter> code</parameter></paramdef>
+  <paramdef>char<parameter> *buffer_return</parameter></paramdef>
+  <paramdef>int<parameter> length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>code</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the error code for which you want to obtain a description.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>buffer_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the error description.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>length</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the size of the buffer.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM  -->
+The
+<function>XGetErrorText</function>
+function copies a null-terminated string describing the specified error code
+into the specified buffer.
+The returned text is in the encoding of the current locale.
+It is recommended that you use this function to obtain an error description
+because extensions to Xlib may define their own error codes
+and error strings.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain error messages from the error database, use
+<function>XGetErrorDatabaseText</function>.
+<indexterm significance="preferred"><primary>XGetErrorDatabaseText</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xgeterrordatabasetext'>
+<funcprototype>
+  <funcdef><function>XGetErrorDatabaseText</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char*name,<parameter> *message</parameter></paramdef>
+  <paramdef>char<parameter> *default_string</parameter></paramdef>
+  <paramdef>char<parameter> *buffer_return</parameter></paramdef>
+  <paramdef>int<parameter> length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the name of the application.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>message</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the type of the error message.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>default_string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the default error message if none is found in the database.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>buffer_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the error description.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>length</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the size of the buffer.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetErrorDatabaseText</function>
+function returns a null-terminated message
+(or the default message) from the error message
+database.
+Xlib uses this function internally to look up its error messages.
+The text in the default_string argument is assumed
+to be in the encoding of the current locale,
+and the text stored in the buffer_return argument
+is in the encoding of the current locale.
+</para>
+<para>
+<!-- .LP -->
+The name argument should generally be the name of your application.
+The message argument should indicate which type of error message you want.
+If the name and message are not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Xlib uses three predefined ``application names'' to report errors.
+In these names,
+uppercase and lowercase matter.
+<variablelist>
+  <varlistentry>
+    <term>
+      XProtoError
+    </term>
+    <listitem>
+      <para>
+The protocol error number is used as a string for the message argument.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      XlibMessage
+    </term>
+    <listitem>
+      <para>
+These are the message strings that are used internally by the library.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      XRequest
+    </term>
+    <listitem>
+      <para>
+For a core protocol request,
+the major request protocol number is used for the message argument.
+For an extension request,
+the extension name (as given by
+<function>InitExtension</function>)
+followed by a period (.) and the minor request protocol number 
+is used for the message argument.
+If no string is found in the error database,
+the default_string is returned to the buffer argument.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To report an error to the user when the requested display does not exist, use
+<function>XDisplayName</function>.
+<indexterm significance="preferred"><primary>XDisplayName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xdisplayname'>
+<funcprototype>
+  <funcdef>char *<function>XDisplayName</function></funcdef>
+  <paramdef>char<parameter> *string</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>string</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the character string.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDisplayName</function>
+function returns the name of the display that 
+<function>XOpenDisplay</function>
+would attempt to use.
+If a NULL string is specified,
+<function>XDisplayName</function>
+looks in the environment for the display and returns the display name that
+<function>XOpenDisplay</function>
+would attempt to use.
+This makes it easier to report to the user precisely which display the
+program attempted to open when the initial connection attempt failed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To handle fatal I/O errors, use
+<function>XSetIOErrorHandler</function>.
+<indexterm significance="preferred"><primary>XSetIOErrorHandler</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xsetioerrorhandler'>
+<funcprototype>
+  <funcdef><type>int</type></funcdef>
+  <paramdef>int(*handler)(Display<parameter> *)</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>handler</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the program's supplied error handler.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetIOErrorHandler</function>
+sets the fatal I/O error handler.
+Xlib calls the program's supplied error handler if any sort of system call
+error occurs (for example, the connection to the server was lost).
+This is assumed to be a fatal condition,
+and the called routine should not return.
+If the I/O error handler does return,
+the client process exits.
+</para>
+<para>
+<!-- .LP -->
+Note that the previous error handler is returned.
+<!-- .bp -->
+
+</para>
+</sect2>
+</sect1>
+</chapter>