doc: add recordlib converted docbook xml

Signed-off-by: Gaetan Nadon <memsize@videotron.ca>

2 files changed, 1517 insertions, 1 deletions

diff --git a/specs/Makefile.am b/specs/Makefile.am
index 8ba5590..fdaba22 100644
--- a/specs/Makefile.am
+++ b/specs/Makefile.am
@@ -22,7 +22,7 @@
 #
 
 if ENABLE_SPECS
-doc_sources = xtestlib.xml
+doc_sources = xtestlib.xml recordlib.xml
 dist_doc_DATA = $(doc_sources)
 
 if HAVE_XMLTO
diff --git a/specs/recordlib.xml b/specs/recordlib.xml
new file mode 100644
index 0000000..903f02a
--- /dev/null
+++ b/specs/recordlib.xml
@@ -0,0 +1,1516 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+
+
+<!-- lifted from troff+ms+XMan by doclifter -->
+<book id="recordlib">
+
+<bookinfo>
+   <title>X Record Extension Library</title>
+   <subtitle>X Consortium Standard</subtitle>
+   <releaseinfo>X Version 11, Release 6.7</releaseinfo>
+   <authorgroup>
+      <author>
+         <firstname>Martha</firstname><surname>Zimet</surname>
+      </author>
+   </authorgroup>
+   <corpname>Network Computing Devices, Inc.</corpname>
+   <copyright><year>1994</year><holder>Network Computing Devices, Inc.</holder></copyright>
+   <copyright><year>1995</year><holder>X Consortium</holder></copyright>
+   <releaseinfo>Version 1.13</releaseinfo>
+   <affiliation><orgname>X Consortium</orgname></affiliation>
+   <productnumber>X Version 11, Release 6.7</productnumber>
+   <editor>
+         <firstname>Stephen</firstname><surname>Gildea</surname>
+         <affiliation><orgname>X Consortium</orgname></affiliation>
+   </editor>
+
+<legalnotice>
+
+<para>
+Permission to use, copy, modify, distribute, and sell this
+documentation for any purpose is hereby granted without fee,
+provided that the above copyright notice and this permission
+notice appear in all copies.  Network Computing Devices, Inc.
+makes no representations about the suitability for any purpose
+of the information in this document.  This documentation is
+provided "as is" without express or implied warranty.
+</para>
+
+<para>
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files
+(the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy,
+modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+</para>
+
+<para>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+</para>
+
+<para>
+Except as contained in this notice, the name of the X Consortium shall
+not be used in advertising or otherwise to promote the sale, use or other
+dealings in this Software without prior written authorization from the
+X Consortium.
+</para>
+
+<para>X Window System is a trademark of The Open Group.</para>
+</legalnotice>
+</bookinfo>
+
+<chapter id="record_extension_overview">
+<title>Record Extension Overview</title>
+<para>
+The purpose of this extension is to support the recording and reporting of
+all core X protocol and arbitrary X extension protocol. This first section
+gives an overview of the Record extension. The following sections describe
+how to use the Record extension library.
+</para>
+
+<sect1 id="synchronous_playback">
+<title>Synchronous Playback</title>
+<para>
+Environment information is generally provided to an X-based playback
+mechanism, which might use the XTest extension to synthesize input
+events. This synchronization information defines the X state prior to
+event synthesis (for example, location of the cursor, window locations
+and sizes, installed colormap, window manager running, and so on) and
+the consequences that occur after the playback mechanism synthesizes
+the event. If the user moves the mouse into the icon window and presses
+and releases a mouse button, the device events
+<function>MotionNotify</function>, <function>ButtonPress</function>,
+and <function>ButtonRelease</function> are generated by the X server.
+Because X follows an
+event-driven model, there are consequences that follow from the user
+actions, or device events, that are in the form of X protocol. As a result
+of the previous user actions, the client could generate requests such as
+<function>ImageText8</function> and <function>PolyLine</function> to the
+X server, or the X server could send non-device events such as
+<function>Expose</function> and <function>MapNotify</function> to the
+client window. Both the
+requests and non-device events that result from user actions are known
+as consequences, which can be used as a synchronization, or control point,
+during playback. That is, the playback mechanism does not generate a specific
+synthesized event until its matching synchronization condition occurs
+(for example, the window is mapped or unmapped, the cursor changes, a text
+string displays, and so on)
+</para>
+<para>
+Because it cannot be predicted what synchronization information is required
+during playback, the Record extension makes no assumptions about the intended
+use of the recorded data. Facilities exist to record any core X protocol or
+X extension protocol. Therefore, Record does not enforce a specific
+synchronization methodology.
+</para>
+</sect1>
+
+<sect1 id="design_approach">
+<title>Design Approach</title>
+<para>
+The design approach of the extension is to record core X protocol and
+arbitrary X extension protocol entirely within the X server itself. When
+the extension has been requested to record specific protocol by one or more
+recording clients, the protocol data is formatted and returned to the
+recording clients. The extension provides a mechanism for capturing all
+events, including input device events that do not go to any clients.
+</para>
+</sect1>
+
+<sect1 id="record_clients">
+<title>Record Clients</title>
+<para>
+The recommended communication model for a Record application is to open two
+connections to the server—one connection for recording control and one
+connection for reading recorded protocol data.
+</para>
+<para>
+Information about recording (for example, what clients to record, what
+protocol to record for each client, and so on) is stored in resources
+called record contexts (type <function>XRecordContext</function>). Most
+Record extension functions take a record context as an argument. Although
+in theory it is possible to share record contexts between applications,
+it is expected that applications will use their own context when performing
+recording operations.
+</para>
+<para>
+A client that wishes to record X protocol does so through the library
+functions defined in
+<link linkend="library_extension_requests">
+<xref linkend="library_extension_requests"></xref></link>
+A typical sequence of requests that a client would make is as follows:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+<function>XRecordQueryVersion</function>
+    </para>
+    <para>
+query the extension protocol version.
+    </para>
+</listitem>
+<listitem>
+    <para>
+<function>XRecordCreateContext</function>
+    </para>
+    <para>
+request that the server create a record context for access by this client,
+and express interest in clients and protocol to be recorded. This request
+returns an <function>XRecord-Context</function>, which is an XID that is
+used by most other extension requests to identify the specified context.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XRecordEnableContext</function>
+    </para>
+    <para>
+begin the recording and reporting of protocol data.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XRecordDisableContext</function>
+    </para>
+    <para>
+end the recording and reporting of protocol data.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<function>XRecordFreeContext</function>
+    </para>
+    <para>
+free the record context.
+    </para>
+  </listitem>
+</itemizedlist>
+
+<para>
+The header for this library is
+&lt;<function>X11/extensions/record.h</function>&gt;. All identifiers defined
+in the interface are supplied by this header and are prefixed with "XRecord".
+The <function>Xtst</function> library contains the
+<function>XRecord</function> functions.
+</para>
+
+</sect1>
+</chapter>
+
+<chapter id="common_arguments">
+<title>Common Arguments</title>
+<para>
+The Record extension functions <function>XRecordCreateContext</function>
+ and <function>XRecordRegisterClients</function> allow applications to
+specify the following:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Individual clients or sets of clients to record
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Ranges of core X protocol and X extension protocol to record for each client
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+Protocol in the ranges specified by the recording client will be recorded
+by the server. The device_events protocol type can be specified by a
+recording client although it may not be sent to a recorded client. The
+device_events type differs from delivered_events, which also can be
+specified by a recording client; delivered_events are actually delivered to
+one or more clients. These event types are discussed in
+<link linkend="protocol_ranges">
+<xref linkend="protocol_ranges"></xref></link>
+</para>
+
+
+<para>
+The Record extension functions <function>XRecordCreateContext</function>
+ and <function>XRecordRegisterClients</function> have the common arguments
+datum_flags, clients, and ranges, which specify whether server time
+and/or client sequence number should precede protocol elements, the
+clients or client set to record, and the protocol ranges to record,
+respectively. These are discussed in the following sections.
+</para>
+
+<sect1 id="datum_flags">
+<title>Datum Flags</title>
+<para>
+The datum_flags argument is a set of flags OR’ed together to specify options
+for the record context.  Specify zero to disable all the options.
+</para>
+
+<para>
+The <function>XRecordFromServerTime</function> flag specifies that
+<function>XRecordInterceptData</function> structures with a category of
+<function>XRecordFromServer</function> will have a server_time field specific to each
+protocol element.
+</para>
+
+<para>
+The <function>XRecordFromClientTime</function> flag specifies that
+<function>XRecordInterceptData</function> structures with a category of
+<function>XRecordFromClient</function> will have a server_time field specific
+to each protocol element.
+</para>
+
+<para>
+The <function>XRecordFromClientSequence</function> flag specifies that
+<function>XRecordInterceptData</function> structures with a category of
+<function>XRecordFromClient</function> or
+<function>XRecordClientDied</function> will have a valid client_seq field.
+</para>
+</sect1>
+
+<sect1 id="selecting_clients">
+<title>Selecting Clients</title>
+
+<para>
+The clients argument is a pointer to an array of
+<function>XRecordClientSpec</function>.
+<function>XRecordClientSpec</function> is an integral type that holds a
+resource ID, a client resource ID base, or one of the client set constants
+defined below.
+</para>
+<para>
+Duplicate elements in the array are ignored by the functions, and if any
+element in the array is not valid, a
+<function>BadMatch</function>
+error results. A resource ID references the client that created that
+resource. The client set may be one of the following constants:
+<function>XRecordCurrentClients</function>,
+<function>XRecordFutureClients</function>, or
+<function>XRecordAllClients</function>.
+</para>
+<para>
+If the element in the array identifies a particular client, protocol
+specified by the ranges argument will be recorded by the server. The
+recorded protocol data will not be returned to the recording client until
+the record context has been enabled. This is described in
+<link linkend="data_transfer">
+<xref linkend="data_transfer"></xref></link>
+</para>
+<para>
+If the element is <function>XRecordCurrentClients</function>, the protocol
+ranges specified by the ranges argument, except for device_events, are
+associated with each current client connection. If the element is
+<function>XRecordFutureClients</function>, the
+protocol ranges specified by the ranges argument are associated with each new
+client connection. If the element is
+<function>XRecordAllClients</function>,
+the protocol ranges specified by the ranges argument are associated with
+each current client connection and with each new client connection.
+When the context is enabled, the data connection is unregistered if it
+was registered. If the context is enabled,
+<function>XRecordCurrentClients</function> and
+<function>XRecordAllClients</function>
+silently exclude the recording data connection. It is an error to explicitly
+register the data connection.
+</para>
+</sect1>
+<sect1 id="protocol_ranges">
+<title>Protocol Ranges</title>
+
+<para>
+The functions <function>XRecordCreateContext</function> and
+<function>XRecordRegisterClients</function> have another common argument,
+ranges, which is an array of pointers to <function>XRecordRange</function>
+structures. Each structure contains ranges of numeric values for each of
+the protocol types that can be specified and recorded individually by the
+Record extension. An <function>XRecordRange</function> structure must be
+allocated by the Record library using the
+<function>XRecordAllocRange</function> function.
+</para>
+<para>
+The <function>XRecordRange</function> typedef is a structure with the
+following members:
+</para>
+
+<literallayout remap='Ds'>
+XRecordRange:
+     XRecordRange8 core_requests     /* core X requests */
+     XRecordRange8 core_replies      /* core X replies */
+     XRecordExtRange ext_requests    /* extension requests */
+     XRecordExtRange ext_replies     /* extension replies */
+     XRecordRange8 delivered_events  /* delivered core and ext events */
+     XRecordRange8 device_events     /* all core and ext device events */
+     XRecordRange8 errors            /* core X and X ext errors */
+     Bool client_started             /* connection setup reply from server */
+     Bool client_died                /* notification of client disconnect */
+</literallayout>
+
+<para>
+The types used in
+<function>XRecordRange</function>
+members are defined as follows.  The
+<function>XRecordRange8</function>
+typedef is a structure with the following members:
+</para>
+
+<literallayout remap='Ds'>
+XRecordRange8:
+     unsigned char first
+     unsigned char last
+</literallayout>
+
+<para>
+The
+<function>XRecordRange16</function>
+typedef is a structure with the following members:
+</para>
+
+<literallayout remap='Ds'>
+XRecordRange16:
+     unsigned short first
+     unsigned short last
+</literallayout>
+
+<para>
+The
+<function>XRecordExtRange</function>
+typedef is a structure with the following members:
+</para>
+
+<literallayout remap='Ds'>
+XRecordExtRange:
+     XRecordRange8  ext_major
+     XRecordRange16 ext_minor
+</literallayout>
+
+<para>
+If any of the values specified in
+<function>XRecordRange</function>
+is invalid, a
+<function>BadValue</function>
+error results.
+</para>
+
+<para>
+The core_requests member specifies the range of core X protocol
+requests to record.  Core X protocol requests with a major opcode
+that is between first and last, inclusive, will be
+recorded.  A
+<function>BadValue</function>
+error results if the value of first is greater than the value of last.
+If the values of both first and last are zero, no core
+X protocol requests will be recorded.
+</para>
+
+<para>
+The core_replies member specifies the range of replies resulting
+from core X protocol requests to record.  Replies that result from
+core X protocol requests with a major opcode between first
+and last, inclusive, will be recorded.  A
+<function>BadValue</function>
+error results if the value of first is greater than the value of last.
+If the values of both first and last are zero, no core X protocol
+replies will be recorded.
+</para>
+
+<para>
+The ext_requests member specifies the range of X extension
+requests to record.  X extension requests with a major opcode
+between ext_major.first and ext_major.last, and with a
+minor opcode
+between ext_minor.first and ext_minor.last, inclusive, will be
+recorded.  A
+<function>BadValue</function>
+error results
+if the value of ext_major.first is greater than the value of
+ext_major.last or if the value of ext_minor.first is
+greater than the value of ext_minor.last.  If the values of both
+ext_major.first
+and ext_major.last are zero,
+no X extension requests will be recorded.
+</para>
+
+<para>
+The ext_replies member specifies the range of replies resulting
+from X extension requests to record.  Replies that result from an X
+extension request with a major opcode between
+ext_major.first and
+ext_major.last, and a minor opcode that is between
+ext_minor.first and ext_minor.last will be recorded.  A
+<function>BadValue</function>
+error results
+if the value of ext_major.first is greater than the value of
+ext_major.last or if the value of ext_minor.first is greater than
+the value of ext_minor.last.  If the values of both
+ext_major.first and ext_major.last are zero, no X extension
+replies will be recorded.
+</para>
+
+<para>
+The delivered_events member specifies the range of both core
+X events and X extension events to record.  These events are
+delivered to at least one client.  Core X events and X extension events
+with a code value between first and last inclusive will be recorded.  A
+<function>BadValue</function>
+error results if the value of first is greater than the value of last.
+If the values of first and last are zero, no events will be recorded.
+</para>
+
+<para>
+The device_events member specifies the range of both core X device
+events and X extension device events to record.  These events may or
+may not be delivered to a client.  Core X device events and X extension
+device events with a code value between first and last inclusive that
+are not delivered to any clients will be recorded.  A
+<function>BadValue</function>
+error results if the value of first is greater than the value of last.  A
+<function>BadValue</function>
+error results if first is less than two or last is less than two, except
+that if first and last are zero, no events will be recorded.
+</para>
+
+<para>
+The errors member specifies the range of both core X errors and X
+extension errors to record.  Core X errors and X extension errors with
+a code value between first and last inclusive will be
+recorded.  A
+<function>BadValue</function>
+error results if the value of first is greater than the value of last.
+If the values of first and last are zero, no errors will be recorded.
+</para>
+
+<para>
+A value of
+<function>True</function>
+for the client_started member specifies the
+connection setup reply from the server to new clients.  If
+<function>False</function>
+the connection setup reply is not specified by this
+<function>XRecordRange</function>
+</para>
+
+<para>
+A value of
+<function>True</function>
+for the client_died member specifies
+notification when a client disconnects.  If
+<function>False</function>
+notification when a client disconnects is not specified by this
+<function>XRecordRange</function>
+</para>
+</sect1>
+</chapter>
+
+<chapter id='library_extension_requests'>
+<title>Library Extension Requests</title>
+
+<para>
+Recording operations are accessed by programs through the use of
+new protocol requests.  The following functions are provided as extensions
+to Xlib.  An Xlib error results if
+an extension request is made to an X server that does not support the
+Record extension.  Note that any of the extension protocol requests may generate
+<function>BadAlloc</function>
+or
+<function>BadLength</function>
+errors.
+</para>
+
+<sect1 id='query_extension_version'>
+<title>Query Extension Version</title>
+
+<para>
+An application uses the
+<function>XRecordQueryVersion</function>
+function to determine
+the version of the Record extension protocol supported by an X server.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>XRecordQueryVersion</function></funcdef>
+    <paramdef>Display <parameter> *display</parameter></paramdef>
+    <paramdef>int <parameter> cmajor_return</parameter></paramdef>
+    <paramdef>int <parameter> cminor_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>display</emphasis></term>
+    <listitem><para>Returns the connection to the X server.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>cmajor_return</emphasis></term>
+    <listitem><para>Returns the extension protocol major version in use.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>cminor_return</emphasis></term>
+    <listitem><para>Returns the extension protocol minor version in use.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+The
+<function>XRecordQueryVersion</function>
+function returns the major and minor protocol version numbers supported by
+the server.
+<function>XRecordQueryVersion</function>
+returns nonzero (success) only if the returned version numbers are
+common to both the library and the server; otherwise, it returns zero.
+</para>
+</sect1>
+
+<sect1 id='create_and_modify_context'>
+<title>Create and Modify Context</title>
+
+<para>
+An application uses the
+<function>XRecordCreateContext</function>
+function to create a record context.  At the time the record context is
+created by the recording client, the clients to be recorded and the
+protocol to record for each client may be specified.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>XRecordContext <function>XRecordCreateContext</function></funcdef>
+    <paramdef>Display <parameter> *display</parameter></paramdef>
+    <paramdef>int <parameter> datum_flags</parameter></paramdef>
+    <paramdef>XRecordClientSpec <parameter> *clients</parameter></paramdef>
+    <paramdef>int <parameter> nclients</parameter></paramdef>
+    <paramdef>XRecordRange <parameter> *ranges</parameter></paramdef>
+    <paramdef>int <parameter> nranges</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>display</emphasis></term>
+    <listitem><para>Returns the connection to the X server.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>datum_flags</emphasis></term>
+    <listitem><para>Specifies whether detailed time or sequence info should be sent.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>clients</emphasis></term>
+    <listitem><para>Specifies the clients to record.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>nclients</emphasis></term>
+    <listitem><para>Specifies the number of clients.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>ranges</emphasis></term>
+    <listitem><para>Specifies the protocol ranges to record.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>nranges</emphasis></term>
+    <listitem><para>Specifies the number of protocol ranges.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+The
+<function>XRecordCreateContext</function>
+function creates a record context and returns an
+<function>XRecordContext</function>
+which is then used in the other Record library calls.  This request is
+typically executed by the recording client over its control connection to
+the X server.  The datum_flags specifies whether server time and/or client
+sequence number should precede protocol elements recorded by context (
+<link linkend="datum_flags">
+<xref linkend="datum_flags"></xref></link>
+).  When a clients element identifies a particular client, the client is added
+to the context and the protocol to record for that client is set to the
+union of all ranges.  When a clients element is
+<function>XRecordCurrentClients</function>
+<function>XRecordFutureClients</function>
+or
+<function>XRecordAllClients</function>
+the actions described in
+<link linkend="selecting_clients">
+<xref linkend="selecting_clients"></xref></link>
+are performed.
+</para>
+
+<para>
+<function>XRecordCreateContext</function>
+returns zero if the request failed.
+<function>XRecordCreateContext</function>
+can generate
+<function>BadIDChoice</function>
+<function>BadMatch</function>
+and
+<function>BadValue</function>
+errors.
+</para>
+
+<para>The ranges argument is an
+<function>XRecordRange</function>
+array, that is, an array
+of pointers.  The structures the elements point to shall be allocated
+by calling
+<function>XRecordAllocRange</function></para>
+
+<literallayout remap='FD'>
+XRecordRange *
+XRecordAllocRange(void)
+</literallayout> <!-- remap='FN' -->
+
+<para>
+The
+<function>XRecordAllocRange</function>
+function
+allocates and returns an
+<function>XRecordRange</function>
+structure.
+The structure is initialized to specify no protocol.
+The function returns NULL if the structure allocation fails.
+The application can free the structure by calling
+<function>XFree</function>
+</para>
+
+<sect2 id='additions'>
+<title>Additions</title>
+
+<para>
+An application uses the
+<function>XRecordRegisterClients</function>
+function to modify a previously created
+record context, by adding clients or modifying the recorded protocol,
+typically over its control connection to the X server.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>XRecordRegisterClients</function></funcdef>
+    <paramdef>Display <parameter> *display</parameter></paramdef>
+    <paramdef>XRecordContext <parameter> context</parameter></paramdef>
+    <paramdef>int <parameter> datum_flags</parameter></paramdef>
+    <paramdef>XRecordClientSpec <parameter> *clients</parameter></paramdef>
+    <paramdef>int <parameter> nclients</parameter></paramdef>
+    <paramdef>XRecordRange <parameter> *ranges</parameter></paramdef>
+    <paramdef>int <parameter> nranges</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>display</emphasis></term>
+    <listitem><para>Returns the connection to the X server.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>context</emphasis></term>
+    <listitem><para>Specifies the record context to modify.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>datum_flags</emphasis></term>
+    <listitem><para>Specifies whether detailed time or sequence info should be sent.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>clients</emphasis></term>
+    <listitem><para>Specifies the clients to record.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>nclients</emphasis></term>
+    <listitem><para>Specifies the number of clients.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>ranges</emphasis></term>
+    <listitem><para>Specifies the protocol ranges to record.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>nranges</emphasis></term>
+    <listitem><para>Specifies the number of protocol ranges.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+The datum_flags specifies whether server time and/or client sequence number
+should precede protocol elements for all clients recorded by context (See
+<link linkend="datum_flags">
+<xref linkend="datum_flags"></xref></link>
+).  When a clients element identifies a particular client and the client is
+not yet targeted for recording in the given context, the client is added
+to the set of clients to record, and the protocol to record for that client
+is set to the union of all ranges.  When the client is
+already targeted for recording, the protocol to record for that client
+is set to the union of all ranges.  When the element is
+<function>XRecordCurrentClients</function>
+<function>XRecordFutureClients</function>
+or
+<function>XRecordAllClients</function>
+the actions described in
+<link linkend="selecting_clients">
+<xref linkend="selecting_clients"></xref></link>
+are performed.
+</para>
+
+<para>
+<function>XRecordRegisterClients</function>
+returns zero if the request failed; otherwise, it
+returns nonzero.
+</para>
+
+<para>
+<function>XRecordRegisterClients</function>
+can generate
+<function>XRecordBadContext</function>
+<function>BadMatch</function>
+and
+<function>BadValue</function>
+errors.
+</para>
+</sect2>
+
+<sect2 id='deletions'>
+<title>Deletions</title>
+
+<para>
+An application uses the
+<function>XRecordUnregisterClients</function>
+function to delete clients from a previously created
+record context, typically over its control connection to the X server.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>XRecordUnRegisterClients</function></funcdef>
+    <paramdef>Display <parameter> *display</parameter></paramdef>
+    <paramdef>XRecordContext <parameter> context</parameter></paramdef>
+    <paramdef>XRecordClientSpec <parameter> *clients</parameter></paramdef>
+    <paramdef>int <parameter> nclients</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>display</emphasis></term>
+    <listitem><para>Returns the connection to the X server.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>context</emphasis></term>
+    <listitem><para>Specifies the record context to modify.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>clients</emphasis></term>
+    <listitem><para>Specifies the clients to stop recording.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>nclients</emphasis></term>
+    <listitem><para>Specifies the number of clients.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+When an element in clients identifies a particular client, and the
+specified client is already targeted for recording in the given
+context, the client and the set of protocol to record for that
+client are deleted from the context.  If the specified client is not
+targeted for recording, then no action is performed.
+</para>
+
+<para>
+When the element is
+<function>XRecordCurrentClients</function>
+all clients currently targeted for recording in context and their
+corresponding sets of protocol to record are deleted from context.
+</para>
+
+<para>
+When the item is
+<function>XRecordFutureClients</function>
+any future client connections will not automatically be targeted for
+recording in context.
+</para>
+
+<para>
+When the element is
+<function>XRecordAllClients</function>
+all clients currently targeted for recording in context and their
+corresponding sets of protocol to record are deleted from context.
+Any future client connections will not automatically be targeted
+for recording in context.
+</para>
+
+<para>
+<function>XRecordUnregisterClients</function>
+returns zero if the request failed; otherwise, it returns nonzero.
+</para>
+
+<para>
+<function>XRecordUnregisterClients</function>
+can generate
+<function>XRecordBadContext</function>
+<function>BadMatch</function>
+and
+<function>BadValue</function>
+errors.</para>
+</sect2>
+</sect1>
+
+<sect1 id='query_context_state'>
+<title>Query Context State</title>
+
+<para>
+An application uses the
+<function>XRecordGetContext</function>
+function to query the current state of a record context, typically over
+its control connection to the X server.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>XRecordGetContext</function></funcdef>
+    <paramdef>Display <parameter> *display</parameter></paramdef>
+    <paramdef>XRecordContext <parameter> context</parameter></paramdef>
+    <paramdef>XRecordState <parameter> **state_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <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'>context</emphasis></term>
+    <listitem><para>Specifies the record context to query.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>state_return</emphasis></term>
+    <listitem><para>Specifies the address of a variable into which
+the function stores a pointer to the current state of the record context.
+    </para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+The
+<function>XRecordState</function>
+typedef returned by
+<function>XRecordGetContext</function>
+is a structure with the following members:
+</para>
+
+<literallayout remap='Ds'>
+XRecordState:
+     Bool              enabled
+     int               datum_flags
+     unsigned long     nclients
+     XRecordClientInfo **client_info
+</literallayout>
+
+<para>
+The enabled member is set to the state of data transfer and is
+<function>True</function>
+when the recording client has asked that recorded data be sent;
+otherwise it is
+<function>False</function>
+The datum_flags member is set to the value of these flags for this context.
+The nclients member is set to the number of
+<function>XRecordClientInfo</function>
+structures returned.  The client_info member is an array of pointers to
+<function>XRecordClientInfo</function>
+structures that contain the protocol to record for each targeted client.  The
+<function>XRecordClientInfo</function>
+typedef is a structure with the following members:
+</para>
+
+<literallayout remap='Ds'>
+XRecordClientInfo:
+     XRecordClientSpec client
+     unsigned long nranges
+     XRecordRange **ranges
+</literallayout>
+
+<para>
+The client member either identifies a client targeted for recording
+or is set to
+<function>XRecordFutureClients</function>
+to describe how future clients will be automatically targeted for recording.
+The nranges member is set to the number of protocol
+ranges to be recorded for the specified client.  The ranges member
+is an array of pointers to
+<function>XRecordRange</function>
+structures, which specify the protocol ranges to record.
+</para>
+
+<para>
+<function>XRecordGetContext</function>
+returns zero if the request failed; otherwise, it returns nonzero.
+The context argument must specify a valid
+<function>XRecordContext</function>
+or a
+<function>XRecordBadContext</function>
+error results.
+</para>
+
+<para>
+Recording clients should use the
+<function>XRecordFreeState</function>
+function to free the state data returned by
+<function>XRecordGetContext</function>
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void <function>XRecordFreeState</function></funcdef>
+    <paramdef>XRecordState <parameter> *state</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>state</emphasis></term>
+    <listitem><para>Specifies the structure that is to be freed.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<function>XRecordFreeState</function>
+frees the data pointed to by state.  If the argument does not match an
+<function>XRecordState</function>
+pointer returned from a successful call to
+<function>XRecordGetContext</function>
+or if
+<function>XRecordFreeState</function>
+has already been called with it, the behavior is undefined.
+</para>
+</sect1>
+
+<sect1 id='data_transfer'>
+<title>Data Transfer</title>
+
+<para>
+An application uses the
+<function>XRecordEnableContext</function>
+and
+<function>XRecordDisableContext</function>
+functions to change the state of data transfer
+between the X server and the recording client.  These functions allow
+the application to start recording and reporting of protocol data
+and to stop recording and reporting of protocol data, respectively.
+</para>
+
+<sect2 id='enable_context'>
+<title>Enable Context</title>
+
+<para>
+To direct the X server to record and report protocol, a program uses
+<function>XRecordEnableContext</function>
+typically over its data connection to the X
+server.  The reporting of recorded protocol back to the recording client
+is handled by the following data structures and procedure definitions.
+Each recorded protocol element is reported to the recording client through an
+<function>XRecordInterceptData</function>
+typedef, a structure with the following members:
+</para>
+
+<literallayout remap='Ds'>
+XRecordInterceptData:
+     XID              id_base
+     Time             server_time
+     unsigned long    client_seq
+     int              category
+     Bool             client_swapped
+     unsigned char    *data
+     unsigned long    data_len
+</literallayout>
+
+<para>
+The id_base member is set to the resource identifier base sent to the
+client in the connection setup reply and therefore identifies the client
+being recorded, except when the recorded protocol data is a device
+event that may have not been delivered to a client.  In this case,
+id_base is set to zero.  The server_time member
+is set to the time of the server when the protocol was recorded.
+It is the time that was attached to this protocol element in the reply,
+if so specified by datum_flags,
+or else the time from the header of the reply that contained
+this protocol element.
+The client_seq member is the sequence number of the recorded
+client's most recent request processed by the server at the time this
+protocol element was recorded, if this information were included in the
+recorded data; otherwise client_seq is 0.
+The category member is set to one of the following values:
+<function>XRecordStartOfData</function>
+<function>XRecordFromServer</function>
+<function>XRecordFromClient</function>
+<function>XRecordClientStarted</function>
+<function>XRecordClientDied</function>
+or
+<function>XRecordEndOfData</function>
+<function>XRecordStartOfData</function>
+is immediately sent as the first reply to confirm that the context is enabled.
+<function>XRecordFromClient</function>
+indicates the protocol
+data is from the recorded client to the server (requests).
+<function>XRecordFromServer</function>
+indicates the protocol data is from the server to the recorded client
+(replies, errors, events, or device events).
+<function>XRecordClientStarted</function>
+indicates that the protocol data is the connection setup reply from the server.
+<function>XRecordClientDied</function>
+indicates that the recorded client has closed its connection
+to the X server; there is no protocol data.
+<function>XRecordEndOfData</function>
+indicates that the context has been disabled and that
+this is the last datum.  It does not correspond to any protocol or
+state change in a recorded client.  There is no protocol data.
+</para>
+
+<para>
+The client_swapped member is set to
+<function>True</function>
+if the byte order of the client being recorded is swapped relative to
+the recording client; otherwise, it is set to
+<function>False</function>
+All recorded protocol data is returned in the byte order of the recorded
+client.  Therefore, recording clients are responsible for all byte swapping,
+if required.  Device events are in the byte order of the recording client.
+For replies of category
+<function>XRecordStartOfData</function>
+and
+<function>XRecordEndOfData</function>
+client_swapped is set according
+to the byte order of the server relative to the recording client.
+</para>
+
+<para>
+The data member contains the actual recorded protocol data.
+When category is set to
+<function>XRecordStartOfData</function>
+<function>XRecordClientDied</function>
+or
+<function>XRecordEndOfData</function>
+no protocol data are contained in data.
+</para>
+
+
+<!--  copied exactly from the protocol document -->
+<para>
+For the core X events
+<function>KeyPress</function>
+<function>KeyRelease</function>
+<function>ButtonPress</function>
+and
+<function>ButtonRelease</function>,
+the fields of a device event that contain
+valid information are time and detail.  For the core X event
+<function>MotionNotify</function>
+the fields of a device event that contain valid information are time, root,
+root-x and root-y.
+The time field refers to the time the event was generated by the device.
+</para>
+
+<para>For the extension input device events
+<function>DeviceKeyPress</function>
+<function>DeviceKeyRelease</function>
+<function>DeviceButtonPress</function>
+and
+<function>DeviceButtonRelease</function>
+the fields of a device event that contain valid information are
+device, time, and detail.  For
+<function>DeviceMotionNotify</function>
+the valid device event fields are device and time.
+For the extension input device events
+<function>ProximityIn</function>
+and
+<function>ProximityOut</function>
+the fields of a device event that contain valid
+information are device and time.  For the extension input device event
+<function>DeviceValuator</function>
+the fields of a device event that contain valid information are
+device, num_valuators, first_valuator, and valuators.
+The time field refers to the time the event was generated by the device.
+</para>
+
+
+<para>
+The data_len member is set to the length of the actual recorded protocol
+data in 4-byte units.
+</para>
+
+<para>
+When the context has been enabled, protocol data the recording client has
+previously expressed interest in is recorded and returned to the
+recording client via multiple replies.  Because the X server batches
+the recorded data, more than one protocol element may be contained
+in the same reply packet.  When a reply is received, a procedure of type
+<function>XRecordInterceptProc</function>
+is called for each protocol element in the reply.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>typedef void <function>(*XRecordInterceptProc)</function></funcdef>
+    <paramdef>XPointer<parameter> closure</parameter></paramdef>
+    <paramdef>XRecordInterceptData<parameter> *recorded_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>closure</emphasis></term>
+    <listitem><para>Pointer that was passed in when the context was enabled.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>recorded_data</emphasis></term>
+    <listitem><para>A protocol element recorded by the server extension.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+This callback may use the control display connection (or any display
+connection other than the data connection).
+</para>
+
+<para>
+Recording clients should use the
+<function>XRecordFreeData</function>
+function to free the
+<function>XRecordInterceptData</function>
+structure.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>XRecordEnableContext</function></funcdef>
+    <paramdef>Display<parameter> *display</parameter></paramdef>
+    <paramdef>XRecordContext<parameter> context</parameter></paramdef>
+    <paramdef>XRecordInterceptProc<parameter> callback</parameter></paramdef>
+    <paramdef>XPointer<parameter> closure</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <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'>context</emphasis></term>
+    <listitem><para>Specifies the record context to enable.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>callback</emphasis></term>
+    <listitem><para>Specifies the function to be called for each protocol element received.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>closure</emphasis></term>
+    <listitem><para>Specifies data passed to callback.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>
+<function>XRecordEnableContext</function>
+enables data transfer between the recording client and
+the X server.  All core and extension protocol received from or sent to
+targeted clients that the recording client has expressed
+interest in will be recorded and reported to the recording client.
+</para>
+
+<para>
+<function>XRecordEnableContext</function>
+returns zero if the request failed; otherwise, it
+returns nonzero.  The context argument must specify a valid
+<function>XRecordContext</function>
+or a
+<function>XRecordBadContext</function>
+error results.  The error
+<function>BadMatch</function>
+results when data transfer is already enabled on the given context.
+</para>
+</sect2>
+
+<sect2 id='enable_context_asynchronously'>
+<title>Enable Context Asynchronously</title>
+
+<para>Because
+<function>XRecordEnableContext</function>
+does not return until
+<function>XRecordDisableContext</function>
+is executed on the control connection, a nonblocking interface in
+addition to
+<function>XRecordEnableContext</function>
+is provided.  This interface also
+enables data transfer; however, it does not block.
+</para>
+
+<para>
+This interface is defined as follows:
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>XRecordEnableContextAsync</function></funcdef>
+    <paramdef>Display<parameter> *display</parameter></paramdef>
+    <paramdef>XRecordContext<parameter> context</parameter></paramdef>
+    <paramdef>XRecordInterceptProc<parameter> callback</parameter></paramdef>
+    <paramdef>XPointer<parameter> closure</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <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'>context</emphasis></term>
+    <listitem><para>Specifies the record context to enable.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>callback</emphasis></term>
+    <listitem><para>Specifies the function to be called for each protocol element received.</para></listitem>
+  </varlistentry>
+  <varlistentry>
+    <term><emphasis remap='I'>closure</emphasis></term>
+    <listitem><para>Specifies data passed to callback.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<function>XRecordEnableContextAsync</function>
+enables data transfer between the recording
+client and the X server just as
+<function>XRecordEnableContext</function>
+does.  Unlike
+<function>XRecordEnableContext</function>
+it does not wait for the context to be disabled
+before returning;
+<function>XRecordEnableContextAsync</function>
+returns as soon as the
+<function>XRecordStartOfData</function>
+reply has been received and processed.
+</para>
+
+<para>
+<function>XRecordEnableContextAsync</function>
+returns zero if it could not allocate the
+necessary memory and nonzero if it sent the request successfully to
+the server.  The context argument must specify a valid
+<function>XRecordContext</function>
+or a
+<function>XRecordBadContext</function>
+error results.  The error
+<function>BadMatch</function>
+results when data transfer is already enabled.
+</para>
+
+<para>
+Each time it reads data from the server connection, Xlib will check
+for incoming replies and call <emphasis remap='I'>callback</emphasis>
+as necessary.  The application may direct Xlib explicitly to check
+for Record data with the
+<function>XRecordProcessReplies</function>
+function.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void <function>XRecordProcessReplies</function></funcdef>
+    <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>display</emphasis></term>
+    <listitem><para>Specifies the connection to the X server.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+<function>XRecordProcessReplies</function>
+will check for any replies that have not yet
+been processed by the application.  The asynchronous callback will be called
+as appropriate.
+<function>XRecordProcessReplies</function>
+returns when all immediately
+available replies have been processed.  It does not block.
+</para>
+
+<para>To free the data passed to the
+<function>XRecordInterceptProc</function>
+callback, use
+<function>XRecordFreeData</function></para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>void <function>XRecordFreeData</function></funcdef>
+    <paramdef>XRecordInterceptData<parameter> *data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>data</emphasis></term>
+    <listitem><para>Specifies the structure that is to be freed.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>
+<function>XRecordFreeData</function>
+frees the data pointed to by data.  If the argument does not match an
+<function>XRecordInterceptData</function>
+pointer earlier passed to an
+<function>XRecordInterceptProc</function>
+callback or if
+<function>XRecordFreeData</function>
+has already been called with it, the behavior is undefined.
+</para>
+</sect2>
+
+<sect2 id='disable_context'>
+<title>Disable Context</title>
+
+<para>
+To direct the X server to halt the reporting of recorded protocol, the
+program executes
+<function>XRecordDisableContext</function>
+typically over its control connection to the X server.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>XRecordDisableContext</function></funcdef>
+    <paramdef>Display<parameter> *display</parameter></paramdef>
+    <paramdef>XRecordContext<parameter> context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <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'>context</emphasis></term>
+    <listitem><para>Specifies the record context to disable.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+
+<para>
+The
+<function>XRecordDisableContext</function>
+function disables context, stopping all recording over its data connection.
+Any complete protocol elements for context that were buffered in the
+server will be sent to the recording client rather than being discarded.
+If a program attempts to disable an
+<function>XRecordContext</function>
+that has not been enabled, no action will take place.
+</para>
+
+<para>
+<function>XRecordDisableContext</function>
+returns zero if the request failed; otherwise, it
+returns nonzero.  The context argument must specify a valid
+<function>XRecordContext</function>
+or an
+<function>XRecordBadContext</function>
+error results.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id='id_base_mask'><title>ID Base Mask</title>
+
+<para>
+To determine the mask the server uses for the client ID base, use
+<function>XRecordIdBaseMask</function></para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>XID <function>XRecordIdBaseMask</function></funcdef>
+    <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <varlistentry>
+    <term><emphasis remap='I'>display</emphasis></term>
+    <listitem><para>Specifies the connection to the X server.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+The
+<function>XRecordIdBaseMask</function>
+function returns the resource ID mask passed to the client by the
+server at connection setup.
+</para>
+
+</sect1>
+
+<sect1 id='free_context'>
+<title>Free Context</title>
+
+<para>
+Before terminating, the program should request that the server
+free the record context.  This is done with the
+<function>XRecordFreeContext</function>
+function, typically over the record client's control connection
+to the X server.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>XRecordFreeContext</function></funcdef>
+    <paramdef>Display<parameter> *display</parameter></paramdef>
+    <paramdef>XRecordContext<parameter> context</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist remap='IP'>
+  <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'>context</emphasis></term>
+    <listitem><para>Specifies the record context to free.</para></listitem>
+  </varlistentry>
+</variablelist>
+
+<para>
+The
+<function>XRecordFreeContext</function>
+function frees the given context for the
+requesting client.  Freeing a record context releases the clients
+targeted for recording and their respective protocol ranges to
+record.  If protocol data is being reported to the recording client,
+generally over the data connection to the X server, the reporting
+ceases as if
+<function>XRecordDisableContext</function>
+had been called on the given context.  When a program terminates
+without freeing its record context, the X server will automatically
+free that context on behalf of the client.
+</para>
+
+<para>
+<function>XRecordFreeContext</function>
+returns zero if the request failed; otherwise,it
+returns nonzero.  The context argument must specify a valid
+<function>XRecordContext</function>
+or a
+<function>XRecordBadContext</function>
+error results.
+</para>
+
+</sect1>
+</chapter>
+</book>