Move libX11 & XIM/locale specs from xorg-docs

If groff is found, and --disable-specs is not passed to configure,
specs will be converted to text, html and ps (or pdf if ps2pdf is
found) and installed to $(docdir)

Signed-off-by: Alan Coopersmith <alan.coopersmith@sun.com>

38 files changed, 57223 insertions, 1 deletions

diff --git a/Makefile.am b/Makefile.am
index 4fcad1c1..e471ff4a 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -3,7 +3,7 @@ ORDER=src modules
 else
 ORDER=modules src
 endif
-SUBDIRS=include $(ORDER) nls man
+SUBDIRS=include $(ORDER) nls man specs
 
 pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = x11.pc
diff --git a/configure.ac b/configure.ac
index b800bf12..f7bec717 100644
--- a/configure.ac
+++ b/configure.ac
@@ -428,6 +428,31 @@ AC_DEFINE_DIR(XERRORDB, XERRORDB, [Location of error message database])
 
 XORG_CHECK_MALLOC_ZERO
 
+# Specification documents are currently provided in troff format
+AC_PATH_PROGS([GROFF], [groff], [none], [$PATH:/usr/gnu/bin])
+AC_PATH_PROGS([PS2PDF], [ps2pdf], [none], [$PATH:/usr/gnu/bin])
+
+AC_MSG_CHECKING([whether to build specifications])
+AC_ARG_ENABLE(specs, AC_HELP_STRING([--enable-specs],
+                                   [Enable building of specification docs]),
+              [build_specs="${enableval}"], [build_specs="auto"])
+
+if test "x${build_specs}" = xauto; then
+    if test "x${GROFF}" = xnone ; then
+        build_specs=no
+    else
+        build_specs=yes
+    fi
+fi
+AC_MSG_RESULT([${build_specs}])
+if test "x${build_specs}" = xyes && test "x${GROFF}" = xnone ; then
+    AC_MSG_ERROR([can't build documentation without groff])
+fi
+
+AM_CONDITIONAL(BUILD_SPECS, [test x$build_specs = xyes])
+AM_CONDITIONAL(HAVE_PS2PDF, [test x$PS2PDF != xnone])
+
+
 AC_OUTPUT([Makefile
            include/Makefile
 	   man/Makefile
@@ -508,6 +533,10 @@ AC_OUTPUT([Makefile
 	   nls/zh_TW/Makefile
 	   nls/zh_TW.big5/Makefile
 	   nls/zh_TW.UTF-8/Makefile
+	   specs/Makefile
+	   specs/i18n/Makefile
+	   specs/libX11/Makefile
+	   specs/XIM/Makefile
 	   x11.pc
 	   x11-xcb.pc])
 
diff --git a/specs/Makefile.am b/specs/Makefile.am
new file mode 100644
index 00000000..8c3cdf87
--- /dev/null
+++ b/specs/Makefile.am
@@ -0,0 +1,3 @@
+SUBDIRS=libX11 i18n XIM
+
+EXTRA_DIST=troffrules.in
diff --git a/specs/XIM/Makefile.am b/specs/XIM/Makefile.am
new file mode 100644
index 00000000..c76a3f72
--- /dev/null
+++ b/specs/XIM/Makefile.am
@@ -0,0 +1,33 @@
+#
+# Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
+#
+# Permission to use, copy, modify, distribute, and sell this software and its
+# documentation for any purpose is hereby granted without fee, provided that
+# the above copyright notice appear in all copies and that both that
+# copyright notice and this permission notice appear in supporting
+# documentation.
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# 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 OPEN GROUP 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.
+#
+# Except as contained in this notice, the name of the copyright holders 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 copyright holders.
+#
+
+# Based on xc/doc/specs/XIM/Makefile from X11R6.9
+
+doc_sources = xim.ms
+
+include $(top_srcdir)/specs/troffrules.in
+
+
diff --git a/specs/XIM/xim.ms b/specs/XIM/xim.ms
new file mode 100644
index 00000000..e41e9bca
--- /dev/null
+++ b/specs/XIM/xim.ms
@@ -0,0 +1,4279 @@
+.\" $Xorg: xim.ms,v 1.3 2000/08/17 19:42:21 cpqbld Exp $
+.\" To print this out, type tbl macros.t ThisFile | troff -ms
+.\" $XFree86: xc/doc/specs/XIM/xim.ms,v 1.2 2000/12/14 17:48:58 dawes Exp $
+.EH ''''
+.OH ''''
+.EF ''''
+.OF ''''
+.ps 11
+.nr PS 11
+\&
+.sp 8
+.TL
+\s+3\fBThe Input Method Protocol\fP\s-3
+.sp
+\fBVersion 1.0\fP
+.sp
+\fBX Consortium Standard\fP
+.sp
+\fBX Version 11, Release 7\fP
+.sp
+\fB\*(xV\fP
+.sp 3
+.AU
+Masahiko Narita
+.AI
+FUJITSU Limited.
+.AU
+Hideki Hiura
+.AI
+SunSoft, Inc.
+.sp 3
+.AB
+.LP
+This specifies a protocol between IM library and IM (Input Method) 
+Server for internationalized text input, which is independent from  
+any specific language, any specific input method and the transport layer 
+used in communication between the IM library and the IM Server, and uses 
+a client-server model. 
+This protocol allows user to use his/her favorite input method for all 
+applications within the stand-alone distributed environment.
+.AE
+.ce 0
+.br
+\&
+.LP
+.ps 11
+.nr PS 11
+.bp
+\&
+.ps 9
+.nr PS 9
+.sp 8
+.LP
+.DS C
+X Window System is a trademark of X Consortium, Inc.
+.sp
+Copyright \(co 1993, 1994 by X Consortium, Inc.
+.DE
+.sp 2
+.LP
+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:
+.LP
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+.LP
+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.
+.LP
+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.
+.sp 3
+.DS C
+Copyright \(co 1993, 1994 by FUJITSU LIMITED
+.sp
+Copyright \(co 1993, 1994 by Sun Microsystems, Inc.
+.DE
+.sp 2
+.LP 
+Permission to use, copy, modify, and distribute this documentation 
+for any purpose and without fee is hereby granted, provided 
+that the above copyright notice and this permission 
+notice appear in all copies.
+Fujitsu and Sun Microsystems make 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. 
+.ps 11
+.nr PS 11
+.bp 1
+.EH '\fBX Input Method Protocol\fP''\fB\*(xV\fP'
+.OH '\fBX Input Method Protocol\fP''\fB\*(xV\fP'
+.EF ''\fB % \fP''
+.OF ''\fB % \fP''
+.NH 1
+Introduction
+.XS
+\*(SN Introduction
+.XE
+.NH 2
+Scope
+.XS
+\*(SN Scope
+.XE
+.LP
+The internationalization in the
+X Window System
+Version 11, Release 5 (X11R5) provides a common API which application 
+developers can use to create portable internationalized programs and to 
+adapt them to the requirements of different native languages, local customs,
+and character string encodings (this is called ``localization'').  
+As one of its internationalization mechanisms X11R5 has defined a functional 
+interface for internationalized text input, called XIM (X Input Method).  
+.LP
+When a client-server model is used with an IM (Input Method) implementation,
+a protocol must be established between the client and the server. 
+However, the protocol used to interface Input Method Servers (IM Servers) 
+with the Input Method libraries (IM libraries) to which applications are 
+linked was not addressed in X11R5. 
+This led application developers to depend on vendor-specific input methods, 
+decreased the user's choice of available input methods, and made it more 
+difficult for developers to create portable applications. This paper describes 
+the Input Method Protocol developed for X11R6 to resolve the above problems 
+and to address the requirements of existing and future input methods.
+.LP
+The Input Method Protocol is independent from the transport layer used in 
+communication between the IM library and the IM Server. 
+Thus, the input method protocol can be built on any inter-process 
+communication mechanism, such as TCP/IP or the X protocol.
+.LP
+In addition, the protocol provides for future extensions such as differing 
+input model types.
+.LP
+.NH 2
+Background
+.XS
+\*(SN Background
+.XE
+.LP
+Text input is much more simple for some languages than
+others.  English, for instance, uses an alphabet of a manageable size,
+and input consists of pressing the corresponding key on a keyboard,
+perhaps in combination with a shift key for capital letters or special
+characters.
+.LP
+Some languages have larger alphabets, or modifiers such as accents,
+which require the addition of special key combinations in order to enter
+text.  These input methods may require ``dead-keys'' or ``compose-keys''
+which, when followed by different combinations of key strokes,
+generate different characters.
+.LP
+Text input for ideographic languages is much less simple.  In these
+languages, characters represent actual objects rather than phonetic 
+sounds used in pronouncing a word, and the number of characters
+in these languages may continue to grow.  In Japanese, for instance, most
+text input methods involve entering characters in a phonetic alphabet,
+after which the input method searches a dictionary for possible
+ideographic equivalents (of which there may be many).  The input method then
+presents the candidate characters for the user to choose from.
+.LP
+In Japanese, either Kana (phonetic symbols) or Roman letters are
+typed and then a region is selected for conversion to Kanji. Several
+Kanji characters may have the same phonetic representation. If that
+is the case with the string entered, a menu of characters is presented
+and the user must choose the appropriate one. If no choice is necessary
+or a preference has been established, the input method does the
+substitution directly.
+.LP
+These complicated input methods must present state information (Status Area), 
+text entry and edit space (Preedit Area), and menu/choice presentations 
+(Auxiliary Area).  Much of the protocol between the IM library and the IM
+Server involves managing these IM areas.
+Because of the size and complexity of these input methods, and because
+of how widely they vary from one language or locale to another, they are
+usually implemented as separate processes which can serve many client
+processes on the same computer or network.
+.LP
+.NH 2
+Input Method Styles
+.XS
+\*(SN Input Method Styles
+.XE
+.LP
+X11 internationalization support includes the following four types of
+input method:
+.RS
+.IP "- on-the-spot:" 20
+The client application is directed by the IM Server to display all
+pre-edit data at the site of text insertion.  The client registers
+callbacks invoked by the input method during pre-editing.
+.IP "- off-the-spot:" 20
+The client application provides display windows for the pre-edit data
+to the input method which displays into them directly.
+.IP "- over-the-spot:" 20
+The input method displays pre-edit data in a window which it brings up
+directly over the text insertion position.
+.IP "- root-window:" 20
+The input method displays all pre-edit data in a separate area of the
+screen in a window specific to the input method.
+.RE
+.LP
+Client applications must choose from the available input methods
+supported by the IM Server and provide the display areas and callbacks
+required by the input method.
+.LP
+.NH 1
+Architecture
+.XS
+\*(SN Architecture
+.XE
+.NH 2
+Implementation Model
+.XS
+\*(SN Implementation Model
+.XE
+.LP
+Within the X Window System environment, the following two typical
+architectural models can be used as an input method's implementation
+model.
+.RS
+.IP "- Client/Server model:" 20
+A separate process, the IM Server, processes input and handles preediting, 
+converting, and committing.  The IM library within the application, acting 
+as client to the IM Server, simply receives the committed string from the 
+IM Server.
+.IP "- Library model:" 20
+All input is handled by the IM library within the application.  The
+event process is closed within the IM library and a separate IM Server
+process may not be required.
+.RE
+.LP
+Most languages which need complex preediting, such as Asian languages,
+are implemented using the Client/Server IM model.  Other languages
+which need only dead key or compose key processing, such as European
+languages, are implemented using the Library model.
+.LP
+In this paper, we discuss mainly the Client/Server IM model and the
+protocol used in communication between the IM library (client) and the IM 
+Server.
+.LP
+.NH 2
+Structure of IM
+.XS
+\*(SN Structure of IM
+.XE
+.LP
+When the client connects or disconnects to the IM Server, an open or close
+operation occurs between the client and the IM Server.
+.LP
+The IM can be specified at the time of XOpenIM() by setting the locale 
+of the client and a locale modifier. Since the IM remembers 
+the locale at the time of creation XOpenIM() can be called
+multiple times (with the 
+setting for the locale and the locale modifier changed) to support 
+multiple languages.
+.LP
+In addition, the supported IM type can be obtained using XGetIMValues().
+.LP
+The client usually holds multiple input (text) fields. Xlib provides a
+value type called the ``Input Context'' (IC) to manage each individual 
+input field.  An IC can be created by specifying XIM using XCreateIC(), 
+and it can be destroyed using XDestroyIC().
+.LP
+The IC can specify the type of IM which is supported by XIM for each 
+input field, so each input field can handle a different type of IM.
+.LP
+Most importantly information such as the committed string sent from
+the IM Server to the client, is exchanged based on each IC.
+.LP
+Since each IC corresponds to an input field, the focused input field 
+should be announced to the IM Server using XSetICFocus(). (XUnsetICFocus() 
+can also be used to change the focus.)
+.LP
+.NH 2
+Event Handling Model
+.XS
+\*(SN Event Handling Model
+.XE
+.LP
+Existing input methods support either the FrontEnd method, the BackEnd method, 
+or both.  This protocol specifically supports the BackEnd method as 
+the default method, but also supports the FrontEnd method as an optional 
+IM Server extension.
+.LP
+The difference between the FrontEnd and BackEnd methods is in how
+events are delivered to the IM Server.  (Fig. 1)
+.LP
+.NH 3
+BackEnd Method
+.XS
+\*(SN BackEnd Method
+.XE
+.LP
+In the BackEnd method, client window input events are always delivered
+to the IM library, which then passes them to the IM Server.  Events are
+handled serially in the order delivered, and therefore there is no
+synchronization problem between the IM library and the IM Server.
+.LP
+Using this method, the IM library forwards all KeyPress and KeyRelease
+events to the IM Server (as required by the Event Flow Control model 
+described in section 2.4. ``Event Flow Control''), and synchronizes 
+with the IM Server (as described in section 4.16.  ``Filtering Events'').
+.LP
+.NH 3
+FrontEnd Method
+.XS
+\*(SN FrontEnd Method
+.XE
+.LP
+In the FrontEnd method, client window input events are delivered by the
+X server directly to both the IM Server and the IM library.  Therefore this
+method provides much better interactive performance while preediting
+(particularly in cases such as when the IM Server is running locally on
+the user's workstation and the client application is running on another
+workstation over a relatively slow network).
+.LP
+However, the FrontEnd model may have synchronization problems between
+the key events handled in the IM Server and other events handled in the
+client, and these problems could possibly cause the loss or duplication
+of key events.  For this reason, the BackEnd method is the core method
+supported, and the FrontEnd method is made available as an extension for
+performance purposes. (Refer to Appendix A for more information.)
+.LP
+.LP
+.bp
+\^... 0.05 6.513 4.737 10.45
+\^... 0.000i 3.937i 4.687i 0.000i
+.nr 00 \n(.u
+.nf
+.PS 3.937i 4.687i 
+.br
+.ps
+.ps 10
+\h'3.687i'\v'3.437i'\v'-.13m'\L'-0.500i\(br'\v'.13m'
+.sp -1
+\h'3.712i'\v'3.037i'\D'l-0.025i -0.100i'
+.sp -1
+\h'3.687i'\v'2.937i'\D'l-0.025i 0.100i'
+.sp -1
+\h'2.187i'\v'1.938i'\v'-.13m'\L'-0.750i\(br'\v'.13m'
+.sp -1
+\h'2.187i'\v'1.188i'\l'0.750i'
+.sp -1
+\h'2.937i'\v'1.188i'\v'-.13m'\L'1.250i\(br'\v'.13m'
+.sp -1
+\h'2.912i'\v'2.338i'\D'l0.025i 0.100i'
+.sp -1
+\h'2.937i'\v'2.438i'\D'l0.025i -0.100i'
+.sp -1
+\h'2.187i'\v'3.437i'\v'-.13m'\L'-1.499i\(br'\v'.13m'
+.sp -1
+\h'2.212i'\v'2.038i'\D'l-0.025i -0.100i'
+.sp -1
+\h'2.187i'\v'1.938i'\D'l-0.025i 0.100i'
+.sp -1
+\h'1.938i'\v'3.437i'\l'1.999i'
+.sp -1
+\h'3.937i'\v'3.437i'\v'-.13m'\L'0.500i\(br'\v'.13m'
+.sp -1
+\h'3.937i'\v'3.937i'\l'-1.999i'
+.sp -1
+\h'1.938i'\v'3.937i'\v'-.13m'\L'-0.500i\(br'\v'.13m'
+.sp -1
+\h'2.562i'\v'2.438i'\l'2.125i'
+.sp -1
+\h'4.687i'\v'2.438i'\v'-.13m'\L'0.499i\(br'\v'.13m'
+.sp -1
+\h'4.687i'\v'2.937i'\l'-2.125i'
+.sp -1
+\h'2.562i'\v'2.937i'\v'-.13m'\L'-0.499i\(br'\v'.13m'
+.sp -1
+\h'2.562i'\v'1.438i'\l'1.313i'
+.sp -1
+\h'3.875i'\v'1.438i'\v'-.13m'\L'0.437i\(br'\v'.13m'
+.sp -1
+\h'3.875i'\v'1.875i'\l'-1.313i'
+.sp -1
+\h'2.562i'\v'1.875i'\v'-.13m'\L'-0.437i\(br'\v'.13m'
+.sp -1
+\h'1.938i'\v'0.438i'\l'1.999i'
+.sp -1
+\h'3.937i'\v'0.438i'\v'-.13m'\L'1.500i\(br'\v'.13m'
+.sp -1
+\h'3.937i'\v'1.938i'\l'-1.999i'
+.sp -1
+\h'1.938i'\v'1.938i'\v'-.13m'\L'-1.500i\(br'\v'.13m'
+.sp -1
+\D'l0.000i 0.000i'
+.sp -1
+.ps
+.ps 12
+\h'3.812i'\v'3.217i'\h'-0.0m'\v'0.2m'FrontEnd Method (Extension)
+.sp -1
+\h'0.813i'\v'3.217i'\h'-0.0m'\v'0.2m'BackEnd Method (Core)
+.sp -1
+\h'2.562i'\v'3.779i'\h'-0.0m'\v'0.2m'X Server
+.sp -1
+\h'3.062i'\v'2.779i'\h'-0.0m'\v'0.2m'IM Server
+.sp -1
+\h'3.062i'\v'1.717i'\h'-0.0m'\v'0.2m'Library
+.sp -1
+\h'2.187i'\v'0.904i'\h'-0.0m'\v'0.2m'Application
+.sp -1
+.ps
+.ft
+.sp 1+3.937i
+.PE
+.if \n(00 .fi
+.ce
+.sp
+Fig.1 The Flow of Events
+.LP
+.NH 2
+Event Flow Control
+.XS
+\*(SN Event Flow Control
+.XE
+.LP
+This protocol supports two event flow models for communication between the 
+IM library and the IM Server (Static and Dynamic).  
+.LP
+Static Event Flow requires that input events always be sent to the IM
+Server from the client.
+.LP
+Dynamic Event Flow, however, requires only that those input events which
+need to be processed (converted) be sent to the IM Server from the client.
+.LP
+For instance, in the case of inputing a combination of ASCII characters
+and Chinese characters, ASCII characters do not need to be processed in
+the IM Server, so their key events do not have to be sent to the IM
+Server.  On the other hand, key events necessary for composing Chinese
+characters must be sent to the IM Server.
+.LP
+Thus, by adopting the Dynamic Event Flow, the number of requests among the
+X Server, the client, and the IM Server is significantly reduced, and the
+number of context switches is also reduced, resulting in improved performance.
+The IM Server can send 
+.PN XIM_REGISTER_TRIGGERKEYS 
+message in order to switch the event flow in the Dynamic Event Flow.
+.LP
+The protocol for this process is described in section 4.5. ``Event Flow
+Control''.
+.LP
+.NH 1
+Default Preconnection Convention
+.XS
+\*(SN Default Preconnection Convention 
+.XE
+.LP
+IM Servers are strongly encouraged to register their symbolic
+names as the ATOM names into the IM Server directory property, 
+.PN XIM_SERVERS,
+on the root window of the screen_number 0.
+This property can contain a list of ATOMs, and the each ATOM represents
+each possible IM Server.
+IM Server names are restricted to POSIX Portable Filename Character Set.
+To discover if the IM Server is active, see if there is an owner for
+the selection with that atom name.  To learn the address of that IM Server, 
+convert the selection target
+.PN TRANSPORT,
+which will return a string form of the transport address(es).
+To learn the supported locales of that IM Server, convert the selection target 
+.PN LOCALES,
+which will return a set of names of the supported locales in the syntax 
+X/Open defines.
+.LP
+The basic semantics to determine the IM Server if there are
+multiple ATOMs are found in 
+.PN XIM_SERVERS
+property, is first fit if the IM Server name is not given as
+a X modifier's category
+.PN im.
+.LP
+The address information retrievable from the 
+.PN TRANSPORT
+target is a transport-specific name. 
+The preregistered formats for transport-specific names are listed in Appendix B.
+Additional transport-specific names may be registered with X Consortium.
+.LP
+For environments that lack X connections, or for IM Servers which
+do not use the X Window System, the preconnection convention with IM Server 
+may be given outside the X Window system (e.g. using a Name Service).
+.LP
+.NH 1
+Protocol
+.XS
+\*(SN Protocol
+.XE
+.LP
+The protocol described below uses the bi-directional
+synchronous/asynchronous request/reply/error model and is specified
+using the same conventions outlined in Section 2 of the core X Window
+System protocol [1]:
+.LP
+.NH 2
+Basic Requests Packet Format
+.XS
+\*(SN Basic Requests Packet Format
+.XE
+.LP
+This section describes the requests that may be exchanged between the client 
+and the IM Server.
+.LP
+The basic request packet header format is as follows.
+.RS
+.DS
+	major-opcode:			CARD8
+	minor-opcode:			CARD8
+	length:				CARD16
+.DE
+.RE
+The MAJOR-OPCODE specifies which core request or extension package this 
+packet represents.  If the MAJOR-OPCODE corresponds to a core request, 
+the MINOR-OPCODE contains 8 bits of request-specific data.  
+(If the MINOR-OPCODE is not used, it is 0.)
+Otherwise, the MAJOR-OPCODE and the MINOR-OPCODE are specified by
+.PN XIM_QUERY_EXTENSION
+message.  (Refer to 4.7. Query the supported extension protocol list.)
+The LENGTH field specifies the number of 4 bytes elements following the 
+header.  If no additional data is followed by the header, the LENGTH field 
+will be 0.
+.LP
+.NH 2
+Data Types
+.XS
+\*(SN Data Types
+.XE
+.LP
+The following data types are used in the core X IM Server protocol:
+.LP
+.nf
+.ta .2i .5i 2.0i
+BITMASK16
+	CARD16
+.sp
+BITMASK32
+	CARD32
+.sp
+PADDING FORMAT
+	Where N is some expression, and Pad(N) is the number of bytes needed to round N up to a 
+	multiple of four.
+		Pad(N) = (4 - (N mod 4)) mod 4
+.sp
+LPCE
+	1		A character from the4 X Portable Character Set in Latin Portable 
+			Character Encoding
+.bp
+STRING
+	2	n	length of string in bytes
+	n	LISTofLPCE	string
+	p		unused, p=Pad(2+n)
+.sp
+STR
+	1	n	length of name in bytes
+	n	STRING8	name
+.sp
+XIMATTR
+	2	CARD16	attribute ID (*1)
+	2	CARD16	type of the value (*2)
+	2	n	length of im-attribute
+	n	STRING8	im-attribute
+	p		unused, p = Pad(2+n)
+.sp
+The im-attribute argument specifies XIM values such as XNQueryInputStyle.
+.sp
+XICATTR
+	2	CARD16	attribute ID (*1)
+	2	CARD16	type of the value (*2) 
+	2	n	length of ic-attribute
+	n	STRING8	ic-attribute
+	p		unused, p = Pad(2+n) 
+.LP
+.IP (*1)
+XIMATTR and XICATTR are used during the setup stage and XIMATTRIBUTE and 
+XICATTRIBUTE are used after each attribute ID has been recognized by
+the IM Server and the IM library.
+.sp
+.IP (*2)
+The value types are defined as follows:
+.TS H
+tab(:);
+l l l s s
+l l l l l
+l l l l l
+l l l l l
+l l l l l
+l l l l l
+l l l l l
+l l l l l
+l l l l l
+l l l l l
+l l l l l
+l l l l l
+l l l l l
+l l l l l
+l l l l l
+l l l l l
+l l l l l
+l l l l l
+l l l l l
+l l l l l
+l l l l l
+l l l l l
+l l l s s
+l l l s s
+l l l s s
+l l l s s
+l l l s s
+l l l l l.
+_
+.sp 6p
+.B
+values:data:format
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+#0:Separator of NestedList:----- (*3)
+#1:byte data:CARD8
+#2:word data:CARD16
+#3:long data:CARD32
+#4:char data:STRING8
+#5:Window:CARD32
+#10:XIMStyles:2:n:number of XIMStyle list
+::2::unused
+::n:CARD32:XIMStyle list
+#11:XRectangle:2:INT16:X
+::2:INT16:Y
+::2:CARD16:width
+::2:CARD16:height
+#12:XPoint:2:INT16:X
+::2:INT16:Y
+#13:XFontSet:2:n:length of Base font name
+::n:STRING8:Base font name list
+::p::unused, p = Pad(2+n)
+#15:XIMHotKeyTriggers:4:n:T{
+number of XIMTRIGGERKEY list (*4)
+T}
+::n:XIMTRIGGERKEY:XIMHotkeyTrigger list
+#16:XIMHotKeyState::XIMHOTKEYSTATE:T{
+HotKey processing state
+T}
+#17:XIMStringConversion:XIMSTRCONVTEXT
+#18:XIMPreeditState:XIMPREEDITSTATE
+#19:XIMResetState:XIMRESETSTATE
+#x7fff:NestedList:-----	
+.sp 6p
+_
+.TE
+.LP
+.IP (*3)
+The IC value for the separator of NestedList is defined as follows,
+.br
+	#define   XNSeparatorofNestedList   ``separatorofNestedList''
+.br
+, which is registered in X Consortium and cannot be used for any 
+other purpose.
+.sp
+.IP (*4)
+LISTofFOO
+.RS
+A Type name of the form LISTof FOO means a counted list of elements of
+type FOO.
+The size of the length field may vary (it is not necessarily the same
+size as a FOO), and in some cases, it may be implicit.
+.RE
+.sp
+.LP
+.nf
+.ta .2i .5i 2.0i
+XIMTRIGGERKEY
+	4	CARD32	keysym
+	4	CARD32	modifier
+	4	CARD32	modifier mask
+.sp
+ENCODINGINFO
+	2	n	length of encoding info
+	n	STRING8	encoding info
+	p		unused, p=Pad(2+n)
+.sp
+EXT
+	1	CARD8	extension major-opcode
+	1	CARD8	extension minor-opcode
+	2	n	length of extension name
+	n	STRING8	extension name
+	p		unused, p = Pad(n)
+.sp
+XIMATTRIBUTE
+	2	CARD16	attribute ID
+	2	n	value length
+	n		value
+	p		unused, p = Pad(n)
+.sp
+XICATTRIBUTE
+	2	CARD16	attribute ID
+	2	n	value length
+	n		value
+	p		unused, p = Pad(n)
+.sp
+.bp
+.ta .2i .5i 3.0i
+XIMSTRCONVTEXT
+	2	CARD16	XIMStringConversionFeedback
+		#x0000001	XIMStringConversionLeftEdge
+		#x0000002	XIMStringConversionRightEdge
+		#x0000004	XIMStringConversionTopEdge
+		#x0000008	XIMStringConversionBottomEdge
+		#x0000010	XIMStringConversionConvealed
+		#x0000020	XIMStringConversionWrapped
+	2	n	byte length of the retrieved string
+	n	STRING8	retrieved string
+	p		unused, p = Pad(n)
+	2	m	byte length of feedback array
+	2		unused
+	m	LISTofXIMSTRCONVFEEDBACK	feedback array(*1)
+.IP (*1)
+This field is reserved for future use.
+.sp
+.LP
+.nf
+.ta .2i .5i 2.0i
+XIMFEEDBACK
+	4	CARD32	XIMFeedback
+		#x000001	XIMReverse
+		#x000002	XIMUnderline
+		#x000004	XIMHighlight
+		#x000008	XIMPrimary
+		#x000010	XIMSecondary
+		#x000020	XIMTertiary
+		#x000040	XIMVisibleToForward
+		#x000080	XIMVisibleToBackward
+		#x000100	XIMVisibleCenter
+.sp
+XIMHOTKEYSTATE
+	4	CARD32	XIMHotKeyState
+		#x0000001	XIMHotKeyStateON
+		#x0000002	XIMHotKeyStateOFF
+.sp
+XIMPREEDITSTATE
+	4	CARD32	XIMPreeditState
+		#x0000001	XIMPreeditEnable
+		#x0000002	XIMPreeditDisable
+.sp
+XIMRESETSTATE
+	4	CARD32	XIMResetState
+		#x0000001	XIMInitialState
+		#x0000002	XIMPreserveState
+.LP
+.NH 2
+Error Notification
+.XS
+\*(SN Error Notification
+.XE
+.LP
+Both the IM Server and the IM library return 
+.PN XIM_ERROR
+messages instead of the corresponding reply messages if any errors occur 
+during data processing.
+.LP
+At most one error is generated per request. If more than one error condition
+is encountered in processing a request, the choice of which error is returned
+is implementation-dependent.
+.LP
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_ERROR (IM Server \(<-\(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:2:BITMASK16:flag (*1)
+::#0000:Both Input-Method-ID and Input-Context-ID are invalid
+::#0001:Input-Method-ID is valid
+::#0002:Input-Context-ID is valid
+:2:CARD16:Error Code
+::#1:BadAlloc
+::#2:BadStyle
+::#3:BadClientWindow
+::#4:BadFocusWindow
+::#5:BadArea
+::#6:BadSpotLocation
+::#7:BadColormap
+::#8:BadAtom
+::#9:BadPixel
+::#10:BadPixmap
+::#11:BadName
+::#12:BadCursor
+::#13:BadProtocol
+::#14:BadForeground
+::#15:BadBackground
+::#16:LocaleNotSupported
+::#999:BadSomething (*2)
+:2:n:byte length of error detail.
+:2:CARD16:type of error detail (*3)
+:n:STRING8:error detail (*4)
+:p::unused, p = Pad(n)
+.TE
+.LP
+.IP (*1)
+Before an IM is created, both Input-Method-ID and 
+Input-Context-ID are invalid.
+Before an IC is created, only Input-Method-ID is valid. 
+After that, both of Input-Method-ID and Input-Context-ID are valid.
+.IP (*2) 
+Unspecific error, for example ``language engine died''
+.IP (*3)
+This field is reserved for future use.
+.IP (*4)
+Vendor defined detail error message
+.RE
+.LP
+.NH 2
+Connection Establishment
+.XS
+\*(SN Connection Establishment
+.XE
+.LP
+.PN XIM_CONNECT
+message requests to establish a connection over a mutually-understood virtual 
+stream.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_CONNECT (IM library \(-> IM Server)
+.sp 6p
+:1::byte order
+::#x42 MSB first
+::#x6c LSB first
+:1::unused
+:2:CARD16:client-major-protocol-version (*1)
+:2:CARD16:client-minor-protocol-version (*1)
+:2:CARD16:number of client-auth-protocol-names
+:n:LISTofSTRING:client-auth-protocol-names
+.TE
+.LP
+.IP (*1)
+Specify the version of IM Protocol that the client supports.
+.RE
+.sp
+.LP
+A client must send 
+.PN XIM_CONNECT
+message as the first message on the connection. 
+The list specifies the names of authentication protocols the sending 
+IM Server is willing to perform.
+(If the client need not authenticate, the list may be omited.)
+.LP
+.PN XIM_AUTH_REQUIRED 
+message is used to send the authentication protocol name and protocol-specific 
+data.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_AUTH_REQUIRED (IM library \(<-\(-> IM Server)
+.sp 6p
+:1:CARD8:auth-protocol-index
+:3::unused
+:2:n:length of authentication data
+:2::unused
+:n:<varies>:data 
+:p::unused, p = Pad(n)
+.TE
+.RE
+.LP
+The auth-protocol is specified by an index into the list of names 
+given in the 
+.PN XIM_CONNECT
+or 
+.PN XIM_AUTH_SETUP
+message. Any protocol-specific data that might be required is also sent.
+.LP
+The IM library sends
+.PN XIM_AUTH_REPLY
+message as the reply to 
+.PN XIM_AUTH_REQUIRED
+message, if the IM Server is authenticated. 
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_AUTH_REPLY (IM library \(-> IM Server)
+.sp 6p
+:2:n:length of authentication data
+:2::unused
+:2:n:length of authentication data
+:2::unused
+:n:<varies>:data
+:p::unused, p = Pad(n)
+.TE
+.RE
+.LP
+The auth data is specific to the authentication protocol in use.
+.LP
+.PN XIM_AUTH_NEXT 
+message requests to send more auth data.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_AUTH_NEXT (IM library \(<-\(-> IM Server)
+.sp 6p
+:2:n:length of authentication data
+:2::unused
+:n:<varies>:data
+:p::unused, p = Pad(n)
+.TE
+.RE
+.LP	
+The auth data is specific to the authentication protocol in use.
+.LP
+The IM Server sends
+.PN XIM_AUTH_SETUP
+message to authenticate the client. 
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_AUTH_SETUP (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:number of client-auth-protocol-names
+:2::unused
+:n:LISTofSTRING:server-auth-protocol-names
+.TE
+.RE
+.LP
+The list specifies the names of authentication protocols the
+client is willing to perform.
+.LP
+.PN XIM_AUTH_NG
+message requests to give up the connection.  
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_AUTH_NG (IM library \(<-\(-> IM Server)
+.TE
+.RE
+.LP
+The IM Server sends
+.PN XIM_CONNECT_REPLY
+message as the reply to
+.PN XIM_CONNECT
+or
+.PN XIM_AUTH_REQUIRED
+message.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_CONNECT_REPLY (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:server-major-protocol-version (*1)
+:2:CARD16:server-minor-protocol-version (*1)
+.TE
+.LP
+.IP (*1)
+Specify the version of IM Protocol that the IM Server supports.
+This document specifies major version one, minor version zero.
+.RE
+.sp
+.LP	
+Here are the state diagrams for the client and the IM Server.
+.sp
+.B
+State transitions for the client
+.R
+.RS
+.LP
+\fIinit_status\fP:
+.RS
+Use authorization function \(-> \fIclient_ask\fP
+.br
+Not use authorization function \(-> \fIclient_no_check\fP
+.RE
+.sp
+.LP
+\fIstart\fP:
+.RS
+Send 
+.PN XIM_CONNECT
+.RS
+If \fIclient_ask\fP \(-> \fIclient_wait1\fP
+.br
+If \fIclient_no_check\fP, client-auth-protocol-names may be omited \(-> \fIclient_wait2\fP
+.RE
+.RE
+.sp
+.LP
+\fIclient_wait1\fP:
+.RS
+Receive 
+.PN XIM_AUTH_REQUIRED
+\(-> \fIclient_check\fP
+.br
+Receive <other> \(-> \fIclient_NG\fP
+.RE
+.sp
+.LP
+\fIclient_check\fP:
+.RS
+If no more auth needed, send 
+.PN XIM_AUTH_REPLY
+\(-> \fIclient_wait2\fP
+.br
+If good auth data, send 
+.PN XIM_AUTH_NEXT
+\(-> \fIclient_wait1\fP
+.br
+If bad auth data, send 
+.PN XIM_AUTH_NG
+\(-> give up on this protocol
+.RE
+.sp
+.LP
+\fIclient_wait2\fP:
+.RS
+Receive 
+.PN XIM_CONNECT_REPLY
+\(-> connect
+.br
+Receive 
+.PN XIM_AUTH_SETUP 
+\(-> \fIclient_more\fP
+.br
+Receive 
+.PN XIM_AUTH_NEXT
+\(-> \fIclient_more\fP
+.br
+Receive 
+.PN XIM_AUTH_NG
+\(-> give up on this protocol
+.br
+Receive <other> \(-> \fIclient_NG\fP
+.RE
+.sp
+.LP
+\fIclient_more\fP:
+.RS
+Send 
+.PN XIM_AUTH_REQUIRED
+\(-> \fIclient_wait2\fP
+.RE
+.sp
+.LP
+\fIclient_NG\fP:
+.RS
+Send 
+.PN XIM_AUTH_NG
+\(-> give up on this protocol
+.RE
+.RE
+.sp
+.LP
+.B
+State transitions for the IM Server
+.R
+.RS
+.LP
+\fIinit-status\fP:
+.RS
+Use authorization function \(-> \fIserver_ask\fP
+.br
+Not use authorization function \(-> \fIserver_no_check\fP
+.RE
+.sp
+.LP
+\fIstart\fP:
+.RS
+Receive 
+.PN XIM_CONNECT
+\(-> \fIstart2\fP
+.br
+Receive <other> \(-> \fIserver_NG\fP
+.RE
+.sp
+.LP
+\fIstart2\fP:
+.RS
+If \fIclient_ask\fP, send 
+.PN XIM_AUTH_REQUIRED
+\(-> \fIserver_wait1\fP
+.br
+If \fIclient_no_check\fP and \fIserver_ask\fP, send 
+.PN XIM_AUTH_SETUP
+\(-> \fIserver_wait2\fP
+.br
+If \fIclient_no_check\fP and \fIserver_no_check\fP, send 
+.PN XIM_CONNECT_REPLY
+\(-> connect
+.RE
+.sp
+.LP
+\fIserver_wait1\fP:
+.RS
+Receive 
+.PN XIM_AUTH_REPLY
+\(-> \fIserver2\fP
+.br
+Receive 
+.PN XIM_AUTH_NEXT
+\(-> \fIserver_more\fP
+.br
+Receive <other> \(-> \fIserver_NG\fP
+.RE
+.sp
+.LP
+\fIserver_more\fP
+.RS
+Send 
+.PN XIM_AUTH_REQUIRED
+\(-> \fIserver_wait1\fP
+.RE
+.sp
+.LP
+\fIserver2\fP
+.RS
+If \fIserver_ask\fP, send 
+.PN XIM_AUTH_SETUP
+\(-> \fIserver_wait2\fP
+.br
+If \fIserver_no_check\fP, send 
+.PN XIM_CONNECT_REPLY 
+\(-> connect
+.RE
+.sp
+.LP
+\fIserver_wait2\fP
+.RS
+Receive 
+.PN XIM_AUTH_REQUIRED
+\(-> \fIserver_check\fP
+.br
+Receive <other> \(-> \fIserver_NG\fP
+.RE
+.sp
+.LP
+\fIserver_check\fP
+.RS
+If no more auth data, send 
+.PN XIM_CONNECT_REPLY
+\(-> connect
+.br
+If bad auth data, send 
+.PN XIM_AUTH_NG
+\(-> give up on this protocol
+.br
+If good auth data, send 
+.PN XIM_AUTH_NEXT
+\(-> \fIserver_wait2\fP
+.RE
+.sp
+.LP
+\fIserver_NG\fP
+.RS
+Send 
+.PN XIM_AUTH_NG
+\(-> give up on this protocol
+.RE
+.RE
+.sp
+.LP
+.PN XIM_DISCONNECT 
+message requests to shutdown the connection over a mutually-understood 
+virtual stream.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_DISCONNECT (IM library \(-> IM Server)
+.TE
+.RE
+.LP
+.PN XIM_DISCONNECT
+is a synchronous request.  The IM library should wait until it receives 
+either an 
+.PN XIM_DISCONNECT_REPLY
+packet or an 
+.PN XIM_ERROR
+packet.  
+.LP
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_DISCONNECT_REPLY (IM Server \(-> IM library)
+.TE
+.RE
+.LP
+.PN XIM_OPEN
+requests to establish a logical connection between the IM library and the IM 
+Server. 
+.LP
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_OPEN (IM library \(-> IM Server)
+.sp 6p
+:n:STR:locale name
+:p::unused, p = Pad(n)
+.TE
+.RE
+.LP
+.PN XIM_OPEN
+is a synchronous request.  The IM library should wait until receiving 
+either an 
+.PN XIM_OPEN_REPLY
+packet or an 
+.PN XIM_ERROR 
+packet. 
+.LP
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_OPEN_REPLY (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:n:byte length of IM attributes supported
+:n:LISTofXIMATTR:IM attributes supported
+:2:m:byte length of IC attributes supported
+:2:CARD16:unused
+:m:LISTofXICATTR: IC attributes supported
+.TE
+.RE
+.LP
+.PN XIM_OPEN_REPLY
+message returns all supported IM and IC attributes in LISTofXIMATTR and 
+LISTofXICATTR.  These IM and IC attribute IDs are used to reduce the amount
+of data which must be transferred via the network. In addition, this
+indicates to the IM library what kinds of IM/IC attributes can be used
+in this session, and what types of data will be exchanged. This allows 
+the IM Server provider and application writer to support IM system 
+enhancements with new IM/IC attributes, without modifying Xlib.
+The IC value for the separator of NestedList must be included in the
+LISTofXICATTR.
+.LP
+.PN XIM_CLOSE 
+message requests to shutdown the logical connection between the IM library
+and the IM Server. 
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_CLOSE (IM library \(-> IM Server)
+.sp 6p
+:2:CARD16:input-method-ID
+:2::unused
+.TE
+.RE
+.LP
+.PN XIM_CLOSE
+is a synchronous request.  The IM library should wait until receiving 
+either an 
+.PN XIM_CLOSE_REPLY
+packet or an 
+.PN XIM_ERROR
+packet. 
+.LP
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_CLOSE_REPLY (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2::unused
+.TE
+.RE
+.LP
+.NH 2
+Event Flow Control 
+.XS
+\*(SN Event Flow Control
+.XE
+.LP
+An IM Server must send 
+.PN XIM_SET_EVENT_MASK 
+message to the IM library in order for events to be forwarded to the IM 
+Server, since the IM library initially doesn't forward any events to the 
+IM Server. In the protocol, the IM Server will specify masks of X events 
+to be forwarded and which need to be synchronized by the IM library.
+.LP
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_SET_EVENT_MASK (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:4:EVENTMASK:forward-event-mask (*1)
+:4:EVENTMASK:synchronous-event-mask (*2)
+.TE
+.LP
+.IP (*1)
+Specify all the events to be forwarded to the IM Server by the IM library.
+.IP (*2)
+Specify the events to be forwarded with synchronous flag on by the IM library.
+.RE
+.sp
+.LP
+.PN XIM_SET_EVENT_MASK 
+is an asynchronous request.  The event masks are valid immediately after 
+they are set until changed by another 
+.PN XIM_SET_EVENT_MASK
+message.  If input-context-ID is set to zero, the default value of the 
+input-method-ID will be changed to the event masks specified in the request. 
+That value will be used for the IC's which have no individual values.
+.LP
+Using the Dynamic Event Flow model, an IM Server sends 
+.PN XIM_REGISTER_TRIGGERKEYS 
+message to the IM library before sending
+.PN XIM_OPEN_REPLY
+message.  
+Or the IM library may suppose that the IM Server uses the Static Event Flow 
+model.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_REGISTER_TRIGGERKEYS (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2::unused
+:4:n:byte length of on-keys
+:n:LISTofXIMTRIGGERKEY:on-keys list
+:4:m:byte length of off-keys
+:m:LISTofXIMTRIGGERKEY:off-keys list
+.TE
+.RE
+.LP
+.PN XIM_REGISTER_TRIGGERKEYS 
+is an asynchronous request.  
+The IM Server notifys the IM library of on-keys and off-keys lists with 
+this message.
+.LP
+The IM library notifys the IM Server with 
+.PN XIM_TRIGGER_NOTIFY 
+message that a key event matching either on-keys or off-keys has been occurred.
+.LP
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_TRIGGER_NOTIFY (IM library \(-> IM Server)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:4:CARD32:flag
+::#0:on-keys list
+::#1:off-keys list
+:4:CARD32:index of keys list
+:4:EVENTMASK:client-select-event-mask (*1)
+.TE
+.LP
+.IP (*1) 
+Specify the events currently selected by the IM library with XSelectInput.
+.RE
+.sp
+.LP
+.PN XIM_TRIGGER_NOTIFY 
+is a synchronous request.  The IM library should wait until receiving 
+either an 
+.PN XIM_TRIGGER_NOTIFY_REPLY
+packet or an 
+.PN XIM_ERROR
+packet. 
+.LP
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_TRIGGER_NOTIFY_REPLY (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+.TE
+.RE
+.LP
+.NH 2
+Encoding Negotiation
+.XS
+\*(SN Encoding Negotiation
+.XE
+.LP
+.PN XIM_ENCODING_NEGOTIATION
+message requests to decide which encoding to be sent across the wire.
+When the negotiation fails, the fallback default encoding is Portable 
+Character Encoding.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_ENCODING_NEGOTIATION (IM library \(-> IM Server).sp 6p
+:2:CARD16:input-method-ID
+:2:n:byte length of encodings listed by name
+:n:LISTofSTR:list of encodings supported in the IM library.
+:p::unused, p = Pad(n)
+:2:m:byte length of encodings listed by detailed data
+:2::unused
+:m:LISTofENCODINGINFO:list of encordings supported in the IM library
+.TE
+.RE
+.LP
+The IM Server must choose one encoding from the list sent by the IM library.
+If index of the encording determined is -1 to indicate that the negotiation
+is failed, the fallback default encoding is used. 
+The message must be issued after sending 
+.PN XIM_OPEN
+message via XOpenIM().
+The name of encoding may be registered with X Consortium.
+.LP
+.PN XIM_ENCODING_NEGOTIATION
+is a synchronous request.  The IM library should wait until receiving 
+either an 
+.PN XIM_ENCODING_NEGOTIATION_REPLY
+packet or an 
+.PN XIM_ERROR
+packet. 
+.LP
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_ENCODING_NEGOTIATION_REPLY (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:category of the encoding determined.
+::#0:name
+::#1:detailed data
+:2:INT16:index of the encoding determinated.
+:2::unused
+.TE
+.RE
+.LP
+.NH 2
+Query the supported extension protocol list
+.XS
+\*(SN Query the supported extension protocol list
+.XE
+.LP
+.PN XIM_QUERY_EXTENSION
+message requests to query the IM extensions supported by the IM Server to 
+which the client is being connected. 
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_QUERY_EXTENSION (IM library \(-> IM Server)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:n:T{
+byte length of extensions supported by the IM library
+T}
+:n:LISTofSTR:extensions supported by the IM library
+:p::unused, p = Pad(n)
+.TE
+.RE
+.LP
+An example of a supported extension is FrontEnd.
+The message must be issued after sending 
+.PN XIM_OPEN 
+message via XOpenIM().
+.LP
+If n is 0, the IM library queries the IM Server for all extensions.
+.LP
+If n is not 0, the IM library queries whether the IM Server supports the 
+contents specified in the list.
+.LP
+If a client uses an extension request without previously having issued a
+.PN XIM_QUERY_EXTENSION
+message for that extension, the IM Server responds with a
+.PN BadProtocol
+error.  If the IM Server encounters a request with an unknown MAJOR-OPCODE 
+or MINOR-OPCODE, it responds with a
+.PN BadProtocol
+error.
+.LP
+.PN XIM_QUERY_EXTENSION
+is a synchronous request.  The IM library should wait until receiving 
+either an 
+.PN XIM_QUERY_EXTENSION_REPLY
+packet or an 
+.PN XIM_ERROR
+packet.
+.LP
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_QUERY_EXTENSION_REPLY (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:n:T{
+byte length of extensions supported by both the IM library and the IM Server
+T}
+:n:LISTofEXT:T{
+list of extensions supported by both the IM library and the IM Server
+T}
+.TE
+.RE
+.LP
+.PN XIM_QUERY_EXTENSION_REPLY
+message returns the list of extensions supported by both the IM library and 
+the IM Server. If the list passed in 
+.PN XIM_QUERY_EXTENSION
+message is NULL, the IM Server returns the full list of extensions supported 
+by the IM Server.  If the list is not NULL, the IM Server returns the 
+extensions in the list that are supported by the IM Server.
+.LP
+A zero-length string is not a valid extension name.  The IM library should 
+disregard any zero-length strings that are returned in the extension list.  
+The IM library does not use the requests which are not supported by the IM 
+Server.
+.LP
+.NH 2
+Setting IM Values
+.XS
+\*(SN Setting IM Values
+.XE
+.LP
+.PN XIM_SET_IM_VALUES 
+requests to set attributes to the IM.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_SET_IM_VALUES (IM library \(-> IM Server)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:n:byte length of im-attribute
+:n:LISTofXIMATTRIBUTE:im-attributes
+.TE
+.RE
+.LP
+The im-attributes in 
+.PN XIM_SET_IM_VALUES
+message are specified as a LISTofXIMATTRIBUTE, specifying the attributes 
+to be set. Attributes other than the ones returned by 
+.PN XIM_OPEN_REPLY
+message should not be specified.  
+.LP
+.PN XIM_SET_IM_VALUES 
+is a synchronous request. The IM library should wait until receiving 
+either an 
+.PN XIM_SET_IM_VALUES_REPLY
+packet or an 
+.PN XIM_ERROR
+packet, because it must receive the error attribute if 
+.PN XIM_ERROR
+message is returned.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_SET_IM_VALUES_REPLY (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2::unused
+.TE
+.RE
+.LP
+.PN XIM_SET_IM_VALUES_REPLY
+message returns the input-method-ID to distinguish replies from multiple IMs.
+.LP
+.NH 2
+Getting IM Values
+.XS
+\*(SN getting IM Values
+.XE
+.LP
+.PN XIM_GET_IM_VALUES 
+requests to query IM values supported by the IM Server currently being 
+connected.
+.LP
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_GET_IM_VALUES (IM library \(-> IM Server)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:n:byte length of im-attribute-id
+:n:LISTofCARD16:im-attribute-id
+:p::unused, p=Pad(n)
+.TE
+.RE
+.LP
+.PN XIM_GET_IM_VALUES
+is a synchronous request.  The IM library should wait until it receives 
+either an 
+.PN XIM_GET_IM_VALUES_REPLY
+packet or an 
+.PN XIM_ERROR
+packet.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_GET_IM_VALUES_REPLY (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:n:byte length of im-attributes returned
+:n:LISTofXIMATTRIBUTE:im-attributes returned
+.TE
+.RE
+.LP
+The IM Server returns IM values with 
+.PN XIM_GET_IM_VALUES_REPLY
+message.  The order of the returned im-attribute values corresponds directly
+to that of the list passed with the 
+.PN XIM_GET_IM_VALUES
+message.
+.LP
+.NH 2
+Creating an IC
+.XS
+\*(SN Creating an IC
+.XE
+.LP
+.PN XIM_CREATE_IC
+message requests to create an IC.
+.LP
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_CREATE_IC (IM library \(-> IM Server)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:n:byte length of ic-attributes
+:n:LISTofXICATTRIBUTE:ic-attributes
+.TE
+.RE
+.LP
+The input-context-id is specified by the IM Server to identify the client
+(IC).  (It is not specified by the client in 
+.PN XIM_CREATE_IC
+message.), and it should not be set to zero.
+.LP
+.PN XIM_CREATE_IC
+is a synchronous request which returns the input-context-ID. 
+The IM library should wait until it receives either an 
+.PN XIM_CREATE_IC_REPLY
+packet or an 
+.PN XIM_ERROR
+packet. 
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_CREATE_IC_REPLY (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+.TE
+.RE
+.LP
+.NH 2
+Destroying the IC
+.XS
+\*(SN Destroying the IC
+.XE
+.LP
+.PN XIM_DESTROY_IC
+message requests to destroy the IC.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_DESTROY_IC (IM library \(-> IM Server)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+.TE
+.RE
+.LP
+.PN XIM_DESTROY_IC 
+is a synchronous request. The IM library should not free its resources 
+until it receives an 
+.PN XIM_DESTROY_IC_REPLY
+message because
+.PN XIM_DESTROY_IC
+message may result in Callback packets such as 
+.PN XIM_PREEDIT_DRAW
+and
+.PN XIM_PREEDIT_DONE.
+.LP
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_DESTROY_IC_REPLY (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+.TE
+.RE
+.LP
+.NH 2
+Setting IC Values
+.XS
+\*(SN Setting IC Values
+.XE
+.LP
+.PN XIM_SET_IC_VALUES
+messages requests to set attributes to the IC.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_SET_IC_VALUES (IM library \(-> IM Server)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:2:n:byte length of ic-attributes
+:2::unused
+:n:LISTofXICATTRIBUTE:ic-attributes
+.TE
+.RE
+.LP
+The ic-attributes in 
+.PN XIM_SET_IC_VALUES
+message are specified as a LISTofXICATTRIBUTE, specifying the attributes 
+to be set. Attributes other than the ones returned by 
+.PN XIM_OPEN_REPLY
+message should not be specified. 
+.LP
+.PN XIM_SET_IC_VALUES 
+is a synchronous request. The IM library should wait until receiving 
+either an 
+.PN XIM_SET_IC_VALUES_REPLY 
+packet or an 
+.PN XIM_ERROR
+packet, because it must receive the error attribute if 
+.PN XIM_ERROR
+message is returned. 
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_SET_IC_VALUES_REPLY (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+.TE
+.RE
+.LP
+.NH 2
+Getting IC Values
+.XS
+\*(SN Getting IC Values
+.XE
+.LP
+.PN XIM_GET_IC_VALUES
+message requests to query IC values supported by the IM Server currently
+being connected.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_GET_IC_VALUES (IM library \(-> IM Server)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:2:n:byte length of ic-attribute-id
+:n:LISTofCARD16:ic-attribute-id
+:p::unused, p=Pad(2+n)
+.TE
+.RE
+.LP
+In LISTofCARD16, the appearance of the ic-attribute-id for the separator 
+of NestedList shows the end of the heading nested list.
+.LP
+.PN XIM_GET_IC_VALUES
+is a synchronous request and returns each attribute with its values to 
+show the correspondence.  The IM library should wait until receiving 
+either an 
+.PN XIM_GET_IC_VALUES_REPLY
+packet or an 
+.PN XIM_ERROR
+packet.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_GET_IC_VALUES_REPLY (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:2:n:byte length of ic-attribute 
+:2::unused
+:n:LISTofXICATTRIBUTE:ic-attribute
+.TE
+.RE
+.LP
+.NH 2
+Setting IC Focus
+.XS
+\*(SN Setting IC Focus
+.XE
+.LP
+.PN XIM_SET_IC_FOCUS
+message requests to set the focus to the IC.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_SET_IC_FOCUS (IM library \(-> IM Server)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+.TE
+.RE
+.LP
+.PN XIM_SET_IC_FOCUS
+is an asynchronous request.
+.LP
+.NH 2
+Unsetting IC Focus
+.XS
+\*(SN Unsetting IC Focus
+.XE
+.LP
+.PN XIM_UNSET_IC_FOCUS
+message requests to unset the focus to the focused IC.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_UNSET_IC_FOCUS (IM library \(-> IM Server)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+.TE
+.RE
+.LP
+.PN XIM_UNSET_IC_FOCUS
+is an asynchronous request.
+.LP
+.NH 2
+Filtering Events
+.XS
+\*(SN Filtering Events
+.XE
+.LP
+Event filtering is mainly provided for BackEnd method to allow input method
+to capture X events transparently to clients.
+.LP
+X Events are forwarded by 
+.PN XIM_FORWARD_EVENT
+message.
+This message can be operated both synchronously and asynchronously. 
+If the requester sets the synchronous flag, the receiver must send 
+.PN XIM_SYNC_REPLY
+message back to the requester when all the data processing is done.
+.sp
+.B
+Protocol flow of BackEnd model
+.R
+.LP
+.LP
+With BackEnd method, the protocol flow can be classified into two
+methods in terms of synchronization, depending on the synchronous-eventmask
+of 
+.PN XIM_SET_EVENT_MASK
+message.  One can be called on-demand-synchronous method and another
+can be called as full-synchronous method.
+.LP
+In on-demand-synchronous method, the IM library always receives
+.PN XIM_FORWARD_EVENT
+or
+.PN XIM_COMMIT
+message as a synchronous request. Also, the IM Server needs to synchronously 
+process the correspondent reply from the IM library and the following 
+.PN XIM_FORWARD_EVENT
+message sent from the IM library when any of the event causes the IM Server 
+to send 
+.PN XIM_FORWARD_EVENT
+or
+.PN XIM_COMMIT
+message to the IM library, so that the input service is consistent.  If the 
+IM library gets the control back from the application after receiving the 
+synchronous request, the IM library replies for the synchronous request before 
+processing any of the events. In this time, the IM Server blocks 
+.PN XIM_FORWARD_EVENT
+message which is sent by the IM library, and handles it after receiving the 
+reply. However, the IM Server handles the other protocols at any time.
+.LP
+In full-synchronous method, the IM library always sends 
+.PN XIM_FORWARD_EVENT
+message to the IM Server as a synchronous request. Therefore, the reply to it 
+from the IM Server will be put between the 
+.PN XIM_FORWARD_EVENT
+message and its 
+.PN XIM_SYNC_REPLY
+message.
+In case of sending 
+.PN XIM_FORWARD_EVENT
+or
+.PN XIM_COMMIT
+message, the IM Server should set the synchronous flag off. Because the 
+synchronization can be done by the following 
+.PN XIM_SYNC_REPLY
+message.
+.sp
+.LP
+.B
+Sample Protocol flow chart 1
+.R
+.LP
+Following chart shows one of the simplest protocol flow which only
+deals with keyevents for preediting operation.
+.LP
+.\"====================== event flow figure start =====================
+\^... 0.425 6.888 6.3 10.296
+\^... 0.000i 3.408i 5.875i 0.000i
+.nr 00 \n(.u
+.nf
+.PS 3.408i 5.875i 
+.br
+.ps 11
+\h'3.125i'\v'0.496i'\D'l1.625i 0.250i'
+.sp -1
+\h'4.647i'\v'0.756i'\D'l0.103i -0.010i'
+.sp -1
+\h'4.655i'\v'0.706i'\D'l0.095i 0.040i'
+.sp -1
+\h'3.125i'\v'1.221i'\D'l1.687i 0.188i'
+.sp -1
+\h'4.710i'\v'1.423i'\D'l0.102i -0.014i'
+.sp -1
+\h'4.715i'\v'1.373i'\D'l0.097i 0.036i'
+.sp -1
+\h'4.750i'\v'0.971i'\D'l-1.625i 0.438i'
+.sp -1
+\h'3.215i'\v'1.359i'\D'l-0.090i 0.050i'
+.sp -1
+\h'3.228i'\v'1.407i'\D'l-0.103i 0.002i'
+.sp -1
+\h'2.000i'\v'0.409i'\D'l1.000i 0.062i'
+.sp -1
+\h'2.899i'\v'0.490i'\D'l0.101i -0.019i'
+.sp -1
+\h'2.902i'\v'0.440i'\D'l0.098i 0.031i'
+.sp -1
+\h'2.000i'\v'1.034i'\D'l1.000i 0.125i'
+.sp -1
+\h'2.898i'\v'1.171i'\D'l0.102i -0.012i'
+.sp -1
+\h'2.904i'\v'1.122i'\D'l0.096i 0.037i'
+.sp -1
+\h'3.000i'\v'1.409i'\D'l-1.000i 0.062i'
+.sp -1
+\h'2.098i'\v'1.440i'\D'l-0.098i 0.031i'
+.sp -1
+\h'2.101i'\v'1.490i'\D'l-0.101i -0.019i'
+.sp -1
+\h'1.125i'\v'1.846i'\l'-0.500i'
+.sp -1
+\h'0.725i'\v'1.821i'\D'l-0.100i 0.025i'
+.sp -1
+\h'0.725i'\v'1.871i'\D'l-0.100i -0.025i'
+.sp -1
+\h'0.688i'\v'0.159i'\l'0.437i'
+.sp -1
+\h'1.025i'\v'0.184i'\D'l0.100i -0.025i'
+.sp -1
+\h'1.025i'\v'0.134i'\D'l0.100i 0.025i'
+.sp -1
+\h'0.688i'\v'0.846i'\l'0.437i'
+.sp -1
+\h'1.025i'\v'0.871i'\D'l0.100i -0.025i'
+.sp -1
+\h'1.025i'\v'0.821i'\D'l0.100i 0.025i'
+.sp -1
+\h'5.562i'\v'1.409i'\l'0.313i'
+.sp -1
+\h'5.875i'\v'1.409i'\v'-.13m'\L'1.937i\(br'\v'.13m'
+.sp -1
+\h'5.875i'\v'3.346i'\D'l-0.250i 0.000i'
+.sp -1
+\h'5.725i'\v'3.321i'\D'l-0.100i 0.025i'
+.sp -1
+\h'5.725i'\v'3.371i'\D'l-0.100i -0.025i'
+.sp -1
+\h'2.062i'\v'2.096i'\l'0.875i'
+.sp -1
+\h'2.837i'\v'2.121i'\D'l0.100i -0.025i'
+.sp -1
+\h'2.837i'\v'2.071i'\D'l0.100i 0.025i'
+.sp -1
+\h'3.000i'\v'0.034i'\v'-.13m'\L'3.374i\(br'\v'.13m'
+.sp -1
+\h'4.875i'\v'0.034i'\v'-.13m'\L'3.374i\(br'\v'.13m'
+.sp -1
+\h'2.013i'\v'2.871i'\D'l0.937i 0.250i'
+.sp -1
+\h'2.847i'\v'3.119i'\D'l0.103i 0.002i'
+.sp -1
+\h'2.860i'\v'3.071i'\D'l0.090i 0.050i'
+.sp -1
+\h'3.062i'\v'3.134i'\D'l1.688i 0.187i'
+.sp -1
+\h'4.648i'\v'3.335i'\D'l0.102i -0.014i'
+.sp -1
+\h'4.653i'\v'3.285i'\D'l0.097i 0.036i'
+.sp -1
+\h'3.062i'\v'2.533i'\D'l1.750i 0.213i'
+.sp -1
+\h'4.710i'\v'2.759i'\D'l0.102i -0.013i'
+.sp -1
+\h'4.716i'\v'2.709i'\D'l0.096i 0.037i'
+.sp -1
+\h'3.062i'\v'2.096i'\l'1.750i'
+.sp -1
+\h'4.712i'\v'2.121i'\D'l0.100i -0.025i'
+.sp -1
+\h'4.712i'\v'2.071i'\D'l0.100i 0.025i'
+.sp -1
+\h'4.812i'\v'2.284i'\l'-1.750i'
+.sp -1
+\h'3.162i'\v'2.259i'\D'l-0.100i 0.025i'
+.sp -1
+\h'3.162i'\v'2.309i'\D'l-0.100i -0.025i'
+.sp -1
+\h'1.250i'\v'0.193i'\h'-0.0m'\v'0.2m'\s10\fRXNextEvent\fP
+.sp -1
+\h'1.250i'\v'0.381i'\h'-0.0m'\v'0.2m'\s10\fRXFilterEvent\fP
+.sp -1
+\h'1.250i'\v'0.881i'\h'-0.0m'\v'0.2m'\s10\fRXNextEvent\fP
+.sp -1
+\h'1.250i'\v'1.068i'\h'-0.0m'\v'0.2m'\s10\fRXFilterEvent\fP
+.sp -1
+\h'1.250i'\v'1.506i'\h'-0.0m'\v'0.2m'\s10\fRXNextEvent\fP
+.sp -1
+\h'1.250i'\v'1.881i'\h'-0.0m'\v'0.2m'\s10\fRXmbLookupString\fP
+.sp -1
+\h'4.875i'\h'-0.0m'\v'0.2m'\s12\fRIM Server\fP
+.sp -1
+\h'2.437i'\h'-0.0m'\v'0.2m'\s12\fRIM library\fP
+.sp -1
+\h'1.250i'\v'1.693i'\h'-0.0m'\v'0.2m'\s10\fRXFilterEvent (returns False)   \fP
+.sp -1
+\v'2.168i'\h'-0.0m'\v'0.2m'\s10\fRthe focus\fP
+.sp -1
+\h'1.250i'\h'-0.0m'\v'0.2m'\s12\fRXlib API\fP
+.sp -1
+\v'2.006i'\h'-0.0m'\v'0.2m'\s10\fRApplication moves\fP
+.sp -1
+\h'3.187i'\v'0.443i'\h'-0.0m'\v'0.2m'\s10\fRXIM_FORWARD_EVENT\fP
+.sp -1
+\h'3.187i'\v'0.881i'\h'-0.0m'\v'0.2m'\s10\fRXIM_FORWARD_EVENT\fP
+.sp -1
+\h'3.187i'\v'1.631i'\h'-0.0m'\v'0.2m'\s10\fRXIM_FORWARD_EVENT\fP
+.sp -1
+\h'3.187i'\v'1.006i'\h'-0.0m'\v'0.2m'\s10\fRor XIM_COMMIT\fP
+.sp -1
+\h'5.000i'\v'0.881i'\h'-0.0m'\v'0.2m'\s10\fRsynchronous \fP
+.sp -1
+\h'5.000i'\v'1.006i'\h'-0.0m'\v'0.2m'\s10\fRrequest\fP
+.sp -1
+\h'0.062i'\v'0.193i'\h'-0.0m'\v'0.2m'\s10\fRKey event\fP
+.sp -1
+\h'0.062i'\v'0.881i'\h'-0.0m'\v'0.2m'\s10\fRKey event\fP
+.sp -1
+\h'3.187i'\v'1.131i'\h'-0.0m'\v'0.2m'\s10\fR(synchronous)   \fP
+.sp -1
+\h'5.000i'\v'1.443i'\h'-0.0m'\v'0.2m'\s10\fRPending\fP
+.sp -1
+\h'5.000i'\v'2.381i'\h'-0.0m'\v'0.2m'\s10\fRprocessed\fP
+.sp -1
+\h'5.000i'\v'2.506i'\h'-0.0m'\v'0.2m'\s10\fR(The focused\fP
+.sp -1
+\h'5.000i'\v'2.631i'\h'-0.0m'\v'0.2m'\s10\fRIC is changed)  \fP
+.sp -1
+\h'5.000i'\v'2.881i'\h'-0.0m'\v'0.2m'\s10\fRprocessed\fP
+.sp -1
+\h'1.250i'\v'2.131i'\h'-0.0m'\v'0.2m'\s10\fRXSetICFocus\fP
+.sp -1
+\h'3.125i'\v'2.881i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SYNC_REPLY as a reply\fP
+.sp -1
+\h'3.125i'\v'3.043i'\h'-0.0m'\v'0.2m'\s10\fRof the XIM_FORWARD_EVENT\fP
+.sp -1
+\h'1.250i'\v'2.881i'\h'-0.0m'\v'0.2m'\s10\fRXNextEvent\fP
+.sp -1
+\h'3.312i'\v'2.506i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SET_IC_FOCUS\fP
+.sp -1
+\h'3.312i'\v'2.006i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SYNC\fP
+.sp -1
+\h'3.312i'\v'2.193i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SYNC_REPLY\fP
+.sp -1
+\h'5.000i'\v'3.381i'\h'-0.0m'\v'0.2m'\s10\fRprocessed\fP
+.sp -1
+.sp 1+3.408i
+.PE
+.if \n(00 .fi
+
+.\"====================== event flow figure end =======================
+.ce
+.sp
+Fig.2 Sample Protocol Flow
+.sp
+.LP
+.B
+Sample Protocol flow chart 2
+.R
+.LP
+Following chart shows one of the complex protocol flow, which deals
+with multiple focus windows and button press event as well as keyevent,
+and the focus is moved by the application triggered by both of keyevent
+and button press event.
+.LP
+.bp
+.\"====================== event2 flow figure start =====================
+\^... 0.425 5.575 6.3 10.296
+\^... 0.000i 4.721i 5.875i 0.000i
+.nr 00 \n(.u
+.nf
+.PS 4.721i 5.875i 
+.br
+.ps 11
+\h'3.125i'\v'0.496i'\D'l1.625i 0.163i'
+.sp -1
+\h'4.648i'\v'0.674i'\D'l0.102i -0.015i'
+.sp -1
+\h'4.653i'\v'0.624i'\D'l0.097i 0.035i'
+.sp -1
+\h'2.000i'\v'0.409i'\D'l1.000i 0.062i'
+.sp -1
+\h'2.899i'\v'0.490i'\D'l0.101i -0.019i'
+.sp -1
+\h'2.902i'\v'0.440i'\D'l0.098i 0.031i'
+.sp -1
+\h'0.688i'\v'0.159i'\l'0.437i'
+.sp -1
+\h'1.025i'\v'0.184i'\D'l0.100i -0.025i'
+.sp -1
+\h'1.025i'\v'0.134i'\D'l0.100i 0.025i'
+.sp -1
+\h'1.250i'\v'0.193i'\h'-0.0m'\v'0.2m'\s10\fRXNextEvent\fP
+.sp -1
+\h'1.250i'\v'0.381i'\h'-0.0m'\v'0.2m'\s10\fRXFilterEvent\fP
+.sp -1
+\h'3.187i'\v'0.443i'\h'-0.0m'\v'0.2m'\s10\fRXIM_FORWARD_EVENT\fP
+.sp -1
+\h'0.062i'\v'0.193i'\h'-0.0m'\v'0.2m'\s10\fRKey event\fP
+.sp -1
+\h'3.125i'\v'1.221i'\D'l1.687i 0.125i'
+.sp -1
+\h'4.710i'\v'1.364i'\D'l0.102i -0.018i'
+.sp -1
+\h'4.714i'\v'1.314i'\D'l0.098i 0.032i'
+.sp -1
+\h'4.750i'\v'0.971i'\D'l-1.625i 0.750i'
+.sp -1
+\h'3.205i'\v'1.656i'\D'l-0.080i 0.065i'
+.sp -1
+\h'3.226i'\v'1.702i'\D'l-0.101i 0.019i'
+.sp -1
+\h'2.000i'\v'1.034i'\D'l1.000i 0.125i'
+.sp -1
+\h'2.898i'\v'1.171i'\D'l0.102i -0.012i'
+.sp -1
+\h'2.904i'\v'1.122i'\D'l0.096i 0.037i'
+.sp -1
+\h'0.688i'\v'0.846i'\l'0.437i'
+.sp -1
+\h'1.025i'\v'0.871i'\D'l0.100i -0.025i'
+.sp -1
+\h'1.025i'\v'0.821i'\D'l0.100i 0.025i'
+.sp -1
+\h'3.000i'\v'0.034i'\v'-.13m'\L'4.687i\(br'\v'.13m'
+.sp -1
+\h'0.750i'\v'1.346i'\l'0.313i'
+.sp -1
+\h'0.963i'\v'1.371i'\D'l0.100i -0.025i'
+.sp -1
+\h'0.963i'\v'1.321i'\D'l0.100i 0.025i'
+.sp -1
+\h'3.125i'\v'1.509i'\D'l1.687i 0.125i'
+.sp -1
+\h'4.710i'\v'1.652i'\D'l0.102i -0.018i'
+.sp -1
+\h'4.714i'\v'1.602i'\D'l0.098i 0.032i'
+.sp -1
+\h'4.812i'\v'1.721i'\D'l-1.687i 0.188i'
+.sp -1
+\h'3.222i'\v'1.873i'\D'l-0.097i 0.036i'
+.sp -1
+\h'3.227i'\v'1.923i'\D'l-0.102i -0.014i'
+.sp -1
+\h'2.937i'\v'1.971i'\D'l-0.937i 0.188i'
+.sp -1
+\h'2.093i'\v'2.115i'\D'l-0.093i 0.044i'
+.sp -1
+\h'2.103i'\v'2.164i'\D'l-0.103i -0.005i'
+.sp -1
+\h'1.125i'\v'2.533i'\l'-0.500i'
+.sp -1
+\h'0.725i'\v'2.508i'\D'l-0.100i 0.025i'
+.sp -1
+\h'0.725i'\v'2.558i'\D'l-0.100i -0.025i'
+.sp -1
+\h'5.562i'\v'1.346i'\l'0.313i'
+.sp -1
+\h'5.875i'\v'1.346i'\v'-.13m'\L'2.687i\(br'\v'.13m'
+.sp -1
+\h'5.875i'\v'4.033i'\D'l-0.250i 0.000i'
+.sp -1
+\h'5.725i'\v'4.008i'\D'l-0.100i 0.025i'
+.sp -1
+\h'5.725i'\v'4.058i'\D'l-0.100i -0.025i'
+.sp -1
+\h'2.013i'\v'3.559i'\D'l0.937i 0.250i'
+.sp -1
+\h'2.847i'\v'3.807i'\D'l0.103i 0.002i'
+.sp -1
+\h'2.860i'\v'3.759i'\D'l0.090i 0.050i'
+.sp -1
+\h'3.062i'\v'3.821i'\D'l1.688i 0.188i'
+.sp -1
+\h'4.648i'\v'4.023i'\D'l0.102i -0.014i'
+.sp -1
+\h'4.653i'\v'3.973i'\D'l0.097i 0.036i'
+.sp -1
+\h'2.000i'\v'1.358i'\D'l1.000i 0.126i'
+.sp -1
+\h'2.898i'\v'1.496i'\D'l0.102i -0.012i'
+.sp -1
+\h'2.904i'\v'1.447i'\D'l0.096i 0.037i'
+.sp -1
+\h'3.062i'\v'2.159i'\D'l-0.250i 0.000i'
+.sp -1
+\h'2.812i'\v'2.159i'\v'-.13m'\L'1.812i\(br'\v'.13m'
+.sp -1
+\h'2.812i'\v'3.971i'\D'l0.125i 0.125i'
+.sp -1
+\h'2.849i'\v'4.043i'\D'l0.088i 0.053i'
+.sp -1
+\h'2.884i'\v'4.008i'\D'l0.053i 0.088i'
+.sp -1
+\h'2.062i'\v'2.783i'\l'0.875i'
+.sp -1
+\h'2.837i'\v'2.808i'\D'l0.100i -0.025i'
+.sp -1
+\h'2.837i'\v'2.758i'\D'l0.100i 0.025i'
+.sp -1
+\h'2.062i'\v'3.783i'\D'l0.813i 0.438i'
+.sp -1
+\h'2.775i'\v'4.196i'\D'l0.100i 0.025i'
+.sp -1
+\h'2.799i'\v'4.152i'\D'l0.076i 0.069i'
+.sp -1
+\h'0.625i'\v'3.533i'\l'0.438i'
+.sp -1
+\h'0.963i'\v'3.558i'\D'l0.100i -0.025i'
+.sp -1
+\h'0.963i'\v'3.508i'\D'l0.100i 0.025i'
+.sp -1
+\h'3.062i'\v'4.346i'\D'l1.625i 0.163i'
+.sp -1
+\h'4.585i'\v'4.524i'\D'l0.102i -0.015i'
+.sp -1
+\h'4.590i'\v'4.474i'\D'l0.097i 0.035i'
+.sp -1
+\h'4.875i'\v'0.034i'\v'-.13m'\L'4.687i\(br'\v'.13m'
+.sp -1
+\h'3.062i'\v'4.146i'\D'l1.688i 0.187i'
+.sp -1
+\h'4.648i'\v'4.347i'\D'l0.102i -0.014i'
+.sp -1
+\h'4.653i'\v'4.297i'\D'l0.097i 0.036i'
+.sp -1
+\h'3.062i'\v'2.871i'\D'l1.750i 0.212i'
+.sp -1
+\h'4.710i'\v'3.096i'\D'l0.102i -0.013i'
+.sp -1
+\h'4.716i'\v'3.046i'\D'l0.096i 0.037i'
+.sp -1
+\h'1.250i'\v'0.881i'\h'-0.0m'\v'0.2m'\s10\fRXNextEvent\fP
+.sp -1
+\h'1.250i'\v'1.068i'\h'-0.0m'\v'0.2m'\s10\fRXFilterEvent\fP
+.sp -1
+\h'4.875i'\h'-0.0m'\v'0.2m'\s12\fRIM Server\fP
+.sp -1
+\h'2.437i'\h'-0.0m'\v'0.2m'\s12\fRIM library\fP
+.sp -1
+\h'1.250i'\h'-0.0m'\v'0.2m'\s12\fRXlib API\fP
+.sp -1
+\h'3.187i'\v'0.881i'\h'-0.0m'\v'0.2m'\s10\fRXIM_FORWARD_EVENT\fP
+.sp -1
+\h'5.000i'\v'0.881i'\h'-0.0m'\v'0.2m'\s10\fRsynchronous \fP
+.sp -1
+\h'5.000i'\v'1.006i'\h'-0.0m'\v'0.2m'\s10\fRrequest\fP
+.sp -1
+\h'0.062i'\v'0.881i'\h'-0.0m'\v'0.2m'\s10\fRKey event\fP
+.sp -1
+\h'3.187i'\v'1.131i'\h'-0.0m'\v'0.2m'\s10\fR(synchronous)   \fP
+.sp -1
+\h'0.062i'\v'1.256i'\h'-0.0m'\v'0.2m'\s10\fRButton press causes\fP
+.sp -1
+\h'0.062i'\v'1.381i'\h'-0.0m'\v'0.2m'\s10\fRfocus change\fP
+.sp -1
+\h'1.250i'\v'1.381i'\h'-0.0m'\v'0.2m'\s10\fRXSetICFocus\fP
+.sp -1
+\h'3.250i'\v'1.006i'\h'-0.0m'\v'0.2m'\s10\fRor XIM_COMMIT\fP
+.sp -1
+\h'3.187i'\v'1.443i'\h'-0.0m'\v'0.2m'\s10\fRXIM_FORWARD_EVENT\fP
+.sp -1
+\h'3.687i'\v'1.693i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SYNC\fP
+.sp -1
+\h'3.375i'\v'2.006i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SYNC_REPLY\fP
+.sp -1
+\h'1.250i'\v'2.193i'\h'-0.0m'\v'0.2m'\s10\fRXNextEvent\fP
+.sp -1
+\h'1.250i'\v'2.568i'\h'-0.0m'\v'0.2m'\s10\fRXmbLookupString\fP
+.sp -1
+\h'1.250i'\v'2.381i'\h'-0.0m'\v'0.2m'\s10\fRXFilterEvent (returns False)   \fP
+.sp -1
+\v'2.856i'\h'-0.0m'\v'0.2m'\s10\fRthe focus\fP
+.sp -1
+\v'2.693i'\h'-0.0m'\v'0.2m'\s10\fRApplication moves\fP
+.sp -1
+\h'5.000i'\v'3.068i'\h'-0.0m'\v'0.2m'\s10\fRprocessed\fP
+.sp -1
+\h'5.000i'\v'3.193i'\h'-0.0m'\v'0.2m'\s10\fR(The focused\fP
+.sp -1
+\h'5.000i'\v'3.318i'\h'-0.0m'\v'0.2m'\s10\fRIC is changed)  \fP
+.sp -1
+\h'5.000i'\v'3.568i'\h'-0.0m'\v'0.2m'\s10\fRprocessed\fP
+.sp -1
+\h'3.125i'\v'3.568i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SYNC_REPLY as a reply\fP
+.sp -1
+\h'3.125i'\v'3.731i'\h'-0.0m'\v'0.2m'\s10\fRof the XIM_FORWARD_EVENT\fP
+.sp -1
+\h'1.250i'\v'3.568i'\h'-0.0m'\v'0.2m'\s10\fRXNextEvent\fP
+.sp -1
+\h'5.000i'\v'4.068i'\h'-0.0m'\v'0.2m'\s10\fRprocessed\fP
+.sp -1
+\h'5.000i'\v'1.381i'\h'-0.0m'\v'0.2m'\s10\fRPending\fP
+.sp -1
+\h'5.000i'\v'4.256i'\h'-0.0m'\v'0.2m'\s10\fRprocessed\fP
+.sp -1
+\h'1.250i'\v'2.818i'\h'-0.0m'\v'0.2m'\s10\fRXSetICFocus\fP
+.sp -1
+\h'3.125i'\v'2.443i'\h'-0.0m'\v'0.2m'\s10\fRis started by XIM_COMMIT\fP
+.sp -1
+\h'3.125i'\v'2.193i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SET_IC_FOCUS is\fP
+.sp -1
+\h'3.125i'\v'2.318i'\h'-0.0m'\v'0.2m'\s10\fRpend because another sync cycle\fP
+.sp -1
+\h'2.062i'\v'1.693i'\h'-0.0m'\v'0.2m'\s10\fRsync cycle is done\fP
+.sp -1
+\h'2.062i'\v'1.568i'\h'-0.0m'\v'0.2m'\s10\fRPending until\fP
+.sp -1
+\v'3.568i'\h'-0.0m'\v'0.2m'\s10\fRKey event\fP
+.sp -1
+\h'1.250i'\v'3.756i'\h'-0.0m'\v'0.2m'\s10\fRXFilterEvent\fP
+.sp -1
+\h'3.125i'\v'4.631i'\h'-0.0m'\v'0.2m'\s10\fRXIM_FORWARD_EVENT\fP
+.sp -1
+\h'3.375i'\v'4.131i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SET_IC_FOCUS\fP
+.sp -1
+\h'3.250i'\v'2.818i'\h'-0.0m'\v'0.2m'\s10\fRXIM_SET_IC_FOCUS\fP
+.sp -1
+.sp 1+4.721i
+.PE
+.if \n(00 .fi
+
+.\"====================== event2 flow figure end =======================
+.ce
+.sp
+Fig.3 Sample Protocol Flow chart
+.LP
+.LP
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_FORWARD_EVENT (IM library \(<-\(-> IM Server)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:2:BITMASK16:flag
+::#0001:synchronous
+::#0002:request filtering (*1)
+::#0004:request lookupstring (*2)
+:2:CARD16:serial number
+::XEVENT:X event
+.TE
+.LP
+.IP (*1)
+Indicate the receiver should filter events and possible preedit may be invoked.
+.IP (*2)
+Indicate the receiver should only do lookup string. The IM Server is expected
+to just do a conversion of the key event to the best candidate. This bit may
+affect the state of the preedit state (e.g. compose of dead key sequences).
+.RE
+.LP
+XEVENT format is same as the X Protocol event format(xEvent).
+As the value of xEvent's sequenceNumber is the bottom of 16 bit of XEvent's 
+xany.serial, the top of 16 bit is sent by serial number(INT16).
+.LP
+.PN XIM_FORWARD_EVENT
+message is used for forwarding the events from the IM library to the IM Server 
+in order for IM to be able to filter the event. On the other hand, this 
+message is also used for forwarding the events from the IM Server to the IM 
+library if the event forwarded from the IM library is not filtered. 
+The IM Server, which receives 
+.PN XIM_FORWARD_EVENT
+message without synchronous bit, should set synchronous bit.
+If both ``request event filtering'' and ``request lookupstring'' flag are
+set, then both filtering and lookup should be done for the same event.
+.LP
+.NH 2
+Synchronizing with the IM Server
+.XS
+\*(SN Synchronizing with the IM Server
+.XE
+.LP
+.PN XIM_SYNC
+message requests to synchronize the IM library and the IM Server. 
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_SYNC (IM library \(<-\(-> IM Server)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+.TE
+.RE
+.LP
+This synchronization can be started either on the IM library side or on the 
+IM Server side.  The side which receives 
+.PN XIM_SYNC
+message should process all XIM requests before replying. The input-context-ID 
+is necessary to distinguish the IC with which the IM library and the IM 
+Server are synchronized.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_SYNC_REPLY (IM Server \(<-\(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+.TE
+.RE
+.LP
+The side which receives 
+.PN XIM_FORWARD_EVENT, 
+.PN XIM_COMMIT
+or any other message with synchronous bit, should process all XIM request 
+before replying, and send 
+.PN XIM_SYNC_REPLY
+message as the reply to the previous message. 
+.LP
+.NH 2
+Sending a committed string
+.XS
+\*(SN Sending a committed string
+.XE
+.LP
+When the IM Server commits a string, the IM Server sends either the committed 
+string or list of KeySym, or both, by 
+.PN XIM_COMMIT
+message.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_COMMIT (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:2:BITMASK16:flag
+::#0001:synchronous
+::#0002:XLookupChars
+::#0004:XLookupKeySym
+::#0006: XLookupBoth = XLookupChars | XLookupKeySym
+.TE
+.LP
+If flag is XLookupKeySym, the arguments continue as follows:
+.TS
+tab(:);
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+:2::unused
+:4:KEYSYM:KeySym
+.TE
+.LP
+If flag is XLookupChars, the arguments continue as follows:
+.TS
+tab(:);
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+:2:m:byte length of committed string
+:m:LISTofBYTE:committed string
+:p::unused, p = Pad(m)
+.TE
+.LP
+If flag is XLookupBoth, the arguments continue as follows:
+.TS
+tab(:);
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+:2::unused
+:4:KEYSYM:KeySym
+:2:n:byte length of committed string
+:n:LISTofBYTE:committed string
+:p::unused, p = Pad(2+n)
+.TE
+.RE
+.LP
+The IM Server which receives 
+.PN XIM_COMMIT
+message without synchronous bit should set synchronous bit.
+.LP
+.NH 2
+Reset IC
+.XS
+\*(SN Reset IC
+.XE
+.LP
+.PN XIM_RESET_IC
+message requests to reset the status of IC in the IM Server. 
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_RESET_IC (IM library \(-> IM Server)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+.TE
+.RE
+.LP
+.PN XIM_RESET_IC
+is a synchronous request. The IM library should wait until receiving either an 
+.PN XIM_RESET_IC_REPLY
+packet or an 
+.PN XIM_ERROR
+packet.
+.LP
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_RESET_IC_REPLY (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:2:n:byte length of preedit string
+:n:LISTofBYTE:preedit string
+:p::unused, p = Pad(2+n)
+.TE
+.RE
+.LP
+.PN XIM_RESET_IC_REPLY 
+message returns the input-context-ID to distinguish replies from multiple ICs.
+.LP
+.\"============================== Callbacks ===============================
+.NH 2
+Callbacks
+.XS
+\*(SN Callbacks
+.XE
+.LP
+If XIMStyle has XIMPreeditArea or XIMStatusArea set, XIMGeometryCallback 
+may be used, and if XIMPreeditCallback and/or XIMStatusCallback are set,
+corresponding callbacks may be used.
+.LP
+Any callback request may be sent from an IM Server to an IM client 
+asynchronously in response to any request previously sent by the IM client 
+to the IM Server.
+.LP
+When an IM Server needs to send a callback request synchronously with
+the request previously sent by an IM client, the IM Server sends it
+before replying to the previous request.
+.LP
+.NH 3
+Negotiating geometry
+.XS
+\*(SN Negotiating geometry
+.XE
+.LP
+The IM Server sends
+.PN XIM_GEOMETRY 
+message to start geometry negotiation, if XIMStyle has XIMPreeditArea or 
+XIMStatusArea set.  
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_GEOMETRY (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+.TE
+.RE
+.LP
+There is always a single Focus Window, even if some input fields have only 
+one IC.
+.LP
+.NH 3
+Converting a string
+.XS
+\*(SN Converting a string
+.XE
+.LP
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_STR_CONVERSION (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:2:CARD16:XIMStringConversionPosition
+:2::unused
+:4:CARD32:XIMCaretDirection
+::#0:XIMForwardChar
+::#1:XIMBackwardChar
+::#2:XIMForwardWord
+::#3:XIMBackwardWord
+::#4:XIMCaretUp
+::#5:XIMCaretDown
+::#6:XIMNextLine
+::#7:XIMCPreviousLine
+::#8:XIMLineStart
+::#9:XIMLineEnd
+::#10:XIMAbsolutePosition
+::#11:XIMDontChange
+:2:CARD16:factor
+:2:CARD16:XIMStringConversionOperation
+::#0001:XIMStringConversionSubstitution
+::#0002:XIMStringConversionRetrieval
+:2:INT16:T{
+byte length to multiply the XIMStringConversionType
+T}
+.TE
+.RE
+.sp
+.LP
+.PN XIM_STR_CONVERSION 
+message may be used to start the string conversion from the IM 
+Server.
+.LP
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_STR_CONVERSION_REPLY (IM library \(-> IM Server)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:4:CARD32:XIMStringConversionFeedback
+::XIMSTRCONVTEXT:XIMStringConversionText
+.sp
+.TE
+.RE
+.LP
+.PN XIM_STR_CONVERSION_REPLY 
+message returns the string to be converted and the feedback information array.
+.LP
+.NH 3
+Preedit Callbacks
+.XS
+\*(SN Preedit Callbacks
+.XE
+.LP
+The IM Server sends
+.PN XIM_PREEDIT_START 
+message to call the XIMPreeditStartCallback function.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_PREEDIT_START (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+.TE
+.RE
+.LP
+The reply to this message must be sent synchronously. The reply forwards 
+the return value from the callback function to the IM Server.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_PREEDIT_START_REPLY (IM library \(-> IM Server)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:4:INT32:return value
+.TE
+.RE
+.LP
+.PN XIM_PREEDIT_START_REPLY
+message returns the input-context-ID to distinguish replies from multiple 
+IC's.  The return value contains the return value of the function 
+XIMPreeditStartCallback.
+.LP
+The IM Server sends
+.PN XIM_PREEDIT_DRAW 
+message to call the XIMPreeditDrawCallback function.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_PREEDIT_DRAW (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:4:INT32:caret
+:4:INT32:chg_first
+:4:INT32:chg_length
+:4:BITMASK32:status
+::#x0000001:no string
+::#x0000002:no feedback
+:2:n:length of preedit string
+:n:STRING8:preedit string
+:p::unused, p = Pad(2+n)
+:2:m:byte length of feedback array
+:2::unused
+:m:LISTofXIMFEEDBACK:feedback array
+.TE
+.RE
+.LP
+The fields ``caret'', ``chg_first'' and ``chg_length'' correspond to the 
+fields of XIMPreeditDrawCallbackStruct.
+When the ``no string'' bit of the status field is set, the text field of 
+XIMPreeditDrawCallbackStruct is NULL.
+When the ``no feedback'' bit of the status field is set, the text feedback 
+field of XIMPreeditDrawCallbackStruct is NULL.
+When the above bits are not set, ``preedit string'' contains the preedit 
+string to be displayed, and the feedback array contains feedback information.
+.LP
+The IM Server sends
+.PN XIM_PREEDIT_CARET 
+message to call the PreeditCaretCallback function.  
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_PREEDIT_CARET (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:4:INT32:position
+:4:CARD32:direction
+::#0:XIMForwardChar
+::#1:XIMBackwardChar
+::#2:XIMForwardWord
+::#3:XIMBackwardWord
+::#4:XIMCaretUp
+::#5:XIMCaretDown
+::#6:XIMNextLine
+::#7:XIMCPreviousLine
+::#8:XIMLineStart
+::#9:XIMLineEnd
+::#10:XIMAbsolutePosition
+::#11:XIMDontChange
+:4:CARD32:style
+::#0:XIMInvisible
+::#1:XIMCPrimary
+::#2:XIMSecondary
+.TE
+.RE
+.LP
+Each entry corresponds to a field of XIMPreeditCaretCallbackStruct. 
+Since this callback sets the caret position, its reply must be sent 
+synchronously.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_PREEDIT_CARET_REPLY (IM library \(-> IM Server)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:4:CARD32:position
+.TE
+.RE
+.LP
+The position is the value returned by the callback function after it
+has been called.
+.LP
+The IM Server sends
+.PN XIM_PREEDIT_DONE 
+message to call the XIMPreeditDoneCallback function.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_PREEDIT_DONE (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+.TE
+.RE
+.LP
+.NH 3
+Preedit state notify
+.XS
+\*(SN Preedit state notify
+.XE
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_PREEDITSTATE (IM Server \(-> IM Library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:4:BITMASK32:XIMPreeditState
+::#x0000000:XIMPreeditUnknown
+::#x0000001:XIMPreeditEnable
+::#x0000002:XIMPreeditDisable
+.TE
+.sp
+.TE
+.RE
+.LP
+.PN XIM_PREEDITSTATE
+message is used to call the XIMPreeditStateNotifyCallback function.
+.LP
+.NH 3
+Status Callbacks
+.XS
+\*(SN Status Callbacks
+.XE
+.LP
+The IM Server sends
+.PN XIM_STATUS_START 
+message to call the XIMStatusStartCallback function.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_STATUS_START (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+.TE
+.RE
+.LP
+The IM Server sends
+.PN XIM_STATUS_DRAW 
+message to call the XIMStatusDrawCallback function.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_STATUS_DRAW (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:4:CARD32:type
+::#0:XIMTextType
+::#1:XIMBitmapType
+.TE
+.LP
+If type is XIMTextType, the arguments continue as follows.
+.TS
+tab(:);
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+:4:BITMASK32:status
+::#x0000001:no string
+::#x0000002:no feedback
+:2:n:length of status string
+:n:STRING8:status string
+:p::unused, p = Pad(2+n)
+:2:m:byte length of feedback array
+:2::unused
+:m:LISTofXIMFEEDBACK:feedback array
+.TE
+.LP
+If type is XIMBitmapType, the arguments continue as follows.
+.TS
+tab(:);
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+:4:PIXMAP:pixmap data
+.TE
+.RE
+.LP
+The field ``type'' corresponds to the field in XIMStatusDrawCallbackStruct.
+.LP
+The IM Server sends
+.PN XIM_STATUS_DONE 
+message to call the XIMStatusDoneCallback function.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_STATUS_DONE (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+.TE
+.RE
+.LP
+.bp
+.NH 1
+Acknowledgements
+.XS
+\*(SN Acknowledgements
+.XE
+.LP
+This document represents the culmination of several years of debate and
+experiments done under the auspices of the MIT X Consortium i18n working 
+group.  Although this was a group effort, the author remains responsible 
+for any errors or omissions.
+.LP
+We would like to thank to all members of this group.
+And we would like to make special thanks to the following people 
+(in alphabetical order) for their participation in the IM Protocol 
+design,
+Hector Chan, Takashi Fujiwara, Yoshio Horiuchi, Makoto Inada, 
+Hiromu Inukai, Mickael Kung, Seiji Kuwari, Franky Ling, Hiroyuki Machida, 
+Hiroyuki Miyamoto, Frank Rojas, Bob Scheifler, Makiko Shimamura, 
+Shoji Sugiyama, Hidetoshi Tajima, Masaki Takeuchi, Makoto Wakamatsu, 
+Masaki Wakao, Nobuyuki Tanaka, Shigeru Yamada, Katsuhisa Yano, Jinsoo Yoon.
+.LP
+.NH 1
+References
+.XS
+\*(SN References
+.XE
+.LP
+All of the following documents are X Consortium standards available from MIT:
+.LP
+[1] Scheifler, Robert W., \fI``X Window System Protocol Version 11''\fP
+.LP
+[2] Scheifler, Robert W. etc., \fI``Xlib \- C Language X Interface''\fP
+.LP
+.bp
+.XS
+Appendix A \- Common Extensions
+.XE
+.ce 10
+.sp 5
+\s+2\fBAppendix A\fP\s-2
+.sp
+\s+1\fBCommon Extensions\fP\s-1
+.ce 0
+.sp
+.LP
+Extension opcodes and packet names (e.g. 
+.PN XIM_EXT_SET_EVENT_MASK
+) for additional extensions may be registered with X Consortium.
+The following is a commonly well-known extended packet.
+.LP
+.LP
+.IP \fB(1)
+Extension to manipulate the event handling\fP 
+.LP
+.PN XIM_EXT_SET_EVENT_MASK 
+message specifies the set of event masks that the IM library should manipulate.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_EXT_SET_EVENT_MASK (IM Server \(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:4:EVENTMASK:filter-event-mask (*1)
+:4:EVENTMASK:intercept-event-mask (*2)
+:4:EVENTMASK:select-event-mask (*3)
+:4:EVENTMASK:forward-event-mask (*4)
+:4:EVENTMASK:synchronous-event-mask (*5)
+.TE
+.IP (*1)
+Specify the events to be neglected by the IM library via XFilterEvent.
+.IP (*2)
+Specify the events to be deselected by the IM library with XSelectInput.
+.IP (*3)
+Specify the events to be selected by the IM library with XSelectInput.
+.IP (*4)
+Specify all the events to be forwarded to the IM Server by the IM library.
+.IP (*5)
+Specify the events to be forwarded with synchronous flag on by the IM library.
+.RE
+.LP
+The IM library must reply 
+.PN XIM_SYNC_REPLY
+message to the IM Server. This request is valid after the ic is created.
+.LP
+.sp
+.IP \fB(2)
+Extension for improvement of performance\fR
+.LP
+The following requests may be used for improvement of performance.
+.LP
+.PN XIM_EXT_FORWARD_KEYEVENT
+message may be used instead of 
+.PN XIM_FORWARD_EVENT
+message.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_EXT_FORWARD_KEYEVENT (IM Server \(<-\(-> IM library)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:2:BITMASK16:flag
+::#0001:synchronous
+:2:CARD16:sequence number
+:1:BYTE:xEvent.u.u.type
+:1:BYTE:keycode
+:2:CARD16:state
+:4:CARD32:time
+:4:CARD32:window
+.TE
+.RE
+.LP
+.bp
+.PN XIM_EXT_MOVE
+message may be used to change the spot location instead of
+.PN
+XIM_SET_IC_VALUES
+message.
+It is effective only if the client specified XIMPreeditPosition.
+.RS
+.TS
+tab(:);
+lfB s s s
+lw(.25i) lw(.25i) lw(1.75i) lw(3.5i).
+XIM_EXT_MOVE (IM library \(-> IM Server)
+.sp 6p
+:2:CARD16:input-method-ID
+:2:CARD16:input-context-ID
+:2:INT16:X
+:2:INT16:Y
+.TE
+.RE
+.LP
+.PN XIM_EXT_MOVE
+message is a asynchronous request.  
+.LP
+.bp
+.XS
+Appendix B \- The list of transport specific IM Server names registered
+.XE
+.ce 10
+.sp 5
+\s+2\fBAppendix B\fP\s-2
+.sp
+\s+1\fBThe list of transport specific IM Server address format registered\fP\s-1
+.ce 0
+.sp
+.LP
+The following format represents the ATOM contained in
+.PN XIM_SERVERS
+property and the string returned from the request converting 
+selection target LOCALES and TRANSPORT.
+.DS 
+	``{@\^\fIcategory\fP\^=[\^\fIvalue\fP,...]}...''
+.DE
+.LP
+The following categories are currently registered.
+.RS
+.TS
+tab(;);
+l l.
+\fBserver\fP;: IM Server name (used for XIM_SERVERS)
+\fBlocale\fP;: XPG4 locale name (LOCALES)
+\fBtransport\fP;: transport-specific name (TRANSPORT)
+.TE
+.RE
+.LP
+The preregistered formats for transport-specific names are as follows:
+.RS
+.LP
+\fBTCP/IP Names\fP
+.LP
+.RS
+The following syntax should be used for system internal domain names:
+.DS
+<\fIlocal name\fP>  ::= ``local/''<\fIhostname\fP>``:''<\fIpathname\fP>
+.DE
+.LP
+Where <\fIpathname\fP> is a path name of socket address.
+.LP
+IM Server's name should be set to <\fIpathname\fP> to run multiple IM Server 
+at the same time
+.LP
+The following syntax should be used for Internet domain names:
+.DS
+<\fITCP name\fP>  ::=  ``tcp/''<\fIhostname\fP>``:''<\fIipportnumber\fP>
+.DE
+where <\fIhostname\fP> is either symbolic (such as expo.lcs.mit.edu) or 
+numeric decimal (such as 18.30.0.212).  The <\fIipportnumber\fP> is the 
+port on which the IM Server is listening for connections.  
+For example:
+.DS
+tcp/expo.lcs.mit.edu:8012
+tcp/18.30.0.212:7890
+.DE
+.RE
+.LP
+\fBDECnet Names\fP
+.LP
+.RS
+The following syntax should be used for DECnet names:
+.DS
+<\fIDECnet name\fP>  ::=  ``decnet/''<\fInodename\fP>``::IMSERVER$''<\fIobjname\fP>
+.DE
+where <\fInodename\fP> is either symbolic (such as SRVNOD) or the numeric 
+decimal form of the DECnet address (such as 44.70).  The <\fIobjname\fP> 
+is normal, case-insensitive DECnet object name. For example:
+.DS
+DECNET/SRVNOD::IMSERVER$DEFAULT
+decnet/44.70::IMSERVER$other
+.DE
+.RE
+.LP
+\fBX Names\fP
+.LP
+.RS
+The following syntax should be used for X names:
+.DS
+<\fIX name\fP>  ::=  ``X/''
+.DE
+.RE
+.RE
+.LP
+If a given category has multiple values, the value is evaluated in order of
+setting.
+.bp
+.XS
+Appendix C \- Protocol number
+.XE
+.ce 10
+.sp 5
+\s+2\fBAppendix C\fP\s-2
+.sp
+\s+1\fBProtocol number\fP\s-1
+.ce 0
+.sp
+.LP
+\fBMajor Protocol number\fP
+.TS
+center, tab(:);
+lw(9c) l.
+XIM_CONNECT:#001
+XIM_CONNECT_REPLY:#002
+XIM_DISCONNECT:#003
+XIM_DISCONNECT_REPLY:#004
+
+XIM_AUTH_REQUIRED:#010
+XIM_AUTH_REPLY:#011
+XIM_AUTH_NEXT:#012
+XIM_AUTH_SETUP:#013
+XIM_AUTH_NG:#014
+
+XIM_ERROR:#020
+
+XIM_OPEN:#030
+XIM_OPEN_REPLY:#031
+XIM_CLOSE:#032
+XIM_CLOSE_REPLY:#033
+XIM_REGISTER_TRIGGERKEYS:#034
+XIM_TRIGGER_NOTIFY:#035
+XIM_TRIGGER_NOTIFY_REPLY:#036
+XIM_SET_EVENT_MASK:#037
+XIM_ENCODING_NEGOTIATION:#038
+XIM_ENCODING_NEGOTIATION_REPLY:#039
+XIM_QUERY_EXTENSION:#040
+XIM_QUERY_EXTENSION_REPLY:#041
+XIM_SET_IM_VALUES:#042
+XIM_SET_IM_VALUES_REPLY:#043
+XIM_GET_IM_VALUES:#044
+XIM_GET_IM_VALUES_REPLY:#045
+
+XIM_CREATE_IC:#050
+XIM_CREATE_IC_REPLY:#051
+XIM_DESTROY_IC:#052
+XIM_DESTROY_IC_REPLY:#053
+XIM_SET_IC_VALUES:#054
+XIM_SET_IC_VALUES_REPLY:#055
+XIM_GET_IC_VALUES:#056
+XIM_GET_IC_VALUES_REPLY:#057
+XIM_SET_IC_FOCUS:#058
+XIM_UNSET_IC_FOCUS:#059
+XIM_FORWARD_EVENT:#060
+XIM_SYNC:#061
+XIM_SYNC_REPLY:#062
+XIM_COMMIT:#063
+XIM_RESET_IC:#064
+XIM_RESET_IC_REPLY:#065
+
+XIM_GEOMETRY:#070
+XIM_STR_CONVERSION:#071
+XIM_STR_CONVERSION_REPLY:#072
+XIM_PREEDIT_START:#073
+XIM_PREEDIT_START_REPLY:#074
+XIM_PREEDIT_DRAW:#075
+XIM_PREEDIT_CARET:#076
+XIM_PREEDIT_CARET_REPLY:#077
+XIM_PREEDIT_DONE:#078
+XIM_STATUS_START:#079
+XIM_STATUS_DRAW:#080
+XIM_STATUS_DONE:#081
+XIM_PREEDITSTATE:#082
+.TE
+.sp
+(*) The IM Server's extension protocol number should be more than #128.
+.bp
+.XS
+Appendix D \- Implementation Tips
+.XE
+.ce 10
+.sp 5
+\s+2\fBAppendix D\fP\s-2
+.sp
+\s+1\fBImplementation Tips\fP\s-1
+.ce 0
+.sp
+.LP
+.B
+.IP \fB(1)
+FrontEnd Method\fP
+.LP
+FrontEnd method is recognized as a performance acceleration by the
+trade off of the variety of the reliability.
+.LP
+In order to use the FrontEnd method, the IM library must query the IM
+Server to see if the FrontEnd extension is available.  The query is
+made by using the 
+.PN XIM_QUERY_EXTENSION
+message. The IM Server may send 
+.PN XIM_EXT_SET_EVENT_MASK
+message with intercept-event-mask, forward-event-mask, and 
+synchronous-event-mask values set after replying 
+.PN XIM_QUERY_EXTENSION_REPLY
+message.  
+.LP
+FrontEnd method can be implemented in a couple of ways depending on
+how the IM Server utilize 
+.PN XIM_EXT_SET_EVENT_MASK
+message.
+.LP
+One approach is to update both of the input mask and the filter-event-mask 
+depending on the preeidting state. The sample protocol sequence using the 
+static event flow is as follows:
+.LP
+.\"===================================================================
+.sp
+\^... 1.675 6.888 6.237 10.296
+\^... 0.000i 3.408i 4.562i 0.000i
+.nr 00 \n(.u
+.nf
+.PS 3.408i 4.562i 
+.br
+.ps 11
+\h'3.750i'\v'0.034i'\v'-.13m'\L'3.374i\(br'\v'.13m'
+.sp -1
+\h'3.912i'\v'1.384i'\D'l-0.100i 0.025i'
+.sp -1
+\h'3.912i'\v'1.434i'\D'l-0.100i -0.025i'
+.sp -1
+\h'3.812i'\v'1.409i'\l'0.750i'
+.sp -1
+\h'3.750i'\h'-0.0m'\v'0.2m'\s12\fRIM Server\fP
+.sp -1
+\h'3.812i'\v'0.818i'\h'-0.0m'\v'0.2m'\s10\fRevent mask is changed\fP
+.sp -1
+\h'3.812i'\v'1.006i'\h'-0.0m'\v'0.2m'\s10\fRto select the event\fP
+.sp -1
+\h'3.875i'\v'2.381i'\h'-0.0m'\v'0.2m'\s10\fRevent mask is changed\fP
+.sp -1
+\h'3.875i'\v'2.568i'\h'-0.0m'\v'0.2m'\s10\fRto deselect the event\fP
+.sp -1
+\h'3.875i'\v'1.631i'\h'-0.0m'\v'0.2m'\s10\fRX events directly come\fP
+.sp -1
+\h'3.875i'\v'1.756i'\h'-0.0m'\v'0.2m'\s10\fRto the IM Server.\fP
+.sp -1
+\h'3.875i'\v'2.006i'\h'-0.0m'\v'0.2m'\s10\fRwhen preediting is turning off\fP
+.sp -1
+\h'0.625i'\v'0.284i'\l'0.875i'
+.sp -1
+\h'1.400i'\v'0.309i'\D'l0.100i -0.025i'
+.sp -1
+\h'1.400i'\v'0.259i'\D'l0.100i 0.025i'
+.sp -1
+\h'1.750i'\v'0.346i'\l'1.687i'
+.sp -1
+\h'3.337i'\v'0.371i'\D'l0.100i -0.025i'
+.sp -1
+\h'3.337i'\v'0.321i'\D'l0.100i 0.025i'
+.sp -1
+\h'1.850i'\v'2.134i'\D'l-0.100i 0.025i'
+.sp -1
+\h'1.850i'\v'2.184i'\D'l-0.100i -0.025i'
+.sp -1
+\h'1.750i'\v'2.159i'\l'1.687i'
+.sp -1
+\h'1.562i'\v'0.034i'\v'-.13m'\L'3.374i\(br'\v'.13m'
+.sp -1
+\h'1.850i'\v'0.446i'\D'l-0.100i 0.025i'
+.sp -1
+\h'1.850i'\v'0.496i'\D'l-0.100i -0.025i'
+.sp -1
+\h'1.750i'\v'0.471i'\l'1.687i'
+.sp -1
+\h'1.687i'\v'0.631i'\h'-0.0m'\v'0.2m'\s10\fRXIM_EXT_SET_EVENT_MASK\fP
+.sp -1
+\h'1.875i'\v'0.818i'\h'-0.0m'\v'0.2m'\s10\fRintercept-event-mask is set\fP
+.sp -1
+\h'1.687i'\v'2.318i'\h'-0.0m'\v'0.2m'\s10\fRXIM_EXT_SET_EVENT_MASK\fP
+.sp -1
+\h'1.875i'\v'2.443i'\h'-0.0m'\v'0.2m'\s10\fRselect-event-mask is set\fP
+.sp -1
+\h'0.937i'\h'-0.0m'\v'0.2m'\s12\fRIM library\fP
+.sp -1
+\v'0.193i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the on-key-list\fP
+.sp -1
+\h'0.250i'\v'2.318i'\h'-0.0m'\v'0.2m'\s10\fRevent mask is changed\fP
+.sp -1
+\h'0.250i'\v'2.506i'\h'-0.0m'\v'0.2m'\s10\fRto select the event\fP
+.sp -1
+\h'0.250i'\v'1.006i'\h'-0.0m'\v'0.2m'\s10\fRto deselect the event\fP
+.sp -1
+\h'0.250i'\v'0.818i'\h'-0.0m'\v'0.2m'\s10\fRevent mask is changed\fP
+.sp -1
+\h'1.812i'\v'0.256i'\h'-0.0m'\v'0.2m'\s10\fRXIM_FORWARD_EVENT\fP
+.sp -1
+.sp 1+3.408i
+.PE
+.if \n(00 .fi
+.sp
+.\"===================================================================
+.LP
+To pursuit a maximum performance regardless of the preediting mode,
+the IM Server may use the dynamic event flow with the following 
+sample protocol sequence.
+.bp
+.LP
+.\"===================================================================
+\^... 1.675 6.888 6.237 10.296
+\^... 0.000i 3.408i 4.562i 0.000i
+.nr 00 \n(.u
+.nf
+.PS 3.408i 4.562i 
+.br
+.ps 11
+\h'3.750i'\v'0.034i'\v'-.13m'\L'3.374i\(br'\v'.13m'
+.sp -1
+\h'3.912i'\v'1.384i'\D'l-0.100i 0.025i'
+.sp -1
+\h'3.912i'\v'1.434i'\D'l-0.100i -0.025i'
+.sp -1
+\h'3.812i'\v'1.409i'\l'0.750i'
+.sp -1
+\h'3.750i'\h'-0.0m'\v'0.2m'\s12\fRIM Server\fP
+.sp -1
+\h'3.812i'\v'0.818i'\h'-0.0m'\v'0.2m'\s10\fRevent mask is changed\fP
+.sp -1
+\h'3.812i'\v'1.006i'\h'-0.0m'\v'0.2m'\s10\fRto select the event\fP
+.sp -1
+\h'3.875i'\v'2.381i'\h'-0.0m'\v'0.2m'\s10\fRevent mask is changed\fP
+.sp -1
+\h'3.875i'\v'2.568i'\h'-0.0m'\v'0.2m'\s10\fRto deselect the event\fP
+.sp -1
+\h'3.875i'\v'1.631i'\h'-0.0m'\v'0.2m'\s10\fRX events directly come\fP
+.sp -1
+\h'3.875i'\v'1.756i'\h'-0.0m'\v'0.2m'\s10\fRto the IM Server.\fP
+.sp -1
+\h'3.875i'\v'2.006i'\h'-0.0m'\v'0.2m'\s10\fRwhen preediting is turning off\fP
+.sp -1
+\h'0.625i'\v'0.284i'\l'0.875i'
+.sp -1
+\h'1.400i'\v'0.309i'\D'l0.100i -0.025i'
+.sp -1
+\h'1.400i'\v'0.259i'\D'l0.100i 0.025i'
+.sp -1
+\h'1.750i'\v'0.346i'\l'1.687i'
+.sp -1
+\h'3.337i'\v'0.371i'\D'l0.100i -0.025i'
+.sp -1
+\h'3.337i'\v'0.321i'\D'l0.100i 0.025i'
+.sp -1
+\h'1.850i'\v'1.196i'\D'l-0.100i 0.025i'
+.sp -1
+\h'1.850i'\v'1.246i'\D'l-0.100i -0.025i'
+.sp -1
+\h'1.750i'\v'1.221i'\l'1.687i'
+.sp -1
+\h'1.850i'\v'2.134i'\D'l-0.100i 0.025i'
+.sp -1
+\h'1.850i'\v'2.184i'\D'l-0.100i -0.025i'
+.sp -1
+\h'1.750i'\v'2.159i'\l'1.687i'
+.sp -1
+\h'1.562i'\v'0.034i'\v'-.13m'\L'3.374i\(br'\v'.13m'
+.sp -1
+\h'1.850i'\v'0.446i'\D'l-0.100i 0.025i'
+.sp -1
+\h'1.850i'\v'0.496i'\D'l-0.100i -0.025i'
+.sp -1
+\h'1.750i'\v'0.471i'\l'1.687i'
+.sp -1
+\h'1.812i'\v'0.256i'\h'-0.0m'\v'0.2m'\s10\fRXIM_TRIGGER_NOTIFY\fP
+.sp -1
+\h'1.687i'\v'1.068i'\h'-0.0m'\v'0.2m'\s10\fRXIM_TRIGGER_NOTIFY_REPLY\fP
+.sp -1
+\h'1.687i'\v'0.631i'\h'-0.0m'\v'0.2m'\s10\fRXIM_EXT_SET_EVENT_MASK\fP
+.sp -1
+\h'1.875i'\v'0.818i'\h'-0.0m'\v'0.2m'\s10\fRintercept-event-mask is set\fP
+.sp -1
+\h'1.687i'\v'2.318i'\h'-0.0m'\v'0.2m'\s10\fRXIM_EXT_SET_EVENT_MASK\fP
+.sp -1
+\h'1.875i'\v'2.443i'\h'-0.0m'\v'0.2m'\s10\fRselect-event-mask is set\fP
+.sp -1
+\h'0.937i'\h'-0.0m'\v'0.2m'\s12\fRIM library\fP
+.sp -1
+\v'0.193i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the on-key-list\fP
+.sp -1
+\h'0.250i'\v'2.318i'\h'-0.0m'\v'0.2m'\s10\fRevent mask is changed\fP
+.sp -1
+\h'0.250i'\v'2.506i'\h'-0.0m'\v'0.2m'\s10\fRto select the event\fP
+.sp -1
+\h'0.250i'\v'1.006i'\h'-0.0m'\v'0.2m'\s10\fRto deselect the event\fP
+.sp -1
+\h'0.250i'\v'0.818i'\h'-0.0m'\v'0.2m'\s10\fRevent mask is changed\fP
+.sp -1
+.sp 1+3.408i
+.PE
+.if \n(00 .fi
+.\"===================================================================
+.LP
+This method can reduce the XIM protocol traffic dramatically
+by updating intercept-event-mask and select-event-mask accordingly.
+The tradeoff of this performance improvement is that the key
+events may be lost or disordered in some particular situation, such as
+when the user types the keyboard in following sequence really fast:
+.sp 6p 
+.RS
+<preediting on key>``some strings''<preediting off key>``another string''
+.RE
+.sp  6p
+Since this method requires the input mask updates to the both the IM Server 
+and Xlib when turning on and off the preediting, and there is a time lag 
+till the requests take effect when two client issues the input mask updates
+simultaneously.
+.LP
+Another approach of the FrontEnd method is to update the filter-event-mask
+depending on the preediting state and not to update the input mask.
+The IM Server must register both of the preediting on key list and off key 
+list by 
+.PN XIM_REGISTER_TRIGGERKEYS
+message.
+In this method, Both the IM Server and the IM client select the same
+events on the same client's window, so that the events are delivered
+to both of the IM Server and the client. The preediting on and off 
+states are expressed by whether the key events are filtered or not.
+The sample protocol sequence are as follows:
+.LP
+.bp
+<<Using static event flow>>
+.LP
+.\"====================================================================
+.sp
+\^... 1.488 7.325 6.487 10.358
+\^... 0.000i 3.033i 4.999i 0.000i
+.nr 00 \n(.u
+.nf
+.PS 3.033i 4.999i 
+.br
+.ps 11
+\h'4.099i'\v'0.383i'\D'l-0.100i 0.025i'
+.sp -1
+\h'4.099i'\v'0.433i'\D'l-0.100i -0.025i'
+.sp -1
+\h'3.999i'\v'0.408i'\l'1.000i'
+.sp -1
+\h'4.099i'\v'1.696i'\D'l-0.100i 0.025i'
+.sp -1
+\h'4.099i'\v'1.746i'\D'l-0.100i -0.025i'
+.sp -1
+\h'3.999i'\v'1.721i'\l'1.000i'
+.sp -1
+\h'3.937i'\v'0.096i'\v'-.13m'\L'2.937i\(br'\v'.13m'
+.sp -1
+\h'3.937i'\v'0.062i'\h'-0.0m'\v'0.2m'\s12\fRIM Server\fP
+.sp -1
+\h'4.062i'\v'0.755i'\h'-0.0m'\v'0.2m'\s10\fRthe specified events\fP
+.sp -1
+\h'4.062i'\v'0.943i'\h'-0.0m'\v'0.2m'\s10\fRare being processed\fP
+.sp -1
+\h'4.062i'\v'2.255i'\h'-0.0m'\v'0.2m'\s10\fRthe specified events\fP
+.sp -1
+\h'4.062i'\v'2.443i'\h'-0.0m'\v'0.2m'\s10\fRare being discarded\fP
+.sp -1
+\h'4.249i'\v'1.568i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the off-key-list\fP
+.sp -1
+\h'4.187i'\v'0.318i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the on-key-list\fP
+.sp -1
+\h'0.812i'\v'0.346i'\l'0.875i'
+.sp -1
+\h'1.587i'\v'0.371i'\D'l0.100i -0.025i'
+.sp -1
+\h'1.587i'\v'0.321i'\D'l0.100i 0.025i'
+.sp -1
+\h'1.937i'\v'0.408i'\l'1.687i'
+.sp -1
+\h'3.524i'\v'0.433i'\D'l0.100i -0.025i'
+.sp -1
+\h'3.524i'\v'0.383i'\D'l0.100i 0.025i'
+.sp -1
+\h'1.749i'\v'0.096i'\v'-.13m'\L'2.937i\(br'\v'.13m'
+.sp -1
+\h'2.037i'\v'0.508i'\D'l-0.100i 0.025i'
+.sp -1
+\h'2.037i'\v'0.558i'\D'l-0.100i -0.025i'
+.sp -1
+\h'1.937i'\v'0.533i'\l'1.687i'
+.sp -1
+\h'0.812i'\v'1.721i'\l'0.875i'
+.sp -1
+\h'1.587i'\v'1.746i'\D'l0.100i -0.025i'
+.sp -1
+\h'1.587i'\v'1.696i'\D'l0.100i 0.025i'
+.sp -1
+\h'2.099i'\v'1.758i'\D'l-0.100i 0.025i'
+.sp -1
+\h'2.099i'\v'1.808i'\D'l-0.100i -0.025i'
+.sp -1
+\h'1.999i'\v'1.783i'\l'1.688i'
+.sp -1
+\h'1.874i'\v'0.693i'\h'-0.0m'\v'0.2m'\s10\fRXIM_EXT_SET_EVENT_MASK\fP
+.sp -1
+\v'0.255i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the on-key-list\fP
+.sp -1
+\h'2.062i'\v'0.880i'\h'-0.0m'\v'0.2m'\s10\fRfilter-event-mask is set\fP
+.sp -1
+\h'0.624i'\v'0.755i'\h'-0.0m'\v'0.2m'\s10\fRthe specified events\fP
+.sp -1
+\h'0.624i'\v'0.943i'\h'-0.0m'\v'0.2m'\s10\fRare being filtered\fP
+.sp -1
+\h'1.937i'\v'1.943i'\h'-0.0m'\v'0.2m'\s10\fRXIM_EXT_SET_EVENT_MASK\fP
+.sp -1
+\h'2.124i'\v'2.068i'\h'-0.0m'\v'0.2m'\s10\fRfilter-event-mask is set\fP
+.sp -1
+\h'0.062i'\v'1.568i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the off-key-list\fP
+.sp -1
+\h'1.062i'\h'-0.0m'\v'0.2m'\s12\fRIM library\fP
+.sp -1
+\h'0.624i'\v'2.255i'\h'-0.0m'\v'0.2m'\s10\fRthe specified events\fP
+.sp -1
+\h'0.624i'\v'2.443i'\h'-0.0m'\v'0.2m'\s10\fRare being processed\fP
+.sp -1
+\h'1.999i'\v'0.318i'\h'-0.0m'\v'0.2m'\s10\fRXIM_FORWARD_EVENT\fP
+.sp -1
+.sp 1+3.033i
+.PE
+.if \n(00 .fi
+.\"====================================================================
+.LP
+<<Using the dynamic event flow>>
+.LP
+.\"====================================================================
+\^... 1.488 7.325 6.487 10.358
+\^... 0.000i 3.033i 4.999i 0.000i
+.nr 00 \n(.u
+.nf
+.PS 3.033i 4.999i 
+.br
+.ps 11
+\h'4.099i'\v'0.383i'\D'l-0.100i 0.025i'
+.sp -1
+\h'4.099i'\v'0.433i'\D'l-0.100i -0.025i'
+.sp -1
+\h'3.999i'\v'0.408i'\l'1.000i'
+.sp -1
+\h'4.099i'\v'1.696i'\D'l-0.100i 0.025i'
+.sp -1
+\h'4.099i'\v'1.746i'\D'l-0.100i -0.025i'
+.sp -1
+\h'3.999i'\v'1.721i'\l'1.000i'
+.sp -1
+\h'3.937i'\v'0.096i'\v'-.13m'\L'2.937i\(br'\v'.13m'
+.sp -1
+\h'3.937i'\v'0.062i'\h'-0.0m'\v'0.2m'\s12\fRIM Server\fP
+.sp -1
+\h'4.062i'\v'0.755i'\h'-0.0m'\v'0.2m'\s10\fRthe specified events\fP
+.sp -1
+\h'4.062i'\v'0.943i'\h'-0.0m'\v'0.2m'\s10\fRare being processed\fP
+.sp -1
+\h'4.062i'\v'2.255i'\h'-0.0m'\v'0.2m'\s10\fRthe specified events\fP
+.sp -1
+\h'4.062i'\v'2.443i'\h'-0.0m'\v'0.2m'\s10\fRare being discarded\fP
+.sp -1
+\h'4.249i'\v'1.568i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the off-key-list\fP
+.sp -1
+\h'4.187i'\v'0.318i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the on-key-list\fP
+.sp -1
+\h'0.812i'\v'0.346i'\l'0.875i'
+.sp -1
+\h'1.587i'\v'0.371i'\D'l0.100i -0.025i'
+.sp -1
+\h'1.587i'\v'0.321i'\D'l0.100i 0.025i'
+.sp -1
+\h'1.937i'\v'0.408i'\l'1.687i'
+.sp -1
+\h'3.524i'\v'0.433i'\D'l0.100i -0.025i'
+.sp -1
+\h'3.524i'\v'0.383i'\D'l0.100i 0.025i'
+.sp -1
+\h'2.037i'\v'1.258i'\D'l-0.100i 0.025i'
+.sp -1
+\h'2.037i'\v'1.308i'\D'l-0.100i -0.025i'
+.sp -1
+\h'1.937i'\v'1.283i'\l'1.687i'
+.sp -1
+\h'1.749i'\v'0.096i'\v'-.13m'\L'2.937i\(br'\v'.13m'
+.sp -1
+\h'2.037i'\v'0.508i'\D'l-0.100i 0.025i'
+.sp -1
+\h'2.037i'\v'0.558i'\D'l-0.100i -0.025i'
+.sp -1
+\h'1.937i'\v'0.533i'\l'1.687i'
+.sp -1
+\h'0.812i'\v'1.721i'\l'0.875i'
+.sp -1
+\h'1.587i'\v'1.746i'\D'l0.100i -0.025i'
+.sp -1
+\h'1.587i'\v'1.696i'\D'l0.100i 0.025i'
+.sp -1
+\h'2.099i'\v'1.758i'\D'l-0.100i 0.025i'
+.sp -1
+\h'2.099i'\v'1.808i'\D'l-0.100i -0.025i'
+.sp -1
+\h'1.999i'\v'1.783i'\l'1.688i'
+.sp -1
+\h'1.999i'\v'0.318i'\h'-0.0m'\v'0.2m'\s10\fRXIM_TRIGGER_NOTIFY\fP
+.sp -1
+\h'1.874i'\v'1.130i'\h'-0.0m'\v'0.2m'\s10\fRXIM_TRIGGER_NOTIFY_REPLY\fP
+.sp -1
+\h'1.874i'\v'0.693i'\h'-0.0m'\v'0.2m'\s10\fRXIM_EXT_SET_EVENT_MASK\fP
+.sp -1
+\v'0.255i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the on-key-list\fP
+.sp -1
+\h'2.062i'\v'0.880i'\h'-0.0m'\v'0.2m'\s10\fRfilter-event-mask is set\fP
+.sp -1
+\h'0.624i'\v'0.755i'\h'-0.0m'\v'0.2m'\s10\fRthe specified events\fP
+.sp -1
+\h'0.624i'\v'0.943i'\h'-0.0m'\v'0.2m'\s10\fRare being filtered\fP
+.sp -1
+\h'1.937i'\v'1.943i'\h'-0.0m'\v'0.2m'\s10\fRXIM_EXT_SET_EVENT_MASK\fP
+.sp -1
+\h'2.124i'\v'2.068i'\h'-0.0m'\v'0.2m'\s10\fRfilter-event-mask is set\fP
+.sp -1
+\h'0.062i'\v'1.568i'\h'-0.0m'\v'0.2m'\s10\fRKeys in the off-key-list\fP
+.sp -1
+\h'1.062i'\h'-0.0m'\v'0.2m'\s12\fRIM library\fP
+.sp -1
+\h'0.624i'\v'2.255i'\h'-0.0m'\v'0.2m'\s10\fRthe specified events\fP
+.sp -1
+\h'0.624i'\v'2.443i'\h'-0.0m'\v'0.2m'\s10\fRare being processed\fP
+.sp -1
+.sp 1+3.033i
+.PE
+.if \n(00 .fi
+
+.\"====================================================================
+.LP
+This method does not have the problem of the time lag when going across
+the preediting on and off mode, however, the amount of the performance
+acceleration is not as good as the method described above.
+.LP
+In general, the FrontEnd method requires some synchronization to some
+of the X protocols, such as the ChangeWindowAttribute protocol for the 
+event mask change or the GrabKey protocol, since it relies on the X's
+principal event dispatching mechanism. Any X protocol bindings do not
+consider the synchronization might cause some mis-synchronization 
+between the IM clients and the IM Server.
+.LP
+.bp
+.IP \fB(2) 
+Transport Layer\fP 
+.LP
+The Xlib XIM implementation is layered into three functions, a protocol
+layer, an interface layer and a transport layer. The purpose of this
+layering is to make the protocol independent of transport implementation.
+Each function of these layers are:
+.RS 3
+.IP "\fIThe protocol layer\fP"
+.br
+implements overall function of XIM and calls the interface layer
+functions when it needs to communicate to IM Server. 
+.IP "\fIThe interface layer\fP"
+.br
+separates the implementation of the transport layer from the protocol
+layer, in other words, it provides implementation independent hook for
+the transport layer functions.
+.IP "\fIThe transport layer\fP"
+.br
+handles actual data communication with IM Server. It is done by a set
+of several functions named transporters.
+.RE
+.LP
+The interface layer and the transport layer make various communication
+channels usable such as X Protocol, TCP/IP, DECnet or STREAM. 
+The following is a sample implementation for the transporter using 
+the X connection.
+Refer to "xtrans" for the transporter using Socket Transport.
+.LP
+At the beginning of the X Transport connection for the XIM transport
+mechanism, two different windows must be created either in an Xlib XIM
+or in an IM Server, with which the Xlib and the IM Server exchange the
+XIM transports by using the ClientMessage events and Window Properties.
+In the following, the window created by the Xlib is referred as the
+"client communication window", and on the other hand, the window created
+by the IM Server is referred as the "IMS communication window".
+.LP
+.B
+Connection
+.LP
+.RS
+In order to establish a connection, a communication window is created.
+A ClientMessage in the following event's format is sent to the owner 
+window of XIM_SERVER selection, which the IM Server has created.
+.LP
+Refer to "The Input Method Protocol" for the XIM_SERVER atom.
+.LP
+.ce
+Table D-1; The ClientMessage sent to the IMS window.
+.TS H
+tab(:);
+l s|l
+l l|l.
+_
+.sp 6p
+.B
+Structure Member:Contents
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+int:type:ClientMessage  
+u_long:serial:Set by the X Window System  
+Bool:send_event:Set by the X Window System  
+Display:*display:The display to which connects
+Window:window:IMS Window ID
+Atom:message_type:XInternAtom(display, ``_XIM_XCONNECT'', False)
+int:format:32  
+long:data.l[0]:client communication window ID  
+long:data.l[1]:client-major-transport-version (*1)
+long:data.l[2]:client-major-transport-version (*1)
+.sp 6p
+_
+.TE
+.LP
+In order to establish the connection (to notify the IM Server communication
+window), the IM Server sends a ClientMessage in the following event's
+format to the client communication window.
+.LP
+.bp
+.ce
+Table D-2; The ClientMessage sent by IM Server.
+.TS H
+tab(:);
+l s | l
+l l | l.
+_
+.sp 6p
+.B
+Structure Member:Contents
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+int:type:ClientMessage  
+u_long:serial:Set by the X Window System  
+Bool:send_event:Set by the X Window System  
+Display:*display:The display to which connects
+Window:window:client communication window ID  
+Atom:message_type:XInternAtom(display, ``_XIM_XCONNECT'', False)
+int:format:32  
+long:data.l[0]:IMS communication window ID  
+long:data.l[1]:server-major-transport-version (*1)
+long:data.l[2]:server-minor-transport-version (*1)
+long:data.l[3]:dividing size between ClientMessage and Property (*2)
+.sp 6p
+_
+.TE
+.LP
+.IP (*1) 
+major/minor-transport-version
+.RS
+The read/write method is decided by the combination of 
+major/minor-transport-version, as follows:
+.LP
+.ce
+Table D-3; The read/write method and the major/minor-transport-version
+.TS
+center, tab(:);
+| c s | l |
+| c | c | l |.
+_
+.sp 6p
+.B
+Transport-version:read/write 
+.sp 6p
+_
+.sp 6p
+major:minor:
+.sp 6p
+_
+.sp 6p
+.R
+0:0:only-CM & Property-with-CM
+:1:only-CM & multi-CM
+:2:only-CM & multi-CM & Property-with-CM
+.sp 6p
+_
+.sp 6p
+1:0:PropertyNotify
+.sp 6p
+_
+.sp 6p
+2:0:only-CM & PropertyNotify
+:1:only-CM & multi-CM & PropertyNotify
+.sp 6p
+_
+.TE
+.LP
+.RS
+.TS
+center, tab(;);
+l n l.
+only-CM;:;data is sent via a ClientMessage
+multi-CM;:;data is sent via multiple ClientMessages 
+Property-with-CM;:;T{
+data is written in Property, and its Atom is send via ClientMessage
+T}
+PropertyNotify;:;T{
+data is written in Property, and its Atom is send via PropertyNotify
+T}
+.TE
+.RE
+.LP
+The method to decide major/minor-transport-version is as follows:
+.LP
+.IP (1)
+The client sends 0 as major/minor-transport-version to the IM Server.
+The client must support all methods in Table D-3.
+The client may send another number as major/minor-transport-version to
+use other method than the above in the future.
+.IP (2)
+The IM Server sends its major/minor-transport-version number to
+the client. The client sends data using the method specified by the 
+IM Server.
+.IP (3)
+If major/minor-transport-version number is not available, it is regarded
+as 0.
+.RE
+.LP
+.IP (*2) 
+dividing size between ClientMessage and Property
+.RS
+If data is sent via both of multi-CM and Property, specify the dividing
+size between ClientMessage and Property. The data, which is smaller than
+this size, is sent via multi-CM (or only-CM), and the data, which is 
+lager than this size, is sent via Property. 
+.RE
+.RE
+.LP
+.sp
+.LP
+.B
+read/write
+.LP  
+.RS
+The data is transferred via either ClientMessage or Window Property in
+the X Window System.
+.LP
+.B
+Format for the data from the Client to the IM Server
+.LP
+.RS
+.B
+ClientMessage
+.LP
+If data is sent via ClientMessage event, the format is as follows:
+.LP
+.ce
+Table D-4; The ClientMessage event's format (first or middle)
+.TS
+tab(;);
+l s | l
+l l | l.
+_
+.sp 6p
+.B
+Structure Member;Contents
+.sp 6p
+_
+.sp 6p
+.R
+int;type;ClientMessage  
+u_long;serial;Set by the X Window System  
+Bool;send_event;Set by the X Window System  
+Display;*display;The display to which connects  
+Window;window;IMS communication window ID  
+Atom;message_type;XInternAtom(display, ``_XIM_MOREDATA'', False)
+int;format;8  
+char;data.b[20];(read/write DATA : 20 byte)  
+.sp 6p
+_
+.TE
+.LP
+.ce
+Table D-5; The ClientMessage event's format (only or last)
+.TS H
+tab(;);
+l s | l
+l l | l.
+_
+.sp 6p
+.B
+Structure Member;Contents
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+int;type;ClientMessage  
+u_long;serial;Set by the X Window System  
+Bool;send_event;Set by the X Window System  
+Display;*display;The display to which connects  
+Window;window;IMS communication window ID  
+Atom;message_type;XInternAtom(display, ``_XIM_PROTOCOL'', False)
+int;format;8  
+char;data.b[20];(read/write DATA : MAX 20 byte)  (*1)
+.sp 6p
+_
+.TE
+.IP (*1)
+If the data is smaller than 20 byte, all data other than available data
+must be 0.
+.RE
+.LP
+.RS
+.B
+Property
+.LP
+In the case of large data, data will be sent via the Window Property 
+for the efficiency.  There are the following two methods to notify 
+Property, and transport-version is decided which method is used.
+.LP
+.IP (1)
+The XChangeProperty function is used to store data in the client 
+communication window, and Atom of the stored data is notified to the 
+IM Server via ClientMessage event.
+.IP (2)
+The XChangeProperty function is used to store data in the client 
+communication window, and Atom of the stored data is notified to the 
+IM Server via PropertyNotify event.
+.LP
+The arguments of the XChangeProperty are as follows:
+.LP
+.bp
+.ce
+Table D-6; The XChangeProperty event's format
+.TS H
+tab(:);
+l s | l
+l l | l.
+_
+.sp 6p
+.B
+Argument:Contents
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+Display:*display:The display to which connects
+Window:window:IMS communication window ID  
+Atom:property:read/write property Atom (*1) 
+Atom:type:XA_STRING  
+int:format:8  
+int:mode:PropModeAppend  
+u_char:*data:read/write DATA 
+int:nelements:length of DATA
+.sp 6p
+_
+.TE
+.LP
+.IP (*1)
+The read/write property ATOM allocates the following strings by
+\fBXInternAtom\fP.
+.RS
+``_clientXXX''
+.RE
+.LP
+The client changes the property with the mode of PropModeAppend and
+the IM Server will read it with the delete mode i.e. (delete = True).
+.LP
+If Atom is notified via ClientMessage event, the format of the ClientMessage 
+is as follows:
+.LP
+.ce 
+Table D-7; The ClientMessage event's format to send Atom of property
+.TS H
+tab(:);
+l s | l 
+l l | l.
+_
+.sp 6p
+.B
+Structure Member:Contents
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+int:type:ClientMessage  
+u_long:serial:Set by the X Window System  
+Bool:send_event:Set by the X Window System  
+Display:*display:The display to which connects
+Window:window:IMS communication window ID  
+Atom:message_type:XInternAtom(display, ``_XIM_PROTOCOL'', False)
+int:format:32  
+long:data.l[0]:length of read/write property Atom  
+long:data.l[1]:read/write property Atom
+.sp 6p
+_
+.TE
+.RE
+.LP
+.B
+Format for the data from the IM Server to the Client
+.LP
+.RS
+.B
+ClientMessage
+.LP
+The format of the ClientMessage is as follows:
+.LP
+.ce
+Table D-8; The ClientMessage event's format (first or middle)
+.TS H
+tab(;);
+l s | l
+l l | l.
+_
+.sp 6p
+.B
+Structure Member;Contents
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+int;type;ClientMessage  
+u_long;serial;Set by the X Window System  
+Bool;send_event ;Set by the X Window System  
+Display;*display;The display to which connects
+Window;window;client communication window ID  
+Atom;message_type;XInternAtom(display, ``_XIM_MOREDATA'', False)
+int;format;8  
+char;data.b[20];(read/write DATA : 20 byte)  
+.sp 6p
+_
+.TE
+.LP
+.bp
+.ce
+Table D-9; The ClientMessage event's format (only or last)
+.TS
+tab(;);
+l s | l
+l l | l.
+_
+.sp 6p
+.B
+Structure Member;Contents
+.sp 6p
+_
+.sp 6p
+.R
+int;type;ClientMessage  
+u_long;serial;Set by the X Window System  
+Bool;send_event ;Set by the X Window System  
+Display;*display;The display to which connects
+Window;window;client communication window ID  
+Atom;message_type;XInternAtom(display, ``_XIM_PROTOCOL'', False)
+int;format;8  
+char;data.b[20];(read/write DATA : MAX 20 byte) (*1) 
+.sp 6p
+_
+.TE
+.LP
+.IP (*1)
+If the data size is smaller than 20 bytes, all data other than available 
+data must be 0.
+.LP
+.B
+Property
+.LP
+In the case of large data, data will be sent via the Window Property
+for the efficiency. There are the following two methods to notify 
+Property, and transport-version is decided which method is used.
+.LP
+.IP (1)
+The XChangeProperty function is used to store data in the IMS 
+communication window, and Atom of the property is sent via the 
+ClientMessage event.
+.IP (2)
+The XChangeProperty function is used to store data in the IMS 
+communication window, and Atom of the property is sent via 
+PropertyNotify event.
+.LP
+The arguments of the XChangeProperty are as follows:
+.LP
+.ce
+Table D-10; The XChangeProperty event's format
+.TS H
+tab(:);
+l s | l
+l l | l.
+_
+.sp 6p
+.B
+Argument:Contents
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+Display:*display:The display which to connects
+Window:window:client communication window ID  
+Atom:property:read/write property Atom (*1)
+Atom:type:XA_STRING  
+int:format:8  
+int:mode:PropModeAppend  
+u_char:*data:read/write DATA  
+int:nelements:length of DATA  
+.sp 6p
+_
+.TE
+.LP  
+.IP (*1)
+The read/write property ATOM allocates some strings, which are not
+allocated by the client, by \fBXInternAtom\fP.
+.LP
+The IM Server changes the property with the mode of PropModeAppend and
+the client reads it with the delete mode, i.e. (delete = True).
+.LP
+If Atom is notified via ClientMessage event, the format of the ClientMessage 
+is as follows:
+.LP
+.bp
+.ce
+Table D-11; The ClientMessage event's format to send Atom of property 
+.TS H
+tab(:);
+l s | l
+l l | l.
+_
+.sp 6p
+.B
+Structure Member:Contents
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+int:type:ClientMessage  
+u_long:serial:Set by the X Window System  
+Bool:send_event:Set by the X Window System  
+Display:*display:The display to which connects  
+Window:window:client communication window ID  
+Atom:message_type:XInternAtom(display, ``_XIM_PROTOCOL'', False)
+int:format:32  
+long:data.l[0]:length of read/write property ATOM  
+long:data.l[1]:read/write property ATOM  
+.sp 6p
+_
+.TE
+.RE
+.RE
+.LP
+.B
+Closing Connection
+.RS
+.LP
+If the client disconnect with the IM Server, shutdown function should 
+free the communication window properties and etc..
+.RE
+.LP
+.bp
+.EH ''''
+.OH ''''
+.EF ''''
+.OF ''''
+.TC
+
diff --git a/specs/i18n/Framework.ms b/specs/i18n/Framework.ms
new file mode 100644
index 00000000..20ff3c7b
--- /dev/null
+++ b/specs/i18n/Framework.ms
@@ -0,0 +1,1567 @@
+.\" $Xorg: Framework.ms,v 1.3 2000/08/17 19:42:49 cpqbld Exp $
+.\" $XdotOrg: xc/doc/specs/i18n/Framework.ms,v 1.2 2004/04/23 18:42:19 eich Exp $
+.\" To print this out, type tbl macros.t ThisFile | troff -ms
+.\" $XFree86: xc/doc/specs/i18n/Framework.ms,v 1.4 2001/01/17 16:57:45 dawes Exp $
+.EH ''''
+.OH ''''
+.EF ''''
+.OF ''''
+.ps 11
+.nr PS 11
+\&
+.TL
+\s+3\fBX11R6 Sample Implementation Frame Work\fP\s-3
+.sp 2
+.AU
+Katsuhisa Yano
+.AI
+TOSHIBA Corporation
+.AU
+Yoshio Horiuchi
+.AI
+IBM Japan
+.LP
+.bp
+.br
+\&
+.sp 15
+.ps 9
+.nr PS 9
+.LP
+Copyright \(co 1994 by TOSHIBA Corporation
+.br
+Copyright \(co 1994 by IBM Corporation
+.LP
+Permission to use, copy, modify, and distribute this documentation
+for any purpose and without fee is hereby granted, provided
+that the above copyright notice and this permission notice appear 
+in all copies.
+TOSHIBA Corporation and IBM Corporation make 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.
+.sp 5
+Copyright \(co 1994 X Consortium
+.LP
+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:
+.LP
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+.LP
+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.
+.LP
+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.
+.sp 3
+\fIX Window System\fP is a trademark of The Open Group.
+.ps 11
+.nr PS 11
+.bp 1
+.EH '\fBSample Implementation Frame Work\fP''\fB\*(xV\fP'
+.OH '\fBSample Implementation Frame Work\fP''\fB\*(xV\fP'
+.EF ''\fB % \fP''
+.OF ''\fB % \fP''
+.NH 1
+Preface 
+.XS \*(SN Preface 
+.XE 
+.LP 
+This document proposes to define the structures, methods and their 
+signatures that are expected to be common to all locale dependent 
+functions within the Xlib sample implementation.  The following 
+illustration (Fig.1) is proposed to outline the separating of 
+the components within the sample implementation.  
+.LP
+.\" figure start
+.in +1c
+\^... 0.237 5.796 5.24 10.14
+\^... 0.000i 4.344i 5.003i 0.000i
+.nr 00 \n(.u
+.nf
+.PS 4.344i 5.003i 
+.br
+.ps 11
+\h'1.753i'\v'2.130i'\v'-.13m'\L'-1.000i\(br'\v'.13m'
+.sp -1
+\h'1.753i'\v'1.130i'\l'1.500i'
+.sp -1
+\h'3.253i'\v'1.130i'\v'-.13m'\L'1.000i\(br'\v'.13m'
+.sp -1
+\h'3.253i'\v'2.130i'\l'-1.500i'
+.sp -1
+\h'1.751i'\v'1.628i'\l'1.499i'
+.sp -1
+\h'2.500i'\v'1.128i'\v'-.13m'\L'0.500i\(br'\v'.13m'
+.sp -1
+\h'1.875i'\v'1.344i'\h'-0.0m'\v'0.2m'\s12\fRInput\fP
+.sp -1
+\h'1.875i'\v'1.532i'\h'-0.0m'\v'0.2m'\s12\fRMethod\fP
+.sp -1
+\h'2.625i'\v'1.344i'\h'-0.0m'\v'0.2m'\s12\fROutput\fP
+.sp -1
+\h'2.625i'\v'1.532i'\h'-0.0m'\v'0.2m'\s12\fRMethod\fP
+.sp -1
+\h'1.938i'\v'1.844i'\h'-0.0m'\v'0.2m'\s12\fR<Locl. Serv. API>\fP
+.sp -1
+\h'2.000i'\v'2.032i'\h'-0.0m'\v'0.2m'\s12\fRX Locale Object\fP
+.sp -1
+\h'3.503i'\v'1.630i'\v'-.13m'\L'-0.500i\(br'\v'.13m'
+.sp -1
+\h'3.503i'\v'1.130i'\l'1.500i'
+.sp -1
+\h'5.003i'\v'1.130i'\v'-.13m'\L'0.500i\(br'\v'.13m'
+.sp -1
+\h'5.003i'\v'1.630i'\l'-1.500i'
+.sp -1
+\h'3.625i'\v'1.344i'\h'-0.0m'\v'0.2m'\s12\fRC Library\fP
+.sp -1
+\h'4.250i'\v'1.532i'\h'-0.0m'\v'0.2m'\s12\fRANSI impl.\fP
+.sp -1
+\h'0.003i'\v'1.630i'\v'-.13m'\L'-0.500i\(br'\v'.13m'
+.sp -1
+\h'0.003i'\v'1.130i'\l'1.500i'
+.sp -1
+\h'1.503i'\v'1.130i'\v'-.13m'\L'0.500i\(br'\v'.13m'
+.sp -1
+\h'1.503i'\v'1.630i'\l'-1.500i'
+.sp -1
+\h'0.125i'\v'1.344i'\h'-0.0m'\v'0.2m'\s12\fRLocale Library\fP
+.sp -1
+\h'0.438i'\v'1.507i'\h'-0.0m'\v'0.2m'\s12\fRnon-AnSI impl.\fP
+.sp -1
+\h'3.500i'\v'0.782i'\h'-0.0m'\v'0.2m'\s12\fR<<  ANSI/MSE API >>\fP
+.sp -1
+\h'4.250i'\v'0.969i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fR(X Contrib)\fP'u/2u'\s12\fR(X Contrib)\fP\h'-\w'\s12\fR(X Contrib)\fP'u/2u'
+.sp -1
+\h'0.125i'\v'3.094i'\h'-0.0m'\v'0.2m'\s12\fRXLC_XLOCALE\fP
+.sp -1
+\h'0.125i'\v'3.282i'\h'-0.0m'\v'0.2m'\s12\fR- MB_CUR_MAX\fP
+.sp -1
+\h'0.125i'\v'3.444i'\h'-0.0m'\v'0.2m'\s12\fR- codeset info\fP
+.sp -1
+\h'0.125i'\v'3.607i'\h'-0.0m'\v'0.2m'\s12\fRo char/charset\fP
+.sp -1
+\h'0.125i'\v'3.769i'\h'-0.0m'\v'0.2m'\s12\fRo conv/charset\fP
+.sp -1
+\h'0.003i'\v'3.880i'\v'-.13m'\L'-1.000i\(br'\v'.13m'
+.sp -1
+\h'0.003i'\v'2.880i'\l'1.500i'
+.sp -1
+\h'1.503i'\v'2.880i'\v'-.13m'\L'1.000i\(br'\v'.13m'
+.sp -1
+\h'1.503i'\v'3.880i'\l'-1.500i'
+.sp -1
+\h'1.875i'\v'3.094i'\h'-0.0m'\v'0.2m'\s12\fRXLC_FONTSET\fP
+.sp -1
+\h'1.875i'\v'3.282i'\h'-0.0m'\v'0.2m'\s12\fR- fonset info\fP
+.sp -1
+\h'1.875i'\v'3.444i'\h'-0.0m'\v'0.2m'\s12\fR- charset info\fP
+.sp -1
+\h'1.875i'\v'3.607i'\h'-0.0m'\v'0.2m'\s12\fR- font/charset\fP
+.sp -1
+\h'1.875i'\v'3.769i'\h'-0.0m'\v'0.2m'\s12\fR- XLFD, GL/GR\fP
+.sp -1
+\h'1.753i'\v'3.880i'\v'-.13m'\L'-1.000i\(br'\v'.13m'
+.sp -1
+\h'1.753i'\v'2.880i'\l'1.500i'
+.sp -1
+\h'3.253i'\v'2.880i'\v'-.13m'\L'1.000i\(br'\v'.13m'
+.sp -1
+\h'3.253i'\v'3.880i'\l'-1.500i'
+.sp -1
+\h'3.625i'\v'3.444i'\h'-0.0m'\v'0.2m'\s12\fR- codeset info\fP
+.sp -1
+\h'3.625i'\v'3.607i'\h'-0.0m'\v'0.2m'\s12\fRo char/charset\fP
+.sp -1
+\h'3.625i'\v'3.769i'\h'-0.0m'\v'0.2m'\s12\fRo conv/charset\fP
+.sp -1
+\h'3.625i'\v'3.282i'\h'-0.0m'\v'0.2m'\s12\fR- MB_CUR_MAX\fP
+.sp -1
+\h'3.625i'\v'3.094i'\h'-0.0m'\v'0.2m'\s12\fRlocaledef DB\fP
+.sp -1
+\h'3.503i'\v'3.880i'\v'-.13m'\L'-1.000i\(br'\v'.13m'
+.sp -1
+\h'3.503i'\v'2.880i'\l'1.500i'
+.sp -1
+\h'5.003i'\v'2.880i'\v'-.13m'\L'1.000i\(br'\v'.13m'
+.sp -1
+\h'5.003i'\v'3.880i'\l'-1.500i'
+.sp -1
+\h'0.753i'\v'0.250i'\D'l0.000i -0.250i'
+.sp -1
+\h'0.753i'\l'3.500i'
+.sp -1
+\h'4.253i'\D'l0.000i 0.250i'
+.sp -1
+\h'4.253i'\v'0.250i'\l'-3.500i'
+.sp -1
+\h'2.500i'\v'0.157i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fRApplication\fP'u/2u'\s12\fRApplication\fP\h'-\w'\s12\fRApplication\fP'u/2u'
+.sp -1
+\v'0.782i'\h'-0.0m'\v'0.2m'\s12\fR<<  ANSI/MSE API >>\fP
+.sp -1
+\h'0.751i'\v'0.969i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fR(X Contrib)\fP'u/2u'\s12\fR(X Contrib)\fP\h'-\w'\s12\fR(X Contrib)\fP'u/2u'
+.sp -1
+\h'2.500i'\v'2.128i'\v'-.13m'\L'0.749i\(br'\v'.13m'
+.sp -1
+\h'2.475i'\v'2.777i'\D'l0.025i 0.100i'
+.sp -1
+\h'2.525i'\v'2.777i'\D'l-0.025i 0.100i'
+.sp -1
+\h'2.500i'\v'2.315i'\D'l-0.250i 0.187i'
+.sp -1
+\h'2.250i'\v'2.502i'\l'-1.124i'
+.sp -1
+\h'1.126i'\v'2.502i'\v'-.13m'\L'0.375i\(br'\v'.13m'
+.sp -1
+\h'1.101i'\v'2.777i'\D'l0.025i 0.100i'
+.sp -1
+\h'1.151i'\v'2.777i'\D'l-0.025i 0.100i'
+.sp -1
+\h'2.500i'\v'2.315i'\D'l0.250i 0.187i'
+.sp -1
+\h'2.750i'\v'2.502i'\l'1.125i'
+.sp -1
+\h'3.875i'\v'2.502i'\v'-.13m'\L'0.375i\(br'\v'.13m'
+.sp -1
+\h'3.850i'\v'2.777i'\D'l0.025i 0.100i'
+.sp -1
+\h'3.900i'\v'2.777i'\D'l-0.025i 0.100i'
+.sp -1
+\h'0.376i'\v'1.628i'\v'-.13m'\L'1.249i\(br'\v'.13m'
+.sp -1
+\h'0.351i'\v'2.777i'\D'l0.025i 0.100i'
+.sp -1
+\h'0.401i'\v'2.777i'\D'l-0.025i 0.100i'
+.sp -1
+\h'4.625i'\v'1.628i'\v'-.13m'\L'1.249i\(br'\v'.13m'
+.sp -1
+\h'4.600i'\v'2.777i'\D'l0.025i 0.100i'
+.sp -1
+\h'4.650i'\v'2.777i'\D'l-0.025i 0.100i'
+.sp -1
+\h'2.125i'\v'0.253i'\v'-.13m'\L'0.375i\(br'\v'.13m'
+.sp -1
+\h'2.100i'\v'0.528i'\D'l0.025i 0.100i'
+.sp -1
+\h'2.150i'\v'0.528i'\D'l-0.025i 0.100i'
+.sp -1
+\h'2.875i'\v'0.253i'\v'-.13m'\L'0.375i\(br'\v'.13m'
+.sp -1
+\h'2.850i'\v'0.528i'\D'l0.025i 0.100i'
+.sp -1
+\h'2.900i'\v'0.528i'\D'l-0.025i 0.100i'
+.sp -1
+\h'1.126i'\v'0.253i'\v'-.13m'\L'0.375i\(br'\v'.13m'
+.sp -1
+\h'1.101i'\v'0.528i'\D'l0.025i 0.100i'
+.sp -1
+\h'1.151i'\v'0.528i'\D'l-0.025i 0.100i'
+.sp -1
+\h'3.875i'\v'0.253i'\v'-.13m'\L'0.375i\(br'\v'.13m'
+.sp -1
+\h'3.850i'\v'0.528i'\D'l0.025i 0.100i'
+.sp -1
+\h'3.900i'\v'0.528i'\D'l-0.025i 0.100i'
+.sp -1
+\v'4.002i'\D'l0.125i 0.125i'
+.sp -1
+\h'0.125i'\v'4.127i'\l'3.000i'
+.sp -1
+\h'3.125i'\v'4.127i'\D'l0.125i -0.125i'
+.sp -1
+\h'3.500i'\v'4.002i'\D'l0.125i 0.125i'
+.sp -1
+\h'3.625i'\v'4.127i'\l'1.250i'
+.sp -1
+\h'4.875i'\v'4.127i'\D'l0.125i -0.125i'
+.sp -1
+\h'1.626i'\v'4.344i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fRXLocale Source (X Core)\fP'u/2u'\s12\fRXLocale Source (X Core)\fP\h'-\w'\s12\fRXLocale Source (X Core)\fP'u/2u'
+.sp -1
+\h'4.250i'\v'4.344i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fRSystem LOcale Source\fP'u/2u'\s12\fRSystem LOcale Source\fP\h'-\w'\s12\fRSystem LOcale Source\fP'u/2u'
+.sp -1
+\h'2.500i'\v'0.782i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fRXLib API\fP'u/2u'\s12\fRXLib API\fP\h'-\w'\s12\fRXLib API\fP'u/2u'
+.sp -1
+\h'2.500i'\v'0.969i'\h'-0.0m'\v'0.2m'\h'-\w'\s12\fR(X Core)\fP'u/2u'\s12\fR(X Core)\fP\h'-\w'\s12\fR(X Core)\fP'u/2u'
+.sp -1
+\h'1.751i'\v'0.782i'\h'-0.0m'\v'0.2m'\s12\fR<<\fP
+.sp -1
+\h'3.063i'\v'0.782i'\h'-0.0m'\v'0.2m'\s12\fR>>\fP
+.sp -1
+.sp 1+4.344i
+.in -1c
+.PE
+.if \n(00 .fi
+.\" figure end
+.LP
+.ce
+.sp 6p
+Fig.1 : Frame Work of Locale Service API Proposal
+.LP
+Generally speaking, the internationalized portion of Xlib (Locale
+Dependent X, LDX) consists of three objects;
+locale (LC) , input method (IM) and output method (OM).
+The LC provides a set of information that depends on user's language
+environment.  The IM manages text inputing, and the OM manages text
+drawing.  Both IM and OM highly depend on LC data.
+.LP
+In X11R5, there are two sample implementations, Ximp and Xsi, for
+Xlib internationalization.  But in both implementations, IM and OM
+actually refer the private extension of LC.  It breaks coexistence 
+of these two sample implementations.  For example, if a user creates 
+a new OM for special purpose as a part of Ximp, it will not work with 
+Xsi.
+.LP
+As a solution of this problem, we propose to define the standard
+APIs between these three objects, and define the structure that are
+common to these objects.
+.LP
+.NH 1
+Objective
+.XS \*(SN Objective
+.XE 
+.LP 
+.IP \(bu
+Explain the current X11R6 sample implementation
+.IP \(bu
+Document the common set of locale dependent interfaces
+.IP \(bu
+Provide more flexible pluggable layer
+.LP
+.NH 1
+Locale Object Binding Functions
+.XS \*(SN Locale Object Binding Functions
+.XE 
+.LP 
+This chapter describes functions related locale object binding for
+implementing the pluggable layer.
+.LP
+A locale loader is an entry point for locale object, which
+instantiates XLCd object and binds locale methods with specified
+locale name. The behavior of loader is implementation dependent.
+And, what kind of loaders are available is also implementation
+dependent.
+.LP
+The loader is called in 
+.PN _XOpenLC, 
+but caller of 
+.PN _XOpenLC 
+does not need to care about its inside.  For example, if the loader is
+implemented with dynamic load functions, and the dynamic module is
+expected to be unloaded when the corresponding XLCd is freed,
+close methods of XLCdMethods should handle unloading.
+.LP
+.sp
+\fBInitializing a locale loader list\fP
+.LP
+.FD 0
+void _XlcInitLoader()
+.FN
+The 
+.PN _XlcInitLoader
+function initializes the locale loader list with vendor specific 
+manner.  Each loader is registered with calling
+.PN _XlcAddLoader.
+The number of loaders and their order in the loader list is
+implementation dependent.
+.sp
+.LP
+\fBAdd a loader\fP
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef XLCd (*XLCdLoadProc)(\fIname\fP);
+      char \fI*name\fP;
+
+typedef int XlcPosition;
+.De
+.TS
+lw(.5i) lw(2i) lw(2i).
+T{
+#define
+T}	T{
+XlcHead
+T}	T{
+ 0
+T}
+T{
+#define
+T}	T{
+XlcTail
+T}	T{
+-1
+T}
+.TE
+.LP
+.FD 0
+Bool _XlcAddLoader(\fIproc, position\fP)
+.br
+      XLCdLoadProc \fIproc\fP;
+.br
+      XlcPosition \fIposition\fP;
+.FN
+.LP
+The 
+.PN _XlcAddLoader
+function registers the specified locale loader ``\fIproc\fP'' to the 
+internal loader list.  The position specifies that the loader 
+``\fIproc\fP'' should be placed in the top of the loader list(XlcHead) 
+or last(XlcTail).
+.LP
+The object loader is called from the top of the loader list in order,
+when calling time.
+.sp
+.LP
+\fBRemove a loader\fP
+.LP
+.FD 0
+void _XlcRemoveLoader(\fIproc\fP)
+.br
+      XLCdLoadProc \fIproc\fP;
+.FN
+.LP
+The 
+.PN _XlcRemoveLoader
+function removes the locale loader specified by ``\fIproc\fP'' from the 
+loader list.
+.LP
+Current implementation provides following locale loaders;
+.DS
+.PN _XlcDefaultLoader
+.PN _XlcGenericLoader
+.PN _XlcEucLoader
+.PN _XlcSjisLoader
+.PN _XlcUtfLoader
+.PN _XaixOsDynamicLoad
+.DE
+.LP
+.NH 1
+Locale Method Interface
+.XS \*(SN Locale Method Interface
+.XE 
+.LP 
+This chapter describes the locale method API, which is a set of 
+accessible functions from both IM and OM parts.
+The locale method API provides the functionalities;  obtaining locale
+dependent information, handling charset, converting text, etc.
+.LP
+As a result of using these APIs instead of accessing vender private
+extension of the locale object, we can keep locale, IM and OM
+independently each other.
+.LP
+.NH 1
+Locale Method Functions
+.XS \*(SN Locale Method Functions
+.XE 
+.LP 
+\fBOpen a Locale Method\fP
+.LP
+.FD 0
+XLCd _XOpenLC(\fIname\fP)
+.br
+      char \fI*name\fP;
+.FN
+.LP
+The 
+.PN _XOpenLC
+function opens a locale method which corresponds to the
+specified locale name.  
+.PN _XOpenLC
+calls a locale object loader, which is registered via 
+.PN _XlcAddLoader into the internal loader list.  If the called loader 
+is valid and successfully opens a locale, 
+.PN _XOpenLC
+returns the XLCd.  If the loader is invalid or failed to open a locale,
+.PN _XOpenLC
+calls the next loader.  If all registered loaders cannot open a locale, 
+.PN _XOpenLC
+returns NULL.
+.LP
+.FD 0
+XLCd _XlcCurrentLC()
+.FN
+.LP
+The 
+.PN _XlcCurrentLC
+function returns an XLCd that are bound to current locale.
+.sp
+.LP
+\fBClose a Locale Method\fP
+.LP
+.FD 0
+void _XCloseLC(\fIlcd\fP)
+.br
+      XLCd \fIlcd\fP;
+.FN
+.LP
+The 
+.PN _XCloseLC
+function close a locale method the specified lcd.
+.sp
+.LP
+\fBObtain Locale Method values\fP
+.LP
+.FD 0
+char * _XGetLCValues(\fIlcd\fP, ...)
+.br
+      XLCd \fIlcd\fP;
+.FN
+.LP
+The 
+.PN _XGetLCValues
+function returns NULL if no error occurred; otherwise, it returns the 
+name of the first argument that could not be obtained.
+The following values are defined as standard arguments. Other values
+are implementation dependent.
+.LP
+.TS H
+tab(:);
+l l l.
+_
+.sp 6p
+.B
+Name:Type:Description
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+XlcNCodeset:char*:codeset part of locale name
+XlcNDefaultString:char*:XDefaultString()
+XlcNEncodingName:char*:encoding name
+XlcNLanguage:char*:language part of locale name
+XlcNMbCurMax:int:ANSI C MB_CUR_MAX
+XlcNStateDependentEncoding:Bool:is state-dependent encoding or not
+XlcNTerritory:char*:territory part of locale name
+.sp 6p
+_
+.TE
+.LP
+.NH 1
+Charset functions
+.XS \*(SN 
+Charset functions
+.XE 
+.LP 
+The XlcCharSet is an identifier which represents a subset of characters
+(character set) in the locale object. 
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef enum {
+      XlcUnknown, XlcC0, XlcGL, XlcC1, XlcGR, XlcGLGR, XlcOther
+} XlcSide;
+
+typedef struct _XlcCharSetRec *XlcCharSet;
+
+typedef struct {
+      char *name;
+      XPointer value;
+} XlcArg, *XlcArgList;
+
+typedef char* (*XlcGetCSValuesProc)(\fIcharset\fP, \fIargs\fP, \fInum_args\fP);
+      XlcCharSet \fIcharset\fP;
+      XlcArgList \fIargs\fP;
+      int \fInum_args\fP;
+
+typedef struct _XlcCharSetRec {
+      char *name;
+      XrmQuark xrm_name;
+      char *encoding_name;
+      XrmQuark xrm_encoding_name;
+      XlcSide side;
+      int char_size;
+      int set_size;
+      char *ct_sequence; 
+      XlcGetCSValuesProc get_values;
+} XlcCharSetRec;
+.De
+.sp
+.LP
+\fBGet an XlcCharSet\fP
+.LP
+.FD 0
+XlcCharSet _XlcGetCharSet(\fIname\fP)
+.br
+      char \fI*name\fP;
+.FN
+.LP
+The 
+.PN _XlcGetCharSet
+function gets an XlcCharSet which corresponds to the charset name 
+specified by ``\fIname\fP''.  
+.PN _XlcGetCharSet 
+returns NULL, if no XlcCharSet bound to specified ``\fIname\fP''.
+.LP
+The following character sets are pre-registered.
+.LP
+.TS H
+tab(@);
+l l.
+_
+.sp 6p
+.B
+Name@Description
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+ISO8859-1:GL@7-bit ASCII graphics (ANSI X3.4-1968),
+@Left half of ISO 8859 sets
+JISX0201.1976-0:GL@Left half of JIS X0201-1976 (reaffirmed 1984),
+@8-Bit Alphanumeric-Katakana Code
+.sp
+ISO8859-1:GR@Right half of ISO 8859-1, Latin alphabet No. 1
+ISO8859-2:GR@Right half of ISO 8859-2, Latin alphabet No. 2
+ISO8859-3:GR@Right half of ISO 8859-3, Latin alphabet No. 3
+ISO8859-4:GR@Right half of ISO 8859-4, Latin alphabet No. 4
+ISO8859-7:GR@Right half of ISO 8859-7, Latin/Greek alphabet
+ISO8859-6:GR@Right half of ISO 8859-6, Latin/Arabic alphabet
+ISO8859-8:GR@Right half of ISO 8859-8, Latin/Hebrew alphabet
+ISO8859-5:GR@Right half of ISO 8859-5, Latin/Cyrillic alphabet
+ISO8859-9:GR@Right half of ISO 8859-9, Latin alphabet No. 5
+JISX0201.1976-0:GR@Right half of JIS X0201-1976 (reaffirmed 1984),
+@8-Bit Alphanumeric-Katakana Code
+.sp
+GB2312.1980-0:GL@GB2312-1980, China (PRC) Hanzi defined as GL
+GB2312.1980-0:GR@GB2312-1980, China (PRC) Hanzi defined as GR
+JISX0208.1983-0:GL@JIS X0208-1983, Japanese Graphic Character Set
+@defined as GL
+JISX0208.1983-0:GR@JIS X0208-1983, Japanese Graphic Character Set
+@defined as GR
+KSC5601.1987-0:GL@KS C5601-1987, Korean Graphic Character Set
+@defined as GL
+KSC5601.1987-0:GR@KS C5601-1987, Korean Graphic Character Set
+@defined as GR
+JISX0212.1990-0:GL@JIS X0212-1990, Japanese Graphic Character Set
+@defined as GL
+JISX0212.1990-0:GR@JIS X0212-1990, Japanese Graphic Character Set
+@defined as GR
+.\" CNS11643.1986-0:GL
+.\" CNS11643.1986-1:GL
+.\" TIS620-0:GR
+.sp 6p
+_
+.TE
+.LP
+.sp
+\fBAdd an XlcCharSet\fP
+.LP
+.FD 0
+Bool _XlcAddCharSet(\fIcharset\fP)
+      XlcCharSet \fIcharset\fP;
+.FN
+.LP
+The 
+.PN _XlcAddCharSet
+function registers XlcCharSet specified by ``\fIcharset\fP''.
+.LP
+.sp
+\fBObtain Character Set values\fP
+.LP
+.FD 0
+char * _XlcGetCSValues(\fIcharset\fP, ...)
+.br
+      XlcCharSet \fIcharset\fP;
+.FN
+.LP
+The 
+.PN _XlcGetCSValues
+function returns NULL if no error occurred; 
+otherwise, it returns the name of the first argument that could not 
+be obtained.  The following values are defined as standard arguments. 
+Other values are implementation dependent.
+.LP
+.TS H
+tab(:);
+l l l.
+_
+.sp 6p
+.B
+Name:Type:Description
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+XlcNName:char*:charset name
+XlcNEncodingName:char*:XLFD CharSet Registry and Encoding
+XlcNSide:XlcSide:charset side (GL, GR, ...)
+XlcNCharSize:int:number of octets per character
+XlcNSetSize:int:number of character sets
+XlcNControlSequence:char*:control sequence of Compound Text
+.sp 6p
+_
+.TE
+.LP
+.NH 1
+Converter Functions
+.XS \*(SN Converter Functions
+.XE 
+.LP 
+We provide a set of the common converter APIs, that are independent 
+from both of source and destination text type.
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct _XlcConvRec *XlcConv;
+
+typedef void (*XlcCloseConverterProc)(\fIconv\fP);
+      XlcConv \fIconv\fP;
+
+typedef int (*XlcConvertProc)(\fIconv\fP, \fIfrom\fP, \fIfrom_left\fP, \fIto\fP, \fIto_left\fP, \fIargs\fP, \fInum_args\fP);
+      XlcConv \fIconv\fP;
+      XPointer \fI*from\fP;
+      int \fI*from_left\fP;
+      XPointer \fI*to\fP;
+      int \fI*to_left\fP;
+      XPointer \fI*args\fP;
+      int \fInum_args\fP;
+
+typedef void (*XlcResetConverterProc)(\fIconv\fP);
+      XlcConv \fIconv\fP;
+
+typedef struct _XlcConvMethodsRec {
+      XlcCloseConverterProc close;
+      XlcConvertProc convert;
+      XlcResetConverterProc reset;
+} XlcConvMethodsRec, *XlcConvMethods;
+
+typedef struct _XlcConvRec {
+    XlcConvMethods methods;
+    XPointer state;
+} XlcConvRec;
+.De
+.LP
+.sp
+\fBOpen a converter\fP
+.LP
+.FD 0
+XlcConv _XlcOpenConverter(\fIfrom_lcd\fP, \fIfrom_type\fP, \fIto_lcd\fP, \fIto_type\fP)
+.br
+      XLCd \fIfrom_lcd\fP;
+.br
+      char \fI*from_type\fP;
+.br
+      XLCd \fIto_lcd\fP;
+.br
+      char \fI*to_type\fP;
+.FN
+.LP
+.PN _XlcOpenConverter 
+function opens the converter which converts a text from specified 
+``\fIfrom_type\fP'' to specified ``\fIto_type\fP'' encoding.  If the 
+function cannot find proper converter or cannot open a corresponding 
+converter, it returns NULL.  Otherwise, it returns the conversion 
+descriptor.
+.LP
+The following types are pre-defined. Other types are implementation
+dependent.
+.LP
+.TS H
+tab(:);
+l l l l.
+_
+.sp 6p
+.B
+Name:Type:Description:Arguments
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+XlcNMultiByte:char *:multibyte:-
+XlcNWideChar:wchar_t *:wide character:-
+XlcNCompoundText:char *:COMPOUND_TEXT:-
+XlcNString:char *:STRING:-
+XlcNCharSet:char *:per charset:XlcCharSet
+XlcNChar:char *:per character:XlcCharSet
+.sp 6p
+_
+.TE
+.LP
+.sp
+\fBClose a converter\fP
+.LP
+.FD 0
+void _XlcCloseConverter(\fIconv\fP)
+.br
+      XlcConv \fIconv\fP;
+.FN
+.LP
+The 
+.PN _XlcCloseConverter
+function closes the specified converter ``\fIconv\fP''.
+.LP
+.sp
+\fBCode conversion\fP
+.LP
+.FD 0
+int _XlcConvert(\fIconv\fP, \fIfrom\fP, \fIfrom_left\fP, \fIto\fP, \fIto_left\fP, \fIargs\fP, \fInum_args\fP)
+.br
+      XlcConv \fIconv\fP;
+.br
+      XPointer \fI*from\fP;
+.br
+      int \fI*from_left\fP;
+.br
+      XPointer \fI*to\fP;
+.br
+      int \fI*to_left\fP;
+.br
+      XPointer \fI*args\fP;
+.br
+      int \fInum_args\fP;
+.FN
+.LP
+The 
+.PN _XlcConvert
+function converts a sequence of characters from one type, in the array 
+specified by ``\fIfrom\fP'', into a sequence of corresponding characters 
+in another type, in the array specified by ``\fIto\fP''.  The types are 
+those specified in the 
+.PN _XlcOpenConverter() 
+call that returned the conversion descriptor, ``\fIconv\fP''.
+The arguments ``\fIfrom\fP'', ``\fIfrom_left\fP'', ``\fIto\fP'' and 
+``\fIto_left\fP'' have the same specification of XPG4 iconv function.
+.LP
+For state-dependent encodings, the conversion descriptor ``\fIconv\fP''
+is placed into its initial shift state by a call for which ``\fIfrom\fP'' 
+is a NULL pointer, or for which ``\fIfrom\fP'' points to a null pointer.
+.LP
+The following 2 converters prepared by locale returns appropriate 
+charset (XlcCharSet) in an area pointed by args[0].
+.LP
+.TS
+tab(:);
+l l l.
+_
+.sp 6p
+.B
+From:To:Description
+.sp 6p
+_
+.sp 6p
+.R
+XlcNMultiByte:XlcNCharSet:Segmentation (Decomposing)
+XlcNWideChar:XlcNCharSet:Segmentation (Decomposing)
+.sp 6p
+_
+.TE
+.LP
+The conversion, from XlcNMultiByte/XlcNWideChar to XlcNCharSet,
+extracts a segment which has same charset encoding characters.
+More than one segment cannot be converted in a call.
+.LP
+.sp
+\fBReset a converter\fP
+.LP
+.FD 0
+void _XlcResetConverter(\fIconv\fP)
+.br
+      XlcConv \fIconv\fP;
+.FN
+.LP
+The 
+.PN _XlcResetConverter 
+function reset the specified converter ``\fIconv\fP''.
+.LP
+.sp
+\fBRegister a converter\fP
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef XlcConv (*XlcOpenConverterProc)(\fIfrom_lcd\fP, \fIfrom_type\fP, \fIto_lcd\fP, \fIto_type\fP);
+      XLCd \fIfrom_lcd\fP;
+      char \fI*from_type\fP;
+      XLCd \fIto_lcd\fP;
+      char \fI*to_type\fP;
+.De
+.LP
+.FD 0
+Bool _XlcSetConverter(\fIfrom_lcd\fP, \fIfrom\fP, \fIto_lcd\fP, \fIto\fP, \fIconverter\fP)
+.br
+      XLCd \fIfrom_lcd\fP;
+.br
+      char \fI*from\fP;
+.br
+      XLCd \fIto_lcd\fP;
+.br
+      char \fI*to\fP;
+.br
+      XlcOpenConverterProc \fIconverter\fP;
+.FN
+.LP
+The \fBXlcSetConverter\fP function registers a converter which convert 
+from ``\fIfrom_type\fP'' to ``\fIto_type\fP'' into the converter list 
+(in the specified XLCd).
+.LP
+.NH 1
+X Locale Database functions
+.XS \*(SN X Locale Database functions
+.XE 
+.LP 
+X Locale Database contains the subset of user's environment that
+depends on language.  The following APIs are provided for accessing
+X Locale Database and other locale relative files.
+.LP
+For more detail about  X Locale Database, please refer
+X Locale Database Definition document.
+.LP
+.sp
+\fBGet a resource from database\fP
+.LP
+.FD 0
+void _XlcGetResource(\fIlcd\fP, \fIcategory\fP, \fIclass\fP, \fIvalue\fP, \fIcount\fP)
+.br
+      XLCd \fIlcd\fP;
+.br
+      char \fI*category\fP;
+.br
+      char \fI*class\fP;
+.br
+      char \fI***value\fP;
+.br
+      int \fI*count\fP;
+.FN
+.LP
+The 
+.PN _XlcGetResource
+function obtains a locale dependent data which is associated with the 
+locale of specified ``\fIlcd\fP''.
+The locale data is provided by system locale or by X Locale Database 
+file, and what kind of data is available is implementation dependent.
+.LP
+The specified ``\fIcategory\fP'' and ``\fIclass\fP'' are used for 
+finding out the objective locale data.
+.LP
+The returned  value is returned in value argument in string list form,
+and the returned count shows the number of strings in the value.
+.LP
+The returned value is owned by locale method, and should not be modified 
+or freed by caller.
+.LP
+.sp
+\fBGet a locale relative file name\fP
+.LP
+.FD 0
+char * _XlcFileName(\fIlcd\fP, \fIcategory\fP)
+.br
+      XLCd \fIlcd\fP;
+.br
+      char \fI*category\fP;
+.FN
+.LP
+The 
+.PN _XlcFileName 
+functions returns a file name which is bound to the specified ``\fIlcd\fP'' 
+and ``\fIcategory\fP'', as a null-terminated string.  If no file name can 
+be found, or there is no readable file for the found file name, 
+.PN _XlcFileName
+returns NULL.  The returned file name should be freed by caller.
+.LP
+The rule for searching a file name is implementation dependent.
+In current implementation, 
+.PN _XlcFileName 
+uses ``{category}.dir'' file as mapping table, which has pairs of 
+strings, a full locale name and a corresponding file name.
+.LP
+.NH 1
+Utility Functions
+.XS \*(SN Utility Functions
+.XE 
+.LP 
+\fBCompare Latin-1 strings\fP
+.LP
+.FD 0
+int _XlcCompareISOLatin1(\fIstr1\fP, \fIstr2\fP)
+.br
+      char \fI*str1\fP, \fI*str2\fP;
+.FN
+.FD 0
+int _XlcNCompareISOLatin1(\fIstr1\fP, \fIstr2\fP, \fIlen\fP)
+.br
+      char \fI*str1\fP, \fI*str2\fP;
+.br
+      int \fIlen\fP;
+.FN
+.LP
+The 
+.PN _XlcCompareIsoLatin1 
+function to compares two ISO-8859-1 strings.  Bytes representing ASCII lower 
+case letters are converted to upper case before making the comparison.  
+The value returned is an integer less than, equal to, or greater than 
+zero, depending on whether ``\fIstr1\fP'' is lexicographicly less than, 
+equal to, or greater than ``\fIstr2\fP''.
+.LP 
+The 
+.PN _XlcNCompareIsoLatin1
+function is identical to 
+.PN _XlcCompareISOLatin1,
+except that at most ``\fIlen\fP'' bytes are compared.
+.LP
+.sp
+\fBResource Utility\fP
+.LP
+.FD 0
+int XlcNumber(\fIarray\fP)
+      ArrayType \fIarray\fP;
+.FN
+.LP
+Similar to XtNumber.
+.LP
+.FD 0
+void _XlcCopyFromArg(\fIsrc\fP, \fIdst\fP, \fIsize\fP)
+.br
+      char \fI*src\fP;
+.br
+      char \fI*dst\fP;
+.br
+      int \fIsize\fP;
+.FN
+.FD 0
+void _XlcCopyToArg(\fIsrc\fP, \fIdst\fP, \fIsize\fP)
+.br
+      char \fI*src\fP;
+.br
+      char \fI**dst\fP;
+.br
+      int \fIsize\fP;
+.FN
+.LP
+Similar to 
+.PN _XtCopyFromArg 
+and 
+.PN _XtCopyToArg.
+.LP
+.FD 0
+void _XlcCountVaList(\fIvar\fP, \fIcount_ret\fP)
+.br
+      va_list \fIvar\fP;
+.br
+      int \fI*count_ret\fP;
+.FN
+.LP
+Similar to 
+.PN _XtCountVaList.
+.LP
+.FD 0
+void _XlcVaToArgList(\fIvar\fP, \fIcount\fP, \fIargs_ret\fP)
+.br
+      va_list \fIvar\fP;
+.br
+      int \fIcount\fP;
+.br
+      XlcArgList \fI*args_ret\fP;
+.FN
+.LP
+Similar to 
+.PN _XtVaToArgList.
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct _XlcResource {
+      char *name;
+      XrmQuark xrm_name;
+      int size;
+      int offset;
+      unsigned long mask;
+} XlcResource, *XlcResourceList;
+.De
+.LP
+.TS
+lw(.5i) lw(2i) lw(2i).
+T{
+#define
+T}	T{
+XlcCreateMask
+T}	T{
+(1L<<0)
+T}
+T{
+#define
+T}	T{
+XlcDefaultMask
+T}	T{
+(1L<<1)
+T}
+T{
+#define
+T}	T{
+XlcGetMask
+T}	T{
+(1L<<2)
+T}
+T{
+#define
+T}	T{
+XlcSetMask
+T}	T{
+(1L<<3)
+T}
+T{
+#define
+T}	T{
+XlcIgnoreMask
+T}	T{
+(1L<<4)
+T}
+.TE
+.LP
+.FD 0
+void _XlcCompileResourceList(\fIresources\fP, \fInum_resources\fP)
+.br
+      XlcResourceList \fIresources\fP;
+.br
+      int \fInum_resources\fP;
+.FN
+.LP
+Similar to 
+.PN _XtCompileResourceList.
+.LP
+.FD 0
+char * _XlcGetValues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, \fIargs\fP, \fInum_args\fP, \fImask\fP)
+.br
+      XPointer \fIbase\fP;
+.br
+      XlcResourceList \fIresources\fP;
+.br
+      int \fInum_resources\fP;
+.br
+      XlcArgList \fIargs\fP;
+.br
+      int \fInum_args\fP;
+.br
+      unsigned long \fImask\fP;
+.FN
+.LP
+Similar to XtGetSubvalues.
+.LP
+.FD 0
+char * _XlcSetValues(\fIbase\fP, \fIresources\fP, \fInum_resources\fP, \fIargs\fP, \fInum_args\fP, \fImask\fP)
+.br
+      XPointer \fIbase\fP;
+.br
+      XlcResourceList \fIresources\fP;
+.br
+      int \fInum_resources\fP;
+.br
+      XlcArgList \fIargs\fP;
+.br
+      int \fInum_args\fP;
+.br
+      unsigned long \fImask\fP;
+.FN
+.LP
+Similar to XtSetSubvalues.
+.LP
+.sp
+\fBANSI C Compatible Functions\fP
+.LP
+The following are ANSI C/MSE Compatible Functions for non-ANSI C environment.
+.LP
+.FD 0
+int _Xmblen(\fIstr\fP, \fIlen\fP)
+.br
+      char \fI*str\fP;
+.br
+      int \fIlen\fP;
+.FN
+.LP
+The 
+.PN _Xmblen 
+function returns the number of characters pointed to by ``\fIstr\fP''.  
+Only ``\fIlen\fP'' bytes in ``\fIstr\fP'' are used in determining the 
+character count returned.  ``\fIStr\fP'' may point at characters from 
+any valid codeset in the current locale.
+.LP 
+The call 
+.PN _Xmblen
+is equivalent to
+.RS
+_Xmbtowc(_Xmbtowc((\fIwchar_t*\fP)NULL, \fIstr\fP, \fIlen\fP))
+.RE
+.LP
+.FD 0
+int _Xmbtowc(\fIwstr\fP, \fIstr\fP, \fIlen\fP)
+.br
+      wchar_t \fI*wstr\fP;
+.br
+      char \fI*str\fP;
+.br
+      int \fIlen\fP;
+.FN
+.LP
+The 
+.PN _Xmbtowc
+function converts the character(s) pointed to by ``\fIstr\fP'' 
+to their wide character representation(s) pointed to by ``\fIwstr\fP''.  
+``\fILen\fP'' is the number of bytes in ``\fIstr\fP'' to be converted.  
+The return value is the number of characters converted.
+.LP 
+The call 
+.PN _Xmbtowc
+is equivalent to
+.RS
+_Xlcmbtowc((XLCd)NULL, \fIwstr\fP, \fIstr\fP, \fIlen\fP)
+.RE
+.LP
+.FD 0
+int _Xlcmbtowc(\fIlcd\fP, \fIwstr\fP, \fIstr\fP, \fIlen\fP)
+.br
+      XLCd \fIlcd\fP;
+.br
+      wchar_t \fI*wstr\fP;
+.br
+      char \fI*str\fP;
+.br
+      int \fIlen\fP;
+.FN
+.LP
+The 
+.PN _Xlcmbtowc
+function is identical to 
+.PN _Xmbtowc, 
+except that it requires the ``\fIlcd\fP'' argument.  If ``\fIlcd\fP'' 
+is (XLCd) NULL, 
+.PN _Xlcmbtowc, 
+calls 
+.PN _XlcCurrentLC 
+to determine the current locale.
+.LP 
+.FD 0
+int _Xwctomb(\fIstr\fP, \fIwc\fP)
+.br
+      char \fI*str\fP;
+.br
+      wchar_t \fIwc\fP;
+.FN
+.LP
+The 
+.PN _Xwctomb 
+function converts a single wide character pointed to by ``\fIwc\fP'' to 
+its multibyte representation pointed to by ``\fIstr\fP''.  
+On success, the return value is 1.
+.LP 
+The call 
+.PN _Xwctomb
+is equivalent to
+.RS
+_Xlcwctomb((XLCd)NULL, \fIstr\fP, \fIwstr\fP)
+.RE
+.LP
+.FD 0
+int _Xlcwctomb(\fIlcd\fP, \fIstr\fP, \fIwc\fP)
+.br
+      XLCd \fIlcd\fP;
+.br
+      char \fI*str\fP;
+.br
+      wchar_t \fIwc\fP;
+.FN
+.LP
+The 
+.PN _Xlcwctomb
+function is identical to _Xwctomb, except that it requires the 
+``\fIlcd\fP'' argument.  If ``\fIlcd\fP'' is (XLCd) NULL, 
+.PN _Xlcwctomb, 
+calls 
+.PN _XlcCurrentLC 
+to determine the current locale.
+.LP
+.FD 0
+int _Xmbstowcs(\fIwstr\fP, \fIstr\fP, \fIlen\fP)
+.br
+      wchar_t \fI*wstr\fP;
+.br
+      char \fI*str\fP;
+.br
+      int \fIlen\fP;
+.FN
+.LP
+The 
+.PN _Xmbstowcs
+function converts the NULL-terminated string pointed to by ``\fIstr\fP'' 
+to its wide character string representation pointed to by ``\fIwstr\fP''.
+``\fILen\fP'' is the number of characters in ``\fIstr\fP'' to be converted.
+.LP
+The call 
+.PN _Xmbstowcs
+is equivalent to
+.RS
+_Xlcmbstowcs((XLCd)NULL, \fIwstr\fP, \fIstr\fP, \fIlen\fP)
+.RE
+.LP
+.FD 0
+int _Xlcmbstowcs(\fIlcd\fP, \fIwstr\fP, \fIstr\fP, \fIlen\fP)
+.br
+      XLCd \fIlcd\fP;
+.br
+      wchar_t \fI*wstr\fP;
+.br
+      char \fI*str\fP;
+.br
+      int \fIlen\fP;
+.FN
+.LP
+The 
+.PN _Xlcmbstowcs 
+function is identical to _Xmbstowcs, except that it requires the 
+``\fIlcd\fP'' argument.  If ``\fIlcd\fP'' is (XLCd) NULL, 
+.PN _Xlcmbstowcs, 
+calls 
+.PN _XlcCurrentLC
+to determine the current locale.
+.LP
+.FD 0
+int _Xwcstombs(\fIstr\fP, \fIwstr\fP, \fIlen\fP)
+.br
+      char \fI*str\fP;
+.br
+      wchar_t \fI*wstr\fP;
+.br
+      int \fIlen\fP;
+.FN
+.LP
+The 
+.PN _Xwcstombs 
+function converts the (wchar_t) NULL terminated wide character string 
+pointed to by ``\fIwstr\fP'' to the NULL terminated multibyte string 
+pointed to by ``\fIstr\fP''.
+.LP 
+The call 
+.PN _Xwcstombs 
+is equivalent to
+.RS
+_Xlcwcstombs((XLCd)NULL, \fIstr\fP, \fIwstr\fP, \fIlen\fP)
+.RE
+.LP
+.FD 0
+int _Xlcwcstombs(\fIlcd\fP, \fIstr\fP, \fIwstr\fP, \fIlen\fP)
+.br
+      XLCd \fIlcd\fP;
+.br
+      char \fI*str\fP;
+.br
+      wchar_t \fI*wstr\fP;
+.br
+      int \fIlen\fP;
+.FN
+.LP
+The 
+.PN _Xlcwcstombs 
+function is identical to _Xwcstombs, except that it requires the 
+``\fIlcd\fP'' argument.  If ``\fIlcd\fP'' is (XLCd) NULL, 
+.PN _Xlcwcstombs, 
+calls 
+.PN _XlcCurrentLC 
+to determine the current locale.
+.LP
+.FD 0
+int _Xwcslen(\fIwstr\fP)
+.br
+      wchar_t \fI*wstr\fP;
+.FN
+.LP
+The 
+.PN _Xwcslen 
+function returns the count of wide characters in the (wchar_t) NULL 
+terminated wide character string pointed to by ``\fIwstr\fP''.
+.LP
+.FD 0
+wchar_t * _Xwcscpy(\fIwstr1\fP, \fIwstr2\fP)
+.br
+      wchar_t \fI*wstr1\fP, \fI*wstr2\fP;
+.FN
+.FD 0
+wchar_t * _Xwcsncpy(\fIwstr1\fP, \fIwstr2\fP, \fIlen\fP)
+.br
+      wchar_t \fI*wstr1\fP, \fI*wstr2\fP;
+.br
+      int \fIlen\fP;
+.FN
+.LP
+The 
+.PN _Xwcscpy 
+function copies the (wchar_t) NULL terminated wide character string 
+pointed to by ``\fIwstr2\fP'' to the object pointed at by ``\fIwstr1\fP''.
+``\fIWstr1\fP'' is (wchar_t) NULL terminated.  The return value is a 
+pointer to ``\fIwstr1\fP''.
+.LP
+The 
+.PN _Xwcsncpy
+function is identical to 
+.PN _Xwcscpy, 
+except that it copies ``\fIlen\fP'' wide characters from the object 
+pointed to by ``\fIwstr2\fP'' to the object pointed to ``\fIwstr1\fP''.
+.LP
+.FD 0
+int _Xwcscmp(\fIwstr1\fP, \fIwstr2\fP)
+.br
+      wchar_t \fI*wstr1\fP, \fI*wstr2\fP;
+.FN
+.FD 0
+int _Xwcsncmp(\fIwstr1\fP, \fIwstr2\fP, \fIlen\fP)
+.br
+      wchar_t \fI*wstr1\fP, \fI*wstr2\fP;
+.br
+      int \fIlen\fP;
+.FN
+.LP
+The 
+.PN _Xwcscmp 
+function  compares two (wchar_t) NULL terminated wide character strings.  
+The value returned is an integer less than, equal to, or greater than zero, 
+depending on whether ``\fIwstr1\fP'' is lexicographicly less then, equal to,
+or greater than ``\fIstr2\fP''.
+.LP 
+The 
+.PN _Xwcsncmp 
+function is identical to 
+.PN _XlcCompareISOLatin1, 
+except that at most ``\fIlen\fP'' wide characters are compared.
+.sp
+.\" --------------------------------------------------------------------
+.\" .LP
+.\" \fBLocale Method Internal Functions\fP
+.\" .LP
+.\" .FD 0
+.\" XlcCharSet _XlcCreateDefaultCharSet(\fIname\fP, \fIct_sequence\fP)
+.\" .br
+.\"       char \fI*name\fP;
+.\" .br
+.\"       char \fI*ct_sequence\fP;
+.\" .FN
+.\" .FD 0
+.\" Bool _XlcParseCharSet(\fIcharset\fP)
+.\" .br
+.\"       XlcCharSet \fIcharset\fP;
+.\" .FN
+.\" .FD 0
+.\" void _XlcGetLocaleDataBase(\fIlcd\fP, \fIcategory\fP, \fIname\fP, \fIvalue\fP, \fIcount\fP)
+.\" .br
+.\"       XLCd \fIlcd\fP;
+.\" .br
+.\"       char \fI*category\fP;
+.\" .br
+.\"       char \fI*name\fP;
+.\" .br
+.\"       char \fI***value\fP;
+.\" .br
+.\"       int \fI*count\fP;
+.\" .FN
+.\" .FD 0
+.\" void _XlcDestroyLocaleDataBase(\fIlcd\fP)
+.\" .br
+.\"       XLCd \fIlcd\fP;
+.\" .FN
+.\" .FD 0
+.\" XPointer _XlcCreateLocaleDataBase(\fIlcd\fP)
+.\" .br
+.\"       XLCd \fIlcd\fP;
+.\" .FN
+.\" .LP
+.\" .sp
+.\" \fBObtain an locale database path\fP
+.\" .LP
+.\" .FD 0
+.\" int _XlcResolveI18NPath(\fIdir\fP)
+.\" .br
+.\"       char \fI*dir\fP;
+.\" .FN
+.\" .LP
+.\" The 
+.\" .PN _XlcResolveI18NPath 
+.\" function returns path name list that is related to X Locale Database.
+.\" The obtained path is stored into the array which is pointed by
+.\" specified ``\fIdir\fP''.  The path consists of directory paths which 
+.\" are separated with colon.
+.\" If the environment variable XLOCALEDIR is specified, the path
+.\" contains its contents.
+.\" .LP
+.\" The default path of X Locale Database is implementation dependent.
+.\" In current implementation, it's determined in build time.
+.\" .LP
+.\" .PN _XlcResolveI18NPath 
+.\" does not check overflow of the array to which the ``\fIdir\fP'' 
+.\" parameter points.  Caller should provide enough buffer to store this 
+.\" string.
+.\" .LP
+.\" .sp
+.\" \fBObtain a full locale name\fP
+.\" .LP
+.\" .FD 0
+.\" int _XlcResolveLocaleName(\fIlc_name\fP, \fIfull_name\fP, \fIlanguage\fP, \fIterritory\fP, \fIcodeset\fP)
+.\" .br
+.\"       char \fI*lc_name\fP;
+.\" .br
+.\"       char \fI*full_name\fP;
+.\" .br
+.\"       char \fI*language\fP;
+.\" .br
+.\"       char \fI*territory\fP;
+.\" .br
+.\"       char \fI*codeset\fP;
+.\" .FN
+.\" .LP
+.\" The 
+.\" .PN _XlcResolveLocaleName 
+.\" function returns a full locale name.
+.\" The obtained full locale name is stored into the array which is
+.\" pointed by specified ``\fIfull_name\fP''.
+.\" The language, territory and codeset part of the full locale name
+.\" are copied to the return arguments, ``\fIlanguage\fP'', 
+.\" ``\fIterritory\fP'' and ``\fIcodeset\fP'', respectively.
+.\" NULL can be specified for these arguments.
+.\" .LP
+.\" The rule for mapping from locale name to full locale name is
+.\" implementation dependent.
+.\" .LP
+.\" .PN _XlcResolveLocaleName 
+.\" does not check overflow of the array to which
+.\" ``\fIfull_name\fP'', ``\fIlanguage\fP'', ``\fIterritory\fP'' and 
+.\" ``\fIcodeset\fP'' parameter point.
+.\" Caller should provide enough buffer to store those string.
+.\" .LP
+.\" In current implementation, 
+.\" .PN _XlcResolveLocaleName 
+.\" uses locale.alias file as mapping table, which has pairs of strings, 
+.\" a locale name and a full locale name.
+.\" .LP
+.\" .FD 0
+.\" int _XlcResolveDBName(\fIlc_name\fP, \fIfile_name\fP)
+.\" .br
+.\"       char \fI*lc_name\fP;
+.\" .br
+.\"       char \fI*file_name\fP;
+.\" .FN
+.\" .FD 0 
+.\" XLCd _XlcCreateLC(\fIname\fP, \fImethods\fP)
+.\" .br
+.\"       char \fI*name\fP;
+.\" .br
+.\"       XLCdMethods \fImethods\fP;
+.\" .FN
+.\" .FD 0
+.\" void _XlcDestroyLC(\fIlcd\fP)
+.\" .br
+.\"       XLCd \fIlcd\fP;
+.\" .FN
+.\" .LP
+.\" 
+
diff --git a/specs/i18n/LocaleDB.ms b/specs/i18n/LocaleDB.ms
new file mode 100644
index 00000000..5ba79229
--- /dev/null
+++ b/specs/i18n/LocaleDB.ms
@@ -0,0 +1,502 @@
+.\" $Xorg: LocaleDB.ms,v 1.3 2000/08/17 19:42:49 cpqbld Exp $
+.\" $XdotOrg: xc/doc/specs/i18n/LocaleDB.ms,v 1.2 2004/04/23 18:42:19 eich Exp $
+.\" To print this out, type tbl macros.t ThisFile | troff -ms
+.EH ''''
+.OH ''''
+.EF ''''
+.OF ''''
+.ps 11
+.nr PS 11
+\&
+.TL
+\s+3\fBX Locale Database Definition\fP\s-3
+.sp 2
+.AU
+Yoshio Horiuchi
+.AI
+IBM Japan
+.LP
+.bp
+.br
+\&
+.ps 9
+.nr PS 9
+.sp 2
+.LP
+Copyright \(co IBM Corporation 1994
+.LP
+All Rights Reserved
+.LP
+License to use, copy, modify, and distribute this software and its
+documentation for any purpose and without fee is hereby granted,
+provided that the above copyright notice appear in all copies and that
+both that copyright notice and this permission notice appear in
+supporting documentation, and that the name of IBM not be
+used in advertising or publicity pertaining to distribution of the
+software without specific, written prior permission.
+.LP
+IBM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
+ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS, AND
+NONINFRINGEMENT OF THIRD PARTY RIGHTS, IN NO EVENT SHALL
+IBM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
+ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
+SOFTWARE.
+.sp 5
+Copyright \(co 1994 X Consortium
+.LP
+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:
+.LP
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+.LP
+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.
+.LP
+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.
+.sp 3
+\fIX Window System\fP is a trademark of The Open Group.
+.LP
+.bp 1
+.ps 11
+.nr PS 11
+.EH '\fBX Locale Database Definition\fP''\fB\*(xV\fP'
+.OH '\fBX Locale Database Definition\fP''\fB\*(xV\fP'
+.EF ''\fB % \fP''
+.OF ''\fB % \fP''
+.NH 1
+General
+.XS
+\*(SN General
+.XE
+.LP
+An X Locale Database contains the subset of a user's environment that
+depends on language, in X Window System.  It is made up from one or more
+categories.  Each category consists of some classes and sub-classes.
+.LP
+It is provided as a plain ASCII text file, so a user can change its
+contents easily.  It allows a user to customize the behavior of
+internationalized portion of Xlib without changing Xlib itself.
+.LP
+This document describes;
+.RS
+.IP
+Database Format Definition
+.IP
+Contents of Database in sample implementation
+.RE
+.LP
+Since it is hard to define the set of required information for all
+platforms, only the flexible database format is defined.
+The available entries in database are implementation dependent.
+.LP
+.NH 1
+Database Format Definition
+.XS
+\*(SN Database Format Definition
+.XE
+.LP
+The X Locale Database contains one or more category definitions.
+This section describes the format of each category definition.
+.LP
+The category definition consists of one or more class definitions.
+Each class definition has a pair of class name and class value, or
+has several subclasses which are enclosed by the left brace ({) and
+the right brace (}).
+.LP
+Comments can be placed by using the number sign character (#).
+Putting the number sign character on the top of the line indicates
+that the entire line is comment.  Also, putting any whitespace character
+followed by the number sign character indicates that a part of the line
+(from the number sign to the end of the line) is comment.
+A line can be continued by placing backslash (\\) character as the
+last character on the line;  this continuation character will be
+discarded from the input.  Comment lines cannot be continued on
+a subsequent line using an escaped new line character.
+.LP
+X Locale Database only accepts XPCS, the X Portable Character Set.
+The reserved symbols are;  the quotation mark("), the number sign (#),
+the semicolon(;), the backslash(\\), the left brace({) and 
+the right brace(}).
+.LP
+The format of category definition is;
+.RS
+.TS
+tab(@);
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l l l
+l r l
+l r l
+l l l.
+CategoryDefinition@::=@CategoryHeader CategorySpec CategoryTrailer
+CategoryHeader@::=@CategoryName NL
+CategorySpec@::=@{ ClassSpec }
+CategoryTrailer@::=@"END" Delimiter CategoryName NL
+CategoryName@::=@String
+ClassSpec@::=@ClassName Delimiter ClassValue NL
+ClassName@::=@String
+ClassValue@::=@ValueList | "{" NL { ClassSpec } "}"
+ValueList@::=@Value | Value ";" ValueList
+Value@::=@ValuePiece | ValuePiece Value
+ValuePiece@::=@String | QuotedString | NumericString
+String@::=@Char { Char }
+QuotedString@::=@""" QuotedChar { QuotedChar } """
+NumericString@::=@"\\\\o" OctDigit { OctDigit }
+@|@"\\\\d" DecDigit { DecDigit }
+@|@"\\\\x" HexDigit { HexDigit }
+Char@::=@<XPCS except NL, Space or unescaped reserved symbols>
+QuotedChar@::=@<XPCS except unescaped """>
+OctDigit@::=@<character in the range of "0" - "7">
+DecDigit@::=@<character in the range of "0" - "9">
+HexDigit@::=@<character in the range of "0" - "9", "a" - "f", "A" - "F">
+Delimiter@::=@ Space { Space }
+Space@::=@<space> | <horizontal tab>
+NL@::=@<newline>
+.TE
+.RE
+.LP
+Elements separated by vertical bar (|) are alternatives.  Curly
+braces ({...}) indicate zero or more repetitions of the enclosed
+elements.  Square brackets ([...]) indicate that the enclosed element
+is optional. Quotes ("...") are used around literal characters.
+.LP
+The backslash, which is not the top character of the NumericString, is
+recognized as an escape character, so that the next one character is
+treated as a literal character.  For example, the two-character
+sequence, ``\\"''(the backslash followed by the quotation mark) is
+recognized and replaced with a quotation mark character.
+Any whitespace character, that is not the Delimiter, unquoted and
+unescaped, is ignored.  
+.LP
+.NH 1
+Contents of Database 
+.XS
+\*(SN Contents of Database 
+.XE
+.LP
+The available categories and classes depend on implementation, because
+different platform will require different information set.
+For example, some platform have system locale but some platform don't.
+Furthermore, there might be a difference in functionality even if the
+platform has system locale.
+.LP
+In current sample implementation, categories listed below are available.
+.RS
+.TS
+tab(:);
+l l.
+XLC_FONTSET:XFontSet relative information
+XLC_XLOCALE:Character classification and conversion information
+.TE
+.RE
+.LP
+.NH 1
+XLC_FONTSET Category
+.XS
+\*(SN XLC_FONTSET Category
+.XE
+.LP
+The XLC_FONTSET category defines the XFontSet relative information.
+It contains the CHARSET_REGISTRY-CHARSET_ENCODING name and character
+mapping side (GL, GR, etc), and is used in Output Method (OM).
+.RS
+.TS H
+tab(:);
+lw(1.5i) l l.
+_
+.sp 6p
+.B
+class:super class:description
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+fsN::Nth fontset (N=0,1,2, ...)
+.sp 
+charset:fsN:list of encoding name
+font:fsN:list of font encoding name
+.sp 6p
+_
+.TE
+.RE
+.LP
+.IP "fsN"
+.br
+Includes an encoding information for Nth charset, where N is
+the index number (0,1,2,...).  If there are 4 charsets available
+in current locale, 4 fontsets, fs0, fs1, fs2 and fs3, should be
+defined.
+This class has two subclasses, `charset' and `font'.
+.IP "charset"
+Specifies an encoding information to be used internally in Xlib
+for this fontset.  The format of value is;
+.RS
+.TS
+tab(;);
+l l l.
+EncodingInfo;::=;EncodingName [ ":" EncodingSide ]
+EncodingName;::=;CHARSET_REGISTRY-CHARSET_ENCODING
+EncodingSide;::=;"GL" | "GR"
+.TE
+.RE
+For detail definition of CHARSET_REGISTRY-CHARSET_ENCODING, refer
+"X Logical Font Descriptions" document.
+.IP
+example:
+.br
+	ISO8859-1:GL
+.IP "font"
+.br
+Specifies a list of encoding information which is used for searching
+appropriate font for this fontset.  The left most entry has highest
+priority.
+.LP
+.NH 1
+XLC_XLOCALE Category
+.XS
+\*(SN XLC_XLOCALE Category
+.XE
+.LP
+The XLC_XLOCALE category defines character classification, conversion
+and other character attributes.
+.RS
+.TS H
+tab(:);
+lw(1.5i) l l.
+_
+.sp 6p
+.B
+class:super class:description
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+encoding_name::codeset name
+mb_cur_max::MB_CUR_MAX
+state_depend_encoding::state dependent or not
+wc_encoding_mask::for parsing wc string
+wc_shift_bits::for conversion between wc and mb
+csN::Nth charset (N=0,1,2,...)
+.sp
+side:csN:mapping side (GL, etc)
+length:csN:length of a character
+mb_encoding:csN:for parsing mb string
+wc_encoding:csN:for parsing wc string
+ct_encoding:csN:list of encoding name for ct
+.sp 6p
+_
+.TE
+.RE
+.LP
+.IP "encoding_name"
+Specifies a codeset name of current locale.
+.IP "mb_cur_max"
+Specifies a maximum allowable number of bytes in a multi-byte character.  
+It is corresponding to MB_CUR_MAX of "ISO/IEC 9899:1990 C Language Standard".
+.IP "state_depend_encoding"
+Indicates a current locale is state dependent. The value should be
+specified "True" or "False".
+.IP "wc_encoding_mask"
+Specifies a bit-mask for parsing wide-char string.  Each wide character is 
+applied bit-and operation with this bit-mask, then is classified into 
+the unique charset, by using `wc_encoding'.
+.IP "wc_shift_bits"
+Specifies a number of bit to be shifted for converting from a multi-byte 
+character to a wide character, and vice-versa.
+.IP "csN"
+.br
+Includes a character set information for Nth charset, where N is the 
+index number (0,1,2,...).  If there are 4 charsets available in current 
+locale, cs0, cs1, cs2 and cs3 should be defined. This class has five 
+subclasses, `side', `length', `mb_encoding' `wc_encoding' and `ct_encoding'.
+.IP "side"
+.br
+Specifies a mapping side of this charset. The format of this value is;
+.RS
+.TS
+tab(@);
+l l l.
+Side@::=@EncodingSide [``:Default'']
+.TE
+.RE
+The suffix ":Default" can be specified.  It indicates that a character 
+belongs to the specified side is mapped to this charset in initial state.
+.IP "length"
+.br
+Specifies a number of bytes of a multi-byte character of this charset.
+It should not contain the length of any single-shift sequence.
+.IP "mb_encoding"
+Specifies a list of shift sequence for parsing multi-byte string.
+The format of this value is;
+.RS
+.TS
+tab(@);
+l l l
+l r l
+l l l
+l l l
+l l l
+l l l
+c l s 
+c l s.
+MBEncoding@::=@ShiftType ShiftSequence
+@|@ShiftType ShiftSequence ";" MBEncoding
+ShiftType@::=@"<SS>" | "<LSL>" | "<LSR>"
+ShiftSequence@::=@SequenceValue | SequenceValue ShiftSequence
+SequenceValue@::=@NumericString
+.sp
+shift types:
+<SS>@Indicates single shift sequence
+<LSL>@Indicates locking shift left sequence
+<LSR>@Indicates locking shift right sequence
+.TE
+.RE
+example:
+.br
+	<LSL> \\x1b \\x28 \\x4a; <LSL> \\x1b \\x28 \\x42
+.LP
+.IP "wc_encoding"
+Specifies an integer value for parsing wide-char string.
+It is used to determine the charset for each wide character, after
+applying bit-and operation using `wc_encoding_mask'.
+This value should be unique in all csN classes.
+.IP "ct_encoding"
+Specifies a list of encoding information that can be used for Compound 
+Text.
+.LP
+.NH 1
+Sample of X Locale Database
+.XS
+\*(SN Sample of X Locale Database
+.XE
+.LP
+The following is sample X Locale Database file.
+.LP
+.sp
+.RS
+.nf
+#  $Xorg: LocaleDB.ms,v 1.3 2000/08/17 19:42:49 cpqbld Exp $
+#  XLocale Database Sample for ja_JP.euc 
+# 
+
+# 
+# 	XLC_FONTSET category
+# 
+XLC_FONTSET
+# 	fs0 class (7 bit ASCII)
+fs0	{
+	charset		ISO8859-1:GL
+	font			ISO8859-1:GL; JISX0201.1976-0:GL
+}
+# 	fs1 class (Kanji)
+fs1	{
+	charset		JISX0208.1983-0:GL
+	font			JISX0208.1983-0:GL
+}
+# 	fs2 class (Half Kana)
+fs2	{
+	charset		JISX0201.1976-0:GR
+	font			JISX0201.1976-0:GR
+}
+# 	fs3 class (User Defined Character)
+# fs3	{
+#	charset		JISX0212.1990-0:GL
+#	font			JISX0212.1990-0:GL
+# }
+END XLC_FONTSET
+
+# 
+# 	XLC_XLOCALE category
+# 
+XLC_XLOCALE
+
+encoding_name		ja.euc
+mb_cur_max		3
+state_depend_encoding	False
+
+wc_encoding_mask	\\x00008080
+wc_shift_bits		8
+
+# 	cs0 class
+cs0	{
+	side			GL:Default
+	length		1
+	wc_encoding	\\x00000000
+	ct_encoding		ISO8859-1:GL; JISX0201.1976-0:GL
+}
+# 	cs1 class
+cs1	{
+	side			GR:Default
+	length		2
+
+	wc_encoding	\\x00008080
+
+	ct_encoding		JISX0208.1983-0:GL; JISX0208.1983-0:GR;\\
+				JISX0208.1983-1:GL; JISX0208.1983-1:GR
+}
+
+# 	cs2 class
+cs2	{
+	side			GR
+	length		1
+	mb_encoding	<SS> \\x8e
+
+	wc_encoding	\\x00000080
+
+	ct_encoding		JISX0201.1976-0:GR
+}
+
+# 	cs3 class
+# cs3	{
+# 	side			GL
+# 	length		2
+# 	mb_encoding	<SS> \\x8f
+# #if HasWChar32
+# 	wc_encoding	\\x20000000
+# #else
+# 	wc_encoding	\\x00008000
+# #endif
+# 	ct_encoding	JISX0212.1990-0:GL; JISX0212.1990-0:GR
+# }
+
+END XLC_XLOCALE
+.fi
+.RE
+.LP
+.NH 1
+Reference
+.XS
+\*(SN Reference
+.XE
+.LP
+.XP
+[1] \fIISO/IEC 9899:1990 C Language Standard\fP
+.XP
+[2] \fIX Logical Font Descriptions\fP
+.LP
diff --git a/specs/i18n/Makefile.am b/specs/i18n/Makefile.am
new file mode 100644
index 00000000..dff852d1
--- /dev/null
+++ b/specs/i18n/Makefile.am
@@ -0,0 +1,33 @@
+#
+# Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
+#
+# Permission to use, copy, modify, distribute, and sell this software and its
+# documentation for any purpose is hereby granted without fee, provided that
+# the above copyright notice appear in all copies and that both that
+# copyright notice and this permission notice appear in supporting
+# documentation.
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# 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 OPEN GROUP 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.
+#
+# Except as contained in this notice, the name of the copyright holders 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 copyright holders.
+#
+
+# Based on xc/doc/specs/i18n/Makefile from X11R6.9
+
+doc_sources = Framework.ms LocaleDB.ms Trans.ms 
+
+include $(top_srcdir)/specs/troffrules.in
+
+
diff --git a/specs/i18n/Trans.ms b/specs/i18n/Trans.ms
new file mode 100644
index 00000000..19c05394
--- /dev/null
+++ b/specs/i18n/Trans.ms
@@ -0,0 +1,1148 @@
+.\" $Xorg: Trans.ms,v 1.3 2000/08/17 19:42:49 cpqbld Exp $
+.\" $XdotOrg: xc/doc/specs/i18n/Trans.ms,v 1.2 2004/04/23 18:42:19 eich Exp $
+.\" To print this out, type tbl macros.t This File | troff -ms
+.EH ''''
+.OH ''''
+.EF ''''
+.OF ''''
+.ps 11
+.nr PS 11
+.\" .nr PD 1v
+.\" .nr DD 1v
+\&
+.sp 8
+.TL
+\s+3\fBThe XIM Transport Specification\s-3\fP
+.sp
+.sp
+\fBRevision 0.1\fP
+.sp
+\fBX Version 11, Release 7\fP
+.sp
+\fB\*(xV\fP
+.sp 3
+.AU
+Takashi Fujiwara
+.AI
+FUJITSU LIMITED
+.sp 3
+.AB
+.LP
+This specification describes the transport layer interfaces between
+Xlib and IM Server, which makes various channels usable such as X
+protocol or, TCP/IP, DECnet and etc.
+.AE
+.ce 0
+.br
+.LP
+.bp
+\&
+.ps 9
+.nr PS 9
+.sp 8
+.LP
+Copyright \(co 1994 by FUJITSU LIMITED
+.LP
+Permission to use, copy, modify, and distribute this documentation
+for any purpose and without fee is hereby granted, provided
+that the above copyright notice and this permission
+notice appear in all copies.
+Fujitsu 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.
+.sp 5
+Copyright \(co 1994 X Consortium
+.LP
+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:
+.LP
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+.LP
+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.
+.LP
+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.
+.sp 3
+\fIX Window System\fP is a trademark of The Open Group.
+.ps 11
+.nr PS 11
+.bp 1
+.EH '\fBXIM Transport Specification\fP''\fB\*(xV\fP'
+.OH '\fBXIM Transport Specification\fP''\fB\*(xV\fP'
+.EF ''\fB % \fP''
+.OF ''\fB % \fP''
+.NH 1
+Introduction
+.XS
+\*(SN Introduction
+.XE
+.LP
+The Xlib XIM implementation is layered into three functions, a protocol
+layer, an interface layer and a transport layer. The purpose of this
+layering is to make the protocol independent of transport implementation.
+Each function of these layers are:
+.RS 3
+.IP "\fIThe protocol layer\fP"
+.br
+implements overall function of XIM and calls the interface layer
+functions when it needs to communicate to IM Server. 
+.IP "\fIThe interface layer\fP"
+.br
+separates the implementation of the transport layer from the protocol
+layer, in other words, it provides implementation independent hook for
+the transport layer functions.
+.IP "\fIThe transport layer\fP"
+.br
+handles actual data communication with IM Server. It is done by a set
+of several functions named transporters.
+.RE
+.LP
+This specification describes the interface layer and the transport 
+layer, which makes various communication channels usable such as 
+X protocol or, TCP/IP, DECnet, STREAM, etc., and provides
+the information needed for adding another new transport layer.
+In addition, sample implementations for the transporter using the 
+X connection is described in section 4.
+.NH 1
+Initialization
+.XS
+\*(SN Initialization
+.XE
+.NH 2
+Registering structure to initialize
+.XS
+\*(SN Registering structure to initialize
+.XE
+.LP
+The structure typed as TransportSW contains the list of the transport
+layer the specific implementations supports.
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+.br
+      char *transport_name;
+.br
+      Bool (*config);
+} TransportSW;
+.De
+.LP
+.IP "\fItransport_name\fP" 15
+name of transport(*1)
+.FS 
+(*1) Refer to "The Input Method Protocol: Appendix B" 
+.FE
+.IP "\fIconfig\fP" 15
+initial configuration function
+.LP
+A sample entry for the Xlib supporting transporters is shown below:
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+TransportSW _XimTransportRec[] = {
+.sp 3p
+/*	char \fI*:
+\ *	transport_name\fP,	Bool \fI(*config)()\fP
+\ */
+	``X'',	_XimXConf,
+	``tcp'',	_XimTransConf,
+	``local'',	_XimTransConf,
+	``decnet'',	_XimTransConf,
+	``streams'',	_XimTransConf,
+	(char *)NULL,	(Bool (*)())NULL,
+};
+.De
+.LP
+.NH 2
+Initialization function
+.XS
+\*(SN Initialization function
+.XE
+.LP
+The following function will be called once when Xlib configures the
+transporter functions.
+.sp 6p 
+.FD 0
+Bool (*config)(\fIim\fP, \fItransport_data\fP)
+.br
+      XIM \fIim\fP;
+.br
+      char \fI*transport_data\fP;
+.br
+.FN
+.IP \fIim\fP 1i
+Specifies XIM structure address.
+.IP \fItransport_data\fP 1i
+Specifies the data specific to the transporter, in IM Server address. (*1)
+.FS 
+(*1) Refer to "The Input Method Protocol: Appendix B" 
+.FE
+.sp 6p
+.LP
+This function must setup the transporter function pointers. 
+.LP
+The actual \fIconfig\fP function will be chosen by IM Server at the
+pre-connection time, matching by the \fItransport_name\fP specified 
+in the \fB_XimTransportRec\fP array; The specific members of XimProto 
+structure listed below must be initialized so that point they 
+appropriate transporter functions.
+.LP
+If the specified transporter has been configured successfully, this
+function returns True. There is no Alternative Entry for config
+function itself.
+.LP
+The structure XimProto contains the following function pointers:
+.DS
+.TA .5i 2.5i
+.ta .5i 2.5i
+Bool (*connect)();			/* Open connection */
+Bool (*shutdown)();			/* Close connection */
+Bool (*write)();				/* Write data */
+Bool (*read)();				/* Read data */
+Bool (*flush)();				/* Flush data buffer */
+Bool (*register_dispatcher)();	/* Register asynchronous data handler */
+Bool (*call_dispatcher)();	/* Call dispatcher */
+.DE
+These functions are called when Xlib needs to communicate the
+IM Server. These functions must process the appropriate procedure
+described below.
+.LP
+.NH 1
+The interface/transport layer functions
+.XS
+\*(SN The interface/transport layer functions
+.XE
+.LP  
+Following functions are used for the transport interface.
+.LP
+.ce
+Table 3-1; The Transport Layer Functions.
+.SM
+.TS
+tab(:) center box;
+cw(4c) | cw(4c) | c
+c | c | c
+l | l | c.
+.B
+Alternative Entry:XimProto member:Section 
+(Interface Layer):(Transport Layer):\^
+=
+.R
+\fB_XimConnect\fP:connect:3.1
+_
+\fB_XimShutdown\fP:shutdown:3.2
+_
+\fB_XimWrite\fP:write:3.3
+_
+\fB_XimRead\fP:read:3.4
+_
+\fB_XimFlush\fP:flush:3.5
+_
+\fB_XimRegisterDispatcher\fP:register_dispatcher:3.6
+_
+\fB_XimCallDispatcher\fP:call_dispatcher:3.7
+.TE
+.NL
+.LP
+The Protocol layer calls the above functions using the Alternative
+Entry in the left column. The transport implementation defines
+XimProto member function in the right column. The Alternative Entry is
+provided so as to make easier to implement the Protocol Layer.
+.LP
+.NH 2
+Opening connection
+.XS
+\*(SN Opening connection
+.XE
+.LP
+When \fBXOpenIM\fP is called, the following function is called to connect
+with the IM Server.
+.sp 6p
+.FD 0
+Bool (*connect)(\fIim\fP)
+.br
+      XIM \fIim\fP;
+.FN
+.IP \fIim\fP 1i
+Specifies XIM structure address.
+.sp 6p
+.LP
+This function must establishes the connection to the IM Server. If the
+connection is established successfully, this function returns True.
+The Alternative Entry for this function is:
+.sp 6p
+.FD 0
+Bool _XimConnect(\fIim\fP)
+.br
+      XIM \fIim\fP;
+.FN
+.IP \fIim\fP 1i
+Specifies XIM structure address.
+.LP
+.NH 2
+Closing connection
+.XS
+\*(SN Closing connection
+.XE
+.LP
+When \fBXCloseIM\fP is called, the following function is called to
+disconnect the connection with the IM Server. The Alternative Entry
+for this function is:
+.sp 6p
+.FD 0
+Bool (*shutdown)(\fIim\fP)
+.br
+      XIM \fIim\fP;
+.FN
+.IP \fIim\fP 1i
+Specifies XIM structure address.
+.sp 6p
+.LP
+This function must close connection with the IM Server. If the
+connection is closed successfully, this function returns True. The
+Alternative Entry for this function is:
+.sp 6p
+.FD 0
+Bool _XimShutdown(\fIim\fP)
+.br
+      XIM \fIim\fP;
+.FN
+.IP \fIim\fP
+Specifies XIM structure address.
+.LP
+.NH 2
+Writing data
+.XS
+\*(SN Writing data
+.XE
+.LP
+The following function is called, when Xlib needs to write data to the
+IM Server.
+.sp 6p
+.FD 0
+Bool (*write)(\fIim\fP, \fIlen\fP, \fIdata\fP)
+.br
+      XIM \fIim\fP;
+.br
+      INT16 \fIlen\fP;
+.br
+      XPointer \fIdata\fP;
+.FN
+.IP \fIim\fP 1i
+Specifies XIM structure address.
+.IP \fIlen\fP 1i
+Specifies the length of writing data.
+.IP \fIdata\fP 1i
+Specifies the writing data.
+.sp 6p
+.LP
+This function writes the \fIdata\fP to the IM Server, regardless
+of the contents.  The number of bytes is passed to \fIlen\fP. The
+writing data is passed to \fIdata\fP. If data is sent successfully,
+the function returns True. Refer to "The Input Method Protocol" for
+the contents of the writing data. The Alternative Entry for this
+function is:
+.sp 6p
+.FD 0
+Bool _XimWrite(\fIim\fP, \fIlen\fP, \fIdata\fP)
+.br
+      XIM \fIim\fP;
+.br
+      INT16 \fIlen\fP;
+.br
+      XPointer \fIdata\fP;
+.FN
+.IP \fIim\fP 1i
+Specifies XIM structure address.
+.IP \fIlen\fP 1i
+Specifies the length of writing data.
+.IP \fIdata\fP 1i
+Specifies the writing data.
+.LP
+.NH 2
+Reading data
+.XS
+\*(SN Reading data
+.XE
+.LP
+The following function is called when Xlib waits for response from IM
+server synchronously.
+.sp 6p
+.FD 0
+Bool (*read)(\fIim\fP, \fIread_buf\fP, \fIbuf_len\fP, \fIret_len\fP)
+.br
+      XIM \fIim\fP;
+.br
+      XPointer \fIread_buf\fP;
+.br
+      int \fIbuf_len\fP;
+.br
+      int \fI*ret_len\fP;
+.FN
+.IP \fIim\fP 1i
+Specifies XIM structure address.
+.IP \fIread_buf\fP 1i
+Specifies the buffer to store data.
+.IP \fIbuf_len\fP 1i
+Specifies the size of the \fIbuffer\fP
+.IP \fIret_len\fP
+Specifies the length of stored data.
+.sp 6p
+.LP
+This function stores the read data in \fIread_buf\fP, which size is
+specified as \fIbuf_len\fP. The size of data is set to \fIret_len\fP. 
+This function return True, if the data is read normally or reading
+data is completed.
+.LP
+The Alternative Entry for this function is:
+.sp 6p
+.FD 0
+Bool _XimRead(\fIim\fP, \fIret_len\fP, \fIbuf\fP, \fIbuf_len\fP, \fIpredicate\fP, \fIpredicate_arg\fP)
+.br
+      XIM \fIim\fP;
+.br
+      INT16 \fI*ret_len\fP;
+.br
+      XPointer \fIbuf\fP;
+.br
+      int \fIbuf_len\fP;
+.br
+      Bool \fI(*predicate)()\fP;
+.br
+      XPointer \fIpredicate_arg\fP;
+.FN
+.IP \fIim\fP 1i
+Specifies XIM structure address.
+.IP \fIret_len\fP 1i
+Specifies the size of the \fIdata\fP buffer.
+.IP \fIbuf\fP 1i
+Specifies the buffer to store data.
+.IP \fIbuf_len\fP 1i
+Specifies the length of \fIbuffer\fP.
+.IP \fIpredicate\fP 1i
+Specifies the predicate for the XIM data.
+.IP \fIpredicate_arg\fP 1i
+Specifies the predicate specific data.
+.sp 6p
+.LP
+The predicate procedure indicates whether the \fIdata\fP is for the
+XIM or not. \fIlen\fP
+This function stores the read data in \fIbuf\fP, which size is specified 
+as \fIbuf_len\fP. The size of data is set to \fIret_len\fP.
+If \fIpreedicate()\fP returns True, this function returns True.
+If not, it calls the registered callback function. 
+.LP
+The procedure and its arguments are:
+.LP
+.sp 6p
+.FD 0
+Bool (*predicate)(\fIim\fP, \fIlen\fP, \fIdata\fP, \fIpredicate_arg\fP)
+.br
+      XIM \fIim\fP;
+.br
+      INT16 \fIlen\fP;
+.br
+      XPointer \fIdata\fP;
+.br
+      XPointer \fIpredicate_arg\fP;
+.FN
+.IP \fIim\fP 1i
+Specifies XIM structure address.
+.IP \fIlen\fP 1i
+Specifies the size of the \fIdata\fP buffer.
+.IP \fIdata\fP 1i
+Specifies the buffer to store data.
+.IP \fIpredicate_arg\fP 1i
+Specifies the predicate specific data.
+.LP
+.NH 2
+Flushing buffer
+.XS
+\*(SN Flushing buffer
+.XE
+.LP
+The following function is called when Xlib needs to flush the data.
+.sp 6p
+.FD 0
+void (*flush)(\fIim\fP)
+.br
+      XIM \fIim\fP;
+.FN
+.IP \fIim\fP 1i
+Specifies XIM structure address.
+.sp 6p
+.LP
+This function must flush the data stored in internal buffer on the
+transport layer. If data transfer is completed, the function returns
+True.  The Alternative Entry for this function is:
+.sp 6p
+.FD 0
+void _XimFlush(\fIim\fP)
+.br
+      XIM \fIim\fP;
+.FN
+.IP \fIim\fP 1i
+Specifies XIM structure address.
+.LP
+.NH 2
+Registering asynchronous data handler
+.XS
+\*(SN Registering asynchronous data handler
+.XE
+.LP  
+Xlib needs to handle asynchronous response from IM Server. This is
+because some of the XIM data occur asynchronously to X events.
+.LP
+Those data will be handled in the \fIFilter\fP, and the \fIFilter\fP
+will call asynchronous data handler in the protocol layer. Then it
+calls dispatchers in the transport layer. The dispatchers are
+implemented by the protocol layer. This function must store the
+information and prepare for later call of the dispatchers using
+\fB_XimCallDispatcher\fP.
+.LP
+When multiple dispatchers are registered, they will be called
+sequentially in order of registration, on arrival of asynchronous
+data. The register_dispatcher is declared as following:
+.sp 6p
+.FD 0
+Bool (*register_dispatcher)(\fIim\fP, \fIdispatcher\fP, \fIcall_data\fP)
+.br
+      XIM \fIim\fP;
+.br
+      Bool \fI(*dispatcher)()\fP;
+.br
+      XPointer \fIcall_data\fP;
+.FN
+.IP \fIim\fP 1i
+Specifies XIM structure address.
+.IP \fIdispatcher\fP 1i
+Specifies the dispatcher function to register.
+.IP \fIcall_data\fP 1i
+Specifies a parameter for the \fIdispatcher\fP.
+.LP
+The dispatcher is a function of the following type:
+.sp 6p
+.FD 0
+Bool (*dispatcher)(\fIim\fP, \fIlen\fP, \fIdata\fP, \fIcall_data\fP)
+.br
+      XIM \fIim\fP;
+.br
+      INT16 \fIlen\fP;
+.br
+      XPointer \fIdata\fP;
+.br
+      XPointer \fIcall_data\fP;
+.FN
+.IP \fIim\fP 1i
+Specifies XIM structure address.
+.IP \fIlen\fP 1i
+Specifies the size of the \fIdata\fP buffer.
+.IP \fIdata\fP 1i
+Specifies the buffer to store data.
+.IP \fIcall_data\fP 1i
+Specifies a parameter passed to the register_dispatcher.
+.sp 6p
+.LP
+The dispatcher is provided by the protocol layer. They are called once
+for every asynchronous data, in order of registration. If the data is
+used, it must return True. otherwise, it must return False.
+.LP
+If the dispatcher function returns True, the Transport Layer assume
+that the data has been processed by the upper layer.  The Alternative
+Entry for this function is:
+.sp 6p
+.FD 0
+Bool _XimRegisterDispatcher(\fIim\fP, \fIdispatcher\fP, \fIcall_data\fP)
+.br
+      XIM \fIim\fP;
+.br
+      Bool \fI(*dispatcher)()\fP;
+.br
+      XPointer \fIcall_data\fP;
+.FN
+.IP \fIim\fP 1i
+Specifies XIM structure address.
+.IP \fIdispatcher\fP 1i
+Specifies the dispatcher function to register.
+.IP \fIcall_data\fP 1i
+Specifies a parameter for the \fIdispatcher\fP.
+.LP
+.NH 2
+Calling dispatcher
+.XS
+\*(SN Calling dispatcher
+.XE
+.LP
+The following function is used to call the registered dispatcher
+function, when the asynchronous response from IM Server has arrived.
+.sp 6p
+.FD 0
+Bool (*call_dispatcher)(\fIim\fP, \fIlen\fP, \fIdata\fP)
+.br
+      XIM \fIim\fP;
+.br
+      INT16 \fIlen\fP;
+.br
+      XPointer \fIdata\fP;
+.FN
+.IP \fIim\fP 1i
+Specifies XIM structure address.
+.IP \fIlen\fP 1i
+Specifies the size of \fIdata\fP buffer.
+.IP \fIdata\fP 1i
+Specifies the buffer to store data.
+.LP
+The call_dispatcher must call the dispatcher function, in order of 
+their registration. \fIlen\fP and \fIdata\fP are the data passed to 
+register_dispatcher.
+.LP
+The return values are checked at each invocation, and if it finds
+True, it immediately return with true for its return value.
+.LP
+It is depend on the upper layer whether the read data is XIM
+Protocol packet unit or not.
+The Alternative Entry for this function is:
+.sp 6p
+.FD 0
+Bool _XimCallDispatcher(\fIim\fP, \fIlen\fP, \fIdata\fP)
+.br
+      XIM \fIim\fP;
+.br
+      INT16 \fIlen\fP;
+.br
+      XPointer \fIcall_data\fP;
+.FN
+.LP
+.bp
+.NH 1
+Sample implementations for the Transport Layer
+.XS
+\*(SN Sample implementations for the Transport Layer
+.XE
+.LP
+Sample implementations for the transporter using the X connection is
+described here.
+.LP
+.NH 2
+X Transport
+.XS
+\*(SN X Transport 
+.XE
+.LP
+At the beginning of the X Transport connection for the XIM transport
+mechanism, two different windows must be created either in an Xlib XIM
+or in an IM Server, with which the Xlib and the IM Server exchange the
+XIM transports by using the ClientMessage events and Window Properties.
+In the following, the window created by the Xlib is referred as the
+"client communication window", and on the other hand, the window created
+by the IM Server is referred as the "IMS communication window".
+.LP
+.NH 3
+Connection
+.XS
+\*(SN X Connection
+.XE
+.LP
+In order to establish a connection, a communication window is created.
+A ClientMessage in the following event's format is sent to the owner 
+window of XIM_SERVER selection, which the IM Server has created.
+.LP
+Refer to "The Input Method Protocol" for the XIM_SERVER atom.
+.LP
+.ce
+Table 4-1; The ClientMessage sent to the IMS window.
+.TS H
+tab(:);
+l s|l
+l l|l.
+_
+.sp 6p
+.B
+Structure Member:Contents
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+int:type:ClientMessage  
+u_long:serial:Set by the X Window System  
+Bool:send_event:Set by the X Window System  
+Display:*display:The display to which connects
+Window:window:IMS Window ID
+Atom:message_type:XInternAtom(display, ``_XIM_XCONNECT'', False)
+int:format:32  
+long:data.l[0]:client communication window ID  
+long:data.l[1]:client-major-transport-version (*1)
+long:data.l[2]:client-major-transport-version (*1)
+.sp 6p
+_
+.TE
+.LP
+In order to establish the connection (to notify the IM Server communication
+window), the IM Server sends a ClientMessage in the following event's
+format to the client communication window.
+.LP
+.ce
+Table 4-2; The ClientMessage sent by IM Server.
+.TS H
+tab(:);
+l s | l
+l l | l.
+_
+.sp 6p
+.B
+Structure Member:Contents
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+int:type:ClientMessage  
+u_long:serial:Set by the X Window System  
+Bool:send_event:Set by the X Window System  
+Display:*display:The display to which connects
+Window:window:client communication window ID  
+Atom:message_type:XInternAtom(display, ``_XIM_XCONNECT'', False)
+int:format:32  
+long:data.l[0]:IMS communication window ID  
+long:data.l[1]:server-major-transport-version (*1)
+long:data.l[2]:server-minor-transport-version (*1)
+long:data.l[3]:dividing size between ClientMessage and Property (*2)
+.sp 6p
+_
+.TE
+.LP
+.IP (*1) 
+major/minor-transport-version
+.RS
+The read/write method is decided by the combination of 
+major/minor-transport-version, as follows:
+.LP
+.ce
+Table 4-3; The read/write method and the major/minor-transport-version
+.TS
+center, tab(:);
+| c s | l |
+| c | c | l |.
+_
+.sp 6p
+.B
+Transport-version:read/write 
+.sp 6p
+_
+.sp 6p
+major:minor:
+.sp 6p
+_
+.sp 6p
+.R
+0:0:only-CM & Property-with-CM
+:1:only-CM & multi-CM
+:2:only-CM & multi-CM & Property-with-CM
+.sp 6p
+_
+.sp 6p
+1:0:PropertyNotify
+.sp 6p
+_
+.sp 6p
+2:0:only-CM & PropertyNotify
+:1:only-CM & multi-CM & PropertyNotify
+.sp 6p
+_
+.TE
+.LP
+.RS
+.TS
+center, tab(;);
+l n l.
+only-CM;:;data is sent via a ClientMessage
+multi-CM;:;data is sent via multiple ClientMessages 
+Property-with-CM;:;T{
+data is written in Property, and its Atom is send via ClientMessage
+T}
+PropertyNotify;:;T{
+data is written in Property, and its Atom is send via PropertyNotify
+T}
+.TE
+.RE
+.LP
+The method to decide major/minor-transport-version is as follows:
+.LP
+.IP (1)
+The client sends 0 as major/minor-transport-version to the IM Server.
+The client must support all methods in Table 4-3.
+The client may send another number as major/minor-transport-version to
+use other method than the above in the future.
+.IP (2)
+The IM Server sends its major/minor-transport-version number to
+the client. The client sends data using the method specified by the 
+IM Server.
+.IP (3)
+If major/minor-transport-version number is not available, it is regarded
+as 0.
+.RE
+.LP
+.IP (*2) 
+dividing size between ClientMessage and Property
+.RS
+If data is sent via both of multi-CM and Property, specify the dividing
+size between ClientMessage and Property. The data, which is smaller than
+this size, is sent via multi-CM (or only-CM), and the data, which is 
+lager than this size, is sent via Property. 
+.RE
+.LP
+.NH 3
+read/write  
+.XS
+\*(SN read/write  
+.XE
+.LP  
+The data is transferred via either ClientMessage or Window Property in
+the X Window System.
+.LP
+.NH 4
+Format for the data from the Client to the IM Server
+.XS
+\*(SN Format for the data from the Client to the IM Server
+.XE
+.LP
+.B
+ClientMessage
+.LP
+.RS
+If data is sent via ClientMessage event, the format is as follows:
+.LP
+.ce
+Table 4-4; The ClientMessage event's format (first or middle)
+.TS H
+tab(;);
+l s | l
+l l | l.
+_
+.sp 6p
+.B
+Structure Member;Contents
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+int;type;ClientMessage  
+u_long;serial;Set by the X Window System  
+Bool;send_event;Set by the X Window System  
+Display;*display;The display to which connects  
+Window;window;IMS communication window ID  
+Atom;message_type;XInternAtom(display, ``_XIM_MOREDATA'', False)
+int;format;8  
+char;data.b[20];(read/write DATA : 20 byte)  
+.sp 6p
+_
+.TE
+.LP
+.ce
+Table 4-5; The ClientMessage event's format (only or last)
+.TS H
+tab(;);
+l s | l
+l l | l.
+_
+.sp 6p
+.B
+Structure Member;Contents
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+int;type;ClientMessage  
+u_long;serial;Set by the X Window System  
+Bool;send_event;Set by the X Window System  
+Display;*display;The display to which connects  
+Window;window;IMS communication window ID  
+Atom;message_type;XInternAtom(display, ``_XIM_PROTOCOL'', False)
+int;format;8  
+char;data.b[20];(read/write DATA : MAX 20 byte)  (*1)
+.sp 6p
+_
+.TE
+.IP (*1)
+If the data is smaller than 20 byte, all data other than available data
+must be 0.
+.RE
+.LP
+.B
+Property
+.LP
+.RS
+In the case of large data, data will be sent via the Window Property 
+for the efficiency.  There are the following two methods to notify 
+Property, and transport-version is decided which method is used.
+.LP
+.IP (1)
+The XChangeProperty function is used to store data in the client 
+communication window, and Atom of the stored data is notified to the 
+IM Server via ClientMessage event.
+.IP (2)
+The XChangeProperty function is used to store data in the client 
+communication window, and Atom of the stored data is notified to the 
+IM Server via PropertyNotify event.
+.LP
+The arguments of the XChangeProperty are as follows:
+.LP
+.ce
+Table 4-6; The XChangeProperty event's format
+.TS H
+tab(:);
+l s | l
+l l | l.
+_
+.sp 6p
+.B
+Argument:Contents
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+Display:*display:The display to which connects
+Window:window:IMS communication window ID  
+Atom:property:read/write property Atom (*1) 
+Atom:type:XA_STRING  
+int:format:8  
+int:mode:PropModeAppend  
+u_char:*data:read/write DATA 
+int:nelements:length of DATA
+.sp 6p
+_
+.TE
+.LP
+.IP (*1)
+The read/write property ATOM allocates the following strings by
+\fBXInternAtom\fP.
+.RS
+``_clientXXX''
+.RE
+.LP
+The client changes the property with the mode of PropModeAppend and
+the IM Server will read it with the delete mode i.e. (delete = True).
+.LP
+If Atom is notified via ClientMessage event, the format of the ClientMessage 
+is as follows:
+.LP
+.ce 
+Table 4-7; The ClientMessage event's format to send Atom of property
+.TS H
+tab(:);
+l s | l 
+l l | l.
+_
+.sp 6p
+.B
+Structure Member:Contents
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+int:type:ClientMessage  
+u_long:serial:Set by the X Window System  
+Bool:send_event:Set by the X Window System  
+Display:*display:The display to which connects
+Window:window:IMS communication window ID  
+Atom:message_type:XInternAtom(display, ``_XIM_PROTOCOL'', False)
+int:format:32  
+long:data.l[0]:length of read/write property Atom  
+long:data.l[1]:read/write property Atom
+.sp 6p
+_
+.TE
+.RE
+.LP
+.NH 4
+Format for the data from the IM Server to the Client
+.XS
+\*(SN Format for the data from the Client to the Client
+.XE
+.LP
+.B
+ClientMessage
+.LP
+.RS
+The format of the ClientMessage is as follows:
+.LP
+.ce
+Table 4-8; The ClientMessage event's format (first or middle)
+.TS H
+tab(;);
+l s | l
+l l | l.
+_
+.sp 6p
+.B
+Structure Member;Contents
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+int;type;ClientMessage  
+u_long;serial;Set by the X Window System  
+Bool;send_event ;Set by the X Window System  
+Display;*display;The display to which connects
+Window;window;client communication window ID  
+Atom;message_type;XInternAtom(display, ``_XIM_MOREDATA'', False)
+int;format;8  
+char;data.b[20];(read/write DATA : 20 byte)  
+.sp 6p
+_
+.TE
+.LP
+.ce
+Table 4-9; The ClientMessage event's format (only or last)
+.TS H
+tab(;);
+l s | l
+l l | l.
+_
+.sp 6p
+.B
+Structure Member;Contents
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+int;type;ClientMessage  
+u_long;serial;Set by the X Window System  
+Bool;send_event ;Set by the X Window System  
+Display;*display;The display to which connects
+Window;window;client communication window ID  
+Atom;message_type;XInternAtom(display, ``_XIM_PROTOCOL'', False)
+int;format;8  
+char;data.b[20];(read/write DATA : MAX 20 byte) (*1) 
+.sp 6p
+_
+.TE
+.LP
+.IP (*1)
+If the data size is smaller than 20 bytes, all data other than available 
+data must be 0.
+.RE
+.LP
+.B
+Property
+.LP
+.RS
+In the case of large data, data will be sent via the Window Property
+for the efficiency. There are the following two methods to notify 
+Property, and transport-version is decided which method is used.
+.LP
+.IP (1)
+The XChangeProperty function is used to store data in the IMS 
+communication window, and Atom of the property is sent via the 
+ClientMessage event.
+.IP (2)
+The XChangeProperty function is used to store data in the IMS 
+communication window, and Atom of the property is sent via 
+PropertyNotify event.
+.LP
+The arguments of the XChangeProperty are as follows:
+.LP
+.ce
+Table 4-10; The XChangeProperty event's format
+.TS H
+tab(:);
+l s | l
+l l | l.
+_
+.sp 6p
+.B
+Argument:Contents
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+Display:*display:The display which to connects
+Window:window:client communication window ID  
+Atom:property:read/write property Atom (*1)
+Atom:type:XA_STRING  
+int:format:8  
+int:mode:PropModeAppend  
+u_char:*data:read/write DATA  
+int:nelements:length of DATA  
+.sp 6p
+_
+.TE
+.LP  
+.IP (*1)
+The read/write property ATOM allocates some strings, which are not
+allocated by the client, by \fBXInternAtom\fP.
+.LP
+The IM Server changes the property with the mode of PropModeAppend and
+the client reads it with the delete mode, i.e. (delete = True).
+.LP
+If Atom is notified via ClientMessage event, the format of the ClientMessage 
+is as follows:
+.LP
+.ce
+Table 4-11; The ClientMessage event's format to send Atom of property 
+.TS H
+tab(:);
+l s | l
+l l | l.
+_
+.sp 6p
+.B
+Structure Member:Contents
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+int:type:ClientMessage  
+u_long:serial:Set by the X Window System  
+Bool:send_event:Set by the X Window System  
+Display:*display:The display to which connects  
+Window:window:client communication window ID  
+Atom:message_type:XInternAtom(display, ``_XIM_PROTOCOL'', False)
+int:format:32  
+long:data.l[0]:length of read/write property ATOM  
+long:data.l[1]:read/write property ATOM  
+.sp 6p
+_
+.TE
+.RE
+.LP
+.NH 3
+Closing Connection
+.XS
+\*(SN Closing Connection
+.XE
+.LP
+If the client disconnect with the IM Server, shutdown function should 
+free the communication window properties and etc..
+.LP
+.NH 1
+References
+.XS
+\*(SN References
+.XE
+.LP
+[1] Masahiko Narita and Hideki Hiura, \fI``The Input Method Protocol''\fP
+.LP
+
diff --git a/specs/libX11/AppA b/specs/libX11/AppA
new file mode 100644
index 00000000..26a1ba32
--- /dev/null
+++ b/specs/libX11/AppA
@@ -0,0 +1,604 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+\&
+.sp 1
+.ce 3
+\s+1\fBAppendix A\fP\s-1
+
+\s+1\fBXlib Functions and Protocol Requests\fP\s-1
+.sp 2
+.na
+.LP
+.XS
+Appendix A: Xlib Functions and Protocol Requests
+.XE
+This appendix provides two tables that relate to Xlib functions 
+and the X protocol.
+The following table lists each Xlib function (in alphabetical order)
+and the corresponding protocol request that it generates.
+.LP
+.TS H
+lw(2.5i) lw(2.5i).
+_
+.sp 6p
+.B
+Xlib Function	Protocol Request
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+XActivateScreenSaver	ForceScreenSaver
+XAddHost	ChangeHosts
+XAddHosts	ChangeHosts
+XAddToSaveSet	ChangeSaveSet
+XAllocColor	AllocColor
+XAllocColorCells	AllocColorCells
+XAllocColorPlanes	AllocColorPlanes
+XAllocNamedColor	AllocNamedColor
+XAllowEvents	AllowEvents
+XAutoRepeatOff	ChangeKeyboardControl
+XAutoRepeatOn	ChangeKeyboardControl
+XBell	Bell
+XChangeActivePointerGrab	ChangeActivePointerGrab
+XChangeGC	ChangeGC
+XChangeKeyboardControl	ChangeKeyboardControl
+XChangeKeyboardMapping	ChangeKeyboardMapping
+XChangePointerControl	ChangePointerControl
+XChangeProperty	ChangeProperty
+XChangeSaveSet	ChangeSaveSet
+XChangeWindowAttributes	ChangeWindowAttributes
+XCirculateSubwindows	CirculateWindow
+XCirculateSubwindowsDown	CirculateWindow
+XCirculateSubwindowsUp	CirculateWindow
+XClearArea	ClearArea
+XClearWindow	ClearArea
+XConfigureWindow	ConfigureWindow
+XConvertSelection	ConvertSelection
+XCopyArea	CopyArea
+XCopyColormapAndFree	CopyColormapAndFree
+XCopyGC	CopyGC
+XCopyPlane	CopyPlane
+XCreateBitmapFromData	CreateGC
+	CreatePixmap
+	FreeGC
+	PutImage
+XCreateColormap	CreateColormap
+XCreateFontCursor	CreateGlyphCursor
+XCreateGC	CreateGC
+XCreateGlyphCursor	CreateGlyphCursor
+XCreatePixmap	CreatePixmap
+XCreatePixmapCursor	CreateCursor
+XCreatePixmapFromData	CreateGC
+	CreatePixmap
+	FreeGC
+	PutImage
+XCreateSimpleWindow	CreateWindow
+XCreateWindow	CreateWindow
+XDefineCursor	ChangeWindowAttributes
+XDeleteProperty	DeleteProperty
+XDestroySubwindows	DestroySubwindows
+XDestroyWindow	DestroyWindow
+XDisableAccessControl	SetAccessControl
+XDrawArc	PolyArc
+XDrawArcs	PolyArc
+XDrawImageString	ImageText8
+XDrawImageString16	ImageText16
+XDrawLine	PolySegment
+XDrawLines	PolyLine
+XDrawPoint	PolyPoint 
+XDrawPoints	PolyPoint
+XDrawRectangle	PolyRectangle
+XDrawRectangles	PolyRectangle
+XDrawSegments	PolySegment
+XDrawString	PolyText8
+XDrawString16	PolyText16
+XDrawText	PolyText8
+XDrawText16	PolyText16
+XEnableAccessControl	SetAccessControl
+XFetchBytes	GetProperty
+XFetchName	GetProperty
+XFillArc	PolyFillArc
+XFillArcs	PolyFillArc
+XFillPolygon	FillPoly
+XFillRectangle	PolyFillRectangle
+XFillRectangles	PolyFillRectangle
+XForceScreenSaver	ForceScreenSaver
+XFreeColormap	FreeColormap
+XFreeColors	FreeColors
+XFreeCursor	FreeCursor
+XFreeFont	CloseFont
+XFreeGC	FreeGC
+XFreePixmap	FreePixmap
+XGetAtomName	GetAtomName
+XGetClassHint	GetProperty
+XGetFontPath	GetFontPath
+XGetGeometry	GetGeometry
+XGetIconName	GetProperty
+XGetIconSizes	GetProperty
+XGetImage	GetImage
+XGetInputFocus	GetInputFocus
+XGetKeyboardControl	GetKeyboardControl
+XGetKeyboardMapping	GetKeyboardMapping
+XGetModifierMapping	GetModifierMapping
+XGetMotionEvents	GetMotionEvents
+XGetNormalHints	GetProperty
+XGetPointerControl	GetPointerControl
+XGetPointerMapping	GetPointerMapping
+XGetRGBColormaps	GetProperty
+XGetScreenSaver	GetScreenSaver
+XGetSelectionOwner	GetSelectionOwner
+XGetSizeHints	GetProperty
+XGetTextProperty	GetProperty
+XGetTransientForHint	GetProperty
+XGetWMClientMachine	GetProperty
+XGetWMColormapWindows	GetProperty
+	InternAtom
+XGetWMHints	GetProperty
+XGetWMIconName	GetProperty
+XGetWMName	GetProperty
+XGetWMNormalHints	GetProperty
+XGetWMProtocols	GetProperty
+	InternAtom
+XGetWMSizeHints	GetProperty
+XGetWindowAttributes	GetWindowAttributes
+	GetGeometry
+XGetWindowProperty	GetProperty
+XGetZoomHints	GetProperty
+XGrabButton	GrabButton
+XGrabKey	GrabKey
+XGrabKeyboard	GrabKeyboard
+XGrabPointer	GrabPointer
+XGrabServer	GrabServer
+XIconifyWindow	InternAtom
+	SendEvent
+XInitExtension	QueryExtension
+XInstallColormap	InstallColormap
+XInternAtom	InternAtom
+XKillClient	KillClient
+XListExtensions	ListExtensions
+XListFonts	ListFonts
+XListFontsWithInfo	ListFontsWithInfo
+XListHosts	ListHosts
+XListInstalledColormaps	ListInstalledColormaps
+XListProperties	ListProperties
+XLoadFont	OpenFont
+XLoadQueryFont	OpenFont
+	QueryFont
+XLookupColor	LookupColor
+XLowerWindow	ConfigureWindow
+XMapRaised	ConfigureWindow
+	MapWindow
+XMapSubwindows	MapSubwindows
+XMapWindow	MapWindow
+XMoveResizeWindow	ConfigureWindow
+XMoveWindow	ConfigureWindow
+XNoOp	NoOperation
+XOpenDisplay	CreateGC
+XParseColor	LookupColor
+XPutImage	PutImage
+XQueryBestCursor	QueryBestSize
+XQueryBestSize	QueryBestSize
+XQueryBestStipple	QueryBestSize
+XQueryBestTile	QueryBestSize
+XQueryColor	QueryColors 
+XQueryColors	QueryColors
+XQueryExtension	QueryExtension
+XQueryFont	QueryFont
+XQueryKeymap	QueryKeymap
+XQueryPointer	QueryPointer
+XQueryTextExtents	QueryTextExtents
+XQueryTextExtents16	QueryTextExtents
+XQueryTree	QueryTree
+XRaiseWindow	ConfigureWindow
+XReadBitmapFile	CreateGC
+	CreatePixmap
+	FreeGC
+	PutImage
+XRecolorCursor	RecolorCursor
+XReconfigureWMWindow	ConfigureWindow
+	SendEvent
+XRemoveFromSaveSet	ChangeSaveSet
+XRemoveHost	ChangeHosts
+XRemoveHosts	ChangeHosts
+XReparentWindow	ReparentWindow
+XResetScreenSaver	ForceScreenSaver
+XResizeWindow	ConfigureWindow 
+XRestackWindows    	ConfigureWindow
+XRotateBuffers	RotateProperties
+XRotateWindowProperties	RotateProperties
+XSelectInput	ChangeWindowAttributes
+XSendEvent	SendEvent
+XSetAccessControl	SetAccessControl
+XSetArcMode	ChangeGC
+XSetBackground	ChangeGC 
+XSetClassHint	ChangeProperty
+XSetClipMask	ChangeGC
+XSetClipOrigin	ChangeGC
+XSetClipRectangles	SetClipRectangles
+XSetCloseDownMode	SetCloseDownMode
+XSetCommand	ChangeProperty
+XSetDashes	SetDashes
+XSetFillRule	ChangeGC
+XSetFillStyle	ChangeGC
+XSetFont	ChangeGC 
+XSetFontPath	SetFontPath
+XSetForeground	ChangeGC 
+XSetFunction	ChangeGC 
+XSetGraphicsExposures	ChangeGC
+XSetIconName	ChangeProperty
+XSetIconSizes	ChangeProperty
+XSetInputFocus	SetInputFocus
+XSetLineAttributes	ChangeGC
+XSetModifierMapping	SetModifierMapping
+XSetNormalHints	ChangeProperty
+XSetPlaneMask	ChangeGC 
+XSetPointerMapping	SetPointerMapping
+XSetRGBColormaps	ChangeProperty
+XSetScreenSaver	SetScreenSaver
+XSetSelectionOwner	SetSelectionOwner
+XSetSizeHints	ChangeProperty
+XSetStandardProperties	ChangeProperty
+XSetState	ChangeGC
+XSetStipple	ChangeGC
+XSetSubwindowMode	ChangeGC
+XSetTextProperty	ChangeProperty
+XSetTile	ChangeGC
+XSetTransientForHint	ChangeProperty
+XSetTSOrigin	ChangeGC
+XSetWMClientMachine	ChangeProperty
+XSetWMColormapWindows	ChangeProperty
+	InternAtom
+XSetWMHints	ChangeProperty
+XSetWMIconName	ChangeProperty
+XSetWMName	ChangeProperty
+XSetWMNormalHints	ChangeProperty
+XSetWMProperties	ChangeProperty
+XSetWMProtocols	ChangeProperty
+	InternAtom
+XSetWMSizeHints	ChangeProperty
+XSetWindowBackground	ChangeWindowAttributes
+XSetWindowBackgroundPixmap	ChangeWindowAttributes
+XSetWindowBorder	ChangeWindowAttributes
+XSetWindowBorderPixmap	ChangeWindowAttributes
+XSetWindowBorderWidth	ConfigureWindow
+XSetWindowColormap	ChangeWindowAttributes
+XSetZoomHints	ChangeProperty
+XStoreBuffer	ChangeProperty
+XStoreBytes	ChangeProperty
+XStoreColor	StoreColors 
+XStoreColors	StoreColors
+XStoreName	ChangeProperty
+XStoreNamedColor	StoreNamedColor
+XSync	GetInputFocus
+XSynchronize	GetInputFocus
+XTranslateCoordinates	TranslateCoordinates
+XUndefineCursor	ChangeWindowAttributes
+XUngrabButton	UngrabButton
+XUngrabKey	UngrabKey
+XUngrabKeyboard	UngrabKeyboard
+XUngrabPointer	UngrabPointer
+XUngrabServer	UngrabServer
+XUninstallColormap	UninstallColormap
+XUnloadFont	CloseFont
+XUnmapSubwindows	UnmapSubwindows
+XUnmapWindow	UnmapWindow
+XWarpPointer	WarpPointer
+XWithdrawWindow	SendEvent
+	UnmapWindow
+.TE
+.bp
+.LP
+The following table lists each X protocol request (in alphabetical
+order) and the Xlib functions that reference it.
+.TS H
+lw(2.5i) lw(2.5i).
+_
+.sp 6p
+.B
+Protocol Request	Xlib Function
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+AllocColor	XAllocColor
+AllocColorCells	XAllocColorCells
+AllocColorPlanes	XAllocColorPlanes
+AllocNamedColor	XAllocNamedColor
+AllowEvents	XAllowEvents
+Bell	XBell
+ChangeActivePointerGrab	XChangeActivePointerGrab
+ChangeGC	XChangeGC
+	XSetArcMode
+	XSetBackground
+	XSetClipMask
+	XSetClipOrigin
+	XSetFillRule
+	XSetFillStyle
+	XSetFont
+	XSetForeground
+	XSetFunction
+	XSetGraphicsExposures
+	XSetLineAttributes
+	XSetPlaneMask
+	XSetState
+	XSetStipple
+	XSetSubwindowMode
+	XSetTile
+	XSetTSOrigin
+ChangeHosts	XAddHost
+	XAddHosts
+	XRemoveHost
+	XRemoveHosts
+ChangeKeyboardControl	XAutoRepeatOff
+	XAutoRepeatOn
+	XChangeKeyboardControl
+ChangeKeyboardMapping	XChangeKeyboardMapping
+ChangePointerControl	XChangePointerControl
+ChangeProperty	XChangeProperty
+	XSetClassHint
+	XSetCommand
+	XSetIconName
+	XSetIconSizes
+	XSetNormalHints
+	XSetRGBColormaps
+	XSetSizeHints
+	XSetStandardProperties
+	XSetTextProperty
+	XSetTransientForHint
+	XSetWMClientMachine
+	XSetWMColormapWindows
+	XSetWMHints
+	XSetWMIconName
+	XSetWMName
+	XSetWMNormalHints
+	XSetWMProperties
+	XSetWMProtocols
+	XSetWMSizeHints
+	XSetZoomHints
+	XStoreBuffer
+	XStoreBytes
+	XStoreName
+ChangeSaveSet	XAddToSaveSet
+	XChangeSaveSet
+	XRemoveFromSaveSet
+ChangeWindowAttributes	XChangeWindowAttributes
+	XDefineCursor
+	XSelectInput
+	XSetWindowBackground
+	XSetWindowBackgroundPixmap
+	XSetWindowBorder
+	XSetWindowBorderPixmap
+	XSetWindowColormap
+	XUndefineCursor
+CirculateWindow	XCirculateSubwindowsDown
+	XCirculateSubwindowsUp
+	XCirculateSubwindows
+ClearArea	XClearArea
+	XClearWindow
+CloseFont	XFreeFont
+	XUnloadFont
+ConfigureWindow	XConfigureWindow
+	XLowerWindow
+	XMapRaised
+	XMoveResizeWindow
+	XMoveWindow
+	XRaiseWindow
+	XReconfigureWMWindow
+	XResizeWindow
+	XRestackWindows
+	XSetWindowBorderWidth
+ConvertSelection	XConvertSelection
+CopyArea	XCopyArea
+CopyColormapAndFree	XCopyColormapAndFree
+CopyGC	XCopyGC
+CopyPlane	XCopyPlane
+CreateColormap	XCreateColormap
+CreateCursor	XCreatePixmapCursor
+CreateGC	XCreateGC
+	XCreateBitmapFromData
+	XCreatePixmapFromData
+	XOpenDisplay
+	XReadBitmapFile
+CreateGlyphCursor	XCreateFontCursor
+	XCreateGlyphCursor
+CreatePixmap	XCreatePixmap
+	XCreateBitmapFromData
+	XCreatePixmapFromData
+	XReadBitmapFile
+CreateWindow	XCreateSimpleWindow
+	XCreateWindow
+DeleteProperty	XDeleteProperty
+DestroySubwindows	XDestroySubwindows
+DestroyWindow	XDestroyWindow
+FillPoly	XFillPolygon
+ForceScreenSaver	XActivateScreenSaver
+	XForceScreenSaver
+	XResetScreenSaver
+FreeColormap	XFreeColormap
+FreeColors	XFreeColors
+FreeCursor	XFreeCursor
+FreeGC	XFreeGC
+	XCreateBitmapFromData
+	XCreatePixmapFromData
+	XReadBitmapFile
+FreePixmap	XFreePixmap
+GetAtomName	XGetAtomName
+GetFontPath	XGetFontPath
+GetGeometry	XGetGeometry
+	XGetWindowAttributes
+GetImage	XGetImage
+GetInputFocus	XGetInputFocus
+	XSync
+	XSynchronize
+GetKeyboardControl	XGetKeyboardControl
+GetKeyboardMapping	XGetKeyboardMapping
+GetModifierMapping	XGetModifierMapping
+GetMotionEvents	XGetMotionEvents
+GetPointerControl	XGetPointerControl
+GetPointerMapping	XGetPointerMapping
+GetProperty	XFetchBytes
+	XFetchName
+	XGetClassHint
+	XGetIconName
+	XGetIconSizes
+	XGetNormalHints
+	XGetRGBColormaps
+	XGetSizeHints
+	XGetTextProperty
+	XGetTransientForHint
+	XGetWMClientMachine
+	XGetWMColormapWindows
+	XGetWMHints
+	XGetWMIconName
+	XGetWMName
+	XGetWMNormalHints
+	XGetWMProtocols
+	XGetWMSizeHints
+	XGetWindowProperty
+	XGetZoomHints
+GetSelectionOwner	XGetSelectionOwner
+GetWindowAttributes	XGetWindowAttributes
+GrabButton	XGrabButton
+GrabKey	XGrabKey
+GrabKeyboard	XGrabKeyboard
+GrabPointer	XGrabPointer
+GrabServer	XGrabServer
+ImageText8	XDrawImageString
+ImageText16	XDrawImageString16
+InstallColormap	XInstallColormap
+InternAtom	XGetWMColormapWindows
+	XGetWMProtocols
+	XIconifyWindow
+	XInternAtom
+	XSetWMColormapWindows
+	XSetWMProtocols
+KillClient	XKillClient
+ListExtensions	XListExtensions
+ListFonts	XListFonts
+ListFontsWithInfo	XListFontsWithInfo
+ListHosts	XListHosts
+ListInstalledColormaps	XListInstalledColormaps
+ListProperties	XListProperties
+LookupColor	XLookupColor
+	XParseColor
+MapSubwindows	XMapSubwindows
+MapWindow	XMapRaised
+	XMapWindow
+NoOperation	XNoOp
+OpenFont	XLoadFont
+	XLoadQueryFont
+PolyArc	XDrawArc
+	XDrawArcs
+PolyFillArc	XFillArc
+	XFillArcs
+PolyFillRectangle	XFillRectangle
+	XFillRectangles
+PolyLine	XDrawLines
+PolyPoint	XDrawPoint
+	XDrawPoints
+PolyRectangle	XDrawRectangle
+	XDrawRectangles
+PolySegment	XDrawLine
+	XDrawSegments
+PolyText8	XDrawString
+	XDrawText
+PolyText16	XDrawString16
+	XDrawText16
+PutImage	XPutImage
+	XCreateBitmapFromData
+	XCreatePixmapFromData
+	XReadBitmapFile
+QueryBestSize	XQueryBestCursor
+	XQueryBestSize
+	XQueryBestStipple
+	XQueryBestTile
+QueryColors	XQueryColor
+	XQueryColors
+QueryExtension	XInitExtension
+	XQueryExtension
+QueryFont	XLoadQueryFont
+	XQueryFont
+QueryKeymap	XQueryKeymap
+QueryPointer	XQueryPointer
+QueryTextExtents	XQueryTextExtents
+	XQueryTextExtents16
+QueryTree	XQueryTree
+RecolorCursor	XRecolorCursor
+ReparentWindow	XReparentWindow
+RotateProperties	XRotateBuffers
+	XRotateWindowProperties
+SendEvent	XIconifyWindow
+	XReconfigureWMWindow
+	XSendEvent
+	XWithdrawWindow
+SetAccessControl	XDisableAccessControl
+	XEnableAccessControl
+	XSetAccessControl
+SetClipRectangles	XSetClipRectangles
+SetCloseDownMode	XSetCloseDownMode
+SetDashes	XSetDashes
+SetFontPath	XSetFontPath
+SetInputFocus	XSetInputFocus
+SetModifierMapping	XSetModifierMapping
+SetPointerMapping	XSetPointerMapping
+SetScreenSaver	XGetScreenSaver
+	XSetScreenSaver
+SetSelectionOwner	XSetSelectionOwner
+StoreColors	XStoreColor
+	XStoreColors
+StoreNamedColor	XStoreNamedColor
+TranslateCoordinates	XTranslateCoordinates
+UngrabButton	XUngrabButton
+UngrabKey	XUngrabKey
+UngrabKeyboard	XUngrabKeyboard
+UngrabPointer	XUngrabPointer
+UngrabServer	XUngrabServer
+UninstallColormap	XUninstallColormap
+UnmapSubwindows	XUnmapSubWindows
+UnmapWindow	XUnmapWindow
+	XWithdrawWindow
+WarpPointer	XWarpPointer
+.TE
+.bp
diff --git a/specs/libX11/AppB b/specs/libX11/AppB
new file mode 100644
index 00000000..2e57ede8
--- /dev/null
+++ b/specs/libX11/AppB
@@ -0,0 +1,101 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+\&
+.sp 1
+.ce 3
+\s+1\fBAppendix B\fP\s-1
+
+\s+1\fBX Font Cursors\fP\s-1
+.sp 2
+.na
+.LP
+.XS
+Appendix B:  X Font Cursors
+.XE
+The following are the available cursors that can be used with
+.PN XCreateFontCursor .
+.LP
+.Ds 0
+.TA 3i
+.ta 3i
+#define XC_X_cursor 0	#define XC_ll_angle 76
+#define XC_arrow 2	#define XC_lr_angle 78
+#define XC_based_arrow_down 4	#define XC_man 80
+#define XC_based_arrow_up 6	#define XC_middlebutton 82
+#define XC_boat 8	#define XC_mouse 84
+#define XC_bogosity 10	#define XC_pencil 86
+#define XC_bottom_left_corner 12	#define XC_pirate 88
+#define XC_bottom_right_corner 14	#define XC_plus 90
+#define XC_bottom_side 16	#define XC_question_arrow 92
+#define XC_bottom_tee 18 	#define XC_right_ptr 94
+#define XC_box_spiral 20	#define XC_right_side 96
+#define XC_center_ptr 22	#define XC_right_tee 98
+#define XC_circle 24	#define XC_rightbutton 100
+#define XC_clock 26	#define XC_rtl_logo 102
+#define XC_coffee_mug 28	#define XC_sailboat 104
+#define XC_cross 30	#define XC_sb_down_arrow 106
+#define XC_cross_reverse 32	#define XC_sb_h_double_arrow 108
+#define XC_crosshair 34	#define XC_sb_left_arrow 110
+#define XC_diamond_cross 36	#define XC_sb_right_arrow 112
+#define XC_dot 38	#define XC_sb_up_arrow 114
+#define XC_dot_box_mask 40	#define XC_sb_v_double_arrow 116
+#define XC_double_arrow 42	#define XC_shuttle 118
+#define XC_draft_large 44	#define XC_sizing 120
+#define XC_draft_small 46	#define XC_spider 122
+#define XC_draped_box 48	#define XC_spraycan 124
+#define XC_exchange 50	#define XC_star 126
+#define XC_fleur 52	#define XC_target 128
+#define XC_gobbler 54	#define XC_tcross 130
+#define XC_gumby 56	#define XC_top_left_arrow 132
+#define XC_hand1 58	#define XC_top_left_corner 134
+#define XC_hand2 60	#define XC_top_right_corner 136
+#define XC_heart 62	#define XC_top_side 138
+#define XC_icon 64	#define XC_top_tee 140
+#define XC_iron_cross 66	#define XC_trek 142
+#define XC_left_ptr 68	#define XC_ul_angle 144
+#define XC_left_side 70	#define XC_umbrella 146
+#define XC_left_tee 72	#define XC_ur_angle 148
+#define XC_leftbutton 74	#define XC_watch 150
+	#define XC_xterm 152
+.De
+.bp
diff --git a/specs/libX11/AppC b/specs/libX11/AppC
new file mode 100644
index 00000000..43261ba8
--- /dev/null
+++ b/specs/libX11/AppC
@@ -0,0 +1,2230 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+\&
+.sp 1
+.ce 3
+\s+1\fBAppendix C\fP\s-1
+
+\s+1\fBExtensions\fP\s-1
+.sp 2
+.na
+.LP
+.XS
+Appendix C: Extensions
+.XE
+Because X can evolve by extensions to the core protocol, 
+it is important that extensions not be perceived as second-class citizens.
+At some point, 
+your favorite extensions may be adopted as additional parts of the 
+X Standard.
+.LP
+Therefore, there should be little to distinguish the use of an extension from 
+that of the core protocol.
+To avoid having to initialize extensions explicitly in application programs, 
+it is also important that extensions perform lazy evaluations,
+automatically initializing themselves when called for the first time.  
+.LP
+This appendix describes techniques for writing extensions to Xlib that will
+run at essentially the same performance as the core protocol requests.
+.NT
+It is expected that a given extension to X consists of multiple
+requests.
+Defining 10 new features as 10 separate extensions is a bad practice.
+Rather, they should be packaged into a single extension
+and should use minor opcodes to distinguish the requests.
+.NE
+.LP
+The symbols and macros used for writing stubs to Xlib are listed in
+.hN X11/Xlibint.h .
+.SH
+Basic Protocol Support Routines
+.LP
+The basic protocol requests for extensions are 
+.PN XQueryExtension
+and
+.PN XListExtensions .
+.IN "XQueryExtension" "" "@DEF@"
+.sM
+.FD 0
+Bool XQueryExtension(\^\fIdisplay\fP, \fIname\fP, \fImajor_opcode_return\fP, \
+\fIfirst_event_return\fP, \fIfirst_error_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      char *\fIname;\fP\^
+.br
+      int *\fImajor_opcode_return\fP\^;
+.br
+      int *\fIfirst_event_return\fP\^;
+.br
+      int *\fIfirst_error_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIname\fP 1i
+Specifies the extension name.
+.IP \fImajor_opcode_return\fP 1i
+Returns the major opcode.
+.IP \fIfirst_event_return\fP 1i
+Returns the first event code, if any.
+.IP \fIfirst_error_return\fP 1i
+Returns the first error code, if any.
+.LP
+.eM
+The
+.PN XQueryExtension
+function determines if the named extension is present.  
+If the extension is not present,
+.PN XQueryExtension
+returns
+.PN False ;
+otherwise, it returns
+.PN True .
+If the extension is present,
+.PN XQueryExtension
+returns the major opcode for the extension to major_opcode_return;
+otherwise,
+it returns zero.
+Any minor opcode and the request formats are specific to the
+extension.  
+If the extension involves additional event types, 
+.PN XQueryExtension
+returns the base event type code to first_event_return;
+otherwise, 
+it returns zero.  
+The format of the events is specific to the extension.  
+If the extension involves additional error codes, 
+.PN XQueryExtension
+returns the base error code to first_error_return;
+otherwise, 
+it returns zero.  
+The format of additional data in the errors is specific to the extension.
+.LP
+If the extension name is not in the Host Portable Character Encoding
+the result is implementation-dependent.
+Uppercase and lowercase matter;
+the strings ``thing'', ``Thing'', and ``thinG'' 
+are all considered different names.
+.IN "XListExtensions" "" "@DEF@"
+.sM
+.FD 0
+char **XListExtensions(\^\fIdisplay\fP, \fInextensions_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int *\fInextensions_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fInextensions_return\fP 1i
+Returns the number of extensions listed.
+.LP
+.eM
+The
+.PN XListExtensions   
+function returns a list of all extensions supported by the server.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned strings are in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+.IN "XFreeExtensionList" "" "@DEF@"
+.sM
+.FD 0
+XFreeExtensionList(\^\fIlist\fP\^)
+.br
+      char **\fIlist\fP\^;
+.FN
+.IP \fIlist\fP 1i
+Specifies the list of extension names.
+.LP
+.eM
+The
+.PN XFreeExtensionList
+function frees the memory allocated by 
+.PN XListExtensions .
+.SH
+Hooking into Xlib 
+.LP
+These functions allow you to hook into the library.  
+They are not normally used by application programmers but are used 
+by people who need to extend the core X protocol and
+the X library interface.
+The functions, which generate protocol requests for X, are typically
+called stubs.
+.LP
+In extensions, stubs first should check to see if they have initialized 
+themselves on a connection.
+If they have not, they then should call 
+.PN XInitExtension 
+to attempt to initialize themselves on the connection.
+.LP
+If the extension needs to be informed of GC/font allocation or
+deallocation or if the extension defines new event types, 
+the functions described here allow the extension to be 
+called when these events occur.
+.LP
+The
+.PN XExtCodes
+structure returns the information from 
+.PN XInitExtension 
+and is defined in
+.hN X11/Xlib.h : 
+.LP
+.IN "XExtCodes" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _XExtCodes {	/* public to extension, cannot be changed */
+	int extension;	/* extension number */
+	int major_opcode;	/* major op-code assigned by server */
+	int first_event;	/* first event number for the extension */
+	int first_error;	/* first error number for the extension */
+} XExtCodes;
+.De
+.LP
+.eM
+.IN "XInitExtension" "" "@DEF@"
+.sM
+.FD 0
+XExtCodes *XInitExtension(\^\fIdisplay\fP, \fIname\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      char *\fIname\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIname\fP 1i
+Specifies the extension name.
+.LP
+.eM
+The
+.PN XInitExtension
+function determines if the named extension exists. 
+Then, it allocates storage for maintaining the 
+information about the extension on the connection, 
+chains this onto the extension list for the connection,
+and returns the information the stub implementor will need to access
+the extension.
+If the extension does not exist,
+.PN XInitExtension
+returns NULL.
+.LP
+If the extension name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Uppercase and lowercase matter;
+the strings ``thing'', ``Thing'', and ``thinG'' 
+are all considered different names.
+.LP
+The extension number in the 
+.PN XExtCodes 
+structure is
+needed in the other calls that follow.  
+This extension number is unique only to a single connection.
+.LP
+.IN "XAddExtension" "" "@DEF@"
+.sM
+.FD 0
+XExtCodes *XAddExtension\^(\^\fIdisplay\fP\^)
+.br
+        Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+For local Xlib extensions, the
+.PN XAddExtension
+function allocates the
+.PN XExtCodes
+structure, bumps the extension number count,
+and chains the extension onto the extension list.
+(This permits extensions to Xlib without requiring server extensions.)
+.SH
+Hooks into the Library
+.LP
+These functions allow you to define procedures that are to be
+called when various circumstances occur.
+The procedures include the creation of a new GC for a connection,
+the copying of a GC, the freeing of a GC, the creating and freeing of fonts,
+the conversion of events defined by extensions to and from wire
+format, and the handling of errors.
+.LP
+All of these functions return the previous procedure defined for this
+extension.
+.IN "XESetCloseDisplay" "" "@DEF@"
+.sM
+.FD 0
+int (*XESetCloseDisplay(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIextension\fP\^;
+.br
+      int (\^*\fIproc\fP\^)(\^);
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIextension\fP 1i
+Specifies the extension number.
+.IP \fIproc\fP 1i
+Specifies the procedure to call when the display is closed.
+.LP
+.eM
+The
+.PN XESetCloseDisplay
+function defines a procedure to be called whenever
+.PN XCloseDisplay 
+is called.  
+It returns any previously defined procedure, usually NULL.
+.LP
+When 
+.PN XCloseDisplay 
+is called, 
+your procedure is called 
+with these arguments:
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+.R
+(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIcodes\fP\^)
+	Display *\fIdisplay\fP\^;
+	XExtCodes *\fIcodes\fP\^;
+.De
+.LP
+.eM
+.IN "XESetCreateGC" "" "@DEF@"
+.sM
+.FD 0
+int (*XESetCreateGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIextension\fP\^;
+.br
+      int (\^*\fIproc\fP\^)(\^);
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIextension\fP 1i
+Specifies the extension number.
+.IP \fIproc\fP 1i
+Specifies the procedure to call when a GC is closed.
+.LP
+.eM
+The
+.PN XESetCreateGC
+function defines a procedure to be called whenever
+a new GC is created.  
+It returns any previously defined procedure, usually NULL.
+.LP
+When a GC is created, 
+your procedure is called with these arguments:
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+.R
+(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIgc\fP, \fIcodes\fP\^)
+	Display *\fIdisplay\fP\^;
+	GC \fIgc\fP\^;
+	XExtCodes *\fIcodes\fP\^;
+.De
+.LP
+.eM
+.IN "XESetCopyGC" "" "@DEF@"
+.sM
+.FD 0
+int (*XESetCopyGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIextension\fP\^;
+.br
+      int (\^*\fIproc\fP\^)(\^);
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIextension\fP 1i
+Specifies the extension number.
+.IP \fIproc\fP 1i
+Specifies the procedure to call when GC components are copied.
+.LP
+.eM
+The
+.PN XESetCopyGC
+function defines a procedure to be called whenever
+a GC is copied.  
+It returns any previously defined procedure, usually NULL.
+.LP
+When a GC is copied, 
+your procedure is called with these arguments:
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+.R
+(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIgc\fP, \fIcodes\fP\^)
+	Display *\fIdisplay\fP\^;
+	GC \fIgc\fP\^;
+	XExtCodes *\fIcodes\fP\^;
+.De
+.LP
+.eM
+.IN "XESetFreeGC" "" "@DEF@"
+.sM
+.FD 0
+int (*XESetFreeGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc)\fP\^)(\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIextension\fP\^;
+.br
+      int (\^*\fIproc\fP\^)(\^);
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIextension\fP 1i
+Specifies the extension number.
+.IP \fIproc\fP 1i
+Specifies the procedure to call when a GC is freed.
+.LP
+.eM
+The
+.PN XESetFreeGC
+function defines a procedure to be called whenever
+a GC is freed.  
+It returns any previously defined procedure, usually NULL.
+.LP
+When a GC is freed, 
+your procedure is called with these arguments:
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+.R
+(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIgc\fP, \fIcodes\fP\^)
+	Display *\fIdisplay\fP\^;
+	GC \fIgc\fP\^;
+	XExtCodes *\fIcodes\fP\^;
+.De
+.LP
+.eM
+.IN "XESetCreateFont" "" "@DEF@"
+.sM
+.FD 0
+int (*XESetCreateFont(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP))(\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIextension\fP\^;
+.br
+      int (\^*\fIproc\fP\^)(\^);
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIextension\fP 1i
+Specifies the extension number.
+.IP \fIproc\fP 1i
+Specifies the procedure to call when a font is created.
+.LP
+.eM
+The
+.PN XESetCreateFont
+function defines a procedure to be called whenever
+.PN XLoadQueryFont 
+and
+.PN XQueryFont
+are called.  
+It returns any previously defined procedure, usually NULL.
+.LP
+When 
+.PN XLoadQueryFont 
+or
+.PN XQueryFont
+is called, 
+your procedure is called with these arguments:
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+.R
+(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIfs\fP, \fIcodes\fP\^)
+	Display *\fIdisplay\fP\^;
+	XFontStruct *\fIfs\fP\^;
+	XExtCodes *\fIcodes\fP\^;
+.De
+.LP
+.eM
+.IN "XESetFreeFont" "" "@DEF@"
+.sM
+.FD 0
+int (*XESetFreeFont(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIextension\fP\^;
+.br
+      int (\^*\fIproc\fP)(\^);
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIextension\fP 1i
+Specifies the extension number.
+.IP \fIproc\fP 1i
+Specifies the procedure to call when a font is freed.
+.LP
+.eM
+The
+.PN XESetFreeFont
+function defines a procedure to be called whenever
+.PN XFreeFont 
+is called.  
+It returns any previously defined procedure, usually NULL.
+.LP
+When 
+.PN XFreeFont 
+is called, your procedure is called with these arguments:
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+.R
+(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIfs\fP, \fIcodes\fP\^)
+	Display *\fIdisplay\fP\^;
+	XFontStruct *\fIfs\fP\^;
+	XExtCodes *\fIcodes\fP\^;
+.De
+.LP
+.eM
+The 
+.PN XESetWireToEvent
+and
+.PN XESetEventToWire
+functions allow you to define new events to the library.
+An 
+.PN XEvent
+structure always has a type code (type
+.PN int )
+as the first component.
+This uniquely identifies what kind of event it is.
+The second component is always the serial number (type
+.PN unsigned
+.PN long )
+of the last request processed by the server.
+The third component is always a Boolean (type
+.PN Bool )
+indicating whether the event came from a
+.PN SendEvent
+protocol request.
+The fourth component is always a pointer to the display
+the event was read from.
+The fifth component is always a resource ID of one kind or another,
+usually a window, carefully selected to be useful to toolkit dispatchers.
+The fifth component should always exist, even if
+the event does not have a natural destination;
+if there is no value
+from the protocol to put in this component, initialize it to zero.
+.NT
+There is an implementation limit such that your host event
+structure size cannot be bigger than the size of the
+.PN XEvent 
+union of structures.
+There also is no way to guarantee that more than 24 elements or 96 characters
+in the structure will be fully portable between machines.
+.NE
+.IN "XESetWireToEvent" "" "@DEF@"
+.sM
+.FD 0
+int (*XESetWireToEvent(\^\fIdisplay\fP, \fIevent_number\fP, \fIproc\fP\^))(\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIevent_number\fP\^;
+.br
+      Status (\^*\fIproc\fP\^)(\^);
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIevent_number\fP 1i
+Specifies the event code.
+.IP \fIproc\fP 1i
+Specifies the procedure to call when converting an event.
+.LP
+.eM
+The
+.PN XESetWireToEvent
+function defines a procedure to be called when an event
+needs to be converted from wire format 
+.Pn ( xEvent )
+to host format 
+.Pn ( XEvent ).
+The event number defines which protocol event number to install a
+conversion procedure for.
+.PN XESetWireToEvent
+returns any previously defined procedure.
+.NT
+You can replace a core event conversion function with one
+of your own, although this is not encouraged.
+It would, however, allow you to intercept a core event 
+and modify it before being placed in the queue or otherwise examined.
+.NE
+When Xlib needs to convert an event from wire format to host
+format, your procedure is called with these arguments:
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+.R
+Status (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIre\fP, \fIevent\fP\^)
+	Display *\fIdisplay\fP\^;
+	XEvent *\fIre\fP\^;
+	xEvent *\fIevent\fP\^;
+.De
+.LP
+.eM
+Your procedure must return status to indicate if the conversion succeeded.
+The re argument is a pointer to where the host format event should be stored,
+and the event argument is the 32-byte wire event structure.
+In the 
+.PN XEvent 
+structure you are creating, 
+you must fill in the five required members of the event structure.
+You should fill in the type member with the type specified for the 
+.PN xEvent 
+structure.
+You should copy all other members from the 
+.PN xEvent 
+structure (wire format) to the
+.PN XEvent 
+structure (host format).
+Your conversion procedure should return 
+.PN True
+if the event should be placed in the queue or
+.PN False
+if it should not be placed in the queue.
+.LP
+To initialize the serial number component of the event, call
+.PN _XSetLastRequestRead
+with the event and use the return value.
+.LP
+.IN "_XSetLastRequestRead" "" "@DEF@"
+.sM
+.FD 0
+unsigned long _XSetLastRequestRead(\^\fIdisplay\fP, \fIrep\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      xGenericReply *\fIrep\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIrep\fP 1i
+Specifies the wire event structure.
+.LP
+.eM
+The
+.PN _XSetLastRequestRead
+function computes and returns a complete serial number from the partial
+serial number in the event.
+.sp
+.LP
+.IN "XESetEventToWire" "" "@DEF@"
+.sM
+.FD 0
+Status (*XESetEventToWire(\^\fIdisplay\fP, \fIevent_number\fP, \fIproc\fP\^))(\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIevent_number\fP\^;
+.br
+      int (\^*\fIproc\fP\^)(\^);
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIevent_number\fP 1i
+Specifies the event code.
+.IP \fIproc\fP 1i
+Specifies the procedure to call when converting an event.
+.LP
+.eM
+The
+.PN XESetEventToWire
+function defines a procedure to be called when an event
+needs to be converted from host format
+.Pn ( XEvent ) 
+to wire format
+.Pn ( xEvent )
+form.  
+The event number defines which protocol event number to install a
+conversion procedure for.
+.PN XESetEventToWire
+returns any previously defined procedure.
+It returns zero if the conversion fails or nonzero otherwise.
+.NT
+You can replace a core event conversion function with one
+of your own, although this is not encouraged.  
+It would, however, allow you to intercept a core event 
+and modify it before being sent to another client.
+.NE
+When Xlib needs to convert an event from host format to wire format, 
+your procedure is called with these arguments:
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+.R
+(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIre\fP, \fIevent\fP\^)
+	Display *\fIdisplay\fP\^;
+	XEvent *\fIre\fP\^;
+	xEvent *\fIevent\fP\^;
+.De
+.LP
+.eM
+The re argument is a pointer to the host format event,
+and the event argument is a pointer to where the 32-byte wire event 
+structure should be stored.
+You should fill in the type with the type from the 
+.PN XEvent 
+structure.
+All other members then should be copied from the host format to the 
+.PN xEvent 
+structure.
+.IN "XESetWireToError" "" "@DEF@"
+.sM
+.FD 0
+Bool (*XESetWireToError(\^\fIdisplay\fP, \fIerror_number\fP, \fIproc\fP\^)(\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIerror_number\fP\^;
+.br
+      Bool (\^*\fIproc\fP\^)(\^);
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIerror_number\fP 1i
+Specifies the error code.
+.IP \fIproc\fP 1i
+Specifies the procedure to call when an error is received.
+.LP
+.eM
+The
+.PN XESetWireToError
+function defines a procedure to be called when an extension
+error needs to be converted from wire format to host format.
+The error number defines which protocol error code to install
+the conversion procedure for.
+.PN XESetWireToError
+returns any previously defined procedure.
+.LP
+Use this function for extension errors that contain additional error values
+beyond those in a core X error, when multiple wire errors must be combined
+into a single Xlib error, or when it is necessary to intercept an
+X error before it is otherwise examined.
+.LP
+When Xlib needs to convert an error from wire format to host format,
+the procedure is called with these arguments:
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+.R
+Bool (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIhe\fP, \fIwe\fP\^)
+	Display *\fIdisplay\fP\^;
+	XErrorEvent *\fIhe\fP\^;
+	xError *\fIwe\fP\^;
+.De
+.LP
+.eM
+The he argument is a pointer to where the host format error should be stored.
+The structure pointed at by he is guaranteed to be as large as an
+.PN XEvent
+structure and so can be cast to a type larger than an
+.PN XErrorEvent
+to store additional values.
+If the error is to be completely ignored by Xlib
+(for example, several protocol error structures will be combined into
+one Xlib error),
+then the function should return
+.PN False ;
+otherwise, it should return
+.PN True .
+.IN "XESetError" "" "@DEF@"
+.sM
+.FD 0
+int (*XESetError(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIextension\fP\^;
+.br
+      int (\^*\fIproc\fP\^)(\^);
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIextension\fP 1i
+Specifies the extension number.
+.IP \fIproc\fP 1i
+Specifies the procedure to call when an error is received.
+.LP
+.eM
+Inside Xlib, there are times that you may want to suppress the
+calling of the external error handling when an error occurs.
+This allows status to be returned on a call at the cost of the call
+being synchronous (though most such functions are query operations, in any
+case, and are typically programmed to be synchronous).
+.LP
+When Xlib detects a protocol error in 
+.PN _XReply , 
+it calls your procedure with these arguments:
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+.R
+int (*\fIproc\fP\^)(\fIdisplay\fP, \fIerr\fP, \fIcodes\fP, \fIret_code\fP\^)
+	Display *\fIdisplay\fP\^;
+	xError *\fIerr\fP\^;
+	XExtCodes *\fIcodes\fP\^;
+	int *\fIret_code\fP\^;
+.De
+.LP
+.eM
+The err argument is a pointer to the 32-byte wire format error.
+The codes argument is a pointer to the extension codes structure.
+The ret_code argument is the return code you may want 
+.PN _XReply 
+returned to.
+.LP
+If your procedure returns a zero value, 
+the error is not suppressed, and 
+the client's error handler is called.
+(For further information, see section 11.8.2.)
+If your procedure returns nonzero, 
+the error is suppressed, and 
+.PN _XReply 
+returns the value of ret_code.
+.IN "XESetErrorString" "" "@DEF@"
+.sM
+.FD 0
+char  *(*XESetErrorString(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIextension\fP\^;
+.br
+      char *(\^*\fIproc\fP\^)(\^);
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIextension\fP 1i
+Specifies the extension number.
+.IP \fIproc\fP 1i
+Specifies the procedure to call to obtain an error string.
+.LP
+.eM
+The 
+.PN XGetErrorText 
+function returns a string to the user for an error.
+.PN XESetErrorString
+allows you to define a procedure to be called that
+should return a pointer to the error message.
+The following is an example.
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+.R
+(*\fIproc\fP\^)(\^\fIdisplay\fP, \fIcode\fP, \fIcodes\fP, \fIbuffer\fP, \fInbytes\fP\^)
+	Display *\fIdisplay\fP\^;
+	int \fIcode\fP\^;
+	XExtCodes *\fIcodes\fP\^;
+	char *\fIbuffer\fP\^;
+	int \fInbytes\fP\^;
+.De
+.LP
+.eM
+Your procedure is called with the error code for every error detected.
+You should copy nbytes of a null-terminated string containing the
+error message into buffer.
+.IN "XESetPrintErrorValues" "" "@DEF@"
+.sM
+.FD 0
+void (*XESetPrintErrorValues(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIextension\fP\^;
+.br
+      void (\^*\fIproc\fP\^)(\^);
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIextension\fP 1i
+Specifies the extension number.
+.IP \fIproc\fP 1i
+Specifies the procedure to call when an error is printed.
+.LP
+.eM
+The
+.PN XESetPrintErrorValues
+function defines a procedure to be called when an extension
+error is printed, to print the error values.
+Use this function for extension errors that contain additional error values
+beyond those in a core X error.
+It returns any previously defined procedure.
+.LP
+When Xlib needs to print an error,
+the procedure is called with these arguments:
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+.R
+void (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIev\fP, \fIfp\fP\^)
+	Display *\fIdisplay\fP\^;
+	XErrorEvent *\fIev\fP\^;
+	void *\fIfp\fP\^;
+.De
+.LP
+.eM
+The structure pointed at by ev is guaranteed to be as large as an
+.PN XEvent
+structure and so can be cast to a type larger than an
+.PN XErrorEvent
+to obtain additional values set by using
+.PN XESetWireToError .
+The underlying type of the fp argument is system dependent;
+on a POSIX-compliant system, fp should be cast to type FILE*.
+.IN "XESetFlushGC" "" "@DEF@"
+.sM
+.FD 0
+int (*XESetFlushGC(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIextension\fP\^;
+.br
+      int *(\^*\fIproc\fP\^)(\^);
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIextension\fP 1i
+Specifies the extension number.
+.IP \fIproc\fP 1i
+Specifies the procedure to call when a GC is flushed.
+.LP
+.eM
+The procedure set by the
+.PN XESetFlushGC
+function has the same interface as the procedure set by the
+.PN XESetCopyGC
+function, but is called when a GC cache needs to be updated in the server.
+.IN "XESetBeforeFlush" "" "@DEF@"
+.sM
+.FD 0
+int (*XESetBeforeFlush(\^\fIdisplay\fP, \fIextension\fP, \fIproc\fP\^))(\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIextension\fP\^;
+.br
+      int *(\^*\fIproc\fP\^)(\^);
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIextension\fP 1i
+Specifies the extension number.
+.IP \fIproc\fP 1i
+Specifies the procedure to call when a buffer is flushed.
+.LP
+.eM
+The
+.PN XESetBeforeFlush
+function defines a procedure to be called when data is about to be
+sent to the server.  When data is about to be sent, your procedure is  
+called one or more times with these arguments:
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+.R
+void (*\fIproc\fP\^)(\^\fIdisplay\fP, \fIcodes\fP, \fIdata\fP, \fIlen\fP\^)
+	Display *\fIdisplay\fP\^;
+	XExtCodes *\fIcodes\fP\^;
+	char *\fIdata\fP\^;
+	long \fIlen\fP\^;
+.De
+.LP
+.eM
+The data argument specifies a portion of the outgoing data buffer,
+and its length in bytes is specified by the len argument.
+Your procedure must not alter the contents of the data and must not
+do additional protocol requests to the same display.
+.SH
+Hooks onto Xlib Data Structures
+.LP
+Various Xlib data structures have provisions for extension procedures
+to chain extension supplied data onto a list.
+These structures are
+.PN GC , 
+.PN Visual , 
+.PN Screen , 
+.PN ScreenFormat , 
+.PN Display , 
+and 
+.PN XFontStruct .
+Because the list pointer is always the first member in the structure, 
+a single set of procedures can be used to manipulate the data
+on these lists.
+.LP
+The following structure is used in the functions in this section
+and is defined in 
+.hN X11/Xlib.h :
+.LP
+.IN "XExtData" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _XExtData {
+	int number;	/* number returned by XInitExtension */
+	struct _XExtData *next;	/* next item on list of data for structure */
+	int (*free_private)();	/* if defined,  called to free private */
+	XPointer private_data;	/* data private to this extension. */
+} XExtData;
+.De
+.LP
+.eM
+When any of the data structures listed above are freed, 
+the list is walked, and the structure's free procedure (if any) is called. 
+If free is NULL, 
+then the library frees both the data pointed to by the private_data member
+and the structure itself. 
+.LP
+.sM
+.Ds 0
+.TA .5i
+.ta .5i
+union {	Display *display;
+	GC gc;
+	Visual *visual;
+	Screen *screen;
+	ScreenFormat *pixmap_format;
+	XFontStruct *font } XEDataObject;
+.De
+.LP
+.eM
+.IN "XEHeadOfExtensionList" "" "@DEF@"
+.sM
+.FD 0
+XExtData **XEHeadOfExtensionList(\^\fIobject\fP\^)
+	XEDataObject \fIobject\fP\^;
+.FN
+.IP \fIobject\fP 1i
+Specifies the object.
+.LP
+.eM
+The
+.PN XEHeadOfExtensionList
+function returns a pointer to the list of extension structures attached
+to the specified object.
+In concert with 
+.PN XAddToExtensionList ,
+.PN XEHeadOfExtensionList
+allows an extension to attach arbitrary data to any of the structures
+of types contained in
+.PN XEDataObject .
+.LP
+.IN "XAddToExtensionList" "" "@DEF@"
+.sM
+.FD 0
+XAddToExtensionList(\^\fIstructure\fP, \fIext_data\fP\^)
+.br
+      XExtData **\fIstructure\fP\^;
+.br
+      XExtData *\fIext_data\fP\^;
+.FN
+.IP \fIstructure\fP 1i
+Specifies the extension list.
+.IP \fIext_data\fP 1i
+Specifies the extension data structure to add.
+.LP
+.eM
+The structure argument is a pointer to one of the data structures
+enumerated above.
+You must initialize ext_data->number with the extension number
+before calling this function.
+.IN "XFindOnExtensionList" "" "@DEF@"
+.sM
+.FD 0
+XExtData *XFindOnExtensionList(\^\fIstructure\fP, \fInumber\fP\^)
+.br
+      struct _XExtData **\fIstructure\fP\^;
+.br
+      int \fInumber\fP\^;
+.FN
+.IP \fIstructure\fP 1i
+Specifies the extension list.
+.IP \fInumber\fP 1i
+Specifies the extension number from
+.PN XInitExtension .
+.LP
+.eM
+The
+.PN XFindOnExtensionList
+function returns the first extension data structure
+for the extension numbered number.
+It is expected that an extension will add at most one extension
+data structure to any single data structure's extension data list.
+There is no way to find additional structures.
+.LP
+The 
+.PN XAllocID 
+macro, which allocates and returns a resource ID, is defined in 
+.hN X11/Xlib.h .
+.IN "XAllocID" "" "@DEF@"
+.sM
+.FD 0
+XAllocID\^(\fIdisplay\fP\^)
+.br
+     Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+This macro is a call through the 
+.PN Display
+structure to an internal resource ID allocator.
+It returns a resource ID that you can use when creating new resources.
+.LP
+The 
+.PN XAllocIDs
+macro allocates and returns an array of resource ID.
+.IN "XAllocIDs" "" "@DEF@"
+.sM
+.FD 0
+XAllocIDs\^(\fIdisplay\fP, \fIids_return\fP, \fIcount\fP\^)
+.br
+     Display *\fIdisplay\fP\^;
+.br
+     XID *\fIids_return\fP\^;
+.br
+     int \fIcount\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIids_return\fP 1i
+Returns the resource IDs.
+.IP \fIrep\fP 1i
+Specifies the number of resource IDs requested.
+.LP
+.eM
+This macro is a call through the 
+.PN Display
+structure to an internal resource ID allocator.
+It returns resource IDs to the array supplied by the caller.
+To correctly handle automatic reuse of resource IDs, you must call
+.PN XAllocIDs
+when requesting multiple resource IDs.  This call might generate
+protocol requests.
+.SH
+GC Caching
+.LP
+GCs are cached by the library to allow merging of independent change
+requests to the same GC into single protocol requests.
+This is typically called a write-back cache.
+Any extension procedure whose behavior depends on the contents of a GC
+must flush the GC cache to make sure the server has up-to-date contents
+in its GC.
+.LP
+The 
+.PN FlushGC
+macro checks the dirty bits in the library's GC structure and calls
+.PN _XFlushGCCache 
+if any elements have changed.
+The
+.PN FlushGC
+macro is defined as follows:
+.IN "FlushGC" "" "@DEF@"
+.sM
+.FD 0
+FlushGC\^(\^\fIdisplay\fP\^, \fIgc\fP\^)
+.br
+      Display *\^\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.LP
+.eM
+Note that if you extend the GC to add additional resource ID components,
+you should ensure that the library stub sends the change request immediately.
+This is because a client can free a resource immediately after
+using it, so if you only stored the value in the cache without
+forcing a protocol request, the resource might be destroyed before being
+set into the GC.
+You can use the
+.PN _XFlushGCCache 
+procedure 
+to force the cache to be flushed.
+The
+.PN _XFlushGCCache 
+procedure
+is defined as follows:
+.IN "_XFlushGCCache" "" "@DEF@"
+.sM
+.FD 0
+_XFlushGCCache\^(\^\fIdisplay\fP\^, \fIgc\fP\^)
+.br
+      Display *\^\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.LP
+.eM
+.SH
+Graphics Batching
+.LP
+If you extend X to add more poly graphics primitives, you may be able to
+take advantage of facilities in the library to allow back-to-back 
+single calls to be transformed into poly requests.
+This may dramatically improve performance of programs that are not
+written using poly requests. 
+A pointer to an 
+.PN xReq ,
+called last_req in the display structure, is the last request being processed.  
+By checking that the last request
+type, drawable, gc, and other options are the same as the new one
+and that there is enough space left in the buffer, you may be able
+to just extend the previous graphics request by extending the length
+field of the request and appending the data to the buffer.  
+This can improve performance by five times or more in naive programs.  
+For example, here is the source for the 
+.PN XDrawPoint 
+stub.
+(Writing extension stubs is discussed in the next section.)
+.IP
+.sM
+.nf
+
+#include <X11/Xlibint.h>
+
+/* precompute the maximum size of batching request allowed */
+
+static int size = sizeof(xPolyPointReq) + EPERBATCH * sizeof(xPoint);
+
+XDrawPoint(dpy, d, gc, x, y)
+    register Display *dpy;
+    Drawable d;
+    GC gc;
+    int x, y; /* INT16 */
+{
+    xPoint *point;
+    LockDisplay(dpy);
+    FlushGC(dpy, gc);
+    {
+    register xPolyPointReq *req = (xPolyPointReq *) dpy->last_req;
+    /* if same as previous request, with same drawable, batch requests */
+    if (
+          (req->reqType == X_PolyPoint)
+       && (req->drawable == d)
+       && (req->gc == gc->gid)
+       && (req->coordMode == CoordModeOrigin)
+       && ((dpy->bufptr + sizeof (xPoint)) <= dpy->bufmax)
+       && (((char *)dpy->bufptr - (char *)req) < size) ) {
+         point = (xPoint *) dpy->bufptr;
+         req->length += sizeof (xPoint) >> 2;
+         dpy->bufptr += sizeof (xPoint);
+         }
+
+    else {
+        GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */
+        req->drawable = d;
+        req->gc = gc->gid;
+        req->coordMode = CoordModeOrigin;
+        point = (xPoint *) (req + 1);
+        }
+    point->x = x;
+    point->y = y;
+    }
+    UnlockDisplay(dpy);
+    SyncHandle();
+}
+.fi
+.LP
+.eM
+To keep clients from generating very long requests that may monopolize the 
+server,
+there is a symbol defined in
+.hN X11/Xlibint.h
+of EPERBATCH on the number of requests batched.
+Most of the performance benefit occurs in the first few merged requests.
+Note that 
+.PN FlushGC 
+is called \fIbefore\fP picking up the value of last_req,
+because it may modify this field.
+.SH
+Writing Extension Stubs
+.LP
+All X requests always contain the length of the request,
+expressed as a 16-bit quantity of 32 bits.
+This means that a single request can be no more than 256K bytes in
+length.
+Some servers may not support single requests of such a length.
+The value of dpy->max_request_size contains the maximum length as
+defined by the server implementation.
+For further information,
+see ``X Window System Protocol.''
+.SH
+Requests, Replies, and Xproto.h
+.LP
+The 
+.hN X11/Xproto.h
+file contains three sets of definitions that
+are of interest to the stub implementor:  
+request names, request structures, and reply structures.
+.LP
+You need to generate a file equivalent to 
+.hN X11/Xproto.h
+for your extension and need to include it in your stub procedure.
+Each stub procedure also must include 
+.hN X11/Xlibint.h .
+.LP
+The identifiers are deliberately chosen in such a way that, if the
+request is called X_DoSomething, then its request structure is
+xDoSomethingReq, and its reply is xDoSomethingReply.  
+The GetReq family of macros, defined in 
+.hN X11/Xlibint.h , 
+takes advantage of this naming scheme.
+.LP
+For each X request, 
+there is a definition in 
+.hN X11/Xproto.h
+that looks similar to this:
+.LP
+.Ds 
+.R
+#define X_DoSomething   42
+.De
+In your extension header file, 
+this will be a minor opcode, 
+instead of a major opcode.
+.SH
+Request Format
+.LP
+Every request contains an 8-bit major opcode and a 16-bit length field
+expressed in units of 4 bytes.  
+Every request consists of 4 bytes of header
+(containing the major opcode, the length field, and a data byte) followed by
+zero or more additional bytes of data. 
+The length field defines the total length of the request, including the header.
+The length field in a request must equal the minimum length required to contain 
+the request. 
+If the specified length is smaller or larger than the required length, 
+the server should generate a 
+.PN BadLength 
+error.
+Unused bytes in a request are not required to be zero.  
+Extensions should be designed in such a way that long protocol requests
+can be split up into smaller requests,
+if it is possible to exceed the maximum request size of the server.
+The protocol guarantees the maximum request size to be no smaller than
+4096 units (16384 bytes).
+.LP
+Major opcodes 128 through 255 are reserved for extensions.
+Extensions are intended to contain multiple requests, 
+so extension requests typically have an additional minor opcode encoded 
+in the second data byte in the request header, 
+but the placement and interpretation of this minor opcode as well as all
+other fields in extension requests are not defined by the core protocol.
+Every request is implicitly assigned a sequence number (starting with one)
+used in replies, errors, and events.
+.LP
+To help but not cure portability problems to certain machines, the
+.PN B16
+and
+.PN B32
+macros have been defined so that they can become bitfield specifications 
+on some machines.
+For example, on a Cray,
+these should be used for all 16-bit and 32-bit quantities, as discussed below.
+.LP
+Most protocol requests have a corresponding structure typedef in
+.hN X11/Xproto.h ,
+which looks like:
+.LP
+.IN "xDoSomethingReq" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _DoSomethingReq {
+	CARD8 reqType;	/* X_DoSomething */
+	CARD8 someDatum;	/* used differently in different requests */
+	CARD16 length B16;	/* total # of bytes in request, divided by 4 */
+	...
+	/* request-specific data */
+	...
+} xDoSomethingReq;
+.De
+.LP
+.eM
+If a core protocol request has a single 32-bit argument, 
+you need not declare a request structure in your extension header file.
+Instead, such requests use the
+.PN xResourceReq
+structure in
+.hN X11/Xproto.h .
+This structure is used for any request whose single argument is a 
+.PN Window , 
+.PN Pixmap ,
+.PN Drawable , 
+.PN GContext , 
+.PN Font , 
+.PN Cursor , 
+.PN Colormap , 
+.PN Atom , 
+or
+.PN VisualID .
+.LP
+.IN "xResourceReq" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _ResourceReq {
+	CARD8 reqType;	/* the request type, e.g. X_DoSomething */
+	BYTE pad;	/* not used */
+	CARD16 length B16;	/* 2 (= total # of bytes in request, divided by 4) */
+	CARD32 id B32;	/* the Window, Drawable, Font, GContext, etc. */
+} xResourceReq;
+.De
+.LP
+.eM
+If convenient,
+you can do something similar in your extension header file. 
+.LP
+In both of these structures, 
+the reqType field identifies the type of the request (for example, 
+X_MapWindow or X_CreatePixmap).  
+The length field tells how long the request is
+in units of 4-byte longwords. 
+This length includes both the request structure itself and any
+variable-length data, such as strings or lists, that follow the
+request structure.  
+Request structures come in different sizes, 
+but all requests are padded to be multiples of four bytes long.
+.LP
+A few protocol requests take no arguments at all. 
+Instead, they use the
+.PN xReq 
+structure in
+.hN X11/Xproto.h ,
+which contains only a reqType and a length (and a pad byte).
+.LP 
+If the protocol request requires a reply, 
+then
+.hN X11/Xproto.h
+also contains a reply structure typedef:
+.LP
+.IN "xDoSomethingReply" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct _DoSomethingReply {
+	BYTE type;	/* always X_Reply */
+	BYTE someDatum;	/* used differently in different requests */
+	CARD16 sequenceNumber B16;	/* # of requests sent so far */
+	CARD32 length B32;	/* # of additional bytes, divided by 4 */
+	...
+	/* request-specific data */
+	...
+} xDoSomethingReply;
+.De
+.LP
+.eM
+Most of these reply structures are 32 bytes long. 
+If there are not that many reply values, 
+then they contain a sufficient number of pad fields
+to bring them up to 32 bytes.  
+The length field is the total number of bytes in the request minus 32, 
+divided by 4.  
+This length will be nonzero only if:
+.IP \(bu 5
+The reply structure is followed by variable-length data,
+such as a list or string.
+.IP \(bu 5
+The reply structure is longer than 32 bytes.
+.LP
+Only 
+.PN GetWindowAttributes , 
+.PN QueryFont , 
+.PN QueryKeymap , 
+and
+.PN GetKeyboardControl 
+have reply structures longer than 32 bytes in the core protocol.
+.LP
+A few protocol requests return replies that contain no data.  
+.hN X11/Xproto.h
+does not define reply structures for these.
+Instead, they use the 
+.PN xGenericReply
+structure, which contains only a type, length,
+and sequence number (and sufficient padding to make it 32 bytes long).
+.SH
+Starting to Write a Stub Procedure
+.LP
+An Xlib stub procedure should start like this:
+.LP
+.Ds 
+.R
+#include "<X11/Xlibint.h>
+
+XDoSomething (arguments, ... )
+/* argument declarations */
+{
+
+register XDoSomethingReq *req;
+\^...
+.De
+If the protocol request has a reply, 
+then the variable declarations should include the reply structure for the request.
+The following is an example:
+.LP
+.Ds 
+.R
+xDoSomethingReply rep;
+.De 
+.SH
+Locking Data Structures
+.LP
+To lock the display structure for systems that
+want to support multithreaded access to a single display connection,
+each stub will need to lock its critical section.
+Generally, this section is the point from just before the appropriate GetReq
+call until all arguments to the call have been stored into the buffer.
+The precise instructions needed for this locking depend upon the machine
+architecture. 
+Two calls, which are generally implemented as macros, have been provided.
+.IN "LockDisplay" "" "@DEF@"
+.sM
+.FD 0
+LockDisplay(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.LP
+.IN "UnlockDisplay" "" "@DEF@"
+.FD 0
+UnlockDisplay(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.SH
+Sending the Protocol Request and Arguments
+.LP
+After the variable declarations, 
+a stub procedure should call one of four macros defined in 
+.hN X11/Xlibint.h : 
+.PN GetReq , 
+.PN GetReqExtra , 
+.PN GetResReq , 
+or 
+.PN GetEmptyReq .  
+All of these macros take, as their first argument,
+the name of the protocol request as declared in 
+.hN X11/Xproto.h
+except with X_ removed.   
+Each one declares a 
+.PN Display 
+structure pointer,
+called dpy, and a pointer to a request structure, called req,
+which is of the appropriate type.
+The macro then appends the request structure to the output buffer, 
+fills in its type and length field, and sets req to point to it.
+.LP
+If the protocol request has no arguments (for instance, X_GrabServer),
+then use 
+.PN GetEmptyReq .
+.LP
+.Ds
+.R 
+GetEmptyReq (DoSomething, req);
+.De
+If the protocol request has a single 32-bit argument (such as a
+.PN Pixmap , 
+.PN Window , 
+.PN Drawable , 
+.PN Atom , 
+and so on),
+then use 
+.PN GetResReq .  
+The second argument to the macro is the 32-bit object.  
+.PN X_MapWindow 
+is a good example.
+.LP
+.Ds
+.R
+GetResReq (DoSomething, rid, req);
+.De
+The rid argument is the 
+.PN Pixmap , 
+.PN Window , 
+or other resource ID.
+.LP
+If the protocol request takes any other argument list, 
+then call 
+.PN GetReq .  
+After the 
+.PN GetReq , 
+you need to set all the other fields in the request structure,
+usually from arguments to the stub procedure.
+.LP
+.Ds 
+.R
+GetReq (DoSomething, req);
+/* fill in arguments here */
+req->arg1 = arg1;
+req->arg2 = arg2;
+\^...
+.De
+A few stub procedures (such as 
+.PN XCreateGC 
+and 
+.PN XCreatePixmap ) 
+return a resource ID to the caller but pass a resource ID as an argument
+to the protocol request.   
+Such procedures use the macro 
+.PN XAllocID 
+to allocate a resource ID from the range of IDs 
+that were assigned to this client when it opened the connection.
+.LP
+.Ds 
+.R
+rid = req->rid = XAllocID();
+\^...
+return (rid);
+.De
+Finally, some stub procedures transmit a fixed amount of variable-length
+data after the request.  
+Typically, these procedures (such as
+.PN XMoveWindow 
+and 
+.PN XSetBackground ) 
+are special cases of more general functions like 
+.PN XMoveResizeWindow 
+and 
+.PN XChangeGC .   
+These procedures use 
+.PN GetReqExtra , 
+which is the same as 
+.PN GetReq
+except that it takes an additional argument (the number of
+extra bytes to allocate in the output buffer after the request structure).  
+This number should always be a multiple of four.
+.SH
+Variable Length Arguments
+.LP
+Some protocol requests take additional variable-length data that
+follow the 
+.PN xDoSomethingReq 
+structure.    
+The format of this data varies from request to request. 
+Some requests require a sequence of 8-bit bytes, 
+others a sequence of 16-bit or 32-bit entities, 
+and still others a sequence of structures.
+.LP
+It is necessary to add the length of any variable-length data to the
+length field of the request structure.  
+That length field is in units of 32-bit longwords.  
+If the data is a string or other sequence of 8-bit bytes, 
+then you must round the length up and shift it before adding:
+.LP
+.Ds
+.R
+req->length += (nbytes+3)>>2;
+.De
+To transmit variable-length data, use the 
+.PN Data 
+macros.
+If the data fits into the output buffer, 
+then this macro copies it to the buffer.  
+If it does not fit, however,
+the 
+.PN Data 
+macro calls 
+.PN _XSend , 
+which transmits first the contents of the buffer and then your data.
+The 
+.PN Data 
+macros take three arguments:  
+the display, a pointer to the beginning of the data, 
+and the number of bytes to be sent.
+.sM
+.FD 0
+Data(\^\fIdisplay\fP, (char *) \fIdata\fP, \fInbytes\fP\^);
+.sp
+Data16(\^\fIdisplay\fP, (short *) \fIdata\fP, \fInbytes\fP\^);
+.sp
+Data32(\^\fIdisplay\fP, (long *) \fIdata\fP, \fInbytes\fP\^);
+.FN
+.LP
+.eM
+.PN Data ,
+.PN Data16 ,
+and
+.PN Data32
+are macros that may use their last argument
+more than once, so that argument should be a variable rather than
+an expression such as ``nitems*sizeof(item)''.  
+You should do that kind of computation in a separate statement before calling 
+them.
+Use the appropriate macro when sending byte, short, or long data.
+.LP
+If the protocol request requires a reply, 
+then call the procedure 
+.PN _XSend 
+instead of the 
+.PN Data 
+macro.  
+.PN _XSend 
+takes the same arguments, but because it sends your data immediately instead of 
+copying it into the output buffer (which would later be flushed
+anyway by the following call on 
+.PN _XReply ), 
+it is faster.
+.SH
+Replies
+.LP
+If the protocol request has a reply, 
+then call 
+.PN _XReply 
+after you have finished dealing with 
+all the fixed-length and variable-length arguments.  
+.PN _XReply 
+flushes the output buffer and waits for an 
+.PN xReply 
+packet to arrive.  
+If any events arrive in the meantime,
+.PN _XReply 
+places them in the queue for later use.
+.IN "_XReply" "" "@DEF@"
+.sM
+.FD 0
+Status _XReply(\^\fIdisplay\fP, \fIrep\fP, \fIextra\fP, \fIdiscard\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      xReply *\fIrep\fP\^;
+.br
+      int \fIextra\fP\^;
+.br
+      Bool \fIdiscard\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIrep\fP 1i
+Specifies the reply structure.
+.IP \fIextra\fP 1i
+Specifies the number of 32-bit words expected after the replay.
+.IP \fIdiscard\fP 1i
+Specifies if any data beyond that specified in the extra argument
+should be discarded.
+.LP
+.eM
+The
+.PN _XReply 
+function waits for a reply packet and copies its contents into the
+specified rep.  
+.PN _XReply 
+handles error and event packets that occur before the reply is received.
+.PN _XReply 
+takes four arguments:
+.IP \(bu 5
+A 
+.PN Display 
+* structure
+.IP \(bu 5
+A pointer to a reply structure (which must be cast to an 
+.PN xReply 
+*)
+.IP \(bu 5
+The number of additional 32-bit words (beyond 
+.Pn sizeof( xReply ) 
+= 32 bytes)
+in the reply structure
+.IP \(bu 5
+A Boolean that indicates whether
+.PN _XReply 
+is to discard any additional bytes
+beyond those it was told to read
+.LP
+Because most reply structures are 32 bytes long, 
+the third argument is usually 0.  
+The only core protocol exceptions are the replies to 
+.PN GetWindowAttributes , 
+.PN QueryFont , 
+.PN QueryKeymap , 
+and 
+.PN GetKeyboardControl ,
+which have longer replies.
+.LP
+The last argument should be 
+.PN False 
+if the reply structure is followed
+by additional variable-length data (such as a list or string).  
+It should be 
+.PN True 
+if there is not any variable-length data.
+.NT
+This last argument is provided for upward-compatibility reasons
+to allow a client to communicate properly with a hypothetical later
+version of the server that sends more data than the client expected.
+For example, some later version of 
+.PN GetWindowAttributes 
+might use a
+larger, but compatible, 
+.PN xGetWindowAttributesReply 
+that contains additional attribute data at the end.
+.NE
+.PN _XReply 
+returns 
+.PN True
+if it received a reply successfully or 
+.PN False 
+if it received any sort of error. 
+.LP
+For a request with a reply that is not followed by variable-length
+data, you write something like:
+.LP
+.Ds 
+.R
+_XReply(display, (xReply *)&rep, 0, True);
+*ret1 = rep.ret1;
+*ret2 = rep.ret2;
+*ret3 = rep.ret3;
+\^...
+UnlockDisplay(dpy);
+SyncHandle();
+return (rep.ret4);
+}
+.De
+If there is variable-length data after the reply, 
+change the 
+.PN True 
+to 
+.PN False , 
+and use the appropriate
+.PN _XRead 
+function to read the variable-length data.
+.LP
+.sM
+.FD 0
+_XRead(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^)
+       Display *\fIdisplay\fP\^;
+       char *\fIdata_return\fP\^;
+       long \fInbytes\fP\^;	
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIdata_return\fP 1i
+Specifies the buffer.
+.IP \fInbytes\fP 1i
+Specifies the number of bytes required.
+.LP
+.eM
+The
+.PN _XRead
+function reads the specified number of bytes into data_return.
+.LP
+.sM
+.FD 0
+_XRead16(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^)
+       Display *\fIdisplay\fP\^;
+       short *\fIdata_return\fP\^;
+       long \fInbytes\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIdata_return\fP 1i
+Specifies the buffer.
+.IP \fInbytes\fP 1i
+Specifies the number of bytes required.
+.LP
+.eM
+The
+.PN _XRead16
+function reads the specified number of bytes,
+unpacking them as 16-bit quantities,
+into the specified array as shorts.
+.LP
+.sM
+.FD 0
+_XRead32(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^)
+       Display *\fIdisplay\fP\^;
+       long *\fIdata_return\fP\^;
+       long \fInbytes\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIdata_return\fP 1i
+Specifies the buffer.
+.IP \fInbytes\fP 1i
+Specifies the number of bytes required.
+.LP
+.eM
+The
+.PN _XRead32
+function reads the specified number of bytes,
+unpacking them as 32-bit quantities,
+into the specified array as longs.
+.LP
+.sM
+.FD 0
+_XRead16Pad(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^)
+       Display *\fIdisplay\fP\^;
+       short *\fIdata_return\fP\^;
+       long \fInbytes\fP\^; 
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIdata_return\fP 1i
+Specifies the buffer.
+.IP \fInbytes\fP 1i
+Specifies the number of bytes required.
+.LP
+.eM
+The
+.PN _XRead16Pad
+function reads the specified number of bytes,
+unpacking them as 16-bit quantities,
+into the specified array as shorts.
+If the number of bytes is not a multiple of four,
+.PN _XRead16Pad
+reads and discards up to two additional pad bytes.
+.LP
+.sM
+.FD 0
+_XReadPad(\^\fIdisplay\fP, \fIdata_return\fP, \fInbytes\fP\^)
+       Display *\fIdisplay\fP\^;
+       char *\fIdata_return\fP\^;
+       long \fInbytes\fP\^; 
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIdata_return\fP 1i
+Specifies the buffer.
+.IP \fInbytes\fP 1i
+Specifies the number of bytes required.
+.LP
+.eM
+The
+.PN _XReadPad
+function reads the specified number of bytes into data_return.
+If the number of bytes is not a multiple of four,
+.PN _XReadPad
+reads and discards up to three additional pad bytes.
+.LP
+Each protocol request is a little different. 
+For further information,
+see the Xlib sources for examples.
+.SH
+Synchronous Calling
+.LP
+Each procedure should have a call, just before returning to the user, 
+to a macro called
+.PN SyncHandle .
+If synchronous mode is enabled (see 
+.PN XSynchronize ), 
+the request is sent immediately.
+The library, however, waits until any error the procedure could generate
+at the server has been handled.
+.SH
+Allocating and Deallocating Memory
+.LP
+To support the possible reentry of these procedures, 
+you must observe several conventions when allocating and deallocating memory,
+most often done when returning data to the user from the window
+system of a size the caller could not know in advance
+(for example, a list of fonts or a list of extensions).
+The standard C library functions on many systems
+are not protected against signals or other multithreaded uses.
+The following analogies to standard I/O library functions
+have been defined:
+.TS
+l l.
+T{
+.PN Xmalloc ()
+T}	T{
+Replaces 
+.PN malloc ()
+T}
+T{
+.PN XFree ()
+T}	T{
+Replaces 
+.PN free ()
+T}
+T{
+.PN Xcalloc ()
+T}	T{
+Replaces 
+.PN calloc ()
+T}
+.TE
+.LP
+These should be used in place of any calls you would make to the normal
+C library functions.
+.LP
+If you need a single scratch buffer inside a critical section 
+(for example, to pack and unpack data to and from the wire protocol),
+the general memory allocators may be too expensive to use
+(particularly in output functions, which are performance critical).  
+The following function returns a scratch buffer for use within a
+critical section:
+.IN "_XAllocScratch" "" "@DEF@"
+.sM
+.FD 0
+char *_XAllocScratch(\^\fIdisplay\fP, \fInbytes\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      unsigned long \fInbytes\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fInbytes\fP 1i
+Specifies the number of bytes required.
+.LP
+.eM
+This storage must only be used inside of a critical section of your
+stub.  The returned pointer cannot be assumed valid after any call
+that might permit another thread to execute inside Xlib.  For example,
+the pointer cannot be assumed valid after any use of the
+.PN GetReq
+or
+.PN Data
+families of macros,
+after any use of
+.PN _XReply ,
+or after any use of the
+.PN _XSend
+or
+.PN _XRead
+families of functions.
+.LP
+.sp
+The following function returns a scratch buffer for use across
+critical sections:
+.IN "_XAllocTemp" "" "@DEF@"
+.sM
+.FD 0
+char *_XAllocTemp(\^\fIdisplay\fP, \fInbytes\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      unsigned long \fInbytes\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fInbytes\fP 1i
+Specifies the number of bytes required.
+.LP
+.eM
+This storage can be used across calls that might permit another thread to
+execute inside Xlib.  The storage must be explicitly returned to Xlib.
+The following function returns the storage:
+.IN "_XFreeTemp" "" "@DEF@"
+.sM
+.FD 0
+void _XFreeTemp(\^\fIdisplay\fP, \fIbuf\fP, \fInbytes\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      char *\fIbuf\fP\^;
+.br
+      unsigned long \fInbytes\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIbuf\fP 1i
+Specifies the buffer to return.
+.IP \fInbytes\fP 1i
+Specifies the size of the buffer.
+.LP
+.eM
+You must pass back the same pointer and size that were returned by
+.PN _XAllocTemp .
+.SH
+Portability Considerations
+.LP
+Many machine architectures, 
+including many of the more recent RISC architectures, 
+do not correctly access data at unaligned locations; 
+their compilers pad out structures to preserve this characteristic.
+Many other machines capable of unaligned references pad inside of structures
+as well to preserve alignment, because accessing aligned data is
+usually much faster.
+Because the library and the server use structures to access data at
+arbitrary points in a byte stream,
+all data in request and reply packets \fImust\fP be naturally aligned;
+that is, 16-bit data starts on 16-bit boundaries in the request
+and 32-bit data on 32-bit boundaries.
+All requests \fImust\fP be a multiple of 32 bits in length to preserve
+the natural alignment in the data stream.
+You must pad structures out to 32-bit boundaries.
+Pad information does not have to be zeroed unless you want to
+preserve such fields for future use in your protocol requests.
+Floating point varies radically between machines and should be
+avoided completely if at all possible.
+.LP
+This code may run on machines with 16-bit ints.  
+So, if any integer argument, variable, or return value either can take 
+only nonnegative values or is declared as a
+.PN CARD16
+in the protocol, be sure to declare it as
+.PN unsigned
+.PN int
+and not as
+.PN int .
+(This, of course, does not apply to Booleans or enumerations.)
+.LP
+Similarly, 
+if any integer argument or return value is declared
+.PN CARD32
+in the protocol, 
+declare it as an
+.PN unsigned
+.PN long
+and not as
+.PN int
+or
+.PN long .
+This also goes for any internal variables that may
+take on values larger than the maximum 16-bit
+.PN unsigned
+.PN int .
+.LP
+The library currently assumes that a
+.PN char
+is 8 bits, a
+.PN short
+is 16 bits, an
+.PN int
+is 16 or 32 bits, and a
+.PN long
+is 32 bits.  
+The 
+.PN PackData 
+macro is a half-hearted attempt to deal with the possibility of 32 bit shorts. 
+However, much more work is needed to make this work properly.
+.SH
+Deriving the Correct Extension Opcode
+.LP
+The remaining problem a writer of an extension stub procedure faces that
+the core protocol does not face is to map from the call to the proper
+major and minor opcodes.  
+While there are a number of strategies, 
+the simplest and fastest is outlined below.
+.IP 1. 5
+Declare an array of pointers, _NFILE long (this is normally found
+in 
+.hN stdio.h
+and is the number of file descriptors supported on the system)
+of type 
+.PN XExtCodes .
+Make sure these are all initialized to NULL.
+.IP 2. 5
+When your stub is entered, your initialization test is just to use
+the display pointer passed in to access the file descriptor and an index
+into the array.  
+If the entry is NULL, then this is the first time you
+are entering the procedure for this display.  
+Call your initialization procedure and pass to it the display pointer.
+.IP 3. 5
+Once in your initialization procedure, call 
+.PN XInitExtension ;
+if it succeeds, store the pointer returned into this array.  
+Make sure to establish a close display handler to allow you to zero the entry.
+Do whatever other initialization your extension requires.
+(For example, install event handlers and so on.)
+Your initialization procedure would normally return a pointer to the
+.PN XExtCodes 
+structure for this extension, which is what would normally
+be found in your array of pointers.
+.IP 4. 5
+After returning from your initialization procedure, 
+the stub can now continue normally, because it has its major opcode safely 
+in its hand in the 
+.PN XExtCodes 
+structure.
+.bp
diff --git a/specs/libX11/AppD b/specs/libX11/AppD
new file mode 100644
index 00000000..f96e0617
--- /dev/null
+++ b/specs/libX11/AppD
@@ -0,0 +1,1183 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+\&
+.sp 1
+.ce 3
+\s+1\fBAppendix D\fP\s-1
+
+\s+1\fBCompatibility Functions\fP\s-1
+.sp 2
+.na
+.LP
+.XS
+Appendix D: Compatibility Functions
+.XE
+.LP
+The X Version 11 and X Version 10 functions discussed in this appendix 
+are obsolete, have been superseded by newer X Version 11 functions,
+and are maintained for compatibility reasons only.
+.SH
+X Version 11 Compatibility Functions
+.LP
+You can use the X Version 11 compatibility functions to:
+.IP \(bu 5
+Set standard properties 
+.IP \(bu 5
+Set and get window sizing hints 
+.IP \(bu 5
+Set and get an
+.PN XStandardColormap
+structure 
+.IP \(bu 5
+Parse window geometry
+.IP \(bu 5
+Get X environment defaults
+.SH
+Setting Standard Properties
+.LP
+To specify a minimum set of properties describing the simplest application,
+use
+.PN XSetStandardProperties .
+This function has been superseded by
+.PN XSetWMProperties
+and sets all or portions of the 
+WM_NAME, WM_ICON_NAME, WM_HINTS, WM_COMMAND, 
+and WM_NORMAL_HINTS properties.
+.IN "XSetStandardProperties" "" "@DEF@"
+.sM
+.FD 0
+XSetStandardProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIwindow_name\fP, \fIicon_name\fP, \fIicon_pixmap\fP, \fIargv\fP, \fIargc\fP, \fIhints\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      char *\fIwindow_name\fP\^;
+.br
+      char *\fIicon_name\fP\^;
+.br
+      Pixmap \fIicon_pixmap\fP\^;
+.br
+      char **\fIargv\fP\^;
+.br
+      int \fIargc\fP\^;
+.br
+      XSizeHints *\fIhints\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIwindow_name\fP 1i
+Specifies the window name,
+which should be a null-terminated string.
+.IP \fIicon_name\fP 1i
+Specifies the icon name,
+which should be a null-terminated string.
+.IP \fIicon_pixmap\fP 1i
+Specifies the bitmap that is to be used for the icon or
+.PN None .
+.IP \fIargv\fP 1i
+Specifies the application's argument list.
+.IP \fIargc\fP 1i
+Specifies the number of arguments.
+.IP \fIhints\fP 1i
+Specifies a pointer to the size hints for the window in its normal state.
+.LP
+.eM
+The
+.PN XSetStandardProperties
+function provides a means by which simple applications set the
+most essential properties with a single call.
+.PN XSetStandardProperties
+should be used to give a window manager some information about 
+your program's preferences. 
+It should not be used by applications that need
+to communicate more information than is possible with
+.PN XSetStandardProperties .
+(Typically, argv is the argv array of your main program.)
+If the strings are not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+.LP
+.PN XSetStandardProperties
+can generate
+.PN BadAlloc
+and
+.PN BadWindow 
+errors.
+.SH
+Setting and Getting Window Sizing Hints
+.LP
+Xlib provides functions that you can use to set or get window sizing hints.
+The functions discussed in this section use the flags and the
+.PN XSizeHints 
+structure, as defined in the
+.hN X11/Xutil.h
+header file and use the WM_NORMAL_HINTS property.
+.LP
+.sp
+To set the size hints for a given window in its normal state, use
+.PN XSetNormalHints .
+This function has been superseded by
+.PN XSetWMNormalHints .
+.IN "XSetNormalHints" "" "@DEF@"
+.sM
+.FD 0
+XSetNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XSizeHints *\fIhints\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIhints\fP 1i
+Specifies a pointer to the size hints for the window in its normal state.
+.LP
+.eM
+The
+.PN XSetNormalHints
+function sets the size hints structure for the specified window.
+Applications use
+.PN XSetNormalHints
+to inform the window manager of the size
+or position desirable for that window.
+In addition, 
+an application that wants to move or resize itself should call
+.PN XSetNormalHints
+and specify its new desired location and size
+as well as making direct Xlib calls to move or resize.  
+This is because window managers may ignore redirected
+configure requests, but they pay attention to property changes.
+.LP
+To set size hints, 
+an application not only must assign values to the appropriate members
+in the hints structure but also must set the flags member of the structure 
+to indicate which information is present and where it came from.  
+A call to
+.PN XSetNormalHints
+is meaningless, unless the flags member is set to indicate which members of
+the structure have been assigned values.
+.LP
+.PN XSetNormalHints
+can generate
+.PN BadAlloc
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To return the size hints for a window in its normal state, use
+.PN XGetNormalHints .
+This function has been superseded by
+.PN XGetWMNormalHints .
+.IN "XGetNormalHints" "" "@DEF@"
+.sM
+.FD 0
+Status XGetNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XSizeHints *\fIhints_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIhints_return\fP 1i
+Returns the size hints for the window in its normal state.
+.LP
+.eM
+The
+.PN XGetNormalHints
+function returns the size hints for a window in its normal state.
+It returns a nonzero status if it succeeds or zero if
+the application specified no normal size hints for this window.
+.LP
+.PN XGetNormalHints
+can generate a
+.PN BadWindow 
+error.
+.LP
+.sp
+The next two functions set and read the WM_ZOOM_HINTS property.
+.LP
+To set the zoom hints for a window, use
+.PN XSetZoomHints .
+This function is no longer supported by the
+\fIInter-Client Communication Conventions Manual\fP.
+.IN "XSetZoomHints" "" "@DEF@"
+.sM
+.FD 0
+XSetZoomHints\^(\^\fIdisplay\fP, \fIw\fP, \fIzhints\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XSizeHints *\fIzhints\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIzhints\fP 1i
+Specifies a pointer to the zoom hints.
+.LP
+.eM
+Many window managers think of windows in one of three states:
+iconic, normal, or zoomed.
+The
+.PN XSetZoomHints
+function provides the window manager with information for the window in the
+zoomed state.
+.LP
+.PN XSetZoomHints
+can generate
+.PN BadAlloc
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To read the zoom hints for a window, use
+.PN XGetZoomHints .
+This function is no longer supported by the
+\fIInter-Client Communication Conventions Manual\fP.
+.IN "XGetZoomHints" "" "@DEF@"
+.sM
+.FD 0
+Status XGetZoomHints\^(\^\fIdisplay\fP, \fIw\fP, \fIzhints_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XSizeHints *\fIzhints_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIzhints_return\fP 1i
+Returns the zoom hints.
+.LP
+.eM
+The
+.PN XGetZoomHints
+function returns the size hints for a window in its zoomed state.
+It returns a nonzero status if it succeeds or zero if
+the application specified no zoom size hints for this window.
+.LP
+.PN XGetZoomHints
+can generate a
+.PN BadWindow 
+error.
+.LP
+.sp
+To set the value of any property of type WM_SIZE_HINTS, use
+.PN XSetSizeHints .
+This function has been superseded by
+.PN XSetWMSizeHints .
+.IN "XSetSizeHints" "" "@DEF@"
+.sM
+.FD 0
+XSetSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP, \fIproperty\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XSizeHints *\fIhints\fP\^;
+.br
+      Atom \fIproperty\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIhints\fP 1i
+Specifies a pointer to the size hints.
+.IP \fIproperty\fP 1i
+Specifies the property name.
+.LP
+.eM
+The
+.PN XSetSizeHints
+function sets the
+.PN XSizeHints
+structure for the named property and the specified window.
+This is used by
+.PN XSetNormalHints
+and
+.PN XSetZoomHints
+and can be used to set the value of any property of type WM_SIZE_HINTS.
+Thus, it may be useful if other properties of that type get defined.
+.LP
+.PN XSetSizeHints
+can generate
+.PN BadAlloc ,
+.PN BadAtom ,
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To read the value of any property of type WM_SIZE_HINTS, use
+.PN XGetSizeHints .
+This function has been superseded by
+.PN XGetWMSizeHints .
+.IN "XGetSizeHints" "" "@DEF@"
+.sM
+.FD 0
+Status XGetSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP, \fIproperty\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XSizeHints *\fIhints_return\fP\^;
+.br
+      Atom \fIproperty\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIhints_return\fP 1i
+Returns the size hints.
+.IP \fIproperty\fP 1i
+Specifies the property name.
+.LP
+.eM
+The
+.PN XGetSizeHints
+function returns the
+.PN XSizeHints
+structure for the named property and the specified window.
+This is used by
+.PN XGetNormalHints
+and
+.PN XGetZoomHints .
+It also can be used to retrieve the value of any property of type
+WM_SIZE_HINTS.
+Thus, it may be useful if other properties of that type get defined.
+.PN XGetSizeHints
+returns a nonzero status if a size hint was defined
+or zero otherwise.
+.LP
+.PN XGetSizeHints
+can generate
+.PN BadAtom
+and 
+.PN BadWindow 
+errors.
+.SH
+Getting and Setting an XStandardColormap Structure
+.LP
+To get the 
+.PN XStandardColormap 
+structure associated with one of the described atoms, use
+.PN XGetStandardColormap .
+This function has been superseded by
+.PN XGetRGBColormap .
+.IN "XGetStandardColormap" "" "@DEF@"
+.sM
+.FD 0
+Status XGetStandardColormap(\^\fIdisplay\fP, \fIw\fP, \fIcolormap_return\fP, \fIproperty\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XStandardColormap *\fIcolormap_return\fP\^;
+.br
+      Atom \fIproperty\fP\^;	/* RGB_BEST_MAP, etc. */
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIcolormap_return\fP 1i
+Returns the colormap associated with the specified atom.
+.IP \fIproperty\fP 1i
+Specifies the property name.
+.LP
+.eM
+The
+.PN XGetStandardColormap
+function returns the colormap definition associated with the atom supplied
+as the property argument.
+.PN XGetStandardColormap
+returns a nonzero status if successful and zero otherwise.
+For example,
+to fetch the standard
+.PN GrayScale
+colormap for a display,
+you use
+.PN XGetStandardColormap
+with the following syntax:
+.LP
+.sM
+.Ds 0
+.TA .5i 1.5i
+.ta .5i 1.5i
+XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_MAP);
+.De
+.LP
+.eM
+See section 14.3 for the semantics of standard colormaps.
+.LP
+.PN XGetStandardColormap
+can generate
+.PN BadAtom
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To set a standard colormap, use
+.PN XSetStandardColormap .
+This function has been superseded by
+.PN XSetRGBColormap .
+.IN "XSetStandardColormap" "" "@DEF@"
+.sM
+.FD 0
+XSetStandardColormap(\^\fIdisplay\fP, \fIw\fP, \fIcolormap\fP, \fIproperty\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XStandardColormap *\fIcolormap\fP\^;
+.br
+      Atom \fIproperty\fP\^;	/* RGB_BEST_MAP, etc. */
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.IP \fIproperty\fP 1i
+Specifies the property name.
+.LP
+.eM
+The
+.PN XSetStandardColormap
+function usually is only used by window or session managers.
+.LP
+.PN XSetStandardColormap
+can generate
+.PN BadAlloc ,
+.PN BadAtom ,
+.PN BadDrawable ,
+and
+.PN BadWindow 
+errors.
+.SH
+Parsing Window Geometry
+.LP
+To parse window geometry given a user-specified position 
+and a default position, use
+.PN XGeometry .
+This function has been superseded by
+.PN XWMGeometry .
+.IN "Window" "determining location"
+.IN "XGeometry" "" "@DEF@"
+.sM
+.FD 0
+int XGeometry\^(\^\fIdisplay\fP, \fIscreen\fP, \fIposition\fP\^, \fIdefault_position\fP\^, \fIbwidth\fP\^, \fIfwidth\fP\^, \fIfheight\fP\^, \fIxadder\fP\^, 
+.br
+                  \fIyadder\fP\^, \fIx_return\fP\^, \fIy_return\fP\^, \fIwidth_return\fP\^, \fIheight_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen\fP\^;
+.br
+      char *\fIposition\fP\^, *\fIdefault_position\fP\^;	
+.br
+      unsigned int \fIbwidth\fP\^;
+.br
+      unsigned int \fIfwidth\fP\^, \fIfheight\fP\^;	
+.br
+      int \fIxadder\fP\^, \fIyadder\fP\^;	
+.br
+      int *\fIx_return\fP\^, *\fIy_return\fP\^;
+.br
+      int *\fIwidth_return\fP\^, *\fIheight_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen\fP 1i
+Specifies the screen.
+.IP \fIposition\fP 1i
+.br
+.ns
+.IP \fIdefault_position\fP 1i
+Specify the geometry specifications.
+.IP \fIbwidth\fP 1i
+Specifies the border width.
+.IP \fIfheight\fP 1i
+.br
+.ns
+.IP \fIfwidth\fP 1i
+Specify the font height and width in pixels (increment size).
+.IP \fIxadder\fP 1i
+.br
+.ns
+.IP \fIyadder\fP 1i
+Specify additional interior padding needed in the window.
+.IP \fIx_return\fP 1i
+.br
+.ns
+.IP \fIy_return\fP 1i
+Return the x and y offsets.
+.IP \fIwidth_return\fP 1i
+.br
+.ns
+.IP \fIheight_return\fP 1i
+Return the width and height determined.
+.LP
+.eM
+You pass in the border width (bwidth),
+size of the increments fwidth and fheight
+(typically font width and height),
+and any additional interior space (xadder and yadder)
+to make it easy to compute the resulting size.
+The
+.PN XGeometry 
+function returns the position the window should be placed given a position and
+a default position.
+.PN XGeometry
+determines the placement of
+a window using a geometry specification as specified by
+.PN XParseGeometry 
+and the additional information about the window.
+Given a fully qualified default geometry specification and
+an incomplete geometry specification, 
+.PN XParseGeometry
+returns a bitmask value as defined above in the 
+.PN XParseGeometry
+call,
+by using the position argument.
+.LP
+The returned width and height will be the width and height specified
+by default_position as overridden by any user-specified position.
+They are not affected by fwidth, fheight, xadder, or yadder.
+The x and y coordinates are computed by using the border width,
+the screen width and height, padding as specified by xadder and yadder,
+and the fheight and fwidth times the width and height from the
+geometry specifications.
+.SH
+Getting the X Environment Defaults
+.LP
+The
+.PN XGetDefault
+function provides a primitive interface to the resource manager facilities 
+discussed in chapter 15.
+It is only useful in very simple applications.
+.LP
+.sp
+.IN "XGetDefault" "" "@DEF@"
+.sM
+.FD 0
+char *XGetDefault\^(\^\fIdisplay\fP, \fIprogram\fP\^, \fIoption\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      char *\fIprogram\fP\^;
+.br
+      char *\fIoption\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIprogram\fP 1i
+Specifies the program name for the Xlib defaults (usually argv[0] 
+of the main program).
+.IP \fIoption\fP 1i
+Specifies the option name.
+.LP
+.eM
+The
+.PN XGetDefault
+function returns the value of the resource \fIprog\fP.\fIoption\fP,
+where \fIprog\fP is the program argument with the directory prefix removed
+and \fIoption\fP must be a single component.
+Note that multilevel resources cannot be used with
+.PN XGetDefault .
+The class "Program.Name" is always used for the resource lookup.
+If the specified option name does not exist for this program,
+.PN XGetDefault
+returns NULL.
+The strings returned by
+.PN XGetDefault
+are owned by Xlib and should not be modified or freed by the client.
+.LP
+If a database has been set with 
+.PN XrmSetDatabase , 
+that database is used for the lookup.
+Otherwise, a database is created
+and is set in the display (as if by calling 
+.PN XrmSetDatabase ).
+The database is created in the current locale.
+To create a database,
+.PN XGetDefault
+uses resources from the RESOURCE_MANAGER property on the root
+window of screen zero.
+If no such property exists,
+a resource file in the user's home directory is used.
+On a POSIX-conformant system, 
+this file is
+.PN "$HOME/.Xdefaults" .
+.IN "Files" "$HOME/.Xdefaults"
+After loading these defaults,
+.PN XGetDefault
+merges additional defaults specified by the XENVIRONMENT
+environment variable.
+If XENVIRONMENT is defined,
+it contains a full path name for the additional resource file.
+If XENVIRONMENT is not defined,
+.PN XGetDefault
+looks for
+.PN "$HOME/.Xdefaults-\fIname\fP" ,
+where \fIname\fP specifies the name of the machine on which the application
+is running.
+.SH
+X Version 10 Compatibility Functions
+.LP
+You can use the X Version 10 compatibility functions to:
+.IP \(bu 5
+Draw and fill polygons and curves
+.IP \(bu 5
+Associate user data with a value
+.SH
+Drawing and Filling Polygons and Curves
+.LP
+Xlib provides functions that you can use to draw or fill
+arbitrary polygons or curves.  
+These functions are provided mainly for compatibility with X Version 10 
+and have no server support.  
+That is, they call other Xlib functions, not the server directly.  
+Thus, if you just have straight lines to draw, using 
+.PN XDrawLines 
+.IN "XDrawLines"
+or
+.PN XDrawSegments 
+.IN "XDrawSegments" 
+is much faster.
+.LP
+The functions discussed here provide all the functionality of the 
+X Version 10 functions 
+.PN XDraw , 
+.IN "X10 compatibility" "XDraw" 
+.PN XDrawFilled , 
+.IN "X10 compatibility" "XDrawFilled"
+.PN XDrawPatterned , 
+.IN "X10 compatibility" "XDrawPatterned" 
+.PN XDrawDashed , 
+.IN "X10 compatibility" "XDrawDashed"
+and
+.PN XDrawTiled .  
+.IN "X10 compatibility" "XDrawTiled"
+They are as compatible as possible given X Version 11's new line-drawing 
+functions.  
+One thing to note, however, is that
+.PN VertexDrawLastPoint 
+is no longer supported. 
+Also, the error status returned is the opposite of what it was under 
+X Version 10 (this is the X Version 11 standard error status).  
+.PN XAppendVertex 
+and 
+.PN XClearVertexFlag 
+from X Version 10 also are not supported.
+.LP
+Just how the graphics context you use is set up actually
+determines whether you get dashes or not, and so on.  
+Lines are properly joined if they connect and include
+the closing of a closed figure  (see 
+.PN XDrawLines ).
+The functions discussed here fail (return zero) only if they run out of memory
+or are passed a 
+.PN Vertex 
+list that has a 
+.PN Vertex 
+with 
+.PN VertexStartClosed
+set that is not followed by a 
+.PN Vertex 
+with 
+.PN VertexEndClosed 
+set.
+.LP
+.sp
+To achieve the effects of the X Version 10
+.PN XDraw , 
+.IN "X10 compatibility" "XDraw" 
+.PN XDrawDashed , 
+.IN "X10 compatibility" "XDrawDashed"
+and 
+.PN XDrawPatterned , 
+.IN "X10 compatibility" "XDrawPatterned" 
+use
+.PN XDraw .  
+.IN "XDraw" "" "@DEF@" 
+.sM
+.FD 0
+#include <X11/X10.h>
+
+Status XDraw(\^\fIdisplay\fP, \fId\fP, \fIgc\fP, \fIvlist\fP, \fIvcount\fP\^)
+.br
+	Display *\fIdisplay\fP\^;
+.br
+	Drawable \fId\fP\^;
+.br
+	GC \fIgc\fP\^;
+.br
+	Vertex *\fIvlist\fP\^;
+.br
+	int \fIvcount\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIvlist\fP 1i
+Specifies a pointer to the list of vertices that indicate what to draw.
+.IP \fIvcount\fP 1i
+Specifies how many vertices are in vlist.
+.LP
+.eM
+The
+.PN XDraw 
+function draws an arbitrary polygon or curve.  
+The figure drawn is defined by the specified list of vertices (vlist).
+The points are connected by lines as specified in the flags in the
+vertex structure.
+.LP
+Each Vertex, as defined in
+.hN X11/X10.h ,
+is a structure with the following members:
+.LP
+.IN "Vertex" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 1.5i
+.ta .5i 1.5i
+typedef struct _Vertex {
+	short x,y;
+	unsigned short flags;
+} Vertex;
+.De
+.LP
+.eM
+The x and y members are the coordinates of the vertex 
+that are relative to either the upper left inside corner of the drawable 
+(if 
+.PN VertexRelative 
+is zero) or the previous vertex (if 
+.PN VertexRelative 
+is one).
+.LP
+The flags, as defined in 
+.hN X11/X10.h , 
+are as follows:
+.IN "VertexRelative" "" "@DEF@"
+.IN "VertexDontDraw" "" "@DEF@"
+.IN "VertexCurved" "" "@DEF@"
+.IN "VertexStartClosed" "" "@DEF@"
+.IN "VertexEndClosed" "" "@DEF@"
+.sM
+.TS
+l l l.
+T{
+.PN VertexRelative
+T}	T{
+0x0001
+T}	T{
+/* else absolute */
+T}
+T{
+.PN VertexDontDraw
+T}	T{
+0x0002
+T}	T{
+/* else draw */
+T}
+T{
+.PN VertexCurved
+T}	T{
+0x0004
+T}	T{
+/* else straight */
+T}
+T{
+.PN VertexStartClosed
+T}	T{
+0x0008
+T}	T{
+/* else not */
+T}
+T{
+.PN VertexEndClosed
+T}	T{
+0x0010
+T}	T{
+/* else not */
+T}
+.TE
+.LP
+.eM
+.IP \(bu 5
+If 
+.PN VertexRelative 
+is not set,  
+the coordinates are absolute (that is, relative to the drawable's origin).  
+The first vertex must be an absolute vertex.
+.IP \(bu 5
+If
+.PN VertexDontDraw 
+is one, 
+no line or curve is drawn from the previous vertex to this one.  
+This is analogous to picking up the pen and moving to another place 
+before drawing another line.
+.IP \(bu 5
+If 
+.PN VertexCurved 
+is one, 
+a spline algorithm is used to draw a smooth curve from the previous vertex
+through this one to the next vertex.  
+Otherwise, a straight line is drawn from the previous vertex to this one.  
+It makes sense to set 
+.PN VertexCurved 
+to one only if a previous and next vertex are both defined
+(either explicitly in the array or through the definition of a closed 
+curve).
+.IP \(bu 5
+It is permissible for 
+.PN VertexDontDraw 
+bits and 
+.PN VertexCurved
+bits both to be one. 
+This is useful if you want to define the previous point for the smooth curve
+but do not want an actual curve drawing to start until this point.
+.IP \(bu 5
+If 
+.PN VertexStartClosed 
+is one, 
+then this point marks the beginning of a closed curve.  
+This vertex must be followed later in the array by another vertex 
+whose effective coordinates are identical
+and that has a
+.PN VertexEndClosed 
+bit of one.
+The points in between form a cycle to determine predecessor 
+and successor vertices for the spline algorithm.
+.LP
+This function uses these GC components:
+function, plane-mask, line-width, line-style, cap-style, join-style,
+fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and
+clip-mask.
+It also uses these GC mode-dependent components: 
+foreground, background, tile, stipple,
+tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list.
+.LP
+.sp
+To achieve the effects of the X Version 10
+.PN XDrawTiled 
+.IN "X10 compatibility" "XDrawTiled"
+and 
+.PN XDrawFilled , 
+.IN "X10 compatibility" "XDrawFilled"
+use
+.PN XDrawFilled .
+.IN "XDrawFilled" "" "@DEF@"
+.sM
+.FD 0
+#include <X11/X10.h>
+
+Status XDrawFilled(\^\fIdisplay\fP, \fId\fP, \fIgc\fP, \fIvlist\fP, \fIvcount\fP\^)
+.br
+	Display *\fIdisplay\fP\^;
+.br
+	Drawable \fId\fP\^;
+.br
+	GC \fIgc\fP\^;
+.br
+	Vertex *\fIvlist\fP\^;
+.br
+	int \fIvcount\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIvlist\fP 1i
+Specifies a pointer to the list of vertices that indicate what to draw.
+.IP \fIvcount\fP 1i
+Specifies how many vertices are in vlist.
+.LP
+.eM
+The
+.PN XDrawFilled 
+function draws arbitrary polygons or curves and then fills them.
+.LP
+This function uses these GC components:
+function, plane-mask, line-width, line-style, cap-style, join-style,
+fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and
+clip-mask.
+It also uses these GC mode-dependent components: 
+foreground, background, tile, stipple,
+tile-stipple-x-origin, tile-stipple-y-origin, 
+dash-offset, dash-list, fill-style, and fill-rule.
+.SH
+Associating User Data with a Value
+.LP
+These functions have been superseded by the context management functions
+(see section 16.10). 
+It is often necessary to associate arbitrary information with resource IDs.
+Xlib provides the 
+.PN XAssocTable 
+functions that you can use to make such an association.
+.IN "Hash Lookup"
+.IN "Window" "IDs"
+.IN "Resource IDs"
+Application programs often need to be able to easily refer to
+their own data structures when an event arrives.
+The 
+.PN XAssocTable
+system provides users of the X library with a method
+for associating their own data structures with X resources
+.Pn ( Pixmaps , 
+.PN Fonts , 
+.PN Windows , 
+and so on).
+.LP
+An 
+.PN XAssocTable
+can be used to type X resources.  
+For example, the user
+may want to have three or four types of windows,
+each with different properties. 
+This can be accomplished by associating each X window ID
+with a pointer to a window property data structure  defined  by  the
+user.
+A generic type has been defined in the X library for resource IDs.
+It is called an XID.
+.LP
+There are a few  guidelines  that  should be observed when using an
+.PN XAssocTable :
+.IP \(bu 5
+All  XIDs  are  relative  to  the  specified display.
+.IP \(bu 5
+Because  of  the  hashing  scheme  used  by  the  association mechanism,
+the following rules for determining the size of a
+.PN XAssocTable
+should be followed.  
+Associations will be  made  and  looked  up  more
+efficiently  if  the  table  size  (number  of  buckets in the hashing
+system) is a power of two and if there are not more than 8 XIDs  per
+bucket.
+.LP
+.sp
+To return a pointer to a new
+.PN XAssocTable , 
+use 
+.PN XCreateAssocTable .
+.IN "XCreateAssocTable" "" "@DEF@"
+.sM
+.FD 0
+XAssocTable *XCreateAssocTable\^(\^\fIsize\fP\^)
+.br
+      int \fIsize\fP\^;	
+.FN
+.IP \fIsize\fP 1i
+Specifies the number of buckets in the hash system of
+.PN XAssocTable .
+.LP
+.eM
+The size argument specifies the number of buckets in the 
+hash system of
+.PN XAssocTable .
+For  reasons  of  efficiency  the number of buckets
+should be a power of two.
+Some size  suggestions  might  be:  use  32 buckets  per  100  objects,
+and a reasonable maximum number of objects per buckets is 8.
+If  an  error  allocating  memory  for  the
+.PN XAssocTable 
+occurs, 
+a NULL pointer is returned. 
+.LP
+.sp
+To create an entry in a given 
+.PN XAssocTable ,
+use 
+.PN XMakeAssoc .
+.IN "XMakeAssoc" "" "@DEF@"
+.sM
+.FD 0
+XMakeAssoc\^(\^\fIdisplay\fP, \fItable\fP\^, \fIx_id\fP\^, \fIdata\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XAssocTable *\fItable\fP\^;	
+.br
+      XID \fIx_id\fP\^;
+.br
+      char *\fIdata\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fItable\fP 1i
+Specifies the assoc table. 
+.IP \fIx_id\fP 1i
+Specifies the X resource ID.
+.IP \fIdata\fP 1i
+Specifies the data to be associated with the X resource ID.
+.LP
+.eM
+The
+.PN XMakeAssoc
+function inserts data into an 
+.PN XAssocTable
+keyed on an XID.
+Data is inserted into the table only once.
+Redundant inserts are ignored.
+The queue in each association bucket is sorted from the lowest XID to 
+the highest XID.
+.LP
+.sp
+To obtain data from a given 
+.PN XAssocTable ,
+use 
+.PN XLookUpAssoc .
+.IN "XLookUpAssoc" "" "@DEF@"
+.sM
+.FD 0
+char *XLookUpAssoc\^(\^\fIdisplay\fP, \fItable\fP\^, \fIx_id\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XAssocTable *\fItable\fP\^;
+.br
+      XID \fIx_id\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fItable\fP 1i
+Specifies the assoc table. 
+.IP \fIx_id\fP 1i
+Specifies the X resource ID.
+.LP
+.eM
+The
+.PN XLookUpAssoc
+function retrieves the data stored in an 
+.PN XAssocTable
+by its XID.  
+If  an appropriately  matching XID can be found in the table,
+.PN XLookUpAssoc
+returns the data associated with it.
+If the x_id cannot be found in the table,
+it returns NULL.
+.LP
+.sp
+To delete an entry from a given 
+.PN XAssocTable ,
+use 
+.PN XDeleteAssoc .
+.IN "XDeleteAssoc" "" "@DEF@"
+.sM
+.FD 0
+XDeleteAssoc\^(\^\fIdisplay\fP, \fItable\fP\^, \fIx_id\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XAssocTable *\fItable\fP\^;
+.br
+      XID \fIx_id\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fItable\fP 1i
+Specifies the assoc table. 
+.IP \fIx_id\fP 1i
+Specifies the X resource ID.
+.LP
+.eM
+The
+.PN XDeleteAssoc
+function deletes an association in an 
+.PN XAssocTable
+keyed on its XID.
+Redundant deletes (and deletes of nonexistent XIDs) are ignored.
+Deleting associations in no way impairs the performance of an 
+.PN XAssocTable .
+.LP
+.sp
+To free the memory associated with a given 
+.PN XAssocTable ,
+use 
+.PN XDestroyAssocTable .
+.IN "XDestroyAssocTable" "" "@DEF@"
+.sM
+.FD 0
+XDestroyAssocTable\^(\^\fItable\fP\^)
+.br
+      XAssocTable *\fItable\fP\^;
+.FN
+.IP \fItable\fP 1i
+Specifies the assoc table. 
+.LP
+.eM
+.bp
diff --git a/specs/libX11/CH01 b/specs/libX11/CH01
new file mode 100644
index 00000000..765e4b5f
--- /dev/null
+++ b/specs/libX11/CH01
@@ -0,0 +1,663 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+.EH '\fBXlib \- C Library\fP''\fB\*(xV\fP'
+.OH '\fBXlib \- C Library\fP''\fB\*(xV\fP'
+.EF ''\fB % \fP''
+.OF ''\fB % \fP''
+.hw WM_NORMAL_HINTS
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 1\fP\s-1
+
+\s+1\fBIntroduction to Xlib\fP\s-1
+.sp 2
+.if \n(GS .nr nh*hl 1
+.nr H1 1
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.na
+.LP
+.XS
+Chapter 1: Introduction to Xlib
+.XE
+The X Window System is a network-transparent window system
+that was designed at MIT.
+X display servers run on computers with either monochrome or color
+bitmap display hardware.
+The server distributes user input to and accepts output requests from various
+client programs located either on the same machine or elsewhere in
+the network.
+Xlib is a C subroutine library that application programs (clients)
+use to interface with the window system by means of a stream connection.
+Although a client usually runs on the same machine as the X server 
+it is talking to, this need not be the case.
+.LP
+\fIXlib \- C Language X Interface\fP is a reference guide to the low-level 
+C language interface to the X Window System protocol.
+It is neither a tutorial nor a user's guide to programming the X Window System.
+Rather, it provides a detailed description of each function in the library
+as well as a discussion of the related background information.
+\fIXlib \- C Language X Interface\fP assumes a basic understanding of a graphics 
+window system and of the C programming language.
+Other higher-level abstractions
+(for example, those provided by the toolkits for X)
+are built on top of the Xlib library.
+For further information about these higher-level libraries,
+see the appropriate toolkit documentation.
+The \fIX Window System Protocol\fP provides the definitive word on the
+behavior of X.
+Although additional information appears here,
+the protocol document is the ruling document.
+.LP
+To provide an introduction to X programming,
+this chapter discusses:
+.IP \(bu 5
+Overview of the X Window System
+.IP \(bu 5
+Errors
+.IP \(bu 5
+Standard header files
+.IP \(bu 5
+Generic values and types
+.IP \(bu 5
+Naming and argument conventions within Xlib
+.IP \(bu 5
+Programming considerations
+.IP \(bu 5
+Character sets and encodings
+.IP \(bu 5
+Formatting conventions
+.NH 2
+Overview of the X Window System
+.XS
+\*(SN Overview of the X Window System
+.XE
+.LP
+Some of the terms used in this book are unique to X,
+and other terms that are common to other window systems 
+have different meanings in X.
+You may find it helpful to refer to the glossary, 
+which is located at the end of the book.
+.LP
+The X Window System supports one or more screens containing
+overlapping windows or subwindows.
+A screen is a physical monitor and hardware
+that can be color, grayscale, or monochrome.
+There can be multiple screens for each display or workstation.
+A single X server can provide display services for any number of screens.
+A set of screens for a single user with one keyboard and one pointer
+(usually a mouse) is called a display.
+.LP
+.IN "Screen"
+All the windows in an X server are arranged in strict hierarchies.
+At the top of each hierarchy is a root window,
+which covers each of the display screens.
+Each root window is partially or completely covered by child windows.
+All windows, except for root windows, have parents.
+There is usually at least one window for each application program.
+.IN "Child window"
+.IN "Parent Window"
+Child windows may in turn have their own children.
+In this way, 
+an application program can create an arbitrarily deep tree 
+on each screen.
+X provides graphics, text, and raster operations for windows.
+.LP
+A child window can be larger than its parent. 
+That is, part or all of
+the child window can extend beyond the boundaries of the parent,
+but all output to a window is clipped by its parent.
+.IN "Stacking order"
+If several children of a window have overlapping locations, 
+one of the children is considered to be on top of or raised over the
+others, thus obscuring them.
+Output to areas covered by other windows is suppressed by the window
+system unless the window has backing store.
+If a window is obscured by a second window, 
+the second window obscures only those ancestors of the second window
+that are also ancestors of the first window.
+.LP
+.IN "Window" "" "@DEF@"
+A window has a border zero or more pixels in width, which can
+be any pattern (pixmap) or solid color you like.
+A window usually but not always has a background pattern,
+which will be repainted by the window system when uncovered.
+Child windows obscure their parents,
+and graphic operations in the parent window usually
+are clipped by the children.
+.LP
+Each window and pixmap has its own coordinate system.
+The coordinate system has the X axis horizontal and the Y axis vertical
+with the origin [0, 0] at the upper-left corner.
+Coordinates are integral,
+in terms of pixels,
+and coincide with pixel centers.
+For a window, 
+the origin is inside the border at the inside, upper-left corner.
+.LP
+X does not guarantee to preserve the contents of windows. 
+When part or all of a window is hidden and then brought back onto the screen,
+its contents may be lost. 
+The server then sends the client program an
+.PN Expose
+event to notify it that part or all of the window needs to be repainted.
+Programs must be prepared to regenerate the contents of windows on demand.
+.LP
+.IN "Pixmap"
+.IN "Drawable"
+.IN "Tile"
+.IN "Bitmap"
+X also provides off-screen storage of graphics objects,
+called pixmaps.
+Single plane (depth 1) pixmaps are sometimes referred to as bitmaps.
+Pixmaps can be used in most graphics functions interchangeably with
+windows and are used in various graphics operations to define patterns or tiles.
+Windows and pixmaps together are referred to as drawables.
+.LP
+Most of the functions in Xlib just add requests to an output buffer.
+These requests later execute asynchronously on the X server.
+Functions that return values of information stored in
+the server do not return (that is, they block)
+until an explicit reply is received or an error occurs.
+You can provide an error handler,
+which will be called when the error is reported.
+.LP
+.IN "XSync"
+If a client does not want a request to execute asynchronously, 
+it can follow the request with a call to 
+.PN XSync , 
+which blocks until all previously buffered
+asynchronous events have been sent and acted on.
+As an important side effect, 
+the output buffer in Xlib is always flushed by a call to any function
+that returns a value from the server or waits for input.
+.LP
+.IN "Resource IDs"
+.IN "Resource IDs" "Window"
+.IN "Resource IDs" "Font"
+.IN "Resource IDs" "Pixmap"
+.IN "Resource IDs" "Cursor"
+.IN "Resource IDs" "GContext"
+Many Xlib functions will return an integer resource ID,
+which allows you to refer to objects stored on the X server.
+These can be of type 
+.PN Window , 
+.PN Font , 
+.PN Pixmap , 
+.PN Colormap ,
+.PN Cursor , 
+and 
+.PN GContext ,
+as defined in the file
+.hN X11/X.h .
+These resources are created by requests and are destroyed
+(or freed) by requests or when connections are closed.
+Most of these resources are potentially sharable between
+applications, and in fact, windows are manipulated explicitly by
+window manager programs.
+Fonts and cursors are shared automatically across multiple screens.
+Fonts are loaded and unloaded as needed and are shared by multiple clients.
+Fonts are often cached in the server.
+Xlib provides no support for sharing graphics contexts between applications.
+.LP
+.IN "Event"
+Client programs are informed of events.
+Events may either be side effects of a request (for example, restacking windows
+generates 
+.PN Expose 
+events) or completely asynchronous (for example, from the keyboard).
+A client program asks to be informed of events.
+Because other applications can send events to your application,
+programs must be prepared to handle (or ignore) events of all types.
+.LP
+Input events (for example, a key pressed or the pointer moved) 
+arrive asynchronously from the server and are queued until they are 
+requested by an explicit call (for example,
+.PN XNextEvent
+or
+.PN XWindowEvent ).
+In addition, some library
+functions (for example,
+.PN XRaiseWindow )
+generate 
+.PN Expose
+and
+.PN ConfigureRequest
+events.
+These events also arrive asynchronously, but the client may
+.IN "XSync"
+wish to explicitly wait for them by calling
+.PN XSync
+after calling a function that can cause the server to generate events.
+.NH 2
+Errors
+.XS
+\*(SN Errors
+.XE
+.LP
+Some functions return 
+.PN Status , 
+an integer error indication.
+If the function fails, it returns a zero.
+If the function returns a status of zero,
+it has not updated the return arguments.
+.IN "Status"
+Because C does not provide multiple return values, 
+many functions must return their results by writing into client-passed storage. 
+.IN "Error" "handling"
+By default, errors are handled either by a standard library function
+or by one that you provide.
+Functions that return pointers to strings return NULL pointers if
+the string does not exist.
+.LP
+The X server reports protocol errors at the time that it detects them.
+If more than one error could be generated for a given request,
+the server can report any of them.
+.LP
+Because Xlib usually does not transmit requests to the server immediately
+(that is, it buffers them), errors can be reported much later than they
+actually occur.
+For debugging purposes, however,
+Xlib provides a mechanism for forcing synchronous behavior 
+(see section 11.8.1).
+When synchronization is enabled, 
+errors are reported as they are generated.
+.LP
+When Xlib detects an error,
+it calls an error handler,
+which your program can provide.
+If you do not provide an error handler,
+the error is printed, and your program terminates.
+.NH 2
+Standard Header Files
+.XS
+\*(SN Standard Header Files
+.XE
+.LP
+The following include files are part of the Xlib standard:
+.IP \(bu 5
+.hN X11/Xlib.h
+.IP
+This is the main header file for Xlib.
+The majority of all Xlib symbols are declared by including this file.
+This file also contains the preprocessor symbol
+.PN XlibSpecificationRelease .
+.IN "XlibSpecificationRelease" "" "@DEF@"
+This symbol is defined to have the 6 in this release of the standard.
+(Release 5 of Xlib was the first release to have this symbol.)
+.IP \(bu 5
+.hN X11/X.h
+.IP
+This file declares types and constants for the X protocol that are
+to be used by applications.
+It is included automatically from
+.hN X11/Xlib.h ,
+so application code should never need to reference this file directly.
+.IP \(bu 5
+.hN X11/Xcms.h
+.IP
+This file contains symbols for much of the color management facilities
+described in chapter 6.
+All functions, types, and symbols with the prefix ``Xcms'',
+plus the Color Conversion Contexts macros, are declared in this file.
+.hN X11/Xlib.h
+must be included before including this file.
+.IP \(bu 5
+.hN X11/Xutil.h
+.IP
+This file declares various functions, types, and symbols used for
+inter-client communication and application utility functions,
+which are described in chapters 14 and 16.
+.hN X11/Xlib.h
+must be included before including this file.
+.IP \(bu 5
+.hN X11/Xresource.h
+.IP
+This file declares all functions, types, and symbols for the
+resource manager facilities, which are described in chapter 15.
+.hN X11/Xlib.h
+must be included before including this file.
+.IP \(bu 5
+.hN X11/Xatom.h
+.IP
+This file declares all predefined atoms, 
+which are symbols with the prefix ``XA_''.
+.IP \(bu 5
+.hN X11/cursorfont.h
+.IP
+This file declares the cursor symbols for the standard cursor font,
+which are listed in appendix B.
+All cursor symbols have the prefix ``XC_''.
+.IP \(bu 5
+.hN X11/keysymdef.h
+.IP
+This file declares all standard KeySym values,
+which are symbols with the prefix ``XK_''.
+The KeySyms are arranged in groups, and a preprocessor symbol controls
+inclusion of each group.  The preprocessor symbol must be defined
+prior to inclusion of the file to obtain the associated values.
+The preprocessor symbols are XK_MISCELLANY, XK_XKB_KEYS, XK_3270,
+XK_LATIN1, XK_LATIN2,
+XK_LATIN3, XK_LATIN4, XK_KATAKANA, XK_ARABIC, XK_CYRILLIC, XK_GREEK,
+XK_TECHNICAL, XK_SPECIAL, XK_PUBLISHING, XK_APL, XK_HEBREW,
+XK_THAI, and XK_KOREAN.
+.IP \(bu 5
+.hN X11/keysym.h
+.IP
+This file defines the preprocessor symbols
+XK_MISCELLANY, XK_XKB_KEYS, XK_LATIN1, XK_LATIN2, XK_LATIN3,
+XK_LATIN4, and XK_GREEK
+and then includes
+.hN X11/keysymdef.h .
+.IP \(bu 5
+.hN X11/Xlibint.h
+.IP
+This file declares all the functions, types, and symbols used for
+extensions, which are described in appendix C.
+This file automatically includes
+.hN X11/Xlib.h .
+.IP \(bu 5
+.hN X11/Xproto.h
+.IP
+This file declares types and symbols for the basic X protocol,
+for use in implementing extensions.
+It is included automatically from
+.hN X11/Xlibint.h ,
+so application and extension code should never need to
+reference this file directly.
+.IP \(bu 5
+.hN X11/Xprotostr.h
+.IP
+This file declares types and symbols for the basic X protocol,
+for use in implementing extensions.
+It is included automatically from
+.hN X11/Xproto.h ,
+so application and extension code should never need to
+reference this file directly.
+.IP \(bu 5
+.hN X11/X10.h
+.IP
+This file declares all the functions, types, and symbols used for the
+X10 compatibility functions, which are described in appendix D.
+.NH 2
+Generic Values and Types
+.XS
+\*(SN Generic Values and Types
+.XE
+.LP
+The following symbols are defined by Xlib and used throughout the manual:
+.IN "Bool" "" "@DEF@"
+.IN "True" "" "@DEF@"
+.IN "False" "" "@DEF@"
+.IP \(bu 5
+Xlib defines the type
+.PN Bool
+and the Boolean values
+.PN True
+and
+.PN False .
+.IN "None" "" "@DEF@"
+.IP \(bu 5
+.PN None
+is the universal null resource ID or atom.
+.IN "XID" "" "@DEF@"
+.IP \(bu 5
+The type
+.PN XID
+is used for generic resource IDs.
+.IN "XPointer" "" "@DEF@"
+.IP \(bu 5
+The type
+.PN XPointer
+is defined to be char\^* and is used as a generic opaque pointer to data.
+.NH 2
+Naming and Argument Conventions within Xlib
+.XS
+\*(SN Naming and Argument Conventions within Xlib
+.XE
+.LP
+Xlib follows a number of conventions for the naming and syntax of the functions.
+Given that you remember what information the function requires,
+these conventions are intended to make the syntax of the functions more 
+predictable.
+.LP
+The major naming conventions are:
+.IP \(bu 5
+To differentiate the X symbols from the other symbols,
+the library uses mixed case for external symbols.
+It leaves lowercase for variables and all uppercase for user macros,
+as per existing convention.
+.IP \(bu 5
+All Xlib functions begin with a capital X.
+.IP \(bu 5
+The beginnings of all function names and symbols are capitalized.
+.IP \(bu 5
+All user-visible data structures begin with a capital X.
+More generally,
+anything that a user might dereference begins with a capital X.
+.IP \(bu 5
+Macros and other symbols do not begin with a capital X.
+To distinguish them from all user symbols,
+each word in the macro is capitalized.
+.IP \(bu 5
+All elements  of or variables in a data structure are in lowercase.
+Compound words, where needed, are constructed with underscores (\^_\^).
+.IP \(bu 5
+The display argument, where used, is always first in the argument list.
+.IP \(bu 5
+All resource objects, where used, occur at the beginning of the argument list
+immediately after the display argument.
+.IP \(bu 5
+When a  graphics context is present together with
+another type of resource (most commonly, a drawable), the
+graphics context occurs in the argument list after the other
+resource.
+Drawables outrank all other resources.
+.IP \(bu 5
+Source arguments always precede the destination arguments in the argument list.
+.IP \(bu 5
+The x argument always precedes the y argument in the argument list.
+.IP \(bu 5
+The width argument always precedes the height argument in the argument list.
+.IP \(bu 5
+Where the x, y, width, and height arguments are used together,
+the x and y arguments always precede the width and height arguments.
+.IP \(bu 5
+Where a mask is accompanied with a structure,
+the mask always precedes the pointer to the structure in the argument list.
+.NH 2
+Programming Considerations
+.XS
+\*(SN Programming Considerations
+.XE
+.LP
+The major programming considerations are:
+.IP \(bu 5
+Coordinates and sizes in X are actually 16-bit quantities.
+This decision was made to minimize the bandwidth required for a
+given level of performance.
+Coordinates usually are declared as an
+.PN int 
+in the interface.
+Values larger than 16 bits are truncated silently.
+Sizes (width and height) are declared as unsigned quantities.
+.IP \(bu 5
+Keyboards are the greatest variable between different
+manufacturers' workstations.
+If you want your program to be portable,
+you should be particularly conservative here.
+.IP \(bu 5
+Many display systems have limited amounts of off-screen memory.
+If you can, you should minimize use of pixmaps and backing
+store.
+.IP \(bu 5
+The user should have control of his screen real estate.
+Therefore, you should write your applications to react to window management
+rather than presume control of the entire screen.
+What you do inside of your top-level window, however,
+is up to your application.
+For further information,
+see chapter 14
+and the \fIInter-Client Communication Conventions Manual\fP.
+.NH 2
+Character Sets and Encodings
+.XS
+\*(SN Character Sets and Encodings
+.XE
+.LP
+Some of the Xlib functions make reference to specific character sets
+and character encodings.
+The following are the most common:
+.IP \(bu 5
+X Portable Character Set
+.IP
+A basic set of 97 characters, 
+which are assumed to exist in all locales supported by Xlib.
+This set contains the following characters:
+.IP
+.Ds 0
+.EQ
+delim DD
+.EN
+a..z A..Z 0..9
+!"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~
+<space>, <tab>, and <newline>
+.EQ
+delim %%
+.EN
+.De
+.IP
+This set is the left/lower half
+of the graphic character set of ISO8859-1 plus space, tab, and newline.
+It is also the set of graphic characters in 7-bit ASCII plus the same
+three control characters.
+The actual encoding of these characters on the host is system dependent.
+.IP \(bu 5
+Host Portable Character Encoding
+.IP
+The encoding of the X Portable Character Set on the host.
+The encoding itself is not defined by this standard,
+but the encoding must be the same in all locales supported by Xlib on the host.
+If a string is said to be in the Host Portable Character Encoding,
+then it only contains characters from the X Portable Character Set,
+in the host encoding.
+.IP \(bu 5
+Latin-1
+.IP
+The coded character set defined by the ISO8859-1 standard.
+.IP \(bu 5
+Latin Portable Character Encoding
+.IP
+The encoding of the X Portable Character Set using the Latin-1 codepoints
+plus ASCII control characters.
+If a string is said to be in the Latin Portable Character Encoding,
+then it only contains characters from the X Portable Character Set,
+not all of Latin-1.
+.IP \(bu 5
+STRING Encoding
+.IP
+Latin-1, plus tab and newline.
+.IP \(bu 5
+POSIX Portable Filename Character Set
+.IP
+The set of 65 characters, 
+which can be used in naming files on a POSIX-compliant host,
+that are correctly processed in all locales.
+The set is:
+.IP
+.Ds 0
+a..z A..Z 0..9 ._-
+.De
+.NH 2
+Formatting Conventions
+.XS
+\*(SN Formatting Conventions
+.XE
+.LP
+\fIXlib \- C Language X Interface\fP uses the following conventions:
+.IP \(bu 5
+Global symbols are printed in 
+.PN this 
+.PN special 
+.PN font .
+These can be either function names,
+symbols defined in include files, or structure names.
+When declared and defined,
+function arguments are printed in \fIitalics\fP.
+In the explanatory text that follows,
+they usually are printed in regular type.
+.IP \(bu 5
+Each function is introduced by a general discussion that 
+distinguishes it from other functions.
+The function declaration itself follows,
+and each argument is specifically explained.
+Although ANSI C function prototype syntax is not used,
+Xlib header files normally declare functions using function prototypes
+in ANSI C environments.
+General discussion of the function, if any is required,
+follows the arguments.
+Where applicable, 
+the last paragraph of the explanation lists the possible 
+Xlib error codes that the function can generate.
+For a complete discussion of the Xlib error codes,
+see section 11.8.2.
+.IP \(bu 5
+To eliminate any ambiguity between those arguments that you pass and those that 
+a function returns to you,
+the explanations for all arguments that you pass start with the word
+\fIspecifies\fP or, in the case of multiple arguments, the word \fIspecify\^\fP.
+The explanations for all arguments that are returned to you start with the
+word \fIreturns\fP or, in the case of multiple arguments, the word \fIreturn\^\fP.
+The explanations for all arguments that you can pass and are returned start
+with the words \fIspecifies and returns\^\fP.
+.IP \(bu 5
+Any pointer to a structure that is used to return a value is designated as 
+such by the \fI_return\fP suffix as part of its name.
+All other pointers passed to these functions are
+used for reading only.
+A few arguments use pointers to structures that are used for
+both input and output and are indicated by using the \fI_in_out\fP suffix.
+.bp
diff --git a/specs/libX11/CH02 b/specs/libX11/CH02
new file mode 100644
index 00000000..61554b89
--- /dev/null
+++ b/specs/libX11/CH02
@@ -0,0 +1,2052 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996, 2000 The Open Group
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" Except as contained in this notice, the name of The Open Group 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 Open Group.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+.\" $XFree86$
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 2\fP\s-1
+
+\s+1\fBDisplay Functions\fP\s-1
+.sp 2
+.nr H1 2
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.na
+.LP
+.XS
+Chapter 2: Display Functions
+.XE
+Before your program can use a display, you must establish a connection
+to the X server.
+Once you have established a connection,
+you then can use the Xlib macros and functions discussed in this chapter
+to return information about the display.
+This chapter discusses how to:
+.IP \(bu 5
+Open (connect to) the display
+.IP \(bu 5
+Obtain information about the display, image formats, or screens
+.IP \(bu 5
+Generate a
+.PN NoOperation
+protocol request
+.IP \(bu 5
+Free client-created data
+.IP \(bu 5
+Close (disconnect from) a display
+.IP \(bu 5
+Use X Server connection close operations
+.IP \(bu 5
+Use Xlib with threads
+.IP \(bu 5
+Use internal connections
+.NH 2
+Opening the Display
+.XS
+\*(SN Opening the Display
+.XE
+.LP
+To open a connection to the X server that controls a display, use
+.PN XOpenDisplay .
+.IN "XOpenDisplay" "" "@DEF@"
+.LP
+.sM
+.FD 0
+Display *XOpenDisplay\^(\^\fIdisplay_name\fP\^)
+.br
+      char *\fIdisplay_name\fP\^;
+.FN	
+.IP \fIdisplay_name\fP 1i
+Specifies the hardware display name, which determines the display
+and communications domain to be used.
+On a POSIX-conformant system, if the display_name is NULL, 
+it defaults to the value of the DISPLAY environment variable. 
+.IN "Environment" "DISPLAY"
+.LP
+.eM
+The encoding and interpretation of the display name are
+implementation-dependent.
+Strings in the Host Portable Character Encoding are supported;
+support for other characters is implementation-dependent.
+On POSIX-conformant systems,
+the display name or DISPLAY environment variable can be a string in the format:
+.LP
+.sM
+.Ds 0
+.TA 1i
+.ta 1i
+	\fIprotocol\fP\^/\^\fIhostname\fP\^:\^\fInumber\fP\^.\^\fIscreen_number\fP
+.De
+.IP \fIprotocol\fP 1i
+Specifies a protocol family or an alias for a protocol family.  Supported 
+protocol families are implementation dependent.  The protocol entry is 
+optional.  If protocol is not specified, the / separating protocol and 
+hostname must also not be specified.
+.IP \fIhostname\fP 1i
+Specifies the name of the host machine on which the display is physically
+attached.
+You follow the hostname with either a single colon (:) or a double colon (::).
+.IP \fInumber\fP 1i
+Specifies the number of the display server on that host machine.
+You may optionally follow this display number with a period (.).
+A single CPU can have more than one display.
+Multiple displays are usually numbered starting with zero.
+.IN "Screen"
+.IP \fIscreen_number\fP 1i
+Specifies the screen to be used on that server.
+Multiple screens can be controlled by a single X server.
+The screen_number sets an internal variable that can be accessed by
+using the 
+.PN DefaultScreen 
+macro or the 
+.PN XDefaultScreen
+function if you are using languages other than C (see section 2.2.1).
+.LP
+.eM
+For example, the following would specify screen 1 of display 0 on the 
+machine named ``dual-headed'':
+.LP
+.Ds
+dual-headed:0.1
+.De
+.LP
+The
+.PN XOpenDisplay
+function returns a 
+.PN Display 
+structure that serves as the
+connection to the X server and that contains all the information
+about that X server.
+.PN XOpenDisplay
+connects your application to the X server through TCP 
+or DECnet communications protocols,
+or through some local inter-process communication protocol.
+.IN "Protocol" "TCP"
+.IN "Protocol" "DECnet"
+If the protocol is specified as "tcp", "inet", or "inet6", or
+if no protocol is specified and the hostname is a host machine name and a single colon (:)
+separates the hostname and display number,
+.PN XOpenDisplay
+connects using TCP streams.  (If the protocol is specified as "inet", TCP over
+IPv4 is used.  If the protocol is specified as "inet6", TCP over IPv6 is used.
+Otherwise, the implementation determines which IP version is used.)
+If the hostname and protocol are both not specified,
+Xlib uses whatever it believes is the fastest transport.
+If the hostname is a host machine name and a double colon (::)
+separates the hostname and display number,
+.PN XOpenDisplay
+connects using DECnet.
+A single X server can support any or all of these transport mechanisms
+simultaneously.
+A particular Xlib implementation can support many more of these transport
+mechanisms.
+.LP
+.IN "Display"
+If successful, 
+.PN XOpenDisplay 
+returns a pointer to a 
+.PN Display 
+structure,
+which is defined in 
+.hN X11/Xlib.h .
+If 
+.PN XOpenDisplay 
+does not succeed, it returns NULL.
+After a successful call to
+.PN XOpenDisplay ,
+all of the screens in the display can be used by the client.
+The screen number specified in the display_name argument is returned 
+by the 
+.PN DefaultScreen
+macro (or the
+.PN XDefaultScreen
+function).
+You can access elements of the
+.PN Display
+and
+.PN Screen
+structures only by using the information macros or functions.
+For information about using macros and functions to obtain information from 
+the
+.PN Display 
+structure,
+see section 2.2.1.
+.LP
+X servers may implement various types of access control mechanisms
+(see section 9.8).
+.NH 2
+Obtaining Information about the Display, Image Formats, or Screens
+.XS
+\*(SN Obtaining Information about the Display, Image Formats, or Screens
+.XE
+.LP
+The Xlib library provides a number of useful macros 
+and corresponding functions that return data from the 
+.PN Display 
+structure.
+The macros are used for C programming, 
+and their corresponding function equivalents are for other language bindings.
+This section discusses the:
+.IP \(bu 5
+Display macros
+.IP \(bu 5
+Image format functions and macros
+.IP \(bu 5
+Screen information macros
+.LP
+.IN "Display" "data structure" 
+All other members of the 
+.PN Display 
+structure (that is, those for which no macros are defined) are private to Xlib 
+and must not be used.
+Applications must never directly modify or inspect these private members of the 
+.PN Display 
+structure.
+.NT Note
+The
+.PN XDisplayWidth ,
+.PN XDisplayHeight ,
+.PN XDisplayCells ,
+.PN XDisplayPlanes ,
+.PN XDisplayWidthMM ,
+and
+.PN XDisplayHeightMM
+functions in the next sections are misnamed.
+These functions really should be named Screen\fIwhatever\fP 
+and XScreen\fIwhatever\fP, not Display\fIwhatever\fP or XDisplay\fIwhatever\fP.
+Our apologies for the resulting confusion.
+.NE
+.NH 3
+Display Macros 
+.XS
+\*(SN Display Macros
+.XE
+.LP
+Applications should not directly modify any part of the
+.PN Display
+and
+.PN Screen
+structures.
+The members should be considered read-only,
+although they may change as the result of other operations on the display.
+.LP 
+The following lists the C language macros,
+their corresponding function equivalents that are for other language bindings,
+and what data both can return.
+.LP
+.sp
+.sM
+.FD 0
+AllPlanes
+.sp
+unsigned long XAllPlanes(\^) 
+.FN
+.LP
+.eM
+.IN "AllPlanes" "" "@DEF@"
+.IN "XAllPlanes" "" "@DEF@"
+Both return a value with all bits set to 1 suitable for use in a plane argument to
+a procedure.
+.LP
+.sp
+Both 
+.PN BlackPixel 
+and 
+.PN WhitePixel 
+can be used in implementing a monochrome application.
+These pixel values are for permanently allocated entries in the default
+colormap.
+The actual RGB (red, green, and blue) values are settable on some screens 
+and, in any case, may not actually be black or white.
+The names are intended to convey the expected relative intensity of the colors.
+.sM
+.FD 0
+BlackPixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.sp
+unsigned long XBlackPixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen_number\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.LP
+.eM
+.IN "BlackPixel" "" "@DEF@"
+.IN "XBlackPixel" "" "@DEF@"
+Both return the black pixel value for the specified screen.
+.LP
+.sp
+.sM
+.FD 0
+WhitePixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.sp
+unsigned long XWhitePixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen_number\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.LP
+.eM
+.IN "WhitePixel" "" "@DEF@"
+.IN "XWhitePixel" "" "@DEF@"
+Both return the white pixel value for the specified screen. 
+.LP
+.sp
+.sM
+.FD 0
+ConnectionNumber\^(\^\fIdisplay\fP\^)
+.sp
+int XConnectionNumber\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.IN "ConnectionNumber" "" "@DEF@"
+.IN "XConnectionNumber" "" "@DEF@"
+Both return a connection number for the specified display.
+On a POSIX-conformant system,
+this is the file descriptor of the connection.
+.LP
+.sp
+.sM
+.FD 0
+DefaultColormap\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.sp
+Colormap XDefaultColormap\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen_number\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.LP
+.eM
+.IN "DefaultColormap" "" "@DEF@"
+.IN "XDefaultColormap" "" "@DEF@"
+Both return the default colormap ID for allocation on the specified screen.
+Most routine allocations of color should be made out of this colormap.
+.LP
+.sp
+.sM
+.FD 0
+DefaultDepth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.sp
+int XDefaultDepth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen_number\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.LP
+.eM
+.IN "DefaultDepth" "" "@DEF@"
+.IN "XDefaultDepth" "" "@DEF@"
+Both return the depth (number of planes) of the default root window for the
+specified screen.
+Other depths may also be supported on this screen (see
+.PN XMatchVisualInfo ).
+.LP
+.sp
+.IN "XListDepths" "" "@DEF@"
+To determine the number of depths that are available on a given screen, use
+.PN XListDepths .
+.sM
+.FD 0
+int *XListDepths\^(\^\fIdisplay\fP, \fIscreen_number\fP, \fIcount_return\fP\^)
+.br
+      Display *\fIdisplay\fP;
+.br
+      int \fIscreen_number\fP;
+.br
+      int *\fIcount_return\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.ds Cn depths
+.IP \fIcount_return\fP 1i
+Returns the number of \*(Cn.
+.LP
+.eM
+The
+.PN XListDepths
+function returns the array of depths 
+that are available on the specified screen.
+If the specified screen_number is valid and sufficient memory for the array
+can be allocated,
+.PN XListDepths
+sets count_return to the number of available depths.
+Otherwise, it does not set count_return and returns NULL.
+To release the memory allocated for the array of depths, use
+.PN XFree .
+.LP
+.sp
+.sM
+.FD 0
+DefaultGC\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.sp
+GC XDefaultGC\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen_number\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.LP
+.eM
+.IN "DefaultGC" "" "@DEF@"
+.IN "XDefaultGC" "" "@DEF@"
+Both return the default graphics context for the root window of the 
+specified screen.
+This GC is created for the convenience of simple applications
+and contains the default GC components with the foreground and
+background pixel values initialized to the black and white
+pixels for the screen, respectively.
+You can modify its contents freely because it is not used in any Xlib
+function.
+This GC should never be freed.
+.LP
+.sp
+.sM
+.FD 0
+DefaultRootWindow\^(\^\fIdisplay\fP\^)
+.sp
+Window XDefaultRootWindow\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.IN "DefaultRootWindow" "" "@DEF@"
+.IN "XDefaultRootWindow" "" "@DEF@"
+Both return the root window for the default screen.
+.LP
+.sp
+.sM
+.FD 0
+DefaultScreenOfDisplay\^(\^\fIdisplay\fP\^)
+.sp
+Screen *XDefaultScreenOfDisplay\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.IN "DefaultScreenOfDisplay" "" "@DEF@"
+.IN "XDefaultScreenOfDisplay" "" "@DEF@"
+Both return a pointer to the default screen.
+.LP
+.sp
+.sM
+.FD 0
+ScreenOfDisplay\^(\^\fIdisplay\fP, \fIscreen_number\fP\^)
+.sp
+Screen *XScreenOfDisplay\^(\^\fIdisplay\fP, \fIscreen_number\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen_number\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.LP
+.eM
+.IN "ScreenOfDisplay" "" "@DEF@"
+.IN "XScreenOfDisplay" "" "@DEF@"
+Both return a pointer to the indicated screen.
+.LP
+.sp
+.sM
+.FD 0
+DefaultScreen\^(\^\fIdisplay\fP\^)
+.sp
+int XDefaultScreen\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.IN "DefaultScreen" "" "@DEF@"
+.IN "XDefaultScreen" "" "@DEF@"
+Both return the default screen number referenced by the 
+.PN XOpenDisplay
+function. 
+This macro or function should be used to retrieve the screen number 
+in applications that will use only a single screen.
+.LP
+.sp
+.sM
+.FD 0
+DefaultVisual\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.sp
+Visual *XDefaultVisual\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen_number\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.LP
+.eM
+.IN "DefaultVisual" "" "@DEF@"
+.IN "XDefaultVisual" "" "@DEF@"
+Both return the default visual type for the specified screen.
+For further information about visual types,
+see section 3.1.
+.LP
+.sp
+.sM
+.FD 0
+DisplayCells\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.sp
+int XDisplayCells\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen_number\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.LP
+.eM
+.IN "DisplayCells" "" "@DEF@"
+.IN "XDisplayCells" "" "@DEF@"
+Both return the number of entries in the default colormap.
+.LP
+.sp
+.sM
+.FD 0
+DisplayPlanes\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.sp
+int XDisplayPlanes\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen_number\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.LP
+.eM
+.IN "DisplayPlanes" "" "@DEF@"
+.IN "XDisplayPlanes" "" "@DEF@"
+Both return the depth of the root window of the specified screen.
+For an explanation of depth,
+see the glossary.
+.LP
+.sp
+.sM
+.FD 0
+DisplayString\^(\^\fIdisplay\fP\^)
+.sp
+char *XDisplayString\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.IN "DisplayString" "" "@DEF@"
+.IN "XDisplayString" "" "@DEF@"
+Both return the string that was passed to 
+.PN XOpenDisplay
+when the current display was opened. 
+On POSIX-conformant systems, 
+if the passed string was NULL, these return the value of
+the DISPLAY environment variable when the current display was opened.
+.IN "POSIX System Call" "fork"
+These are useful to applications that invoke the 
+.PN fork
+system call and want to open a new connection to the same display from the 
+child process as well as for printing error messages.
+.LP
+.sp
+.sM
+.FD 0
+long XExtendedMaxRequestSize(\^\fIdisplay\fP\^)
+	Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.IN "XExtendedMaxRequestSize" "" "@DEF@"
+The
+.PN XExtendedMaxRequestSize
+function returns zero if the specified display does not support an
+extended-length protocol encoding; otherwise,
+it returns the maximum request size (in 4-byte units) supported
+by the server using the extended-length encoding.
+The Xlib functions
+.PN XDrawLines ,
+.PN XDrawArcs ,
+.PN XFillPolygon ,
+.PN XChangeProperty ,
+.PN XSetClipRectangles ,
+and
+.PN XSetRegion
+will use the extended-length encoding as necessary, if supported
+by the server.  Use of the extended-length encoding in other Xlib
+functions (for example,
+.PN XDrawPoints ,
+.PN XDrawRectangles ,
+.PN XDrawSegments ,
+.PN XFillArcs ,
+.PN XFillRectangles ,
+.PN XPutImage )
+is permitted but not required; an Xlib implementation may choose to
+split the data across multiple smaller requests instead.
+.LP
+.sp
+.sM
+.FD 0
+long XMaxRequestSize(\^\fIdisplay\fP\^)
+	Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.IN "XMaxRequestSize" "" "@DEF@"
+The
+.PN XMaxRequestSize
+function returns the maximum request size (in 4-byte units) supported
+by the server without using an extended-length protocol encoding.
+Single protocol requests to the server can be no larger than this size
+unless an extended-length protocol encoding is supported by the server.
+The protocol guarantees the size to be no smaller than 4096 units
+(16384 bytes).
+Xlib automatically breaks data up into multiple protocol requests
+as necessary for the following functions:
+.PN XDrawPoints ,
+.PN XDrawRectangles ,
+.PN XDrawSegments ,
+.PN XFillArcs ,
+.PN XFillRectangles ,
+and 
+.PN XPutImage .
+.LP
+.sp
+.sM
+.FD 0
+LastKnownRequestProcessed\^(\^\fIdisplay\fP\^)
+.sp
+unsigned long XLastKnownRequestProcessed\^(\^\fIdisplay\fP\^)
+.br
+     Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.IN "LastKnownRequestProcessed" "" "@DEF@"
+.IN "XLastKnownRequestProcessed" "" "@DEF@"
+Both extract the full serial number of the last request known by Xlib
+to have been processed by the X server.
+Xlib automatically sets this number when replies, events, and errors
+are received.
+.LP
+.sp
+.sM
+.FD 0
+NextRequest\^(\^\fIdisplay\fP\^)
+.sp
+unsigned long XNextRequest\^(\^\fIdisplay\fP\^)
+.br
+     Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.IN "NextRequest" "" "@DEF@"
+.IN "XNextRequest" "" "@DEF@"
+Both extract the full serial number that is to be used for the next
+request.
+Serial numbers are maintained separately for each display connection.
+.LP
+.sp
+.sM
+.FD 0
+ProtocolVersion\^(\^\fIdisplay\fP\^)
+.sp
+int XProtocolVersion\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.IN "ProtocolVersion" "" "@DEF@"
+.IN "XProtocolVersion" "" "@DEF@"
+Both return the major version number (11) of the X protocol associated with 
+the connected display.
+.LP
+.sp
+.sM
+.FD 0
+ProtocolRevision\^(\^\fIdisplay\fP\^)
+.sp
+int XProtocolRevision\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.IN "ProtocolRevision" "" "@DEF@"
+.IN "XProtocolRevision" "" "@DEF@"
+Both return the minor protocol revision number of the X server.
+.LP
+.sp
+.sM
+.FD 0
+QLength\^(\^\fIdisplay\fP\^)
+.sp
+int XQLength\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.IN "QLength" "" "@DEF@"
+.IN "XQLength" "" "@DEF@"
+Both return the length of the event queue for the connected display.
+Note that there may be more events that have not been read into
+the queue yet (see
+.PN XEventsQueued ).
+.LP
+.sp
+.sM
+.FD 0
+RootWindow\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.sp
+Window XRootWindow\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen_number\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.LP
+.eM
+.IN "Window" "RootWindow"
+.IN "RootWindow" "" "@DEF@"
+.IN "Window" "XRootWindow"
+.IN "XRootWindow" "" "@DEF@"
+Both return the root window.
+These are useful with functions that need a drawable of a particular screen
+and for creating top-level windows.
+.LP
+.sp
+.sM
+.FD 0
+ScreenCount\^(\^\fIdisplay\fP\^)
+.sp
+int XScreenCount\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.IN "ScreenCount" "" "@DEF@"
+.IN "XScreenCount" "" "@DEF@"
+Both return the number of available screens.
+.LP
+.sp
+.sM
+.FD 0
+ServerVendor\^(\^\fIdisplay\fP\^)
+.sp
+char *XServerVendor\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.IN "ServerVendor" "" "@DEF@"
+.IN "XServerVendor" "" "@DEF@"
+Both return a pointer to a null-terminated string that provides
+some identification of the owner of the X server implementation.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the string is in the Host Portable Character Encoding.
+Otherwise, the contents of the string are implementation-dependent.
+.LP
+.sp
+.sM
+.FD 0
+VendorRelease\^(\^\fIdisplay\fP\^)
+.sp
+int XVendorRelease\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.IN "VendorRelease" "" "@DEF@"
+.IN "XVendorRelease" "" "@DEF@"
+Both return a number related to a vendor's release of the X server.
+.NH 3
+Image Format Functions and Macros
+.XS
+\*(SN Image Format Functions and Macros
+.XE
+.LP
+Applications are required to present data to the X server
+in a format that the server demands.
+To help simplify applications,
+most of the work required to convert the data is provided by Xlib
+(see sections 8.7 and 16.8).
+.LP
+The
+.PN XPixmapFormatValues
+structure provides an interface to the pixmap format information
+that is returned at the time of a connection setup.
+It contains:
+.LP
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int depth;
+	int bits_per_pixel;
+	int scanline_pad;
+} XPixmapFormatValues;
+.De
+.LP
+.eM
+.sp
+To obtain the pixmap format information for a given display, use
+.PN XListPixmapFormats .
+.IN "XListPixmapFormats" "" "@DEF@"
+.sM
+.FD 0
+XPixmapFormatValues *XListPixmapFormats\^(\^\fIdisplay\fP, \fIcount_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int *\fIcount_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Cn pixmap formats that are supported by the display
+.IP \fIcount_return\fP 1i
+Returns the number of \*(Cn.
+.LP
+.eM
+The
+.PN XListPixmapFormats
+function returns an array of
+.PN XPixmapFormatValues
+structures that describe the types of Z format images supported
+by the specified display.
+If insufficient memory is available,
+.PN XListPixmapFormats
+returns NULL.
+To free the allocated storage for the
+.PN XPixmapFormatValues
+structures, use
+.PN XFree .
+.LP 
+The following lists the C language macros,
+their corresponding function equivalents that are for other language bindings,
+and what data they both return for the specified server and screen.
+These are often used by toolkits as well as by simple applications.
+.LP
+.sp
+.sM
+.FD 0
+ImageByteOrder\^(\^\fIdisplay\fP\^)
+.sp
+int XImageByteOrder\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.IN "ImageByteOrder" "" "@DEF@"
+.IN "XImageByteOrder" "" "@DEF@"
+Both specify the required byte order for images for each scanline unit in 
+XY format (bitmap) or for each pixel value in 
+Z format.
+The macro or function can return either
+.PN LSBFirst 
+or 
+.PN MSBFirst .
+.LP
+.sp
+.sM
+.FD 0
+BitmapUnit\^(\^\fIdisplay\fP\^)
+.sp
+int XBitmapUnit\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.IN "BitmapUnit" "" "@DEF@"
+.IN "XBitmapUnit" "" "@DEF@"
+Both return the size of a bitmap's scanline unit in bits.
+The scanline is calculated in multiples of this value.
+.LP
+.sp
+.sM
+.FD 0
+BitmapBitOrder\^(\^\fIdisplay\fP\^)
+.sp
+int XBitmapBitOrder\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.IN "BitmapBitOrder" "" "@DEF@"
+.IN "XBitmapBitOrder" "" "@DEF@"
+Within each bitmap unit, the left-most bit in the bitmap as displayed
+on the screen is either the least significant or most significant bit in the
+unit.
+This macro or function can return 
+.PN LSBFirst
+or 
+.PN MSBFirst .
+.LP
+.sp
+.sM
+.FD 0
+BitmapPad\^(\^\fIdisplay\fP\^)
+.sp
+int XBitmapPad\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.IN "BitmapPad" "" "@DEF@"
+.IN "XBitmapPad" "" "@DEF@"
+Each scanline must be padded to a multiple of bits returned
+by this macro or function.
+.LP
+.sp
+.sM
+.FD 0
+DisplayHeight\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.sp
+int XDisplayHeight\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen_number\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.LP
+.eM
+.IN "DisplayHeight" "" "@DEF@"
+.IN "XDisplayHeight" "" "@DEF@"
+Both return an integer that describes the height of the screen
+in pixels.
+.LP
+.sp
+.sM
+.FD 0
+DisplayHeightMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.sp
+int XDisplayHeightMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen_number\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.LP
+.eM
+.IN "DisplayHeightMM" "" "@DEF@"
+.IN "XDisplayHeightMM" "" "@DEF@"
+Both return the height of the specified screen in millimeters.
+.LP
+.sp
+.sM
+.FD 0
+DisplayWidth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.sp
+int XDisplayWidth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen_number\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.LP
+.eM
+.IN "DisplayWidth" "" "@DEF@"
+.IN "XDisplayWidth" "" "@DEF@"
+Both return the width of the screen in pixels.
+.LP
+.sp
+.sM
+.FD 0
+DisplayWidthMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.sp
+int XDisplayWidthMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen_number\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.LP
+.eM
+.IN "DisplayWidthMM" "" "@DEF@"
+.IN "XDisplayWidthMM" "" "@DEF@"
+Both return the width of the specified screen in millimeters.
+.NH 3
+Screen Information Macros
+.XS
+\*(SN Screen Information Macros
+.XE
+.LP
+The following lists the C language macros,
+their corresponding function equivalents that are for other language bindings,
+and what data they both can return.
+These macros or functions all take a pointer to the appropriate screen
+structure.
+.LP
+.sp
+.sM
+.FD 0
+BlackPixelOfScreen\^(\^\fIscreen\fP\^)
+.sp
+unsigned long XBlackPixelOfScreen\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+.IN "BlackPixelOfScreen" "" "@DEF@"
+.IN "XBlackPixelOfScreen" "" "@DEF@"
+Both return the black pixel value of the specified screen.
+.LP
+.sp
+.sM
+.FD 0
+WhitePixelOfScreen\^(\^\fIscreen\fP\^)
+.sp
+unsigned long XWhitePixelOfScreen\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+.IN "WhitePixelOfScreen" "" "@DEF@"
+.IN "XWhitePixelOfScreen" "" "@DEF@"
+Both return the white pixel value of the specified screen.
+.LP
+.sp
+.sM
+.FD 0
+CellsOfScreen\^(\^\fIscreen\fP\^)
+.sp
+int XCellsOfScreen\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+.IN "CellsOfScreen" "" "@DEF@"
+.IN "XCellsOfScreen" "" "@DEF@"
+Both return the number of colormap cells in the default colormap 
+of the specified screen.
+.LP
+.sp
+.sM
+.FD 0
+DefaultColormapOfScreen\^(\^\fIscreen\fP\^)
+.sp
+Colormap XDefaultColormapOfScreen\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+.IN "DefaultColormapOfScreen" "" "@DEF@"
+.IN "XDefaultColormapOfScreen" "" "@DEF@"
+Both return the default colormap of the specified screen.
+.LP
+.sp
+.sM
+.FD 0
+DefaultDepthOfScreen\^(\^\fIscreen\fP\^)
+.sp 
+int XDefaultDepthOfScreen\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+.IN "DefaultDepthOfScreen" "" "@DEF@"
+.IN "XDefaultDepthOfScreen" "" "@DEF@"
+Both return the depth of the root window.
+.LP
+.sp
+.sM
+.FD 0
+DefaultGCOfScreen\^(\^\fIscreen\fP\^)
+.sp
+GC XDefaultGCOfScreen\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+.IN "DefaultGCOfScreen" "" "@DEF@"
+.IN "XDefaultGCOfScreen" "" "@DEF@"
+Both return a default graphics context (GC) of the specified screen,
+which has the same depth as the root window of the screen.
+The GC must never be freed.
+.LP
+.sp
+.sM
+.FD 0
+DefaultVisualOfScreen\^(\^\fIscreen\fP\^)
+.sp
+Visual *XDefaultVisualOfScreen\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+.IN "DefaultVisualOfScreen" "" "@DEF@"
+.IN "XDefaultVisualOfScreen" "" "@DEF@"
+Both return the default visual of the specified screen.
+For information on visual types,
+see section 3.1.
+.LP
+.sp
+.sM
+.FD 0
+DoesBackingStore\^(\^\fIscreen\fP\^)
+.sp
+int XDoesBackingStore\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+.IN "DoesBackingStore" "" "@DEF@"
+.IN "XDoesBackingStore" "" "@DEF@"
+Both return a value indicating whether the screen supports backing
+stores.
+The value returned can be one of 
+.PN WhenMapped ,
+.PN NotUseful ,
+or
+.PN Always 
+(see section 3.2.4).
+.LP
+.sp
+.sM
+.FD 0
+DoesSaveUnders\^(\^\fIscreen\fP\^)
+.sp
+Bool XDoesSaveUnders\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+.IN "DoesSaveUnders" "" "@DEF@"
+.IN "XDoesSaveUnders" "" "@DEF@"
+Both return a Boolean value indicating whether the
+screen supports save unders.
+If
+.PN True ,
+the screen supports save unders.
+If
+.PN False ,
+the screen does not support save unders (see section 3.2.5).
+.LP
+.sp
+.sM
+.FD 0
+DisplayOfScreen\^(\^\fIscreen\fP\^)
+.sp
+Display *XDisplayOfScreen\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+.IN "DisplayOfScreen" "" "@DEF@"
+.IN "XDisplayOfScreen" "" "@DEF@"
+Both return the display of the specified screen.
+.LP
+.sp
+.sM
+.IN "XScreenNumberOfScreen" "" "@DEF@"
+.FD 0
+int XScreenNumberOfScreen\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+The
+.PN XScreenNumberOfScreen
+function returns the screen index number of the specified screen.
+.LP
+.sp
+.sM
+.FD 0
+EventMaskOfScreen\^(\^\fIscreen\fP\^)
+.sp
+long XEventMaskOfScreen\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+.IN "EventMaskOfScreen" "" "@DEF@"
+.IN "XEventMaskOfScreen" "" "@DEF@"
+Both return the event mask of the root window for the specified screen
+at connection setup time.
+.LP
+.sp
+.sM
+.FD 0
+WidthOfScreen\^(\^\fIscreen\fP\^)
+.sp
+int XWidthOfScreen\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+.IN "WidthOfScreen" "" "@DEF@"
+.IN "XWidthOfScreen" "" "@DEF@"
+Both return the width of the specified screen in pixels.
+.LP
+.sp
+.sM
+.FD 0
+HeightOfScreen\^(\^\fIscreen\fP\^)
+.sp
+int XHeightOfScreen\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+.IN "HeightOfScreen" "" "@DEF@"
+.IN "XHeightOfScreen" "" "@DEF@"
+Both return the height of the specified screen in pixels.
+.LP
+.sp
+.sM
+.FD 0
+WidthMMOfScreen\^(\^\fIscreen\fP\^)
+.sp
+int XWidthMMOfScreen\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+.IN "WidthMMOfScreen" "" "@DEF@"
+.IN "XWidthMMOfScreen" "" "@DEF@"
+Both return the width of the specified screen in millimeters.
+.LP
+.sp
+.sM
+.FD 0
+HeightMMOfScreen\^(\^\fIscreen\fP\^)
+.sp
+int XHeightMMOfScreen\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+.IN "HeightMMOfScreen" "" "@DEF@"
+.IN "XHeightMMOfScreen" "" "@DEF@"
+Both return the height of the specified screen in millimeters.
+.LP
+.sp
+.sM
+.FD 0
+MaxCmapsOfScreen\^(\^\fIscreen\fP\^)
+.sp
+int XMaxCmapsOfScreen\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+.IN "MaxCmapsOfScreen" "" "@DEF@"
+.IN "XMaxCmapsOfScreen" "" "@DEF@"
+Both return the maximum number of installed colormaps supported 
+by the specified screen (see section 9.3).
+.LP
+.sp
+.sM
+.FD 0
+MinCmapsOfScreen\^(\^\fIscreen\fP\^)
+.sp
+int XMinCmapsOfScreen\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+.IN "MinCmapsOfScreen" "" "@DEF@"
+.IN "XMinCmapsOfScreen" "" "@DEF@"
+Both return the minimum number of installed colormaps supported 
+by the specified screen (see section 9.3).
+.LP
+.sp
+.sM
+.FD 0
+PlanesOfScreen\^(\^\fIscreen\fP\^)
+.sp
+int XPlanesOfScreen\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+.IN "PlanesOfScreen" "" "@DEF@"
+.IN "XPlanesOfScreen" "" "@DEF@"
+Both return the depth of the root window.
+.LP
+.sp
+.sM
+.FD 0
+RootWindowOfScreen\^(\^\fIscreen\fP\^)
+.sp
+Window XRootWindowOfScreen\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the appropriate 
+.PN Screen
+structure.
+.LP
+.eM
+.IN "RootWindowOfScreen" "" "@DEF@"
+.IN "XRootWindowOfScreen" "" "@DEF@"
+Both return the root window of the specified screen.
+.NH 2
+Generating a NoOperation Protocol Request
+.XS
+\*(SN Generating a NoOperation Protocol Request
+.XE
+.LP
+To execute a 
+.PN NoOperation 
+protocol request, use
+.PN XNoOp .
+.IN "XNoOp" "" "@DEF@"
+.sM
+.FD 0
+XNoOp\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+The
+.PN XNoOp
+function sends a 
+.PN NoOperation 
+protocol request to the X server,
+thereby exercising the connection.
+.NH 2
+Freeing Client-Created Data
+.XS
+\*(SN Freeing Client-Created Data
+.XE
+.LP
+To free in-memory data that was created by an Xlib function, use
+.PN XFree .
+.IN "XFree" "" "@DEF@"
+.sM
+.FD 0
+XFree\^(\^\fIdata\fP\^)
+.br
+     void *\fIdata\fP\^; 
+.FN
+.IP \fIdata\fP 1i
+Specifies the data that is to be freed.
+.LP
+.eM
+The
+.PN XFree
+function is a general-purpose Xlib routine that frees the specified data.
+You must use it to free any objects that were allocated by Xlib,
+unless an alternate function is explicitly specified for the object.
+A NULL pointer cannot be passed to this function.
+.NH 2
+Closing the Display
+.XS
+\*(SN Closing the Display
+.XE
+.LP
+To close a display or disconnect from the X server, use
+.PN XCloseDisplay .
+.IN "XCloseDisplay" "" "@DEF@"
+.LP
+.sM
+.FD 0
+XCloseDisplay\^(\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+The
+.PN XCloseDisplay
+function closes the connection to the X server for the display specified in the
+.PN Display
+structure and destroys all windows, resource IDs
+.Pn ( Window ,
+.PN Font ,
+.PN Pixmap ,
+.PN Colormap ,
+.PN Cursor ,
+and
+.PN GContext ),
+or other resources that the client has created
+on this display, unless the close-down mode of the resource has been changed
+(see
+.PN XSetCloseDownMode ).
+Therefore, these windows, resource IDs, and other resources should never be 
+referenced again or an error will be generated.
+Before exiting, you should call
+.PN XCloseDisplay
+explicitly so that any pending errors are reported as
+.PN XCloseDisplay
+performs a final
+.PN XSync
+operation.
+.IN "Resource IDs"
+.IN "XCloseDisplay"
+.LP
+.PN XCloseDisplay
+can generate a
+.PN BadGC
+error.
+.sp
+.LP
+Xlib provides a function to permit the resources owned by a client
+to survive after the client's connection is closed.
+To change a client's close-down mode, use
+.PN XSetCloseDownMode .
+.IN "XSetCloseDownMode" "" "@DEF@"
+.sM
+.FD 0
+XSetCloseDownMode\^(\^\fIdisplay\fP, \fIclose_mode\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIclose_mode\fP\^;	
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIclose_mode\fP 1i
+Specifies the client close-down mode.
+You can pass 
+.PN DestroyAll , 
+.PN RetainPermanent , 
+or
+.PN RetainTemporary . 
+.LP
+.eM
+The
+.PN XSetCloseDownMode
+defines what will happen to the client's resources at connection close.
+A connection starts in
+.PN DestroyAll
+mode.
+For information on what happens to the client's resources when the
+close_mode argument is
+.PN RetainPermanent
+or
+.PN RetainTemporary ,
+see section 2.6.
+.LP
+.PN XSetCloseDownMode
+can generate a
+.PN BadValue 
+error.
+.NH 2
+Using X Server Connection Close Operations 
+.XS
+\*(SN Using X Server Connection Close Operations
+.XE
+.LP
+When the X server's connection to a client is closed
+either by an explicit call to
+.PN XCloseDisplay
+or by a process that exits, the X server performs the following
+automatic operations:
+.IP \(bu 5
+It disowns all selections owned by the client
+(see 
+.PN XSetSelectionOwner ).
+.IP \(bu 5
+It performs an
+.PN XUngrabPointer
+and
+.PN XUngrabKeyboard 
+if the client has actively grabbed the pointer 
+or the keyboard.
+.IP \(bu 5
+It performs an
+.PN XUngrabServer 
+if the client has grabbed the server.
+.IP \(bu 5
+It releases all passive grabs made by the client.  
+.IP \(bu 5
+It marks all resources (including colormap entries) allocated 
+by the client either as permanent or temporary, 
+depending on whether the close-down mode is 
+.PN RetainPermanent
+or
+.PN RetainTemporary .
+However, this does not prevent other client applications from explicitly
+destroying the resources (see 
+.PN XSetCloseDownMode ).
+.LP
+When the close-down mode is
+.PN DestroyAll ,
+the X server destroys all of a client's resources as follows:
+.IP \(bu 5
+It examines each window in the client's save-set to determine if it is an inferior
+(subwindow) of a window created by the client.
+(The save-set is a list of other clients' windows
+that are referred to as save-set windows.)
+If so, the X server reparents the save-set window to the closest ancestor so
+that the save-set window is not an inferior of a window created by the client.
+The reparenting leaves unchanged the absolute coordinates (with respect to
+the root window) of the upper-left outer corner of the save-set
+window.
+.IP \(bu 5
+It performs a
+.PN MapWindow
+request on the save-set window if the save-set window is unmapped.
+The X server does this even if the save-set window was not an inferior of 
+a window created by the client.
+.IP \(bu 5
+It destroys all windows created by the client.
+.IP \(bu 5
+It performs the appropriate free request on each nonwindow resource created by
+the client in the server (for example, 
+.PN Font , 
+.PN Pixmap , 
+.PN Cursor , 
+.PN Colormap , 
+and 
+.PN GContext ).
+.IP \(bu 5
+It frees all colors and colormap entries allocated by a client application.
+.LP
+Additional processing occurs when the last connection to the X server closes.
+An X server goes through a cycle of having no connections and having some
+connections.
+When the last connection to the X server closes as a result of a connection
+closing with the close_mode of
+.PN DestroyAll ,
+the X server does the following: 
+.IP \(bu 5
+It resets its state as if it had just been
+started.  
+The X server begins by destroying all lingering resources from
+clients that have terminated in 
+.PN RetainPermanent
+or
+.PN RetainTemporary
+mode.
+.IP \(bu 5
+It deletes all but the predefined atom identifiers.
+.IP \(bu 5
+It deletes all properties on all root windows (see section 4.3).
+.IP \(bu 5
+It resets all device maps and attributes 
+(for example, key click, bell volume, and acceleration) 
+as well as the access control list.
+.IP \(bu 5
+It restores the standard root tiles and cursors.
+.IP \(bu 5
+It restores the default font path.
+.IP \(bu 5
+It restores the input focus to state
+.PN PointerRoot .
+.LP
+However, the X server does not reset if you close a connection with a close-down
+mode set to
+.PN RetainPermanent
+or
+.PN RetainTemporary .
+.NH 2
+Using Xlib with Threads
+.XS
+\*(SN Using Xlib with Threads
+.XE
+.LP
+On systems that have threads, support may be provided to permit
+multiple threads to use Xlib concurrently.
+.LP
+.sp
+To initialize support for concurrent threads, use
+.PN XInitThreads .
+.IN "XInitThreads" "" "@DEF@"
+.sM
+.FD 0
+Status XInitThreads\^(\|);
+.FN
+.LP
+.eM
+The
+.PN XInitThreads
+function initializes Xlib support for concurrent threads.
+This function must be the first Xlib function a
+multi-threaded program calls, and it must complete
+before any other Xlib call is made.
+This function returns a nonzero status if initialization was
+successful; otherwise, it returns zero.
+On systems that do not support threads, this function always returns zero.
+.LP
+It is only necessary to call this function if multiple threads
+might use Xlib concurrently.  If all calls to Xlib functions
+are protected by some other access mechanism (for example,
+a mutual exclusion lock in a toolkit or through explicit client
+programming), Xlib thread initialization is not required.
+It is recommended that single-threaded programs not call this function.
+
+.LP
+.sp
+To lock a display across several Xlib calls, use
+.PN XLockDisplay .
+.IN "XLockDisplay" "" "@DEF@"
+.sM
+.FD 0
+void XLockDisplay\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+The
+.PN XLockDisplay
+function locks out all other threads from using the specified display.
+Other threads attempting to use the display will block until
+the display is unlocked by this thread.
+Nested calls to
+.PN XLockDisplay
+work correctly; the display will not actually be unlocked until
+.PN XUnlockDisplay
+has been called the same number of times as
+.PN XLockDisplay .
+This function has no effect unless Xlib was successfully initialized
+for threads using
+.PN XInitThreads .
+.LP
+.sp
+To unlock a display, use
+.PN XUnlockDisplay .
+.IN "XUnlockDisplay" "" "@DEF@"
+.sM
+.FD 0
+void XUnlockDisplay\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+The
+.PN XUnlockDisplay
+function allows other threads to use the specified display again.
+Any threads that have blocked on the display are allowed to continue.
+Nested locking works correctly; if
+.PN XLockDisplay
+has been called multiple times by a thread, then
+.PN XUnlockDisplay
+must be called an equal number of times before the display is
+actually unlocked.
+This function has no effect unless Xlib was successfully initialized
+for threads using
+.PN XInitThreads .
+.NH 2
+Using Internal Connections
+.XS
+\*(SN Using Internal Connections
+.XE
+.LP
+In addition to the connection to the X server, an Xlib implementation
+may require connections to other kinds of servers (for example, to
+input method servers as described in chapter 13).  Toolkits and clients
+that use multiple displays, or that use displays in combination with
+other inputs, need to obtain these additional connections to correctly
+block until input is available and need to process that input
+when it is available.  Simple clients that use a single display and
+block for input in an Xlib event function do not need to use these
+facilities.
+.LP
+To track internal connections for a display, use
+.PN XAddConnectionWatch .
+.LP
+.IN "XWatchProc" "" "@DEF@"
+.IN "XAddConnectionWatch" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XConnectionWatchProc)\^(\^\fIdisplay\fP, \fIclient_data\fP, \fIfd\fP, \fIopening\fP, \fIwatch_data\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XPointer \fIclient_data\fP\^;
+.br
+      int \fIfd\fP\^;
+.br
+      Bool \fIopening\fP\^;
+.br
+      XPointer *\fIwatch_data\fP\^;
+.sp
+Status XAddConnectionWatch\^(\^\fIdisplay\fP, \fIprocedure\fP\^, \fIclient_data\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XWatchProc \fIprocedure\fP\^;
+.br
+      XPointer \fIclient_data\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIprocedure\fP 1i
+Specifies the procedure to be called.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data.
+.LP
+.eM
+The
+.PN XAddConnectionWatch
+function registers a procedure to be called each time Xlib opens or closes an
+internal connection for the specified display.  The procedure is passed the
+display, the specified client_data, the file descriptor for the connection,
+a Boolean indicating whether the connection is being opened or closed, and a
+pointer to a location for private watch data.  If opening is
+.PN True ,
+the procedure can store a pointer to private data in the location pointed
+to by watch_data;
+when the procedure is later called for this same connection and opening is
+.PN False ,
+the location pointed to by watch_data will hold this same private data pointer.
+.LP
+This function can be called at any time after a display is opened.
+If internal connections already exist, the registered procedure will
+immediately be called for each of them, before
+.PN XAddConnectionWatch
+returns.
+.PN XAddConnectionWatch
+returns a nonzero status if the procedure is successfully registered;
+otherwise, it returns zero.
+.LP
+The registered procedure should not call any Xlib functions.
+If the procedure directly or indirectly causes the state of internal
+connections or watch procedures to change, the result is not defined.
+If Xlib has been initialized for threads, the procedure is called with
+the display locked and the result of a call by the procedure to any
+Xlib function that locks the display is not defined unless the executing
+thread has externally locked the display using
+.PN XLockDisplay .
+.LP
+.sp
+To stop tracking internal connections for a display, use
+.PN XRemoveConnectionWatch .
+.IN "XRemoveConnectionWatch" "" "@DEF@"
+.sM
+.FD 0
+Status XRemoveConnectionWatch\^(\^\fIdisplay\fP, \fIprocedure\fP\^, \fIclient_data\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XWatchProc \fIprocedure\fP\^;
+.br
+      XPointer \fIclient_data\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIprocedure\fP 1i
+Specifies the procedure to be called.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data.
+.LP
+.eM
+The
+.PN XRemoveConnectionWatch
+function removes a previously registered connection watch procedure.
+The client_data must match the client_data used when the procedure
+was initially registered.
+
+.LP
+.sp
+To process input on an internal connection, use
+.PN XProcessInternalConnection .
+.IN "XProcessInternalConnection" "" "@DEF@"
+.sM
+.FD 0
+void XProcessInternalConnection\^(\^\fIdisplay\fP, \fIfd\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIfd\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIfd\fP 1i
+Specifies the file descriptor.
+.LP
+.eM
+The
+.PN XProcessInternalConnection
+function processes input available on an internal connection.
+This function should be called for an internal connection only
+after an operating system facility (for example,
+.PN select
+or
+.PN poll )
+has indicated that input is available; otherwise,
+the effect is not defined.
+.LP
+.sp
+To obtain all of the current internal connections for a display, use
+.PN XInternalConnectionNumbers .
+.IN "XInternalConnectionNumbers" "" "@DEF@"
+.sM
+.FD 0
+Status XInternalConnectionNumbers\^(\^\fIdisplay\fP, \fIfd_return\fP\^, \fIcount_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int **\fIfd_return\fP\^;
+.br
+      int *\fIcount_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIfd_return\fP 1i
+Returns the file descriptors.
+.ds Cn file descriptors
+.IP \fIcount_return\fP 1i
+Returns the number of \*(Cn.
+.LP
+.eM
+The
+.PN XInternalConnectionNumbers
+function returns a list of the file descriptors for all internal
+connections currently open for the specified display.
+When the allocated list is no longer needed,
+free it by using
+.PN XFree .
+This functions returns a nonzero status if the list is successfully allocated;
+otherwise, it returns zero.
+.LP
+.bp
diff --git a/specs/libX11/CH03 b/specs/libX11/CH03
new file mode 100644
index 00000000..f7eb2d4c
--- /dev/null
+++ b/specs/libX11/CH03
@@ -0,0 +1,3121 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 3\fP\s-1
+
+\s+1\fBWindow Functions\fP\s-1
+.sp 2
+.nr H1 3
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.na
+.LP
+.XS
+Chapter 3: Window Functions
+.XE
+In the X Window System, 
+a window is a rectangular area on the screen that lets you
+view graphic output.
+Client applications
+can display overlapping and nested windows on one or more
+screens that are driven by X servers on one or more machines.
+Clients who want to create windows must first 
+connect their program to the X server
+by calling 
+.PN XOpenDisplay .
+This chapter begins with a discussion of 
+visual types and window attributes.
+The chapter continues with a discussion of the Xlib functions you can use to:
+.IP \(bu 5
+Create windows 
+.IP \(bu 5
+Destroy windows
+.IP \(bu 5
+Map windows
+.IP \(bu 5
+Unmap windows
+.IP \(bu 5
+Configure windows
+.IP \(bu 5
+Change window stacking order
+.IP \(bu 5
+Change window attributes
+.LP
+This chapter also identifies the window actions that may generate events.
+.LP
+Note that it is vital that your application conform to the
+established conventions for communicating with window managers
+for it to work well with the various window managers in use (see section 14.1).
+Toolkits generally adhere to these conventions for you,
+relieving you of the burden.
+Toolkits also often supersede many functions in this chapter
+with versions of their own.
+For more information,
+refer to the documentation for the toolkit that you are using.
+.NH 2
+Visual Types
+.XS
+\*(SN Visual Types
+.XE
+.LP
+.IN "Visual Type" "" "@DEF@"
+On some display hardware, 
+it may be possible to deal with color resources in more than one way.
+For example, you may be able to deal with a screen of either 12-bit depth
+with arbitrary mapping of pixel to color (pseudo-color) or 24-bit depth
+with 8 bits of the pixel dedicated to each of red, green, and blue.
+These different ways of dealing with the visual aspects of the screen
+are called visuals.
+For each screen of the display, there may be a list of valid visual types
+supported at different depths of the screen.
+Because default windows and visual types are defined for each screen,
+most simple applications need not deal with this complexity.
+Xlib provides macros and functions that return the default root window, 
+the default depth of the default root window, and the default visual type
+(see sections 2.2.1 and 16.7).
+.LP
+Xlib uses an opaque 
+.PN Visual 
+.IN "Visual" "" "@DEF@"
+structure that contains information about the possible color mapping.
+The visual utility functions (see section 16.7) use an
+.PN XVisualInfo
+structure to return this information to an application.
+The members of this structure pertinent to this discussion are class, red_mask,
+green_mask, blue_mask, bits_per_rgb, and colormap_size.
+The class member specifies one of the possible visual classes of the screen
+and can be 
+.IN "Visual Classes" "StaticGray"
+.IN "Visual Classes" "StaticColor"
+.IN "Visual Classes" "TrueColor"
+.IN "Visual Classes" "StaticColor"
+.IN "Visual Classes" "GrayScale"
+.IN "Visual Classes" "PseudoColor"
+.PN StaticGray ,
+.PN StaticColor ,
+.PN TrueColor ,
+.PN GrayScale ,
+.PN PseudoColor ,
+or
+.PN DirectColor .
+.LP
+The following concepts may serve to make the explanation of
+visual types clearer. 
+The screen can be color or grayscale,
+can have a colormap that is writable or read-only,
+and can also have a colormap whose indices are decomposed into separate 
+RGB pieces, provided one is not on a grayscale screen.
+This leads to the following diagram:
+.LP
+.DS
+.TS
+center;
+  c   c   s   c   s
+  c   c   c   c   c
+| c | c | c | c | c |.
+	Color	Gray-scale
+	R/O	R/W	R/O	R/W
+_
+Undecomposed	Static	Pseudo	Static	Gray
+Colormap	Color	Color	Gray	Scale
+_
+.T&
+| c | c | c |.
+Decomposed	True	Direct
+Colormap	Color	Color
+_	_	_
+.TE
+.DE
+.LP
+Conceptually, 
+as each pixel is read out of video memory for display on the screen,
+it goes through a look-up stage by indexing into a colormap.
+Colormaps can be manipulated arbitrarily on some hardware, 
+in limited ways on other hardware, and not at all on other hardware.  
+The visual types affect the colormap and 
+the RGB values in the following ways:
+.LP
+.IP \(bu 5
+For 
+.PN PseudoColor , 
+a pixel value indexes a colormap to produce
+independent RGB values, and the RGB values can be changed dynamically.
+.IP \(bu 5
+.PN GrayScale 
+is treated the same way as 
+.PN PseudoColor  
+except that the primary that drives the screen is undefined. 
+Thus, the client should always store the
+same value for red, green, and blue in the colormaps.  
+.IP \(bu 5
+For 
+.PN DirectColor ,
+a pixel value is decomposed into separate RGB subfields, and each
+subfield separately indexes the colormap for the corresponding value.
+The RGB values can be changed dynamically.  
+.IP \(bu 5
+.PN TrueColor
+is treated the same way as 
+.PN DirectColor 
+except that the colormap has predefined, read-only RGB values.
+These RGB values are server dependent but provide linear or near-linear
+ramps in each primary.  
+.IP \(bu 5
+.PN StaticColor
+is treated the same way as 
+.PN PseudoColor 
+except that the colormap has predefined, 
+read-only, server-dependent RGB values.
+.IP \(bu 5
+.PN StaticGray 
+is treated the same way as 
+.PN StaticColor 
+except that the RGB values are equal for any single pixel
+value, thus resulting in shades of gray.  
+.PN StaticGray 
+with a two-entry
+colormap can be thought of as monochrome.
+.LP
+The red_mask, green_mask, and blue_mask members are only defined for
+.PN DirectColor
+and 
+.PN TrueColor . 
+Each has one contiguous set of bits with no
+intersections.
+The bits_per_rgb member specifies the log base 2 of the
+number of distinct color values (individually) of red, green, and blue.
+Actual RGB values are unsigned 16-bit numbers.
+The colormap_size member defines the number of available colormap entries
+in a newly created colormap.  
+For 
+.PN DirectColor 
+and 
+.PN TrueColor , 
+this is the size of an individual pixel subfield.
+.sp
+.LP
+To obtain the visual ID from a 
+.PN Visual ,
+use
+.PN XVisualIDFromVisual .
+.IN "XVisualIDFromVisual" "" "@DEF@"
+.sM
+.FD 0
+VisualID XVisualIDFromVisual\^(\^\fIvisual\fP\^)
+.br
+       Visual *\^\fIvisual\fP\^;
+.FN
+.IP \fIvisual\fP 1i
+Specifies the visual type.
+.LP
+.eM
+The
+.PN XVisualIDFromVisual
+function returns the visual ID for the specified visual type.
+.NH 2
+Window Attributes
+.XS
+\*(SN Window Attributes
+.XE
+.LP
+.IN "Window"
+.IN "Window" "attributes"
+All 
+.PN InputOutput
+windows have a border width of zero or more pixels, an optional background, 
+an event suppression mask (which suppresses propagation of events from 
+children), and a property list (see section 4.3).
+The window border and background can be a solid color or a pattern, called
+a tile.
+All windows except the root have a parent and are clipped by their parent.
+If a window is stacked on top of another window, it obscures that other
+window for the purpose of input.
+If a window has a background (almost all do), it obscures the other
+window for purposes of output.
+Attempts to output to the obscured area do nothing, 
+and no input events (for example, pointer motion) are generated for the 
+obscured area.
+.LP
+Windows also have associated property lists (see section 4.3).
+.LP
+Both
+.PN InputOutput
+and
+.PN InputOnly
+windows have the following common attributes,
+which are the only attributes of an
+.PN InputOnly
+window:
+.IP \(bu 5
+win-gravity
+.IP \(bu 5
+event-mask
+.IP \(bu 5
+do-not-propagate-mask
+.IP \(bu 5
+override-redirect
+.IP \(bu 5
+cursor
+.LP
+If you specify any other attributes for an
+.PN InputOnly
+window,
+a
+.PN BadMatch
+error results.
+.LP
+.PN InputOnly
+windows are used for controlling input events in situations where
+.PN InputOutput
+windows are unnecessary.
+.PN InputOnly
+windows are invisible; can only be used to control such things as
+cursors, input event generation, and grabbing;
+and cannot be used in any graphics requests.
+Note that
+.PN InputOnly
+windows cannot have
+.PN InputOutput
+windows as inferiors.
+.LP
+Windows have borders of a programmable width and pattern
+as well as a background pattern or tile.
+.IN "Tile" "pixmaps"
+Pixel values can be used for solid colors.
+.IN "Resource IDs" "freeing"
+.IN "Freeing" "resources"
+The background and border pixmaps can be destroyed immediately after
+creating the window if no further explicit references to them
+are to be made.
+.IN "Tile" "mode" 
+The pattern can either be relative to the parent 
+or absolute.
+If
+.PN ParentRelative ,
+the parent's background is used.
+.LP
+When windows are first created, 
+they are not visible (not mapped) on the screen.
+Any output to a window that is not visible on the screen 
+and that does not have backing store will be discarded.
+.IN "Window" "mapping"
+An application may wish to create a window long before it is
+mapped to the screen.
+When a window is eventually mapped to the screen 
+(using
+.PN XMapWindow ),
+.IN "XMapWindow"
+the X server generates an 
+.PN Expose 
+event for the window if backing store has not been maintained.
+.LP
+A window manager can override your choice of size, 
+border width, and position for a top-level window.
+Your program must be prepared to use the actual size and position
+of the top window.
+It is not acceptable for a client application to resize itself
+unless in direct response to a human command to do so.
+Instead, either your program should use the space given to it,
+or if the space is too small for any useful work, your program
+might ask the user to resize the window.
+The border of your top-level window is considered fair game 
+for window managers.
+.LP
+To set an attribute of a window,
+set the appropriate member of the
+.PN XSetWindowAttributes
+structure and OR in the corresponding value bitmask in your subsequent calls to
+.PN XCreateWindow
+and
+.PN XChangeWindowAttributes ,
+or use one of the other convenience functions that set the appropriate 
+attribute.
+The symbols for the value mask bits and the
+.PN XSetWindowAttributes
+structure are:
+.sM
+.LP
+/* Window attribute value mask bits */
+.TS
+lw(.5i) lw(2.5i) lw(.8i).
+T{
+#define
+T}	T{
+.PN CWBackPixmap
+T}	T{
+(1L<<0)
+T}
+T{
+#define
+T}	T{
+.PN CWBackPixel
+T}	T{
+(1L<<1)
+T}
+T{
+#define
+T}	T{
+.PN CWBorderPixmap
+T}	T{
+(1L<<2)
+T}
+T{
+#define
+T}	T{
+.PN CWBorderPixel
+T}	T{
+(1L<<3)
+T}
+T{
+#define
+T}	T{
+.PN CWBitGravity
+T}	T{
+(1L<<4)
+T}
+T{
+#define
+T}	T{
+.PN CWWinGravity
+T}	T{
+(1L<<5)
+T}
+T{
+#define
+T}	T{
+.PN CWBackingStore
+T}	T{
+(1L<<6)
+T}
+T{
+#define
+T}	T{
+.PN CWBackingPlanes
+T}	T{
+(1L<<7)
+T}
+T{
+#define
+T}	T{
+.PN CWBackingPixel
+T}	T{
+(1L<<8)
+T}
+T{
+#define
+T}	T{
+.PN CWOverrideRedirect
+T}	T{
+(1L<<9)
+T}
+T{
+#define
+T}	T{
+.PN CWSaveUnder
+T}	T{
+(1L<<10)
+T}
+T{
+#define
+T}	T{
+.PN CWEventMask
+T}	T{
+(1L<<11)
+T}
+T{
+#define
+T}	T{
+.PN CWDontPropagate
+T}	T{
+(1L<<12)
+T}
+T{
+#define
+T}	T{
+.PN CWColormap
+T}	T{
+(1L<<13)
+T}
+T{
+#define
+T}	T{
+.PN CWCursor
+T}	T{
+(1L<<14)
+T}
+.TE
+.IN "XSetWindowAttributes" "" "@DEF@"
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+/* Values */
+
+typedef struct {
+	Pixmap background_pixmap;	/* background, None, or ParentRelative */
+	unsigned long background_pixel;	/* background pixel */
+	Pixmap border_pixmap;		/* border of the window or CopyFromParent */
+	unsigned long border_pixel;	/* border pixel value */
+	int bit_gravity;	/* one of bit gravity values */
+	int win_gravity;	/* one of the window gravity values */
+	int backing_store;	/* NotUseful, WhenMapped, Always */
+	unsigned long backing_planes;	/* planes to be preserved if possible */
+	unsigned long backing_pixel;	/* value to use in restoring planes */
+	Bool save_under;	/* should bits under be saved? (popups) */
+	long event_mask;	/* set of events that should be saved */
+	long do_not_propagate_mask;	/* set of events that should not propagate */
+	Bool override_redirect;	/* boolean value for override_redirect */
+	Colormap colormap;	/* color map to be associated with window */
+	Cursor cursor;		/* cursor to be displayed (or None) */
+} XSetWindowAttributes;
+.De
+.LP
+.eM
+The following lists the defaults for each window attribute and indicates
+whether the attribute is applicable to
+.PN InputOutput
+and
+.PN InputOnly
+windows:
+.TS H
+l l l l
+lw(1.4i) lw(1.3i) cw(.9i) cw(.8i).
+_
+.sp 6p
+T{
+.B Attribute
+T}	T{
+.B Default 
+T}	T{
+.PN InputOutput
+T}	T{
+.PN InputOnly
+T}
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+T{
+background-pixmap
+T}	T{
+.PN None
+T}	T{
+Yes
+T}	T{
+No
+T}
+background-pixel	Undefined	Yes	No
+T{
+border-pixmap
+T}	T{
+.PN CopyFromParent
+T}	T{
+Yes
+T}	T{
+No
+T}
+border-pixel	Undefined	Yes	No
+T{
+bit-gravity
+T}	T{
+.PN ForgetGravity
+T}	T{
+Yes
+T}	T{
+No
+T}
+T{
+win-gravity
+T}	T{
+.PN NorthWestGravity
+T}	T{
+Yes
+T}	T{
+Yes
+T}
+T{
+backing-store
+T}	T{
+.PN NotUseful
+T}	T{
+Yes
+T}	T{
+No
+T}
+backing-planes	All ones	Yes	No
+backing-pixel	zero	Yes	No
+T{
+save-under
+T}	T{
+.PN False
+T}	T{
+Yes
+T}	T{
+No
+T}
+event-mask	empty set	Yes	Yes
+do-not-propagate-mask	empty set	Yes	Yes
+T{
+override-redirect
+T}	T{
+.PN False
+T}	T{
+Yes
+T}	T{
+Yes
+T}
+T{
+colormap
+T}	T{
+.PN CopyFromParent
+T}	T{
+Yes
+T}	T{
+No
+T}
+T{
+cursor
+T}	T{
+.PN None
+T}	T{
+Yes
+T}	T{
+Yes
+T}
+_
+.TE
+.NH 3
+Background Attribute
+.XS
+\*(SN Background Attribute
+.XE
+.LP
+Only
+.PN InputOutput
+windows can have a background.
+You can set the background of an
+.PN InputOutput
+window by using a pixel or a pixmap.
+.LP
+The background-pixmap attribute of a window specifies the pixmap to be used for 
+a window's background.
+This pixmap can be of any size, although some sizes may be faster than others.
+The background-pixel attribute of a window specifies a pixel value used to paint
+a window's background in a single color.
+.LP
+You can set the background-pixmap to a pixmap,  
+.PN None 
+(default), or 
+.PN ParentRelative .
+You can set the background-pixel of a window to any pixel value (no default).
+If you specify a background-pixel, 
+it overrides either the default background-pixmap
+or any value you may have set in the background-pixmap.
+A pixmap of an undefined size that is filled with the background-pixel is used 
+for the background.
+Range checking is not performed on the background pixel;
+it simply is truncated to the appropriate number of bits.
+.LP
+If you set the background-pixmap,
+it overrides the default.
+The background-pixmap and the window must have the same depth,
+or a
+.PN BadMatch
+error results.
+If you set background-pixmap to
+.PN None ,
+the window has no defined background.  
+If you set the background-pixmap to
+.PN ParentRelative :
+.IP \(bu 5
+The parent window's background-pixmap is used. 
+The child window, however, must have the same depth as 
+its parent,
+or a
+.PN BadMatch
+error results.
+.IP \(bu 5
+If the parent window has a background-pixmap of
+.PN None ,
+the window also has a background-pixmap of
+.PN None . 
+.IP \(bu 5
+A copy of the parent window's background-pixmap is not made.
+The parent's background-pixmap is examined each time the child window's 
+background-pixmap is required.  
+.IP \(bu 5
+The background tile origin always aligns with the parent window's
+background tile origin. 
+If the background-pixmap is not
+.PN ParentRelative ,
+the background tile origin is the child window's origin.
+.LP
+Setting a new background, whether by setting background-pixmap or
+background-pixel, overrides any previous background.
+The background-pixmap can be freed immediately if no further explicit reference
+is made to it (the X server will keep a copy to use when needed).
+If you later draw into the pixmap used for the background,
+what happens is undefined because the
+X implementation is free to make a copy of the pixmap or
+to use the same pixmap.
+.LP
+When no valid contents are available for regions of a window
+and either the regions are visible or the server is maintaining backing store,
+the server automatically tiles the regions with the window's background
+unless the window has a background of
+.PN None .
+If the background is
+.PN None ,
+the previous screen contents from other windows of the same depth as the window
+are simply left in place as long as the contents come from the parent of the
+window or an inferior of the parent.
+Otherwise, the initial contents of the exposed regions are undefined.
+.PN Expose 
+events are then generated for the regions, even if the background-pixmap
+is
+.PN None 
+(see section 10.9).
+.NH 3
+Border Attribute
+.XS
+\*(SN Border Attribute
+.XE
+.LP
+Only
+.PN InputOutput
+windows can have a border.
+You can set the border of an
+.PN InputOutput
+window by using a pixel or a pixmap.
+.LP
+The border-pixmap attribute of a window specifies the pixmap to be used 
+for a window's border.
+The border-pixel attribute of a window specifies a pixmap of undefined size 
+filled with that pixel be used for a window's border. 
+Range checking is not performed on the background pixel;
+it simply is truncated to the appropriate number of bits.
+The border tile origin is always the same as the background tile origin.
+.LP
+You can also set the border-pixmap to a pixmap of any size (some may be faster
+than others) or to
+.PN CopyFromParent 
+(default).
+You can set the border-pixel to any pixel value (no default).
+.LP
+If you set a border-pixmap, 
+it overrides the default.
+The border-pixmap and the window must have the same depth,
+or a
+.PN BadMatch
+error results.
+If you set the border-pixmap to 
+.PN CopyFromParent ,
+the parent window's border-pixmap is copied.
+Subsequent changes to the parent window's border attribute do not affect 
+the child window.
+However, the child window must have the same depth as the parent window,
+or a
+.PN BadMatch
+error results.
+.LP
+The border-pixmap can be freed immediately if no further explicit reference
+is made to it.
+If you later draw into the pixmap used for the border,
+what happens is undefined because the
+X implementation is free either to make a copy of the pixmap or
+to use the same pixmap.
+If you specify a border-pixel, 
+it overrides either the default border-pixmap
+or any value you may have set in the border-pixmap.
+All pixels in the window's border will be set to the border-pixel.
+Setting a new border, whether by setting border-pixel or by setting
+border-pixmap, overrides any previous border.
+.LP
+Output to a window is always clipped to the inside of the window. 
+Therefore, graphics operations never affect the window border.
+.NH 3
+Gravity Attributes
+.XS
+\*(SN Gravity Attributes
+.XE
+.LP
+The bit gravity of a window defines which region of the window should be 
+retained when an
+.PN InputOutput
+window is resized. 
+The default value for the bit-gravity attribute is 
+.PN ForgetGravity .
+The window gravity of a window allows you to define how the 
+.PN InputOutput
+or
+.PN InputOnly
+window should be repositioned if its parent is resized.  
+The default value for the win-gravity attribute is 
+.PN NorthWestGravity .
+.LP
+If the inside width or height of a window is not changed 
+and if the window is moved or its border is changed, 
+then the contents of the window are not lost but move with the window.
+Changing the inside width or height of the window causes its contents to be
+moved or lost (depending on the bit-gravity of the window) and causes
+children to be reconfigured (depending on their win-gravity).
+For a
+change of width and height, the (x, y) pairs are defined:
+.LP
+.TS
+l l
+l l.
+_
+.sp 6p
+.B
+Gravity Direction	Coordinates
+.sp 6p
+_
+.sp 6p
+.R
+T{
+.PN NorthWestGravity
+T}	T{
+(0, 0)
+T}
+T{
+.PN NorthGravity
+T}	T{
+(Width/2, 0)
+T}
+T{
+.PN NorthEastGravity
+T}	T{
+(Width, 0)
+T}
+T{
+.PN WestGravity
+T}	T{
+(0, Height/2)
+T}
+T{
+.PN CenterGravity
+T}	T{
+(Width/2, Height/2)
+T}
+T{
+.PN EastGravity
+T}	T{
+(Width, Height/2)
+T}
+T{
+.PN SouthWestGravity
+T}	T{
+(0, Height)
+T}
+T{
+.PN SouthGravity
+T}	T{
+(Width/2, Height)
+T}
+T{
+.PN SouthEastGravity
+T}	T{
+(Width, Height)
+T}
+.sp 6p
+_
+.TE
+.LP
+When a window with one of these bit-gravity values is resized, 
+the corresponding pair
+defines the change in position of each pixel in the window.
+When a window with one of these win-gravities has its parent window resized,
+the corresponding pair defines the change in position of the window 
+within the parent.
+When a window is so repositioned, a
+.PN GravityNotify
+event is generated (see section 10.10.5).
+.LP
+A bit-gravity of
+.PN StaticGravity 
+indicates that the contents or origin should not move relative to the 
+origin of the root window.
+If the change in size of the window is coupled with a change in position (x, y),
+then for bit-gravity the change in position of each pixel is (\-x, \-y), and for
+win-gravity the change in position of a child when its parent is so resized is
+(\-x, \-y).
+Note that
+.PN StaticGravity
+still only takes effect when the width or height of the window is changed, 
+not when the window is moved.
+.LP
+A bit-gravity of 
+.PN ForgetGravity 
+indicates that the window's contents are always discarded after a size change, 
+even if a backing store or save under has been requested.
+The window is tiled with its background
+and zero or more 
+.PN Expose 
+events are generated. 
+If no background is defined, the existing screen contents are not
+altered.
+Some X servers may also ignore the specified bit-gravity and 
+always generate 
+.PN Expose
+events.
+.LP
+The contents and borders of inferiors are not affected by their parent's
+bit-gravity.
+A server is permitted to ignore the specified bit-gravity and use
+.PN Forget
+instead.
+.LP
+A win-gravity of 
+.PN UnmapGravity 
+is like 
+.PN NorthWestGravity
+(the window is not moved),
+except the child is also
+unmapped when the parent is resized,
+and an 
+.PN UnmapNotify 
+event is
+generated.
+.NH 3
+Backing Store Attribute
+.XS
+\*(SN Backing Store Attribute
+.XE
+.LP
+Some implementations of the X server may choose to maintain the contents of 
+.PN InputOutput
+windows.
+If the X server maintains the contents of a window, 
+the off-screen saved pixels
+are known as backing store.
+The backing store advises the X server on what to do 
+with the contents of a window.
+The backing-store attribute can be set to
+.PN NotUseful 
+(default),
+.PN WhenMapped ,
+or
+.PN Always .
+.LP
+A backing-store attribute of 
+.PN NotUseful 
+advises the X server that 
+maintaining contents is unnecessary, 
+although some X implementations may
+still choose to maintain contents and, therefore, not generate 
+.PN Expose
+events.
+A backing-store attribute of 
+.PN WhenMapped 
+advises the X server that maintaining contents of 
+obscured regions when the window is mapped would be beneficial.
+In this case,
+the server may generate an 
+.PN Expose 
+event when the window is created.
+A backing-store attribute of 
+.PN Always 
+advises the X server that maintaining contents even when 
+the window is unmapped would be beneficial.  
+Even if the window is larger than its parent, 
+this is a request to the X server to maintain complete contents, 
+not just the region within the parent window boundaries.  
+While the X server maintains the window's contents, 
+.PN Expose 
+events normally are not generated, 
+but the X server may stop maintaining 
+contents at any time.  
+.LP
+When the contents of obscured regions of a window are being maintained,
+regions obscured by noninferior windows are included in the destination
+of graphics requests (and source, when the window is the source).
+However, regions obscured by inferior windows are not included.
+.NH 3
+Save Under Flag
+.XS
+\*(SN Save Under Flag
+.XE
+.IN "Save Unders"
+.LP
+Some server implementations may preserve contents of 
+.PN InputOutput
+windows under other 
+.PN InputOutput
+windows.
+This is not the same as preserving the contents of a window for you.
+You may get better visual
+appeal if transient windows (for example, pop-up menus) request that the system
+preserve the screen contents under them, 
+so the temporarily obscured applications do not have to repaint.
+.LP
+You can set the save-under flag to
+.PN True
+or
+.PN False 
+(default).
+If save-under is 
+.PN True , 
+the X server is advised that, when this window is mapped, 
+saving the contents of windows it obscures would be beneficial.
+.NH 3
+Backing Planes and Backing Pixel Attributes
+.XS
+\*(SN Backing Planes and Backing Pixel Attributes
+.XE
+.LP
+You can set backing planes to indicate (with bits set to 1) 
+which bit planes of an
+.PN InputOutput
+window hold dynamic data that must be preserved in backing store 
+and during save unders.
+The default value for the backing-planes attribute is all bits set to 1.
+You can set backing pixel to specify what bits to use in planes not 
+covered by backing planes.
+The default value for the backing-pixel attribute is all bits set to 0.
+The X server is free to save only the specified bit planes in the backing store
+or the save under and is free to regenerate the remaining planes with 
+the specified pixel value.
+Any extraneous bits in these values (that is, those bits beyond 
+the specified depth of the window) may be simply ignored.
+If you request backing store or save unders,
+you should use these members to minimize the amount of off-screen memory 
+required to store your window.
+.NH 3
+Event Mask and Do Not Propagate Mask Attributes
+.XS
+\*(SN Event Mask and Do Not Propagate Mask Attributes
+.XE
+.LP
+The event mask defines which events the client is interested in for this 
+.PN InputOutput
+or
+.PN InputOnly
+window (or, for some event types, inferiors of this window).
+The event mask is the bitwise inclusive OR of zero or more of the 
+valid event mask bits.
+You can specify that no maskable events are reported by setting 
+.PN NoEventMask 
+(default).
+.LP
+The do-not-propagate-mask attribute
+defines which events should not be propagated to 
+ancestor windows when no client has the event type selected in this 
+.PN InputOutput
+or
+.PN InputOnly
+window.
+The do-not-propagate-mask is the bitwise inclusive OR of zero or more
+of the following masks:
+.PN KeyPress , 
+.PN KeyRelease ,
+.PN ButtonPress , 
+.PN ButtonRelease ,
+.PN PointerMotion ,
+.PN Button1Motion , 
+.PN Button2Motion , 
+.PN Button3Motion ,
+.PN Button4Motion , 
+.PN Button5Motion , 
+and
+.PN ButtonMotion .
+You can specify that all events are propagated by setting 
+.PN NoEventMask 
+(default).
+.NH 3
+Override Redirect Flag
+.XS
+\*(SN Override Redirect Flag
+.XE
+.LP
+To control window placement or to add decoration,
+a window manager often needs to intercept (redirect) any map or configure
+request.
+Pop-up windows, however, often need to be mapped without a window manager
+getting in the way.
+To control whether an
+.PN InputOutput
+or
+.PN InputOnly
+window is to ignore these structure control facilities,
+use the override-redirect flag.
+.LP
+The override-redirect flag specifies whether map and configure requests 
+on this window should override a 
+.PN SubstructureRedirectMask 
+on the parent.
+You can set the override-redirect flag to
+.PN True
+or
+.PN False 
+(default).
+Window managers use this information to avoid tampering with pop-up windows
+(see also chapter 14).
+.NH 3
+Colormap Attribute
+.XS
+\*(SN Colormap Attribute
+.XE
+.LP
+The colormap attribute specifies which colormap best reflects the true
+colors of the 
+.PN InputOutput
+window.  
+The colormap must have the same visual type as the window,
+or a 
+.PN BadMatch 
+error results.  
+X servers capable of supporting multiple 
+hardware colormaps can use this information, 
+and window managers can use it for calls to
+.PN XInstallColormap .
+You can set the colormap attribute to a colormap or to
+.PN CopyFromParent
+(default).
+.LP
+If you set the colormap to
+.PN CopyFromParent ,
+the parent window's colormap is copied and used by its child.
+However, the child window must have the same visual type as the parent, 
+or a 
+.PN BadMatch 
+error results. 
+The parent window must not have a colormap of 
+.PN None ,
+or a 
+.PN BadMatch 
+error results.
+The colormap is copied by sharing the colormap object between the child 
+and parent, not by making a complete copy of the colormap contents.
+Subsequent changes to the parent window's colormap attribute do
+not affect the child window.
+.NH 3
+Cursor Attribute
+.XS
+\*(SN Cursor Attribute
+.XE
+.LP
+The cursor attribute specifies which cursor is to be used when the pointer is
+in the 
+.PN InputOutput
+or
+.PN InputOnly
+window.
+You can set the cursor to a cursor or
+.PN None
+(default).
+.LP
+If you set the cursor to
+.PN None ,
+the parent's cursor is used when the 
+pointer is in the 
+.PN InputOutput
+or
+.PN InputOnly
+window, and any change in the parent's cursor will cause an
+immediate change in the displayed cursor.
+By calling
+.PN XFreeCursor ,
+the cursor can be freed immediately as long as no further explicit reference 
+to it is made.
+.NH 2
+Creating Windows
+.XS
+\*(SN Creating Windows
+.XE
+.LP
+Xlib provides basic ways for creating windows,
+and toolkits often supply higher-level functions specifically for
+creating and placing top-level windows,
+which are discussed in the appropriate toolkit documentation.
+If you do not use a toolkit, however,
+you must provide some standard information or hints for the window
+manager by using the Xlib inter-client communication functions
+(see chapter 14).
+.LP
+If you use Xlib to create your own top-level windows
+(direct children of the root window),
+you must observe the following rules so that all applications interact
+reasonably across the different styles of window management:
+.IP \(bu 5
+You must never fight with the window manager for the size or
+placement of your top-level window.
+.IP \(bu 5
+You must be able to deal with whatever size window you get, 
+even if this means that your application just prints a message 
+like ``Please make me bigger'' in its window.
+.IP \(bu 5
+You should only attempt to resize or move top-level windows in
+direct response to a user request.
+If a request to change the size of a top-level window fails,
+you must be prepared to live with what you get.
+You are free to resize or move the children of top-level
+windows as necessary.
+(Toolkits often have facilities for automatic relayout.)
+.IP \(bu 5
+If you do not use a toolkit that automatically sets standard window properties,
+you should set these properties for top-level windows before mapping them.
+.LP
+For further information,
+see chapter 14 and the \fIInter-Client Communication Conventions Manual\fP.
+.LP
+.PN XCreateWindow
+is the more general function that allows you to set specific window attributes 
+when you create a window.
+.PN XCreateSimpleWindow 
+creates a window that inherits its attributes from its parent window.
+.LP
+.IN "Window" "InputOnly"
+The X server acts as if 
+.PN InputOnly 
+windows do not exist for
+the purposes of graphics requests, exposure processing, and
+.PN VisibilityNotify 
+events.
+An 
+.PN InputOnly 
+window cannot be used as a
+drawable (that is, as a source or destination for graphics requests).
+.PN InputOnly
+and 
+.PN InputOutput 
+windows act identically in other respects (properties,
+grabs, input control, and so on).
+Extension packages can define other classes of windows.
+.LP
+To create an unmapped window and set its window attributes, use
+.PN XCreateWindow .
+.IN "XCreateWindow" "" "@DEF@"
+.sM
+.FD 0
+Window XCreateWindow\^(\^\fIdisplay\fP, \fIparent\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIborder_width\fP\^, \fIdepth\fP\^, 
+.br
+                       \fIclass\fP\^, \fIvisual\fP\^, \fIvaluemask\fP\^, \fIattributes\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIparent\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^; 
+.br
+      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
+.br
+      unsigned int \fIborder_width\fP\^;
+.br
+      int \fIdepth\fP\^;
+.br
+      unsigned int \fIclass\fP\^;
+.br
+      Visual *\fIvisual\fP\^;
+.br
+      unsigned long \fIvaluemask\fP\^;
+.br
+      XSetWindowAttributes *\fIattributes\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIparent\fP 1i
+Specifies the parent window.
+.ds Xy , which are the top-left outside corner of the created window's \
+borders and are relative to the inside of the parent window's borders
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.ds Wh , which are the created window's inside dimensions \
+and do not include the created window's borders
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height\*(Wh.
+The dimensions must be nonzero,
+or a
+.PN BadValue
+error results.
+.IP \fIborder_width\fP 1i
+Specifies the width of the created window's border in pixels.
+.IP \fIdepth\fP 1i
+Specifies the window's depth.
+A depth of 
+.PN CopyFromParent
+means the depth is taken from the parent.
+.IP \fIclass\fP 1i
+Specifies the created window's class.
+You can pass
+.PN InputOutput , 
+.PN InputOnly , 
+or 
+.PN CopyFromParent .
+A class of 
+.PN CopyFromParent
+means the class
+is taken from the parent.
+.IP \fIvisual\fP 1i
+Specifies the visual type.
+A visual of 
+.PN CopyFromParent 
+means the visual type is taken from the 
+parent.
+.IP \fIvaluemask\fP 1i
+Specifies which window attributes are defined in the attributes
+argument.
+This mask is the bitwise inclusive OR of the valid attribute mask bits.
+If valuemask is zero,
+the attributes are ignored and are not referenced.
+.IP \fIattributes\fP 1i
+Specifies the structure from which the values (as specified by the value mask)
+are to be taken.
+The value mask should have the appropriate bits
+set to indicate which attributes have been set in the structure.
+.LP
+.eM
+The
+.PN XCreateWindow
+function creates an unmapped subwindow for a specified parent window, 
+returns the window ID of the created window, 
+and causes the X server to generate a
+.PN CreateNotify
+event.
+The created window is placed on top in the stacking order 
+with respect to siblings.
+.LP
+The coordinate system has the X axis horizontal and the Y axis vertical
+with the origin [0, 0] at the upper-left corner.
+Coordinates are integral,
+in terms of pixels,
+and coincide with pixel centers.
+Each window and pixmap has its own coordinate system.
+For a window, 
+the origin is inside the border at the inside, upper-left corner.
+.LP
+The border_width for an
+.PN InputOnly
+window must be zero, or a
+.PN BadMatch
+error results.
+For class
+.PN InputOutput ,
+the visual type and depth must be a combination supported for the screen,
+or a
+.PN BadMatch
+error results.
+The depth need not be the same as the parent,
+but the parent must not be a window of class 
+.PN InputOnly ,
+or a
+.PN BadMatch
+error results.
+For an
+.PN InputOnly
+window,
+the depth must be zero, and the visual must be one supported by the screen.
+If either condition is not met,
+a
+.PN BadMatch
+error results.
+The parent window, however, may have any depth and class.
+If you specify any invalid window attribute for a window, a
+.PN BadMatch
+error results.
+.LP
+The created window is not yet displayed (mapped) on the user's display.
+To display the window, call
+.PN XMapWindow .
+The new window initially uses the same cursor as
+its parent. 
+A new cursor can be defined for the new window by calling
+.PN XDefineCursor .
+.IN "Cursor" "Initial State"
+.IN "XDefineCursor" 
+The window will not be visible on the screen unless it and all of its
+ancestors are mapped and it is not obscured by any of its ancestors.
+.LP
+.PN XCreateWindow
+can generate
+.PN BadAlloc ,
+.PN BadColor ,
+.PN BadCursor ,
+.PN BadMatch ,
+.PN BadPixmap ,
+.PN BadValue ,
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To create an unmapped 
+.PN InputOutput
+subwindow of a given parent window, use
+.PN XCreateSimpleWindow .
+.IN "XCreateSimpleWindow" "" "@DEF@"
+.sM
+.FD 0
+Window XCreateSimpleWindow\^(\^\fIdisplay\fP, \fIparent\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIborder_width\fP\^, 
+.br
+                             \fIborder\fP\^, \fIbackground\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIparent\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
+.br
+      unsigned int \fIborder_width\fP\^;
+.br
+      unsigned long \fIborder\fP\^;
+.br
+      unsigned long \fIbackground\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIparent\fP 1i
+Specifies the parent window.
+.ds Xy , which are the top-left outside corner of the new window's borders \
+and are relative to the inside of the parent window's borders
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.ds Wh , which are the created window's inside dimensions \
+and do not include the created window's borders
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height\*(Wh.
+The dimensions must be nonzero,
+or a
+.PN BadValue
+error results.
+.IP \fIborder_width\fP 1i
+Specifies the width of the created window's border in pixels.
+.IP \fIborder\fP 1i
+Specifies the border pixel value of the window.
+.IP \fIbackground\fP 1i
+Specifies the background pixel value of the window.
+
+.LP
+.eM
+The
+.PN XCreateSimpleWindow
+function creates an unmapped
+.PN InputOutput
+subwindow for a specified parent window, returns the
+window ID of the created window, and causes the X server to generate a
+.PN CreateNotify
+event.
+The created window is placed on top in the stacking order with respect to 
+siblings.
+Any part of the window that extends outside its parent window is clipped.
+The border_width for an
+.PN InputOnly
+window must be zero, or a
+.PN BadMatch
+error results.
+.PN XCreateSimpleWindow
+inherits its depth, class, and visual from its parent.
+All other window attributes, except background and border, 
+have their default values.
+.LP
+.PN XCreateSimpleWindow
+can generate
+.PN BadAlloc ,
+.PN BadMatch ,
+.PN BadValue ,
+and
+.PN BadWindow 
+errors.
+.NH 2
+Destroying Windows
+.XS
+\*(SN Destroying Windows 
+.XE
+.LP
+Xlib provides functions that you can use to destroy a window or destroy all
+subwindows of a window.
+.LP
+.sp
+To destroy a window and all of its subwindows, use
+.PN XDestroyWindow .
+.IN "XDestroyWindow" "" "@DEF@"
+.sM
+.FD 0
+XDestroyWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.LP
+.eM
+The
+.PN XDestroyWindow
+function destroys the specified window as well as all of its subwindows and causes
+the X server to generate a
+.PN DestroyNotify
+event for each window.
+The window should never be referenced again.
+If the window specified by the w argument is mapped,
+it is unmapped automatically.
+The ordering of the
+.PN DestroyNotify
+events is such that for any given window being destroyed,
+.PN DestroyNotify
+is generated on any inferiors of the window before being generated on
+the window itself.
+The ordering among siblings and across subhierarchies is not otherwise
+constrained.
+If the window you specified is a root window, no windows are destroyed.
+Destroying a mapped window will generate 
+.PN Expose 
+events on other windows that were obscured by the window being destroyed.
+.LP
+.PN XDestroyWindow
+can generate a
+.PN BadWindow 
+error.
+.LP
+.sp
+To destroy all subwindows of a specified window, use 
+.PN XDestroySubwindows .
+.IN "XDestroySubwindows" "" "@DEF@"
+.sM
+.FD 0
+XDestroySubwindows\^(\^\fIdisplay\fP, \fIw\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.LP
+.eM
+The
+.PN XDestroySubwindows
+function destroys all inferior windows of the specified window, 
+in bottom-to-top stacking order.
+It causes the X server to generate a
+.PN DestroyNotify
+event for each window.
+If any mapped
+subwindows were actually destroyed,
+.PN XDestroySubwindows
+causes the X server to generate 
+.PN Expose 
+events on the specified window.
+This is much more efficient than deleting many windows
+one at a time because much of the work need be performed only once for all
+of the windows, rather than for each window.
+The subwindows should never be referenced again.  
+.LP
+.PN XDestroySubwindows
+can generate a
+.PN BadWindow 
+error.
+.NH 2
+Mapping Windows 
+.XS
+\*(SN Mapping Windows 
+.XE
+.LP
+A window is considered mapped if an 
+.PN XMapWindow
+call has been made on it.
+It may not be visible on the screen for one of the following reasons:
+.IP \(bu 5
+It is obscured by another opaque window.
+.IP \(bu 5
+One of its ancestors is not mapped.
+.IP \(bu 5
+It is entirely clipped by an ancestor.
+.LP
+.PN Expose 
+events are generated for the window when part or all of
+it becomes visible on the screen. 
+A client receives the
+.PN Expose 
+events only if it has asked for them.
+Windows retain their position in the stacking order when they are unmapped.
+.LP
+A window manager may want to control the placement of subwindows.
+If 
+.PN SubstructureRedirectMask 
+has been selected by a window manager
+on a parent window (usually a root window),
+a map request initiated by other clients on a child window is not performed,
+and the window manager is sent a 
+.PN MapRequest 
+event.
+However, if the override-redirect flag on the child had been set to
+.PN True
+(usually only on pop-up menus),
+the map request is performed.
+.LP
+A tiling window manager might decide to reposition and resize other clients' 
+windows and then decide to map the window to its final location.
+A window manager that wants to provide decoration might
+reparent the child into a frame first.
+For further information,
+see sections 3.2.8 and 10.10.
+Only a single client at a time can select for 
+.PN SubstructureRedirectMask .
+.LP
+Similarly, a single client can select for 
+.PN ResizeRedirectMask 
+on a parent window.
+Then, any attempt to resize the window by another client is suppressed, and
+the client receives a 
+.PN ResizeRequest 
+event.
+.LP
+.sp
+To map a given window, use 
+.PN XMapWindow .
+.IN "XMapWindow" "" "@DEF@"
+.sM
+.FD 0
+XMapWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.LP
+.eM
+The
+.PN XMapWindow
+function
+maps the window and all of its
+subwindows that have had map requests.
+Mapping a window that has an unmapped ancestor does not display the
+window but marks it as eligible for display when the ancestor becomes
+mapped.
+Such a window is called unviewable.
+When all its ancestors are mapped,
+the window becomes viewable
+and will be visible on the screen if it is not obscured by another window.
+This function has no effect if the window is already mapped.
+.LP
+If the override-redirect of the window is
+.PN False 
+and if some other client has selected
+.PN SubstructureRedirectMask
+on the parent window, then the X server generates a
+.PN MapRequest
+event, and the
+.PN XMapWindow
+function does not map the window.
+Otherwise, the window is mapped, and the X server generates a
+.PN MapNotify
+event.
+.LP
+If the window becomes viewable and no earlier contents for it are remembered,
+the X server tiles the window with its background.
+If the window's background is undefined,
+the existing screen contents are not
+altered, and the X server generates zero or more 
+.PN Expose
+events.
+If backing-store was maintained while the window was unmapped, no 
+.PN Expose
+events
+are generated.
+If backing-store will now be maintained, 
+a full-window exposure is always generated.
+Otherwise, only visible regions may be reported.
+Similar tiling and exposure take place for any newly viewable inferiors.
+.LP
+.IN "XMapWindow"
+If the window is an
+.PN InputOutput 
+window,
+.PN XMapWindow
+generates 
+.PN Expose 
+events on each 
+.PN InputOutput
+window that it causes to be displayed.
+If the client maps and paints the window 
+and if the client begins processing events, 
+the window is painted twice.
+To avoid this,
+first ask for 
+.PN Expose 
+events and then map the window,
+so the client processes input events as usual.
+The event list will include 
+.PN Expose 
+for each
+window that has appeared on the screen. 
+The client's normal response to
+an 
+.PN Expose 
+event should be to repaint the window.
+This method usually leads to simpler programs and to proper interaction
+with window managers.
+.LP
+.PN XMapWindow
+can generate a
+.PN BadWindow 
+error.
+.LP
+.sp
+To map and raise a window, use
+.PN XMapRaised .
+.IN "XMapRaised" "" "@DEF@"
+.sM
+.FD 0
+XMapRaised\^(\^\fIdisplay\fP, \fIw\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.LP
+.eM
+The
+.PN XMapRaised
+function
+essentially is similar to
+.PN XMapWindow
+in that it maps the window and all of its
+subwindows that have had map requests.
+However, it also raises the specified window to the top of the stack.
+For additional information,
+see 
+.PN XMapWindow .
+.LP
+.PN XMapRaised
+can generate multiple
+.PN BadWindow 
+errors.
+.LP
+.sp
+To map all subwindows for a specified window, use 
+.PN XMapSubwindows .
+.IN "XMapSubwindows" "" "@DEF@"
+.sM
+.FD 0
+XMapSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.LP
+.eM
+The
+.PN XMapSubwindows
+.IN "XMapSubwindows"
+function maps all subwindows for a specified window in top-to-bottom stacking 
+order.
+The X server generates
+.PN Expose
+events on each newly displayed window.
+This may be much more efficient than mapping many windows
+one at a time because the server needs to perform much of the work
+only once, for all of the windows, rather than for each window.
+.LP
+.PN XMapSubwindows
+can generate a
+.PN BadWindow 
+error.
+.NH 2
+Unmapping Windows
+.XS
+\*(SN Unmapping Windows 
+.XE
+.LP
+Xlib provides functions that you can use to unmap a window or all subwindows.
+.LP
+.sp
+To unmap a window, use 
+.PN XUnmapWindow .
+.IN "XUnmapWindow" "" "@DEF@"
+.sM
+.FD 0
+XUnmapWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.LP
+.eM
+The
+.PN XUnmapWindow
+function unmaps the specified window and causes the X server to generate an
+.PN UnmapNotify
+.IN "UnmapNotify Event"
+.IN "XUnmapWindow"
+event.
+If the specified window is already unmapped, 
+.PN XUnmapWindow 
+has no effect.
+Normal exposure processing on formerly obscured windows is performed.
+Any child window will no longer be visible until another map call is
+made on the parent.
+In other words, the subwindows are still mapped but are not visible
+until the parent is mapped.
+Unmapping a window will generate 
+.PN Expose 
+events on windows that were formerly obscured by it.
+.LP
+.PN XUnmapWindow
+can generate a
+.PN BadWindow 
+error.
+.LP
+.sp
+To unmap all subwindows for a specified window, use 
+.PN XUnmapSubwindows .
+.IN "XUnmapSubwindows" "" "@DEF@"
+.sM
+.FD 0
+XUnmapSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.LP
+.eM
+The
+.PN XUnmapSubwindows
+function unmaps all subwindows for the specified window in bottom-to-top
+stacking order.
+It causes the X server to generate an
+.PN UnmapNotify
+event on each subwindow and 
+.PN Expose 
+events on formerly obscured windows.
+.IN "UnmapNotify Event"
+Using this function is much more efficient than unmapping multiple windows
+one at a time because the server needs to perform much of the work
+only once, for all of the windows, rather than for each window.
+.LP
+.PN XUnmapSubwindows
+can generate a
+.PN BadWindow 
+error.
+.NH 2
+Configuring Windows
+.XS
+\*(SN Configuring Windows 
+.XE
+.LP
+.LP
+Xlib provides functions that you can use to
+move a window, resize a window, move and resize a window, or
+change a window's border width.
+To change one of these parameters,
+set the appropriate member of the
+.PN XWindowChanges
+structure and OR in the corresponding value mask in subsequent calls to
+.PN XConfigureWindow .
+The symbols for the value mask bits and the
+.PN XWindowChanges
+structure are:
+.sM
+.LP
+/* Configure window value mask bits */
+.TS
+lw(.5i) lw(2.5i) lw(.8i).
+T{
+#define
+T}	T{
+.PN CWX
+T}	T{
+(1<<0)
+T}
+T{
+#define
+T}	T{
+.PN CWY
+T}	T{
+(1<<1)
+T}
+T{
+#define
+T}	T{
+.PN CWWidth
+T}	T{
+(1<<2)
+T}
+T{
+#define
+T}	T{
+.PN CWHeight
+T}	T{
+(1<<3)
+T}
+T{
+#define
+T}	T{
+.PN CWBorderWidth
+T}	T{
+(1<<4)
+T}
+T{
+#define
+T}	T{
+.PN CWSibling
+T}	T{
+(1<<5)
+T}
+T{
+#define
+T}	T{
+.PN CWStackMode
+T}	T{
+(1<<6)
+T}
+.TE
+.IN "XWindowChanges" "" "@DEF@"
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+/* Values */
+
+typedef struct {
+	int x, y;
+	int width, height;
+	int border_width;
+	Window sibling;
+	int stack_mode;
+} XWindowChanges;
+.De
+.LP
+.eM
+The x and y members are used to set the window's x and y coordinates,
+which are relative to the parent's origin
+and indicate the position of the upper-left outer corner of the window.
+The width and height members are used to set the inside size of the window,
+not including the border, and must be nonzero, or a
+.PN BadValue
+error results.
+Attempts to configure a root window have no effect.
+.LP
+The border_width member is used to set the width of the border in pixels.
+Note that setting just the border width leaves the outer-left corner of the window
+in a fixed position but moves the absolute position of the window's origin.
+If you attempt to set the border-width attribute of an
+.PN InputOnly
+window nonzero, a
+.PN BadMatch
+error results. 
+.LP
+The sibling member is used to set the sibling window for stacking operations.
+The stack_mode member is used to set how the window is to be restacked 
+and can be set to
+.PN Above , 
+.PN Below , 
+.PN TopIf , 
+.PN BottomIf ,
+or 
+.PN Opposite .
+.LP
+If the override-redirect flag of the window is
+.PN False 
+and if some other client has selected
+.PN SubstructureRedirectMask
+on the parent, the X server generates a
+.PN ConfigureRequest
+event, and no further processing is performed.
+Otherwise, 
+if some other client has selected 
+.PN ResizeRedirectMask 
+on the window and the inside
+width or height of the window is being changed,
+a 
+.PN ResizeRequest
+event is generated, and the current inside width and height are
+used instead.
+Note that the override-redirect flag of the window has no effect
+on
+.PN ResizeRedirectMask 
+and that
+.PN SubstructureRedirectMask
+on the parent has precedence over
+.PN ResizeRedirectMask 
+on the window.
+.LP
+When the geometry of the window is changed as specified, 
+the window is restacked among siblings, and a
+.PN ConfigureNotify 
+event is generated if the state of the window actually changes.
+.PN GravityNotify
+events are generated after 
+.PN ConfigureNotify 
+events.
+If the inside width or height of the window has actually changed, 
+children of the window are affected as specified.
+.LP
+If a window's size actually changes,
+the window's subwindows move according to their window gravity.
+Depending on the window's bit gravity,
+the contents of the window also may be moved (see section 3.2.3).
+.LP
+If regions of the window were obscured but now are not,
+exposure processing is performed on these formerly obscured windows, 
+including the window itself and its inferiors. 
+As a result of increasing the width or height,
+exposure processing is also performed on any new regions of the window 
+and any regions where window contents are lost.
+.LP
+The restack check (specifically, the computation for 
+.PN BottomIf ,
+.PN TopIf ,
+and 
+.PN Opposite )
+is performed with respect to the window's final size and position (as
+controlled by the other arguments of the request), not its initial position.
+If a sibling is specified without a stack_mode,
+a
+.PN BadMatch
+error results.
+.LP
+If a sibling and a stack_mode are specified, 
+the window is restacked as follows:
+.TS
+lw(1i) lw(5i).
+T{
+.PN Above
+T}	T{
+The window is placed just above the sibling.
+T}
+.sp 6p
+T{
+.PN Below
+T}	T{
+The window is placed just below the sibling.
+T}
+.sp 6p
+T{
+.PN TopIf
+T}	T{
+If the sibling occludes the window, the window is placed
+at the top of the stack.
+T}
+.sp 6p
+T{
+.PN BottomIf
+T}	T{
+If the window occludes the sibling, the window is
+placed at the bottom of the stack.
+T}
+.sp 6p
+T{
+.PN Opposite
+T}	T{
+If the sibling occludes the window, the window 
+is placed at the top of the stack.
+If the window occludes the sibling, 
+the window is placed at the bottom of the stack.
+T}
+.TE
+.LP
+If a stack_mode is specified but no sibling is specified,
+the window is restacked as follows:
+.TS
+lw(1i) lw(5i).
+T{
+.PN Above
+T}	T{
+The window is placed at the top of the stack.
+T}
+.sp 6p
+T{
+.PN Below
+T}	T{
+The window is placed at the bottom of the stack.
+T}
+.sp 6p
+T{
+.PN TopIf
+T}	T{
+If any sibling occludes the window, the window is placed at
+the top of the stack.
+T}
+.sp 6p
+T{
+.PN BottomIf
+T}	T{
+If the window occludes any sibling, the window is placed at
+the bottom of the stack.
+T}
+.sp 6p
+T{
+.PN Opposite
+T}	T{
+If any sibling occludes the window, the window 
+is placed at the top of the stack. 
+If the window occludes any sibling, 
+the window is placed at the bottom of the stack.
+T}
+.TE
+.LP
+Attempts to configure a root window have no effect.
+.LP
+.sp
+To configure a window's size, location, stacking, or border, use
+.PN XConfigureWindow .
+.IN "XConfigureWindow" "" "@DEF@"
+.sM
+.FD 0
+XConfigureWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIvalue_mask\fP\^, \fIvalues\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      unsigned int \fIvalue_mask\fP\^;
+.br
+      XWindowChanges *\fIvalues\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Wi to be reconfigured
+.IP \fIw\fP 1i
+Specifies the window \*(Wi.
+.IP \fIvalue_mask\fP 1i
+Specifies which values are to be set using information in
+the values structure.
+This mask is the bitwise inclusive OR of the valid configure window values bits.
+.IP \fIvalues\fP 1i
+Specifies the 
+.PN XWindowChanges 
+structure.
+.LP
+.eM
+The
+.PN XConfigureWindow
+function uses the values specified in the
+.PN XWindowChanges
+structure to reconfigure a window's size, position, border, and stacking order.
+Values not specified are taken from the existing geometry of the window.
+.LP
+If a sibling is specified without a stack_mode or if the window
+is not actually a sibling,
+a
+.PN BadMatch
+error results. 
+Note that the computations for
+.PN BottomIf ,
+.PN TopIf ,
+and
+.PN Opposite
+are performed with respect to the window's final geometry (as controlled by the
+other arguments passed to
+.PN XConfigureWindow ),
+not its initial geometry.
+Any backing store contents of the window, its
+inferiors, and other newly visible windows are either discarded or
+changed to reflect the current screen contents 
+(depending on the implementation).
+.LP
+.PN XConfigureWindow
+can generate
+.PN BadMatch ,
+.PN BadValue ,
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To move a window without changing its size, use 
+.PN XMoveWindow .
+.IN "XMoveWindow" "" "@DEF@"
+.sM
+.FD 0 
+XMoveWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIx\fP\^, \fIy\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.FN	
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Wi to be moved
+.IP \fIw\fP 1i
+Specifies the window \*(Wi.
+.ds Xy , which define the new location of the top-left pixel \
+of the window's border or the window itself if it has no border
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.LP
+.eM
+The
+.PN XMoveWindow
+function moves the specified window to the specified x and y coordinates,
+but it does not change the window's size, raise the window, or
+change the mapping state of the window.
+Moving a mapped window may or may not lose the window's contents 
+depending on if the window is obscured by nonchildren 
+and if no backing store exists.
+If the contents of the window are lost, 
+the X server generates
+.PN Expose 
+events.
+Moving a mapped window generates
+.PN Expose 
+events on any formerly obscured windows. 
+.LP
+If the override-redirect flag of the window is 
+.PN False 
+and some
+other client has selected 
+.PN SubstructureRedirectMask 
+on the parent, the X server generates a
+.PN ConfigureRequest 
+event, and no further processing is
+performed.  
+Otherwise, the window is moved.
+.LP
+.PN XMoveWindow
+can generate a
+.PN BadWindow 
+error.
+.LP
+.sp
+To change a window's size without changing the upper-left coordinate, use 
+.PN XResizeWindow .
+.IN "XResizeWindow" "" "@DEF@"
+.sM
+.FD 0
+XResizeWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.ds Wh , which are the interior dimensions of the window \
+after the call completes
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height\*(Wh.
+.LP
+.eM
+The
+.PN XResizeWindow
+function changes the inside dimensions of the specified window, not including
+its borders.
+This function does not change the window's upper-left coordinate or
+the origin and does not restack the window.
+Changing the size of a mapped window may lose its contents and generate
+.PN Expose 
+events.
+If a mapped window is made smaller, 
+changing its size generates
+.PN Expose 
+events on windows that the mapped window formerly obscured.
+.LP
+If the override-redirect flag of the window is 
+.PN False 
+and some
+other client has selected 
+.PN SubstructureRedirectMask 
+on the parent, the X server generates a
+.PN ConfigureRequest 
+event, and no further processing is performed.  
+If either width or height is zero,
+a
+.PN BadValue
+error results.
+.LP
+.PN XResizeWindow
+can generate
+.PN BadValue
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To change the size and location of a window, use 
+.PN XMoveResizeWindow .
+.IN "XMoveResizeWindow" "" "@DEF@"
+.sM
+.FD 0
+XMoveResizeWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Wi to be reconfigured
+.IP \fIw\fP 1i
+Specifies the window \*(Wi.
+.ds Xy , which define the new position of the window relative to its parent
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.ds Wh , which define the interior size of the window
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height\*(Wh.
+.LP
+.eM
+The
+.PN XMoveResizeWindow
+function changes the size and location of the specified window 
+without raising it.
+Moving and resizing a mapped window may generate an
+.PN Expose 
+event on the window.
+Depending on the new size and location parameters,
+moving and resizing a window may generate 
+.PN Expose 
+events on windows that the window formerly obscured. 
+.LP
+If the override-redirect flag of the window is 
+.PN False 
+and some
+other client has selected 
+.PN SubstructureRedirectMask 
+on the parent, the X server generates a
+.PN ConfigureRequest 
+event, and no further processing is performed.  
+Otherwise, the window size and location are changed.
+.LP
+.PN XMoveResizeWindow
+can generate
+.PN BadValue 
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To change the border width of a given window, use
+.PN XSetWindowBorderWidth .
+.IN "XSetWindowBorderWidth" "" "@DEF@"
+.sM
+.FD 0
+XSetWindowBorderWidth\^(\^\fIdisplay\fP, \fIw\fP, \fIwidth\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      unsigned int \fIwidth\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIwidth\fP 1i
+Specifies the width of the window border.
+.LP
+.eM
+The
+.PN XSetWindowBorderWidth
+function sets the specified window's border width to the specified width.
+.LP
+.PN XSetWindowBorderWidth
+can generate a
+.PN BadWindow 
+error.
+.NH 2
+Changing Window Stacking Order
+.XS
+\*(SN Changing Window Stacking Order 
+.XE
+.LP
+.LP
+Xlib provides functions that you can use to raise, lower, circulate,
+or restack windows.
+.LP
+.sp
+To raise a window so that no sibling window obscures it, use 
+.PN XRaiseWindow .
+.IN "XRaiseWindow" "" "@DEF@"
+.sM
+.FD 0
+XRaiseWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.LP
+.eM
+The
+.PN XRaiseWindow
+function
+raises the specified window to the top of the stack so that no sibling window
+obscures it.
+If the windows are regarded as overlapping sheets of paper stacked 
+on a desk,
+then raising a window is analogous to moving the sheet to the top of
+the stack but leaving its x and y location on the desk constant.
+Raising a mapped window may generate 
+.PN Expose
+events for the window and any mapped subwindows that were formerly obscured.  
+.LP
+If the override-redirect attribute of the window is 
+.PN False 
+and some
+other client has selected 
+.PN SubstructureRedirectMask 
+on the parent, the X server generates a
+.PN ConfigureRequest 
+event, and no processing is performed.
+Otherwise, the window is raised.
+.LP
+.PN XRaiseWindow
+can generate a
+.PN BadWindow 
+error.
+.LP
+.sp
+To lower a window so that it does not obscure any sibling windows, use 
+.PN XLowerWindow .
+.IN "XLowerWindow" "" "@DEF@"
+.sM
+.FD 0
+XLowerWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.LP
+.eM
+The
+.PN XLowerWindow
+function lowers the specified window to the bottom of the stack
+so that it does not obscure any sibling
+windows.
+If the windows are regarded as overlapping sheets of paper
+stacked on a desk, then lowering a window is analogous to moving the
+sheet to the bottom of the stack but leaving its x and y location on
+the desk constant.
+Lowering a mapped window will generate 
+.PN Expose 
+events on any windows it formerly obscured.
+.LP
+If the override-redirect attribute of the window is 
+.PN False 
+and some
+other client has selected 
+.PN SubstructureRedirectMask 
+on the parent, the X server generates a
+.PN ConfigureRequest 
+event, and no processing is performed.  
+Otherwise, the window is lowered to the bottom of the
+stack.
+.LP
+.PN XLowerWindow
+can generate a
+.PN BadWindow 
+error.
+.LP
+.sp
+To circulate a subwindow up or down, use
+.PN XCirculateSubwindows .
+.IN "XCirculateSubwindows" "" "@DEF@"
+.sM
+.FD 0
+XCirculateSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^, \fIdirection\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      int \fIdirection\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIdirection\fP 1i
+Specifies the direction (up or down) that you want to circulate
+the window. 
+You can pass 
+.PN RaiseLowest
+or
+.PN LowerHighest .
+.LP
+.eM
+The
+.PN XCirculateSubwindows
+function circulates children of the specified window in the specified 
+direction.
+If you specify
+.PN RaiseLowest ,
+.PN XCirculateSubwindows
+raises the lowest mapped child (if any) that is occluded 
+by another child to the top of the stack.
+If you specify
+.PN LowerHighest ,
+.PN XCirculateSubwindows
+lowers the highest mapped child (if any) that occludes another child
+to the bottom of the stack.
+Exposure processing is then performed on formerly obscured windows.
+If some other client has selected 
+.PN SubstructureRedirectMask 
+on the window, the X server generates a 
+.PN CirculateRequest 
+event, and no further processing is performed.
+If a child is actually restacked,
+the X server generates a
+.PN CirculateNotify
+event. 
+.LP
+.PN XCirculateSubwindows
+can generate
+.PN BadValue
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To raise the lowest mapped child of a window that is partially or completely
+occluded by another child, use
+.PN XCirculateSubwindowsUp .
+.IN "XCirculateSubwindowsUp" "" "@DEF@"
+.sM
+.FD 0
+XCirculateSubwindowsUp\^(\^\fIdisplay\fP, \fIw\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.LP
+.eM
+The
+.PN XCirculateSubwindowsUp
+function raises the lowest mapped child of the specified window that
+is partially
+or completely
+occluded by another child.
+Completely unobscured children are not affected.
+This is a convenience function equivalent to
+.PN XCirculateSubwindows
+with
+.PN RaiseLowest
+specified.
+.LP
+.PN XCirculateSubwindowsUp
+can generate a
+.PN BadWindow 
+error.
+.LP
+.sp
+To lower the highest mapped child of a window that partially or 
+completely occludes another child, use 
+.PN XCirculateSubwindowsDown .
+.IN "XCirculateSubwindowsDown" "" "@DEF@"
+.sM
+.FD 0
+XCirculateSubwindowsDown\^(\^\fIdisplay\fP, \fIw\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.LP
+.eM
+The
+.PN XCirculateSubwindowsDown
+function lowers the highest mapped child of the specified window that partially
+or completely occludes another child.
+Completely unobscured children are not affected.
+This is a convenience function equivalent to
+.PN XCirculateSubwindows
+with
+.PN LowerHighest
+specified.
+.LP
+.PN XCirculateSubwindowsDown
+can generate a
+.PN BadWindow 
+error.
+.LP
+.sp
+To restack a set of windows from top to bottom, use 
+.PN XRestackWindows .
+.IN "XRestackWindows" "" "@DEF@"
+.sM
+.FD 0
+XRestackWindows\^(\^\fIdisplay\fP, \fIwindows\fP\^, \^\fInwindows\fP\^);
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIwindows\fP\^[];
+.br
+      int \fInwindows\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIwindows\fP 1i
+Specifies an array containing the windows to be restacked.
+.IP \fInwindows\fP 1i
+Specifies the number of windows to be restacked.
+.LP
+.eM
+The
+.PN XRestackWindows
+function restacks the windows in the order specified,
+from top to bottom.
+The stacking order of the first window in the windows array is unaffected,
+but the other windows in the array are stacked underneath the first window,
+in the order of the array.
+The stacking order of the other windows is not affected.
+For each window in the window array that is not a child of the specified window,
+a
+.PN BadMatch
+error results.
+.LP
+If the override-redirect attribute of a window is 
+.PN False 
+and some
+other client has selected 
+.PN SubstructureRedirectMask 
+on the parent, the X server generates 
+.PN ConfigureRequest 
+events for each window whose override-redirect flag is not set, 
+and no further processing is performed.
+Otherwise, the windows will be restacked in top-to-bottom order.
+.LP
+.PN XRestackWindows
+can generate a
+.PN BadWindow 
+error.
+.NH 2
+Changing Window Attributes
+.XS
+\*(SN Changing Window Attributes 
+.XE
+.LP
+.LP
+Xlib provides functions that you can use to set window attributes.
+.PN XChangeWindowAttributes
+is the more general function that allows you to set one or more window
+attributes provided by the
+.PN XSetWindowAttributes
+structure.
+The other functions described in this section allow you to set one specific
+window attribute, such as a window's background.
+.LP
+.sp
+To change one or more attributes for a given window, use
+.PN XChangeWindowAttributes .
+.IN "XChangeWindowAttributes" "" "@DEF@"
+.sM
+.FD 0
+XChangeWindowAttributes\^(\^\fIdisplay\fP, \fIw\fP\^, \fIvaluemask\fP\^, \fIattributes\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      unsigned long \fIvaluemask\fP\^;
+.br
+      XSetWindowAttributes *\fIattributes\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIvaluemask\fP 1i
+Specifies which window attributes are defined in the attributes
+argument.
+This mask is the bitwise inclusive OR of the valid attribute mask bits.
+If valuemask is zero,
+the attributes are ignored and are not referenced.
+The values and restrictions are
+the same as for
+.PN XCreateWindow .
+.IP
+.IP \fIattributes\fP 1i
+Specifies the structure from which the values (as specified by the value mask)
+are to be taken.
+The value mask should have the appropriate bits
+set to indicate which attributes have been set in the structure 
+(see section 3.2).
+.LP
+.eM
+Depending on the valuemask,
+the
+.PN XChangeWindowAttributes
+function uses the window attributes in the
+.PN XSetWindowAttributes
+structure to change the specified window attributes.
+Changing the background does not cause the window contents to be
+changed.
+To repaint the window and its background, use 
+.PN XClearWindow .
+Setting the border or changing the background such that the
+border tile origin changes causes the border to be repainted.
+Changing the background of a root window to 
+.PN None 
+or 
+.PN ParentRelative
+restores the default background pixmap.
+Changing the border of a root window to
+.PN CopyFromParent
+restores the default border pixmap.
+Changing the win-gravity does not affect the current position of the
+window.
+Changing the backing-store of an obscured window to 
+.PN WhenMapped 
+or
+.PN Always , 
+or changing the backing-planes, backing-pixel, or
+save-under of a mapped window may have no immediate effect.
+Changing the colormap of a window (that is, defining a new map, not
+changing the contents of the existing map) generates a 
+.PN ColormapNotify
+event.
+Changing the colormap of a visible window may have no
+immediate effect on the screen because the map may not be installed
+(see
+.PN XInstallColormap ).
+Changing the cursor of a root window to 
+.PN None 
+restores the default
+cursor.
+Whenever possible, you are encouraged to share colormaps.
+.LP
+Multiple clients can select input on the same window. 
+Their event masks are maintained separately.
+When an event is generated, 
+it is reported to all interested clients. 
+However, only one client at a time can select for 
+.PN SubstructureRedirectMask , 
+.PN ResizeRedirectMask , 
+and
+.PN ButtonPressMask .
+If a client attempts to select any of these event masks 
+and some other client has already selected one, 
+a
+.PN BadAccess
+error results.
+There is only one do-not-propagate-mask for a window, 
+not one per client.
+.LP
+.PN XChangeWindowAttributes
+can generate
+.PN BadAccess ,
+.PN BadColor ,
+.PN BadCursor ,
+.PN BadMatch ,
+.PN BadPixmap ,
+.PN BadValue ,
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To set the background of a window to a given pixel, use 
+.PN XSetWindowBackground .
+.IN "XSetWindowBackground" "" "@DEF@"
+.sM
+.FD 0
+XSetWindowBackground\^(\^\fIdisplay\fP, \fIw\fP\^, \fIbackground_pixel\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      unsigned long \fIbackground_pixel\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIbackground_pixel\fP 1i
+Specifies the pixel that is to be used for the background.
+.LP
+.eM
+The
+.PN XSetWindowBackground
+function sets the background of the window to the specified pixel value.
+Changing the background does not cause the window contents to be changed.
+.PN XSetWindowBackground
+uses a pixmap of undefined size filled with the pixel value you passed.
+If you try to change the background of an 
+.PN InputOnly
+window, a
+.PN BadMatch
+error results.
+.LP
+.PN XSetWindowBackground
+can generate
+.PN BadMatch
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+.LP
+To set the background of a window to a given pixmap, use 
+.PN XSetWindowBackgroundPixmap .
+.IN "Window" "background"
+.IN "XSetWindowBackgroundPixmap" "" "@DEF@"
+.sM
+.FD 0
+XSetWindowBackgroundPixmap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIbackground_pixmap\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Pixmap \fIbackground_pixmap\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIbackground_pixmap\fP 1i
+Specifies the background pixmap,
+.PN ParentRelative ,
+or
+.PN None .
+.LP
+.eM
+.IN "Resource IDs" "freeing"
+.IN "Freeing" "resources"
+The
+.PN XSetWindowBackgroundPixmap
+function sets the background pixmap of the window to the specified pixmap.
+The background pixmap can immediately be freed if no further explicit
+references to it are to be made.
+If 
+.PN ParentRelative
+is specified, 
+the background pixmap of the window's parent is used,
+or on the root window, the default background is restored.
+If you try to change the background of an 
+.PN InputOnly
+window, a
+.PN BadMatch
+error results.
+If the background is set to
+.PN None ,
+the window has no defined background.
+.LP
+.PN XSetWindowBackgroundPixmap
+can generate
+.PN BadMatch ,
+.PN BadPixmap ,
+and 
+.PN BadWindow 
+errors.
+.NT Note
+.PN XSetWindowBackground
+and
+.PN XSetWindowBackgroundPixmap
+do not change the current contents of the window.
+.NE
+.LP
+.sp
+To change and repaint a window's border to a given pixel, use 
+.PN XSetWindowBorder .
+.IN "XSetWindowBorder" "" "@DEF@"
+.sM
+.FD 0
+XSetWindowBorder\^(\^\fIdisplay\fP, \fIw\fP\^, \fIborder_pixel\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      unsigned long \fIborder_pixel\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIborder_pixel\fP 1i
+Specifies the entry in the colormap. 
+.LP
+.eM
+The
+.PN XSetWindowBorder
+function sets the border of the window to the pixel value you specify.
+If you attempt to perform this on an
+.PN InputOnly
+window, a
+.PN BadMatch
+error results.
+.LP
+.PN XSetWindowBorder
+can generate
+.PN BadMatch 
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To change and repaint the border tile of a given window, use 
+.PN XSetWindowBorderPixmap .
+.IN "XSetWindowBorderPixmap" "" "@DEF@"
+.sM
+.FD 0
+XSetWindowBorderPixmap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIborder_pixmap\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Pixmap \fIborder_pixmap\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIborder_pixmap\fP 1i
+Specifies the border pixmap or
+.PN CopyFromParent .
+.LP
+.eM
+The
+.PN XSetWindowBorderPixmap
+function sets the border pixmap of the window to the pixmap you specify.
+The border pixmap can be freed immediately if no further explicit
+references to it are to be made.
+If you specify
+.PN CopyFromParent ,
+a copy of the parent window's border pixmap is used.
+If you attempt to perform this on an
+.PN InputOnly
+window, a
+.PN BadMatch
+error results.
+.IN "Resource IDs" "freeing"
+.IN "Freeing" "resources"
+.LP
+.PN XSetWindowBorderPixmap
+can generate
+.PN BadMatch ,
+.PN BadPixmap ,
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To set the colormap of a given window, use
+.PN XSetWindowColormap .
+.IN "XSetWindowColormap" "" "@DEF@"
+.sM
+.FD 0
+XSetWindowColormap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIcolormap\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.LP
+.eM
+The
+.PN XSetWindowColormap
+function sets the specified colormap of the specified window.
+The colormap must have the same visual type as the window,
+or a
+.PN BadMatch
+error results.
+.LP
+.PN XSetWindowColormap
+can generate
+.PN BadColor ,
+.PN BadMatch ,
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To define which cursor will be used in a window, use
+.PN XDefineCursor .
+.IN "Window" "defining the cursor"
+.IN "XDefineCursor" "" "@DEF@"
+.sM
+.FD 0
+XDefineCursor\^(\^\fIdisplay\fP, \fIw\fP\^, \fIcursor\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Cursor \fIcursor\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIcursor\fP 1i
+Specifies the cursor that is to be displayed or
+.PN None .
+.LP
+.eM
+If a cursor is set, it will be used when the pointer is in the window.
+If the cursor is
+.PN None ,
+it is equivalent to
+.PN XUndefineCursor .
+.LP
+.PN XDefineCursor
+can generate
+.PN BadCursor
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To undefine the cursor in a given window, use
+.PN XUndefineCursor .
+.IN "Window" "undefining the cursor"
+.IN "XUndefineCursor" "" "@DEF@"
+.sM
+.FD 0
+XUndefineCursor\^(\^\fIdisplay\fP, \fIw\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.LP
+.eM
+The
+.PN XUndefineCursor
+function undoes the effect of a previous
+.PN XDefineCursor
+for this window.
+When the pointer is in the window,
+the parent's cursor will now be used.
+On the root window,
+the default cursor is restored.
+.LP
+.PN XUndefineCursor
+can generate a
+.PN BadWindow 
+error.
+.bp
diff --git a/specs/libX11/CH04 b/specs/libX11/CH04
new file mode 100644
index 00000000..b964198c
--- /dev/null
+++ b/specs/libX11/CH04
@@ -0,0 +1,1595 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 4\fP\s-1
+
+\s+1\fBWindow Information Functions\fP\s-1
+.sp 2
+.nr H1 4
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.na
+.LP
+.XS
+Chapter 4: Window Information Functions 
+.XE
+After you connect the display to the X server and create a window,
+you can use the Xlib window information functions to:
+.IP \(bu 5
+Obtain information about a window
+.IP \(bu 5
+Translate screen coordinates
+.IP \(bu 5
+Manipulate property lists
+.IP \(bu 5
+Obtain and change window properties
+.IP \(bu 5
+Manipulate selections
+.NH 2
+Obtaining Window Information
+.XS
+\*(SN Obtaining Window Information 
+.XE
+.LP
+Xlib provides functions that you can use to obtain information about 
+the window tree, the window's current attributes, 
+the window's current geometry, or the current pointer coordinates.
+Because they are most frequently used by window managers,
+these functions all return a status to indicate whether the window still
+exists.
+.LP
+.sp
+To obtain the parent, a list of children, and number of children for 
+a given window, use 
+.PN XQueryTree .
+.IN "Child Window"
+.IN "Parent Window"
+.IN "XQueryTree" "" "@DEF@"
+.sM
+.FD 0
+Status XQueryTree\^(\^\fIdisplay\fP, \fIw\fP\^, \fIroot_return\fP\^, \fIparent_return\fP\^, \fIchildren_return\fP\^, \fInchildren_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Window *\fIroot_return\fP\^;
+.br
+      Window *\fIparent_return\fP\^;
+.br
+      Window **\fIchildren_return\fP\^;
+.br
+      unsigned int *\fInchildren_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Wi whose list of children, root, parent, and number of children \
+you want to obtain
+.IP \fIw\fP 1i
+Specifies the window \*(Wi.
+.IP \fIroot_return\fP 1i
+Returns the root window.
+.IP \fIparent_return\fP 1i
+Returns the parent window.
+.IP \fIchildren_return\fP 1i
+Returns the list of children.
+.IP \fInchildren_return\fP 1i
+Returns the number of children.
+.LP
+.eM
+The
+.PN XQueryTree
+function returns the root ID, the parent window ID, 
+a pointer to the list of children windows
+(NULL when there are no children), 
+and the number of children in the list for the specified window.
+The children are listed in current stacking order, from bottom-most 
+(first) to top-most (last).
+.PN XQueryTree
+returns zero if it fails and nonzero if it succeeds.
+To free a non-NULL children list when it is no longer needed, use 
+.PN XFree .
+.LP
+.PN XQueryTree
+can generate a
+.PN BadWindow
+error.
+.LP
+.sp
+To obtain the current attributes of a given window, use 
+.PN XGetWindowAttributes .
+.IN "XGetWindowAttributes" "" "@DEF@"
+.sM
+.FD 0
+Status XGetWindowAttributes\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_attributes_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XWindowAttributes *\fIwindow_attributes_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Wi whose current attributes you want to obtain
+.IP \fIw\fP 1i
+Specifies the window \*(Wi.
+.IP \fIwindow_attributes_return\fP 1i
+Returns the specified window's attributes in the
+.PN XWindowAttributes
+structure.
+.LP
+.eM
+The
+.PN XGetWindowAttributes
+function returns the current attributes for the specified window to an
+.PN XWindowAttributes
+structure.
+.LP
+.IN "XWindowAttributes" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int x, y;	/* location of window */
+	int width, height;	/* width and height of window */
+	int border_width;	/* border width of window */
+	int depth;	/* depth of window */
+	Visual *visual;	/* the associated visual structure */
+	Window root;	/* root of screen containing window */
+	int class;	/* InputOutput, InputOnly*/
+	int bit_gravity;	/* one of the bit gravity values */
+	int win_gravity;	/* one of the window gravity values */
+	int backing_store;	/* NotUseful, WhenMapped, Always */
+	unsigned long backing_planes;	/* planes to be preserved if possible */
+	unsigned long backing_pixel;	/* value to be used when restoring planes */
+	Bool save_under;	/* boolean, should bits under be saved? */
+	Colormap colormap;	/* color map to be associated with window */
+	Bool map_installed;	/* boolean, is color map currently installed*/
+	int map_state;	/* IsUnmapped, IsUnviewable, IsViewable */
+	long all_event_masks;	/* set of events all people have interest in*/
+	long your_event_mask;	/* my event mask */
+	long do_not_propagate_mask;	/* set of events that should not propagate */
+	Bool override_redirect;	/* boolean value for override-redirect */
+	Screen *screen;	/* back pointer to correct screen */
+} XWindowAttributes;
+.De
+.LP
+.eM
+The x and y members are set to the upper-left outer
+corner relative to the parent window's origin.
+The width and height members are set to the inside size of the window, 
+not including the border.
+The border_width member is set to the window's border width in pixels.
+The depth member is set to the depth of the window 
+(that is, bits per pixel for the object).
+The visual member is a pointer to the screen's associated
+.PN Visual
+structure.
+The root member is set to the root window of the screen containing the window.
+The class member is set to the window's class and can be either
+.PN InputOutput
+or
+.PN InputOnly .
+.LP
+The bit_gravity member is set to the window's bit gravity
+and can be one of the following:
+.LP
+.TS
+lw(1.5i) lw(1.5i).
+T{
+.PN ForgetGravity
+T}	T{
+.PN EastGravity
+T}
+T{
+.PN NorthWestGravity
+T}	T{
+.PN SouthWestGravity
+T}
+T{
+.PN NorthGravity
+T}	T{
+.PN SouthGravity
+T}
+T{
+.PN NorthEastGravity
+T}	T{
+.PN SouthEastGravity
+T}
+T{
+.PN WestGravity
+T}	T{
+.PN StaticGravity
+T}
+.PN CenterGravity
+.TE
+.LP
+The win_gravity member is set to the window's window gravity
+and can be one of the following:
+.LP
+.TS
+lw(1.5i) lw(1.5i).
+T{
+.PN UnmapGravity
+T}	T{
+.PN EastGravity
+T}
+T{
+.PN NorthWestGravity
+T}	T{
+.PN SouthWestGravity
+T}
+T{
+.PN NorthGravity
+T}	T{
+.PN SouthGravity
+T}
+T{
+.PN NorthEastGravity
+T}	T{
+.PN SouthEastGravity
+T}
+T{
+.PN WestGravity
+T}	T{
+.PN StaticGravity
+T}
+.PN CenterGravity
+.TE
+.LP
+For additional information on gravity,
+see section 3.2.3.
+.LP
+The backing_store member is set to indicate how the X server should maintain
+the contents of a window 
+and can be 
+.PN WhenMapped ,
+.PN Always ,
+or
+.PN NotUseful .
+The backing_planes member is set to indicate (with bits set to 1) which bit 
+planes of the window hold dynamic data that must be preserved in backing_stores 
+and during save_unders.
+The backing_pixel member is set to indicate what values to use 
+for planes not set in backing_planes.
+.LP
+The save_under member is set to 
+.PN True
+or
+.PN False .
+The colormap member is set to the colormap for the specified window and can be
+a colormap ID or 
+.PN None .
+The map_installed member is set to indicate whether the colormap is 
+currently installed and can be 
+.PN True
+or
+.PN False .
+The map_state member is set to indicate the state of the window and can be
+.PN IsUnmapped ,
+.PN IsUnviewable ,
+or
+.PN IsViewable .
+.PN IsUnviewable
+is used if the window is mapped but some ancestor is unmapped.
+.LP
+The all_event_masks member is set to the bitwise inclusive OR of all event 
+masks selected on the window by all clients.
+The your_event_mask member is set to the bitwise inclusive OR of all event 
+masks selected by the querying client.
+The do_not_propagate_mask member is set to the bitwise inclusive OR of the 
+set of events that should not propagate.
+.LP
+The override_redirect member is set to indicate whether this window overrides
+structure control facilities and can be 
+.PN True
+or
+.PN False .
+Window manager clients should ignore the window if this member is
+.PN True .
+.LP
+The screen member is set to a screen pointer that gives you a back pointer 
+to the correct screen.
+This makes it easier to obtain the screen information without
+having to loop over the root window fields to see which field matches.
+.LP
+.PN XGetWindowAttributes
+can generate
+.PN BadDrawable
+and
+.PN BadWindow
+errors.
+.LP
+.sp
+To obtain the current geometry of a given drawable, use 
+.PN XGetGeometry .
+.IN "XGetGeometry" "" "@DEF@"
+.sM
+.FD 0
+Status XGetGeometry\^(\^\fIdisplay\fP, \fId\fP\^, \^\fIroot_return\fP\^, \fIx_return\fP\^, \fIy_return\fP\^, \fIwidth_return\fP\^, 
+.br
+                      \fIheight_return\fP\^, \fIborder_width_return\fP\^, \fIdepth_return\fP\^)
+.br
+        Display *\fIdisplay\fP\^;
+.br
+        Drawable \fId\fP\^;
+.br
+        Window *\fIroot_return\fP\^;
+.br
+        int *\fIx_return\fP\^, *\fIy_return\fP\^;
+.br
+        unsigned int *\fIwidth_return\fP\^, *\fIheight_return\fP\^;
+.br
+        unsigned int *\fIborder_width_return\fP\^;
+.br
+        unsigned int *\fIdepth_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Dr , which can be a window or a pixmap
+.IP \fId\fP 1i
+Specifies the drawable\*(Dr. 
+.IP \fIroot_return\fP 1i
+Returns the root window.
+.IP \fIx_return\fP 1i
+.br
+.ns
+.IP \fIy_return\fP 1i
+Return the x and y coordinates that define the location of the drawable.
+For a window, 
+these coordinates specify the upper-left outer corner relative to
+its parent's origin.
+For pixmaps, these coordinates are always zero.
+.IP \fIwidth_return\fP 1i
+.br
+.ns
+.IP \fIheight_return\fP 1i
+Return the drawable's dimensions (width and height).
+For a window, 
+these dimensions specify the inside size, not including the border.
+.IP \fIborder_width_return\fP 1i
+Returns the border width in pixels. 
+If the drawable is a pixmap, it returns zero.
+.IP \fIdepth_return\fP 1i
+Returns the depth of the drawable (bits per pixel for the object).
+.LP
+.eM
+The
+.PN XGetGeometry
+function returns the root window and the current geometry of the drawable.
+The geometry of the drawable includes the x and y coordinates, width and height,
+border width, and depth.
+These are described in the argument list.
+It is legal to pass to this function a window whose class is
+.PN InputOnly .
+.LP
+.PN XGetGeometry
+can generate a
+.PN BadDrawable
+error.
+.NH 2
+Translating Screen Coordinates
+.XS
+\*(SN Translating Screen Coordinates 
+.XE
+.LP
+Applications sometimes
+need to perform a coordinate transformation from the coordinate
+space of one window to another window or need to determine which
+window the pointing device is in.
+.PN XTranslateCoordinates
+and
+.PN XQueryPointer
+fulfill these needs (and avoid any race conditions) by
+asking the X server to perform these operations.
+.LP
+.sp
+To translate a coordinate in one window to the coordinate
+space of another window, use
+.PN XTranslateCoordinates .
+.IN "XTranslateCoordinates" "" "@DEF@"
+.sM
+.FD 0
+Bool XTranslateCoordinates\^(\^\fIdisplay\fP, \fIsrc_w\fP\^, \fIdest_w\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIdest_x_return\fP\^, 
+.br
+                            \fIdest_y_return\fP\^, \fIchild_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIsrc_w\fP\^, \fIdest_w\fP\^;
+.br
+      int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
+.br
+      int *\fIdest_x_return\fP\^, *\fIdest_y_return\fP\^;
+.br
+      Window *\fIchild_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIsrc_w\fP 1i
+Specifies the source window.
+.IP \fIdest_w\fP 1i
+Specifies the destination window.
+.IP \fIsrc_x\fP 1i
+.br
+.ns
+.IP \fIsrc_y\fP 1i
+Specify the x and y coordinates within the source window.
+.IP \fIdest_x_return\fP 1i
+.br
+.ns
+.IP \fIdest_y_return\fP 1i
+Return the x and y coordinates within the destination window.
+.IP \fIchild_return\fP 1i
+Returns the child if the coordinates are contained in a mapped child of the
+destination window.
+.LP
+.eM
+If
+.PN XTranslateCoordinates
+returns
+.PN True ,
+it takes the src_x and src_y coordinates relative
+to the source window's origin and returns these coordinates to 
+dest_x_return and dest_y_return
+relative to the destination window's origin.
+If
+.PN XTranslateCoordinates
+returns 
+.PN False , 
+src_w and dest_w are on different screens,
+and dest_x_return and dest_y_return are zero.
+If the coordinates are contained in a mapped child of dest_w,
+that child is returned to child_return.
+Otherwise, child_return is set to
+.PN None .
+.LP
+.PN XTranslateCoordinates
+can generate a
+.PN BadWindow 
+error.
+.LP
+.sp
+To obtain the screen coordinates of the pointer
+or to determine the pointer coordinates relative to a specified window, use 
+.PN XQueryPointer .
+.IN "XQueryPointer" "" "@DEF@"
+.sM
+.FD 0
+Bool XQueryPointer\^(\^\fIdisplay\fP, \fIw\fP\^, \fIroot_return\fP\^, \fIchild_return\fP\^, \fIroot_x_return\fP\^, \fIroot_y_return\fP\^, 
+.br
+                     \fIwin_x_return\fP\^, \fIwin_y_return\fP\^, \fImask_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Window *\fIroot_return\fP\^, *\fIchild_return\fP\^;
+.br
+      int *\fIroot_x_return\fP\^, *\fIroot_y_return\fP\^;
+.br
+      int *\fIwin_x_return\fP\^, *\fIwin_y_return\fP\^;
+.br
+      unsigned int *\fImask_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.ds Ro that the pointer is in
+.IP \fIroot_return\fP 1i
+Returns the root window \*(Ro.
+.IP \fIchild_return\fP 1i
+Returns the child window that the pointer is located in, if any.
+.IP \fIroot_x_return\fP 1i
+.br
+.ns
+.IP \fIroot_y_return\fP 1i
+Return the pointer coordinates relative to the root window's origin.
+.IP \fIwin_x_return\fP 1i
+.br
+.ns
+.IP \fIwin_y_return\fP 1i
+Return the pointer coordinates relative to the specified window.
+.IP \fImask_return\fP 1i
+Returns the current state of the modifier keys and pointer buttons.
+.LP
+.eM
+The
+.PN XQueryPointer
+function returns the root window the pointer is logically on and the pointer
+coordinates relative to the root window's origin.
+If
+.PN XQueryPointer
+returns 
+.PN False , 
+the pointer is not on the same screen as the specified window, and
+.PN XQueryPointer
+returns 
+.PN None
+to child_return and zero to win_x_return and win_y_return.
+If 
+.PN XQueryPointer
+returns 
+.PN True , 
+the pointer coordinates returned to win_x_return and win_y_return
+are relative to the origin of the specified window.
+In this case, 
+.PN XQueryPointer
+returns the child that contains the pointer, if any,
+or else
+.PN None
+to child_return.
+.LP
+.PN XQueryPointer
+returns the current logical state of the keyboard buttons 
+and the modifier keys in mask_return.
+It sets mask_return to the bitwise inclusive OR of one or more
+of the button or modifier key bitmasks to match 
+the current state of the mouse buttons and the modifier keys.
+.LP
+Note that the logical state of a device (as seen through Xlib)
+may lag the physical state if device event processing is frozen
+(see section 12.1).
+.LP
+.PN XQueryPointer
+can generate a
+.PN BadWindow 
+error.
+.NH 2
+Properties and Atoms
+.XS
+\*(SN Properties and Atoms 
+.XE
+.LP
+A property is a collection of named, typed data.
+The window system has a set of predefined properties
+.IN "Atom" "predefined"
+(for example, the name of a window, size hints, and so on), and users can
+define any other arbitrary information and associate it with windows.
+Each property has a name,
+which is an ISO Latin-1 string.
+For each named property,
+a unique identifier (atom) is associated with it. 
+A property also has a type, for example, string or integer.
+These types are also indicated using atoms, so arbitrary new
+types can be defined.
+Data of only one type may be associated with a single
+property name.
+Clients can store and retrieve properties associated with windows.
+For efficiency reasons,
+an atom is used rather than a character string.
+.PN XInternAtom
+can be used to obtain the atom for property names.
+.IN "Atom" 
+.LP
+A property is also stored in one of several possible formats.
+The X server can store the information as 8-bit quantities, 16-bit
+quantities, or 32-bit quantities.
+This permits the X server to present the data in the byte order that the
+client expects.
+.NT Note
+If you define further properties of complex type, 
+you must encode and decode them yourself.
+These functions must be carefully written if they are to be portable.
+For further information about how to write a library extension,
+see appendix C.
+.NE
+The type of a property is defined by an atom, which allows for
+arbitrary extension in this type scheme.
+.IN "Atom" 
+.LP
+Certain property names are
+predefined in the server for commonly used functions.
+The atoms for these properties are defined in 
+.hN X11/Xatom.h .
+To avoid name clashes with user symbols, the 
+.PN #define 
+name for each atom has the XA_ prefix.
+For an explanation of the functions that let you get and set
+much of the information stored in these predefined properties,
+see chapter 14.
+.LP
+The core protocol imposes no semantics on these property names,
+but semantics are specified in other X Consortium standards,
+such as the \fIInter-Client Communication Conventions Manual\fP
+and the \fIX Logical Font Description Conventions\fP.
+.LP
+You can use properties to communicate other information between
+applications.
+The functions described in this section let you define new properties 
+and get the unique atom IDs in your applications.
+.LP
+Although any particular atom can have some client interpretation 
+within each of the name spaces, 
+atoms occur in five distinct name spaces within the protocol: 
+.IP \(bu 5
+Selections
+.IP \(bu 5
+Property names
+.IP \(bu 5
+Property types
+.IP \(bu 5
+Font properties 
+.IP \(bu 5
+Type of a 
+.PN ClientMessage 
+event (none are built into the X server)
+.LP
+.LP
+The built-in selection property names are:
+.LP
+.Ds 0
+.TA .5i 1.5i 3i
+.ta .5i 1.5i 3i
+.R
+PRIMARY
+SECONDARY
+.De
+.LP
+The built-in property names are: 
+.TS
+lw(2i) lw(2i).
+.sp 6p
+CUT_BUFFER0	RESOURCE_MANAGER
+CUT_BUFFER1	WM_CLASS
+CUT_BUFFER2	WM_CLIENT_MACHINE
+CUT_BUFFER3	WM_COLORMAP_WINDOWS
+CUT_BUFFER4	WM_COMMAND
+CUT_BUFFER5	WM_HINTS
+CUT_BUFFER6	WM_ICON_NAME
+CUT_BUFFER7	WM_ICON_SIZE
+RGB_BEST_MAP	WM_NAME
+RGB_BLUE_MAP	WM_NORMAL_HINTS
+RGB_DEFAULT_MAP	WM_PROTOCOLS
+RGB_GRAY_MAP	WM_STATE
+RGB_GREEN_MAP	WM_TRANSIENT_FOR
+RGB_RED_MAP	WM_ZOOM_HINTS
+.sp 6p
+.TE
+.LP
+The built-in property types are: 
+.LP
+.TS
+lw(2i) lw(2i).
+.sp 6p
+ARC	POINT
+ATOM	RGB_COLOR_MAP
+BITMAP	RECTANGLE
+CARDINAL	STRING
+COLORMAP	VISUALID
+CURSOR	WINDOW
+DRAWABLE	WM_HINTS
+FONT	WM_SIZE_HINTS
+INTEGER	
+PIXMAP
+.sp 6p
+.TE
+.LP
+The built-in font property names are: 
+.TS
+lw(2i) lw(2i).
+.sp 6p
+MIN_SPACE	STRIKEOUT_DESCENT
+NORM_SPACE	STRIKEOUT_ASCENT
+MAX_SPACE	ITALIC_ANGLE
+END_SPACE	X_HEIGHT
+SUPERSCRIPT_X	QUAD_WIDTH
+SUPERSCRIPT_Y	WEIGHT
+SUBSCRIPT_X	POINT_SIZE
+SUBSCRIPT_Y	RESOLUTION
+UNDERLINE_POSITION	COPYRIGHT
+UNDERLINE_THICKNESS	NOTICE
+FONT_NAME	FAMILY_NAME
+FULL_NAME	CAP_HEIGHT
+.sp 6p
+.TE
+.LP
+For further information about font properties,
+see section 8.5.
+.LP
+.sp
+To return an atom for a given name, use 
+.PN XInternAtom .
+.IN "Atom" "interning"
+.IN "XInternAtom" "" "@DEF@"
+.sM
+.FD 0
+Atom XInternAtom\^(\^\fIdisplay\fP, \fIatom_name\fP\^, \fIonly_if_exists\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      char *\fIatom_name\fP\^;
+.br
+      Bool \fIonly_if_exists\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIatom_name\fP 1i
+Specifies the name associated with the atom you want returned.
+.IP \fIonly_if_exists\fP 1i
+Specifies a Boolean value that indicates whether the atom must be created.
+.LP
+.eM
+The
+.PN XInternAtom
+function returns the atom identifier associated with the specified atom_name
+string.
+If only_if_exists is 
+.PN False ,
+the atom is created if it does not exist.
+Therefore,
+.PN XInternAtom
+can return
+.PN None .
+If the atom name is not in the Host Portable Character Encoding, 
+the result is implementation-dependent.
+Uppercase and lowercase matter;
+the strings ``thing'', ``Thing'', and ``thinG'' 
+all designate different atoms.  
+The atom will remain defined even after the client's connection closes.
+It will become undefined only when the last connection to
+the X server closes.
+.LP
+.PN XInternAtom
+can generate
+.PN BadAlloc
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To return atoms for an array of names, use 
+.PN XInternAtoms .
+.IN "Atom" "interning"
+.IN "XInternAtoms" "" "@DEF@"
+.sM
+.FD 0
+Status XInternAtoms\^(\^\fIdisplay\fP, \fInames\fP\^, \fIcount\fP\^, \fIonly_if_exists\fP, \fIatoms_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      char **\fInames\fP\^;
+.br
+      int \fIcount\fP\^;
+.br
+      Bool \fIonly_if_exists\fP\^;
+.br
+      Atom *\fIatoms_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fInames\fP 1i
+Specifies the array of atom names.
+.ds Cn atom names in the array
+.IP \fIcount\fP 1i
+Specifies the number of \*(Cn.
+.IP \fIonly_if_exists\fP 1i
+Specifies a Boolean value that indicates whether the atom must be created.
+.IP \fIatoms_return\fP 1i
+Returns the atoms.
+.LP
+.eM
+The
+.PN XInternAtoms
+function returns the atom identifiers associated with the specified names.
+The atoms are stored in the atoms_return array supplied by the caller.
+Calling this function is equivalent to calling
+.PN XInternAtom
+for each of the names in turn with the specified value of only_if_exists,
+but this function minimizes the number of round-trip protocol exchanges
+between the client and the X server.
+.LP
+This function returns a nonzero status if atoms are returned for
+all of the names;
+otherwise, it returns zero.
+.LP
+.PN XInternAtoms
+can generate
+.PN BadAlloc
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To return a name for a given atom identifier, use 
+.PN XGetAtomName .
+.IN "Atom" "getting name"
+.IN "XGetAtomName" "" "@DEF@"
+.sM
+.FD 0
+char *XGetAtomName\^(\^\fIdisplay\fP, \fIatom\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Atom \fIatom\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIatom\fP 1i
+Specifies the atom for the property name you want returned.
+.LP
+.eM
+The
+.PN XGetAtomName
+function returns the name associated with the specified atom.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned string is in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+To free the resulting string,
+call
+.PN XFree .
+.LP
+.PN XGetAtomName
+can generate a
+.PN BadAtom 
+error.
+.LP
+.sp
+To return the names for an array of atom identifiers, use 
+.PN XGetAtomNames .
+.IN "Atom" "getting name"
+.IN "XGetAtomNames" "" "@DEF@"
+.sM
+.FD 0
+Status XGetAtomNames\^(\^\fIdisplay\fP, \fIatoms\fP, \fIcount\fP\^, \fInames_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Atom *\fIatoms\fP\^;
+.br
+      int \fIcount\fP\^;
+.br
+      char **\fInames_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIatoms\fP 1i
+Specifies the array of atoms.
+.ds Cn atoms in the array
+.IP \fIcount\fP 1i
+Specifies the number of \*(Cn.
+.IP \fInames_return\fP 1i
+Returns the atom names.
+.LP
+.eM
+The
+.PN XGetAtomNames
+function returns the names associated with the specified atoms.
+The names are stored in the names_return array supplied by the caller.
+Calling this function is equivalent to calling
+.PN XGetAtomName
+for each of the atoms in turn,
+but this function minimizes the number of round-trip protocol exchanges
+between the client and the X server.
+.LP
+This function returns a nonzero status if names are returned for
+all of the atoms;
+otherwise, it returns zero.
+.LP
+.PN XGetAtomNames
+can generate a
+.PN BadAtom 
+error.
+.NH 2
+Obtaining and Changing Window Properties
+.XS
+\*(SN Obtaining and Changing Window Properties 
+.XE
+.LP
+You can attach a property list to every window.
+Each property has a name, a type, and a value (see section 4.3).
+The value is an array of 8-bit, 16-bit, or 32-bit quantities,
+whose interpretation is left to the clients.  The type
+.PN char
+is used to represent 8-bit quantities, the type
+.PN short
+is used to represent 16-bit quantities, and the type
+.PN long
+is used to represent 32-bit quantities.
+.LP
+Xlib provides functions that you can use to obtain, 
+change, update, or interchange window properties.
+In addition, Xlib provides other utility functions for inter-client
+communication (see chapter 14).
+.LP
+.sp
+To obtain the type, format, and value of a property of a given window, use 
+.PN XGetWindowProperty .
+.IN "Property" "getting"
+.LP
+.IN "XGetWindowProperty" "" "@DEF@"
+.sM
+.FD 0
+int XGetWindowProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^, \fIlong_offset\fP\^, \fIlong_length\fP\^, \fIdelete\fP\^, \fIreq_type\fP\^, 
+.br
+                        \fIactual_type_return\fP\^, \fIactual_format_return\fP\^, \fInitems_return\fP\^, \fIbytes_after_return\fP\^, 
+.br
+                        \fIprop_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Atom \fIproperty\fP\^;
+.br
+      long \fIlong_offset\fP\^, \fIlong_length\fP\^;
+.br
+      Bool \fIdelete\fP\^;
+.br
+      Atom \fIreq_type\fP\^; 
+.br
+      Atom *\fIactual_type_return\fP\^;
+.br
+      int *\fIactual_format_return\fP\^;
+.br
+      unsigned long *\fInitems_return\fP\^;
+.br
+      unsigned long *\fIbytes_after_return\fP\^;
+.br
+      unsigned char **\fIprop_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Wi whose property you want to obtain
+.IP \fIw\fP 1i
+Specifies the window \*(Wi.
+.IP \fIproperty\fP 1i
+Specifies the property name.
+.IP \fIlong_offset\fP 1i
+Specifies the offset in the specified property (in 32-bit quantities) 
+where the data is to be retrieved.
+.IP \fIlong_length\fP 1i
+Specifies the length in 32-bit multiples of the data to be retrieved.
+.IP \fIdelete\fP 1i
+Specifies a Boolean value that determines whether the property is deleted.
+.IP \fIreq_type\fP 1i
+Specifies the atom identifier associated with the property type or
+.PN AnyPropertyType .
+.IP \fIactual_type_return\fP 1i
+Returns the atom identifier  that defines the actual type of the property.
+.IP \fIactual_format_return\fP 1i
+Returns the actual format of the property.
+.IP \fInitems_return\fP 1i
+Returns the actual number of 8-bit, 16-bit, or 32-bit items 
+stored in the prop_return data.
+.IP \fIbytes_after_return\fP 1i
+Returns the number of bytes remaining to be read in the property if 
+a partial read was performed.
+.IP \fIprop_return\fP 1i
+Returns the data in the specified format.
+.LP
+.eM
+The
+.PN XGetWindowProperty
+function returns the actual type of the property; the actual format of the property;
+the number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes remaining
+to be read in the property; and a pointer to the data actually returned.
+.PN XGetWindowProperty
+sets the return arguments as follows:
+.IP \(bu 5
+If the specified property does not exist for the specified window,
+.PN XGetWindowProperty 
+returns 
+.PN None
+to actual_type_return and the value zero to 
+actual_format_return and bytes_after_return.
+The nitems_return argument is empty.
+In this case, the delete argument is ignored.
+.IP \(bu 5
+If the specified property exists 
+but its type does not match the specified type,
+.PN XGetWindowProperty 
+returns the actual property type to actual_type_return, 
+the actual property format (never zero) to actual_format_return, 
+and the property length in bytes
+(even if the actual_format_return is 16 or 32) 
+to bytes_after_return.
+It also ignores the delete argument.
+The nitems_return argument is empty.
+.IP \(bu 5
+If the specified property exists and either you assign 
+.PN AnyPropertyType 
+to the req_type argument or the specified type matches the actual property type,
+.PN XGetWindowProperty 
+returns the actual property type to actual_type_return and the actual
+property format (never zero) to actual_format_return. 
+It also returns a value to bytes_after_return and nitems_return, by 
+defining the following
+values:
+.IP
+.nf
+	N = actual length of the stored property in bytes
+	     (even if the format is 16 or 32)
+	I = 4 * long_offset
+	T = N - I
+	L = MINIMUM(T, 4 * long_length)
+	A = N - (I + L)
+.fi
+.IP
+The returned value starts at byte index I in the property (indexing
+from zero), and its length in bytes is L.
+If the value for long_offset causes L to be negative,
+a
+.PN BadValue
+error results. 
+The value of bytes_after_return is A, 
+giving the number of trailing unread bytes in the stored property.
+.LP
+If the returned format is 8, the returned data is represented as a
+.PN char
+array.
+If the returned format is 16, the returned data is represented as a
+.PN short
+array and should be cast to that type to obtain the elements.
+If the returned format is 32, the returned data is represented as a
+.PN long
+array and should be cast to that type to obtain the elements.
+.LP
+.PN XGetWindowProperty
+always allocates one extra byte in prop_return 
+(even if the property is zero length) 
+and sets it to zero so that simple properties consisting of characters
+do not have to be copied into yet another string before use.
+.LP
+If delete is 
+.PN True 
+and bytes_after_return is zero, 
+.PN XGetWindowProperty
+deletes the property 
+from the window and generates a 
+.PN PropertyNotify 
+event on the window.
+.LP
+The function returns
+.PN Success
+if it executes successfully.
+To free the resulting data,
+use
+.PN XFree .
+.LP
+.PN XGetWindowProperty
+can generate
+.PN BadAtom ,
+.PN BadValue ,
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To obtain a given window's property list, use 
+.PN XListProperties .
+.IN "Property" "listing"
+.IN "XListProperties" "" "@DEF@"
+.sM
+.FD 0
+Atom *XListProperties\^(\^\fIdisplay\fP, \fIw\fP\^, \fInum_prop_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      int *\fInum_prop_return\fP\^; 
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Wi whose property list you want to obtain
+.IP \fIw\fP 1i
+Specifies the window \*(Wi.
+.IP \fInum_prop_return\fP 1i
+Returns the length of the properties array.
+.LP
+.eM
+The
+.PN XListProperties
+function returns a pointer to an array of atom properties that are defined for 
+the specified window or returns NULL if no properties were found.
+To free the memory allocated by this function, use
+.PN XFree .
+.LP
+.PN XListProperties
+can generate a
+.PN BadWindow 
+error.
+.LP
+.sp
+To change a property of a given window, use
+.PN XChangeProperty .
+.IN "Property" "changing"
+.IN "Property" "appending"
+.IN "Property" "prepending"
+.IN "Property" "replacing"
+.IN "Property" "format"
+.IN "Property" "type"
+.IN "XChangeProperty" "" "@DEF@"
+.sM
+.FD 0
+XChangeProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^, \fItype\fP\^, \fIformat\fP\^, \fImode\fP\^, \fIdata\fP\^, \fInelements\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Atom \fIproperty\fP\^, \fItype\fP\^;
+.br
+      int \fIformat\fP\^;
+.br
+      int \fImode\fP\^;
+.br
+      unsigned char *\fIdata\fP\^;
+.br
+      int \fInelements\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Wi whose property you want to change
+.IP \fIw\fP 1i
+Specifies the window \*(Wi.
+.IP \fIproperty\fP 1i
+Specifies the property name.
+.IP \fItype\fP 1i
+Specifies the type of the property.
+The X server does not interpret the type but simply
+passes it back to an application that later calls 
+.PN XGetWindowProperty .
+.IP \fIformat\fP 1i
+Specifies whether the data should be viewed as a list
+of 8-bit, 16-bit, or 32-bit quantities.
+Possible values are 8, 16, and 32.
+This information allows the X server to correctly perform
+byte-swap operations as necessary.
+If the format is 16-bit or 32-bit,
+you must explicitly cast your data pointer to an (unsigned char *) in the call
+to 
+.PN XChangeProperty .
+.\" Changed name of this file to prop_mode.a on 1/13/87
+.IP \fImode\fP 1i
+Specifies the mode of the operation.
+You can pass
+.PN PropModeReplace ,
+.PN PropModePrepend ,
+or
+.PN PropModeAppend .
+.IP \fIdata\fP 1i
+Specifies the property data.
+.IP \fInelements\fP 1i
+Specifies the number of elements of the specified data format.
+.LP
+.eM
+The
+.PN XChangeProperty
+function alters the property for the specified window and
+causes the X server to generate a
+.PN PropertyNotify
+event on that window.
+.PN XChangeProperty
+performs the following:
+.IP \(bu 5
+If mode is
+.PN PropModeReplace ,
+.PN XChangeProperty
+discards the previous property value and stores the new data.
+.IP \(bu 5
+If mode is
+.PN PropModePrepend
+or
+.PN PropModeAppend ,
+.PN XChangeProperty
+inserts the specified data before the beginning of the existing data
+or onto the end of the existing data, respectively.
+The type and format must match the existing property value,
+or a
+.PN BadMatch
+error results.
+If the property is undefined, 
+it is treated as defined with the correct type and
+format with zero-length data.
+.LP
+If the specified format is 8, the property data must be a
+.PN char
+array.
+If the specified format is 16, the property data must be a
+.PN short
+array.
+If the specified format is 32, the property data must be a
+.PN long
+array.
+.LP
+The lifetime of a property is not tied to the storing client.
+Properties remain until explicitly deleted, until the window is destroyed,
+or until the server resets.
+For a discussion of what happens when the connection to the X server is closed,
+see section 2.6. 
+The maximum size of a property is server dependent and can vary dynamically
+depending on the amount of memory the server has available.
+(If there is insufficient space, a
+.PN BadAlloc
+error results.)
+.LP
+.PN XChangeProperty
+can generate
+.PN BadAlloc ,
+.PN BadAtom ,
+.PN BadMatch ,
+.PN BadValue ,
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To rotate a window's property list, use
+.PN XRotateWindowProperties .
+.LP
+.IN "XRotateWindowProperties" "" "@DEF@"
+.sM
+.FD 0
+XRotateWindowProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIproperties\fP, \fInum_prop\fP, \fInpositions\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Atom \fIproperties\fP\^[]\^;
+.br
+      int \fInum_prop\fP\^;
+.br
+      int \fInpositions\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIproperties\fP 1i
+Specifies the array of properties that are to be rotated.
+.IP \fInum_prop\fP 1i
+Specifies the length of the properties array.
+.IP \fInpositions\fP 1i
+Specifies the rotation amount.
+.LP
+.eM
+The
+.PN XRotateWindowProperties
+function allows you to rotate properties on a window and causes
+the X server to generate
+.PN PropertyNotify
+events.
+If the property names in the properties array are viewed as being numbered 
+starting from zero and if there are num_prop property names in the list,
+then the value associated with property name I becomes the value associated 
+with property name (I + npositions) mod N for all I from zero to N \- 1.
+The effect is to rotate the states by npositions places around the virtual ring
+of property names (right for positive npositions, 
+left for negative npositions).
+If npositions mod N is nonzero,
+the X server generates a
+.PN PropertyNotify
+event for each property in the order that they are listed in the array.
+If an atom occurs more than once in the list or no property with that 
+name is defined for the window,
+a 
+.PN BadMatch 
+error results.
+If a 
+.PN BadAtom 
+or 
+.PN BadMatch 
+error results,
+no properties are changed.
+.LP
+.PN XRotateWindowProperties
+can generate
+.PN BadAtom ,
+.PN BadMatch ,
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To delete a property on a given window, use 
+.PN XDeleteProperty .
+.IN "Property" "deleting"
+.IN "XDeleteProperty" "" "@DEF@"
+.sM
+.FD 0
+XDeleteProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Atom \fIproperty\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Wi whose property you want to delete
+.IP \fIw\fP 1i
+Specifies the window \*(Wi.
+.IP \fIproperty\fP 1i
+Specifies the property name.
+.LP
+.eM
+The
+.PN XDeleteProperty
+function deletes the specified property only if the
+property was defined on the specified window
+and causes the X server to generate a
+.PN PropertyNotify
+event on the window unless the property does not exist.
+.LP
+.PN XDeleteProperty
+can generate
+.PN BadAtom
+and
+.PN BadWindow 
+errors.
+.NH 2
+Selections
+.XS
+\*(SN Selections
+.XE
+.LP
+.IN "Selection"
+Selections are one method used by applications to exchange data.
+By using the property mechanism,
+applications can exchange data of arbitrary types and can negotiate
+the type of the data.
+A selection can be thought of as an indirect property with a dynamic type.
+That is, rather than having the property stored in the X server,
+the property is maintained by some client (the owner).
+A selection is global in nature (considered to belong to the user 
+but be maintained by clients) rather than being private to a particular 
+window subhierarchy or a particular set of clients.
+.LP
+Xlib provides functions that you can use to set, get, or request conversion
+of selections.
+This allows applications to implement the notion of current selection,
+which requires that notification be sent to applications when they no 
+longer own the selection.
+Applications that support selection often highlight the current selection
+and so must be informed when another application has
+acquired the selection so that they can unhighlight the selection.
+.LP
+When a client asks for the contents of
+a selection, it specifies a selection target type.
+This target type
+can be used to control the transmitted representation of the contents.
+For example, if the selection is ``the last thing the user clicked on''
+and that is currently an image, then the target type might specify
+whether the contents of the image should be sent in XY format or Z format.
+.LP
+The target type can also be used to control the class of
+contents transmitted, for example, 
+asking for the ``looks'' (fonts, line
+spacing, indentation, and so forth) of a paragraph selection, not the
+text of the paragraph.
+The target type can also be used for other
+purposes.
+The protocol does not constrain the semantics.
+.LP
+.sp
+To set the selection owner, use 
+.PN XSetSelectionOwner .
+.IN "Selection" "setting the owner"
+.IN "XSetSelectionOwner" "" "@DEF@"
+.sM
+.FD 0
+XSetSelectionOwner\^(\^\fIdisplay\fP, \fIselection\fP\^, \fIowner\fP\^, \fItime\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Atom \fIselection\fP\^;
+.br
+      Window \fIowner\fP\^; 
+.br
+      Time \fItime\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIselection\fP 1i
+Specifies the selection atom.
+.IP \fIowner\fP 1i
+Specifies the owner of the specified selection atom.
+You can pass a window or
+.PN None .
+.IP \fItime\fP 1i
+Specifies the time.
+You can pass either a timestamp or
+.PN CurrentTime .
+.LP
+.eM
+The
+.PN XSetSelectionOwner
+function changes the owner and last-change time for the specified selection
+and has no effect if the specified time is earlier than the current
+last-change time of the specified selection 
+or is later than the current X server time.
+Otherwise, the last-change time is set to the specified time,
+with
+.PN CurrentTime
+replaced by the current server time.
+If the owner window is specified as
+.PN None ,
+then the owner of the selection becomes 
+.PN None
+(that is, no owner).
+Otherwise, the owner of the selection becomes the client executing
+the request.
+.LP 
+If the new owner (whether a client or
+.PN None )
+is not
+the same as the current owner of the selection and the current
+owner is not
+.PN None ,
+the current owner is sent a 
+.PN SelectionClear 
+event.
+If the client that is the owner of a selection is later
+terminated (that is, its connection is closed)
+or if the owner window it has specified in the request is later
+destroyed,
+the owner of the selection automatically
+reverts to
+.PN None ,
+but the last-change time is not affected.
+The selection atom is uninterpreted by the X server.
+.PN XGetSelectionOwner
+returns the owner window, which is reported in 
+.PN SelectionRequest
+and
+.PN SelectionClear
+events.
+Selections are global to the X server.
+.LP
+.PN XSetSelectionOwner
+can generate
+.PN BadAtom
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To return the selection owner, use 
+.PN XGetSelectionOwner .
+.IN "Selection" "getting the owner"
+.IN "XGetSelectionOwner" "" "@DEF@"
+.sM
+.FD 0
+Window XGetSelectionOwner\^(\^\fIdisplay\fP, \fIselection\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Atom \fIselection\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Se whose owner you want returned
+.IP \fIselection\fP 1i
+Specifies the selection atom \*(Se.
+.LP
+.eM
+The
+.PN XGetSelectionOwner
+function
+returns the window ID associated with the window that currently owns the
+specified selection.
+If no selection was specified, the function returns the constant
+.PN None .
+If
+.PN None
+is returned,
+there is no owner for the selection.
+.LP
+.PN XGetSelectionOwner
+can generate a
+.PN BadAtom 
+error.
+.LP
+.sp
+To request conversion of a selection, use 
+.PN XConvertSelection .
+.IN "Selection" "converting"
+.IN "XConvertSelection" "" "@DEF@"
+.sM
+.FD 0
+XConvertSelection\^(\^\fIdisplay\fP, \fIselection\fP\^, \fItarget\fP\^, \fIproperty\fP\^, \fIrequestor\fP\^, \fItime\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Atom \fIselection\fP\^, \fItarget\fP\^;
+.br
+      Atom \fIproperty\fP\^;
+.br
+      Window \fIrequestor\fP\^;
+.br
+      Time \fItime\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIselection\fP 1i
+Specifies the selection atom.
+.IP \fItarget\fP 1i
+Specifies the target atom.
+.IP \fIproperty\fP 1i
+Specifies the property name.
+You also can pass 
+.PN None .
+.IP \fIrequestor\fP 1i
+Specifies the requestor.
+.IP \fItime\fP 1i
+Specifies the time.
+You can pass either a timestamp or
+.PN CurrentTime .
+.LP
+.eM
+.PN XConvertSelection
+requests that the specified selection be converted to the specified target
+type:
+.IP \(bu 5
+If the specified selection has an owner, the X server sends a
+.PN SelectionRequest
+event to that owner.
+.IP \(bu 5
+If no owner for the specified
+selection exists, the X server generates a
+.PN SelectionNotify
+event to the
+requestor with property
+.PN None .
+.LP
+The arguments are passed on unchanged in either of the events.
+There are two predefined selection atoms: PRIMARY and SECONDARY.
+.LP
+.PN XConvertSelection
+can generate
+.PN BadAtom
+and
+.PN BadWindow 
+errors.
+.bp
diff --git a/specs/libX11/CH05 b/specs/libX11/CH05
new file mode 100644
index 00000000..6ea21837
--- /dev/null
+++ b/specs/libX11/CH05
@@ -0,0 +1,518 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 5\fP\s-1
+
+\s+1\fBPixmap and Cursor Functions\fP\s-1
+.sp 2
+.nr H1 5
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.na
+.LP
+.XS
+Chapter 5: Pixmap and Cursor Functions 
+.XE
+Once you have connected to an X server,
+you can use the Xlib functions to:
+.IP \(bu 5
+Create and free pixmaps
+.IP \(bu 5
+Create, recolor, and free cursors
+.NH 2
+Creating and Freeing Pixmaps
+.XS
+\*(SN Creating and Freeing Pixmaps
+.XE
+.LP
+Pixmaps can only be used on the screen on which they were created.
+Pixmaps are off-screen resources that are used for various operations,
+such as defining cursors as tiling patterns 
+or as the source for certain raster operations.
+Most graphics requests can operate either on a window or on a pixmap.
+A bitmap is a single bit-plane pixmap.
+.LP
+.sp
+To create a pixmap of a given size, use
+.PN XCreatePixmap .
+.IN "XCreatePixmap" "" "@DEF@"
+.sM
+.FD 0
+Pixmap XCreatePixmap\^(\^\fIdisplay\fP, \fId\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIdepth\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
+.br
+      unsigned int \fIdepth\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies which screen the pixmap is created on. 
+.ds Wh , which define the dimensions of the pixmap
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height\*(Wh.
+.IP \fIdepth\fP 1i
+Specifies the depth of the pixmap.
+.LP
+.eM 
+The
+.PN XCreatePixmap
+function creates a pixmap of the width, height, and depth you specified
+and returns a pixmap ID that identifies it.
+It is valid to pass an 
+.PN InputOnly
+window to the drawable argument.
+The width and height arguments must be nonzero,
+or a 
+.PN BadValue
+error results.
+The depth argument must be one of the depths supported by the screen
+of the specified drawable,
+or a
+.PN BadValue
+error results.
+.LP
+The server uses the specified drawable to determine on which screen
+to create the pixmap.
+The pixmap can be used only on this screen
+and only with other drawables of the same depth (see
+.PN XCopyPlane
+for an exception to this rule).
+The initial contents of the pixmap are undefined.
+.LP
+.PN XCreatePixmap
+can generate
+.PN BadAlloc ,
+.PN BadDrawable ,
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To free all storage associated with a specified pixmap, use
+.PN XFreePixmap .
+.IN "XFreePixmap" "" "@DEF@"
+.sM
+.FD 0
+XFreePixmap\^(\^\fIdisplay\fP, \fIpixmap\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Pixmap \fIpixmap\fP\^;
+.FN	
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIpixmap\fP 1i
+Specifies the pixmap.
+.LP
+.eM 
+The
+.PN XFreePixmap
+function first deletes the association between the pixmap ID and the pixmap.
+Then, the X server frees the pixmap storage when there are no references to it.
+The pixmap should never be referenced again.
+.LP
+.PN XFreePixmap
+can generate a
+.PN BadPixmap 
+error.
+.NH 2
+Creating, Recoloring, and Freeing Cursors
+.XS
+\*(SN Creating, Recoloring, and Freeing Cursors 
+.XE
+.LP
+Each window can have a different cursor defined for it.
+Whenever the pointer is in a visible window, 
+it is set to the cursor defined for that window.
+If no cursor was defined for that window, 
+the cursor is the one defined for the parent window.
+.LP
+From X's perspective, 
+a cursor consists of a cursor source, mask, colors, and a hotspot. 
+The mask pixmap determines the shape of the cursor and must be a depth
+of one.
+The source pixmap must have a depth of one,
+and the colors determine the colors of the source.
+The hotspot defines the point on the cursor that is reported
+when a pointer event occurs.
+There may be limitations imposed by the hardware on
+cursors as to size and whether a mask is implemented. 
+.IN "XQueryBestCursor"
+.PN XQueryBestCursor
+can be used to find out what sizes are possible.
+There is a standard font for creating cursors, but
+Xlib provides functions that you can use to create cursors
+from an arbitrary font or from bitmaps.
+.LP
+.sp
+To create a cursor from the standard cursor font, use
+.PN XCreateFontCursor .
+.IN "XCreateFontCursor" "" "@DEF@"
+.sM
+.FD 0
+#include <X11/cursorfont.h>
+.sp 6p
+Cursor XCreateFontCursor\^(\^\fIdisplay\fP, \fIshape\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      unsigned int \fIshape\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIshape\fP 1i
+Specifies the shape of the cursor.
+.LP
+.eM
+X provides a set of standard cursor shapes in a special font named
+cursor.
+Applications are encouraged to use this interface for their cursors
+because the font can be customized for the individual display type.
+The shape argument specifies which glyph of the standard fonts
+to use.
+.LP
+The hotspot comes from the information stored in the cursor font.
+The initial colors of a cursor are a black foreground and a white
+background (see
+.PN XRecolorCursor ).
+For further information about cursor shapes,
+see appendix B.
+.LP
+.PN XCreateFontCursor
+can generate
+.PN BadAlloc
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To create a cursor from font glyphs, use
+.PN XCreateGlyphCursor .
+.IN "XCreateGlyphCursor" "" "@DEF@"
+.sM
+.FD 0
+Cursor XCreateGlyphCursor\^(\^\fIdisplay\fP, \fIsource_font\fP\^, \fImask_font\fP\^, \fIsource_char\fP\^, \fImask_char\fP\^,
+.br
+                           \fIforeground_color\fP\^, \fIbackground_color\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Font \fIsource_font\fP\^, \fImask_font\fP\^;
+.br
+      unsigned int \fIsource_char\fP\^, \fImask_char\fP\^;
+.br
+      XColor *\fIforeground_color\fP\^;
+.br
+      XColor *\fIbackground_color\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIsource_font\fP 1i
+Specifies the font for the source glyph.
+.IP \fImask_font\fP 1i
+Specifies the font for the mask glyph or
+.PN None .
+.IP \fIsource_char\fP 1i
+Specifies the character glyph for the source.
+.IP \fImask_char\fP 1i
+Specifies the glyph character for the mask. 
+.IP \fIforeground_color\fP 1i
+Specifies the RGB values for the foreground of the source. 
+.IP \fIbackground_color\fP 1i
+Specifies the RGB values for the background of the source.
+.LP
+.eM
+The
+.PN XCreateGlyphCursor
+function is similar to
+.PN XCreatePixmapCursor
+except that the source and mask bitmaps are obtained from the specified 
+font glyphs.
+The source_char must be a defined glyph in source_font, 
+or a
+.PN BadValue
+error results.
+If mask_font is given, 
+mask_char must be a defined glyph in mask_font,
+or a
+.PN BadValue
+error results.
+The mask_font and character are optional.
+The origins of the source_char and mask_char (if defined) glyphs are
+positioned coincidently and define the hotspot. 
+The source_char and mask_char need not have the same bounding box metrics, 
+and there is no restriction on the placement of the hotspot relative to the bounding
+boxes. 
+If no mask_char is given, all pixels of the source are displayed.
+You can free the fonts immediately by calling
+.PN XFreeFont
+if no further explicit references to them are to be made. 
+.LP
+For 2-byte matrix fonts, 
+the 16-bit value should be formed with the byte1
+member in the most significant byte and the byte2 member in the 
+least significant byte.
+.LP
+.PN XCreateGlyphCursor
+can generate
+.PN BadAlloc ,
+.PN BadFont ,
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To create a cursor from two bitmaps,
+use
+.PN XCreatePixmapCursor .
+.IN "XCreatePixmapCursor" "" "@DEF@"
+.sM
+.FD 0
+Cursor XCreatePixmapCursor\^(\^\fIdisplay\fP, \fIsource\fP\^, \fImask\fP\^, \fIforeground_color\fP\^, \fIbackground_color\fP\^, \fIx\fP\^, \fIy\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Pixmap \fIsource\fP\^;
+.br
+      Pixmap \fImask\fP\^;
+.br
+      XColor *\fIforeground_color\fP\^;
+.br
+      XColor *\fIbackground_color\fP\^;
+.br
+      unsigned int \fIx\fP\^, \fIy\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIsource\fP 1i
+Specifies the shape of the source cursor.
+.\" *** JIM: NEED TO CHECK THIS. ***
+.IP \fImask\fP 1i
+Specifies the cursor's source bits to be displayed or
+.PN None .
+.IP \fIforeground_color\fP 1i
+Specifies the RGB values for the foreground of the source. 
+.IP \fIbackground_color\fP 1i
+Specifies the RGB values for the background of the source.
+.ds Xy , which indicate the hotspot relative to the source's origin
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.LP
+.eM
+The
+.PN XCreatePixmapCursor
+function creates a cursor and returns the cursor ID associated with it.
+The foreground and background RGB values must be specified using
+foreground_color and background_color,
+even if the X server only has a
+.PN StaticGray
+or
+.PN GrayScale
+screen.
+The foreground color is used for the pixels set to 1 in the
+source, and the background color is used for the pixels set to 0.
+Both source and mask, if specified, must have depth one (or a 
+.PN BadMatch
+error results) but can have any root.
+The mask argument defines the shape of the cursor.
+The pixels set to 1 in the mask define which source pixels are displayed,
+and the pixels set to 0 define which pixels are ignored.
+If no mask is given, 
+all pixels of the source are displayed.
+The mask, if present, must be the same size as the pixmap defined by the 
+source argument, or a
+.PN BadMatch
+error results.
+The hotspot must be a point within the source,
+or a
+.PN BadMatch
+error results.
+.LP
+The components of the cursor can be transformed arbitrarily to meet
+display limitations.
+The pixmaps can be freed immediately if no further explicit references
+to them are to be made.
+Subsequent drawing in the source or mask pixmap has an undefined effect on the
+cursor.
+The X server might or might not make a copy of the pixmap.
+.LP
+.PN XCreatePixmapCursor
+can generate
+.PN BadAlloc
+and
+.PN BadPixmap
+errors.
+.LP
+.sp
+To determine useful cursor sizes, use
+.PN XQueryBestCursor .
+.IN "XQueryBestCursor" "" "@DEF@"
+.sM
+.FD 0
+Status XQueryBestCursor\^(\^\fIdisplay\fP, \fId\fP, \fIwidth\fP\^, \fIheight\fP\^, \fIwidth_return\fP\^, \fIheight_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
+.br
+      unsigned int *\fIwidth_return\fP\^, *\fIheight_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Dr , which indicates the screen
+.IP \fId\fP 1i
+Specifies the drawable\*(Dr. 
+.ds Wh \ of the cursor that you want the size information for
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height\*(Wh.
+.IP \fIwidth_return\fP 1i
+.br
+.ns
+.IP \fIheight_return\fP 1i
+Return the best width and height that is closest to the specified width 
+and height.
+.LP
+.eM
+Some displays allow larger cursors than other displays.
+The
+.PN XQueryBestCursor
+function provides a way to find out what size cursors are actually
+possible on the display.
+.IN "Cursor" "limitations" 
+It returns the largest size that can be displayed.
+Applications should be prepared to use smaller cursors on displays that
+cannot support large ones.
+.LP
+.PN XQueryBestCursor
+can generate a
+.PN BadDrawable 
+error.
+.LP
+.sp
+To change the color of a given cursor, use
+.PN XRecolorCursor .
+.IN "XRecolorCursor" "" "@DEF@"
+.sM
+.FD 0
+XRecolorCursor\^(\^\fIdisplay\fP, \fIcursor\fP\^, \fIforeground_color\fP\^, \fIbackground_color\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Cursor \fIcursor\fP\^;
+.br
+      XColor *\fIforeground_color\fP\^, *\fIbackground_color\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcursor\fP 1i
+Specifies the cursor. 
+.IP \fIforeground_color\fP 1i
+Specifies the RGB values for the foreground of the source. 
+.IP \fIbackground_color\fP 1i
+Specifies the RGB values for the background of the source.
+.LP
+.eM
+The
+.PN XRecolorCursor
+function changes the color of the specified cursor, and
+if the cursor is being displayed on a screen,
+the change is visible immediately.
+The pixel members of the
+.PN XColor
+structures are ignored; only the RGB values are used.
+.LP
+.PN XRecolorCursor
+can generate a
+.PN BadCursor 
+error.
+.LP
+.sp
+To free (destroy) a given cursor, use
+.PN XFreeCursor .
+.IN "XFreeCursor" "" "@DEF@"
+.sM
+.FD 0
+XFreeCursor\^(\^\fIdisplay\fP, \fIcursor\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Cursor \fIcursor\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcursor\fP 1i
+Specifies the cursor. 
+.LP
+.eM 
+The
+.PN XFreeCursor
+function deletes the association between the cursor resource ID 
+and the specified cursor.
+The cursor storage is freed when no other resource references it.
+The specified cursor ID should not be referred to again.
+.LP
+.PN XFreeCursor
+can generate a
+.PN BadCursor 
+error.
+.bp
diff --git a/specs/libX11/CH06 b/specs/libX11/CH06
new file mode 100644
index 00000000..44824d32
--- /dev/null
+++ b/specs/libX11/CH06
@@ -0,0 +1,4773 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 6\fP\s-1
+
+\s+1\fBColor Management Functions\fP\s-1
+.sp 2
+.nr H1 6
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.na
+.LP
+.XS
+Chapter 6: Color Management Functions 
+.XE
+Each X window always has an associated colormap that
+provides a level of indirection between pixel values and colors displayed
+on the screen.
+Xlib provides functions that you can use to manipulate a colormap.
+The X protocol defines colors using values in the RGB color space.
+The RGB color space is device dependent;
+rendering an RGB value on differing output devices typically results
+in different colors.
+Xlib also provides a means for clients to specify color using
+device-independent color spaces for consistent results across devices.
+Xlib supports device-independent color spaces derivable from the CIE XYZ
+color space.
+This includes the CIE XYZ, xyY, L*u*v*, and L*a*b* color spaces as well as
+the TekHVC color space.
+.LP
+This chapter discusses how to:
+.IP \(bu 5
+Create, copy, and destroy a colormap
+.IP \(bu 5
+Specify colors by name or value
+.IP \(bu 5
+Allocate, modify, and free color cells
+.IP \(bu 5
+Read entries in a colormap
+.IP \(bu 5
+Convert between color spaces
+.IP \(bu 5
+Control aspects of color conversion
+.IP \(bu 5
+Query the color gamut of a screen
+.IP \(bu 5
+Add new color spaces
+.LP
+All functions, types, and symbols in this chapter with the prefix ``Xcms''
+are defined in
+.hN X11/Xcms.h .
+The remaining functions and types are defined in
+.hN X11/Xlib.h .
+.LP
+Functions in this chapter manipulate the representation of color on the
+screen.
+For each possible value that a pixel can take in a window,
+there is a color cell in the colormap.
+For example, 
+if a window is 4 bits deep, pixel values 0 through 15 are defined. 
+A colormap is a collection of color cells.
+A color cell consists of a triple of red, green, and blue (RGB) values.
+The hardware imposes limits on the number of significant
+bits in these values.
+As each pixel is read out of display memory, the pixel
+is looked up in a colormap.
+The RGB value of the cell determines what color is displayed on the screen.
+On a grayscale display with a black-and-white monitor, 
+the values are combined to determine the brightness on the screen.
+.LP
+Typically, an application allocates color cells or sets of color cells
+to obtain the desired colors.
+The client can allocate read-only cells.
+In which case, 
+the pixel values for these colors can be shared among multiple applications, 
+and the RGB value of the cell cannot be changed.
+If the client allocates read/write cells,
+they are exclusively owned by the client,
+and the color associated with the pixel value can be changed at will.
+Cells must be allocated (and, if read/write, initialized with an RGB value)
+by a client to obtain desired colors.
+The use of pixel value for an
+unallocated cell results in an undefined color.
+.LP
+Because colormaps are associated with windows, X supports displays
+with multiple colormaps and, indeed, different types of colormaps.
+If there are insufficient colormap resources in the display,
+some windows will display in their true colors, and others
+will display with incorrect colors.
+A window manager usually controls which windows are displayed
+in their true colors if more than one colormap is required for
+the color resources the applications are using.
+At any time, there is a set of installed colormaps for a screen.
+Windows using one of the installed colormaps display with true colors, and
+windows using other colormaps generally display with incorrect colors.
+You can control the set of installed colormaps by using
+.PN XInstallColormap
+and
+.PN XUninstallColormap .
+.LP
+Colormaps are local to a particular screen.
+Screens always have a default colormap,
+and programs typically allocate cells out of this colormap.
+Generally, you should not write applications that monopolize 
+color resources.
+Although some hardware supports multiple colormaps installed at one time,
+many of the hardware displays
+built today support only a single installed colormap, so the primitives
+are written to encourage sharing of colormap entries between applications.
+.LP
+The 
+.PN DefaultColormap 
+macro returns the default colormap.
+The 
+.PN DefaultVisual 
+macro
+returns the default visual type for the specified screen.
+.IN "Color map"
+Possible visual types are 
+.PN StaticGray , 
+.PN GrayScale , 
+.PN StaticColor ,
+.PN PseudoColor , 
+.PN TrueColor , 
+or 
+.PN DirectColor 
+(see section 3.1).
+.NH 2
+Color Structures
+.XS
+\*(SN Color Structures
+.XE
+.LP
+Functions that operate only on RGB color space values use an
+.PN XColor
+structure, which contains:
+.LP
+.IN "XColor" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	unsigned long pixel;	/* pixel value */
+	unsigned short red, green, blue;	/* rgb values */
+	char flags;	/* DoRed, DoGreen, DoBlue */	
+	char pad;
+} XColor;
+.De
+.LP
+.eM
+The red, green, and blue values are always in the range 0 to 65535
+inclusive, independent of the number of bits actually used in the
+display hardware.
+The server scales these values down to the range used by the hardware.
+Black is represented by (0,0,0), 
+and white is represented by (65535,65535,65535).
+.IN "Color"
+In some functions,
+the flags member controls which of the red, green, and blue members is used 
+and can be the inclusive OR of zero or more of
+.PN DoRed ,
+.PN DoGreen ,
+and 
+.PN DoBlue .
+.LP
+.sp
+Functions that operate on all color space values use an
+.PN XcmsColor
+structure.
+This structure contains a union of substructures,
+each supporting color specification encoding for a particular color space.
+Like the
+.PN XColor
+structure, the
+.PN XcmsColor
+structure contains pixel
+and color specification information (the spec member in the 
+.PN XcmsColor
+structure).
+.IN "XcmsColor" "" "@DEF@"
+.sM
+.LP
+.Ds 0
+.TA .5i 1i 2.5i
+.ta .5i 1i 2.5i
+typedef unsigned long XcmsColorFormat;			/* Color Specification Format */
+
+typedef struct {
+	union {
+		XcmsRGB RGB;
+		XcmsRGBi RGBi;
+		XcmsCIEXYZ CIEXYZ;
+		XcmsCIEuvY CIEuvY;
+		XcmsCIExyY CIExyY;
+		XcmsCIELab CIELab;
+		XcmsCIELuv CIELuv;
+		XcmsTekHVC TekHVC;
+		XcmsPad Pad;
+	} spec;
+	unsigned long pixel;
+	XcmsColorFormat format;
+} XcmsColor;			/* Xcms Color Structure */
+.De
+.LP
+.eM
+Because the color specification can be encoded for the various color spaces, 
+encoding for the spec member is identified by the format member,
+which is of type
+.PN XcmsColorFormat .
+The following macros define standard formats.
+.sM
+.TS
+lw(.5i) lw(1.6i) lw(1.4i) lw(1.5i).
+T{
+#define
+T}	T{
+.PN XcmsUndefinedFormat
+T}	T{
+0x00000000
+T}
+T{
+#define
+T}	T{
+.PN XcmsCIEXYZFormat
+T}	T{
+0x00000001
+T}	T{
+/* CIE XYZ */
+T}
+T{
+#define
+T}	T{
+.PN XcmsCIEuvYFormat
+T}	T{
+0x00000002
+T}	T{
+/* CIE u'v'Y */
+T}
+T{
+#define
+T}	T{
+.PN XcmsCIExyYFormat
+T}	T{
+0x00000003
+T}	T{
+/* CIE xyY */
+T}
+T{
+#define
+T}	T{
+.PN XcmsCIELabFormat
+T}	T{
+0x00000004
+T}	T{
+/* CIE L*a*b* */
+T}
+T{
+#define
+T}	T{
+.PN XcmsCIELuvFormat
+T}	T{
+0x00000005
+T}	T{
+/* CIE L*u*v* */
+T}
+T{
+#define
+T}	T{
+.PN XcmsTekHVCFormat
+T}	T{
+0x00000006
+T}	T{
+/* TekHVC */
+T}
+T{
+#define
+T}	T{
+.PN XcmsRGBFormat
+T}	T{
+0x80000000
+T}	T{
+/* RGB Device */
+T}
+T{
+#define
+T}	T{
+.PN XcmsRGBiFormat
+T}	T{
+0x80000001
+T}	T{
+/* RGB Intensity */
+T}
+.TE
+.LP
+.eM
+Formats for device-independent color spaces are
+distinguishable from those for device-dependent spaces by the 32nd bit.
+If this bit is set,
+it indicates that the color specification is in a device-dependent form;
+otherwise, it is in a device-independent form.
+If the 31st bit is set,
+this indicates that the color space has been added to Xlib at run time
+(see section 6.12.4).
+The format value for a color space added at run time may be different each
+time the program is executed.
+If references to such a color space must be made outside the client
+(for example, storing a color specification in a file),
+then reference should be made by color space string prefix
+(see 
+.PN XcmsFormatOfPrefix
+and
+.PN XcmsPrefixOfFormat ).
+.LP
+Data types that describe the color specification encoding for the various
+color spaces are defined as follows:
+.sM
+.IN "XcmsRGB" "" "@DEF@"
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef double XcmsFloat;
+
+typedef struct {
+	unsigned short red;	/* 0x0000 to 0xffff */
+	unsigned short green;	/* 0x0000 to 0xffff */
+	unsigned short blue;	/* 0x0000 to 0xffff */
+} XcmsRGB;		/* RGB Device */
+.De
+.IN "XcmsRGBi" "" "@DEF@"
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	XcmsFloat red;	/* 0.0 to 1.0 */
+	XcmsFloat green;	/* 0.0 to 1.0 */
+	XcmsFloat blue;	/* 0.0 to 1.0 */
+} XcmsRGBi;		/* RGB Intensity */
+.De
+.IN "XcmsCIEXYZ" "" "@DEF@"
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	XcmsFloat X;
+	XcmsFloat Y;	/* 0.0 to 1.0 */
+	XcmsFloat Z;
+} XcmsCIEXYZ;		/* CIE XYZ */
+.De
+.IN "XcmsCIEuvY" "" "@DEF@"
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	XcmsFloat u_prime;	/* 0.0 to ~0.6 */
+	XcmsFloat v_prime;	/* 0.0 to ~0.6 */
+	XcmsFloat Y; 	/* 0.0 to 1.0 */
+} XcmsCIEuvY;		/* CIE u'v'Y */
+.De
+.IN "XcmsCIExyY" "" "@DEF@"
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	XcmsFloat x; 	/* 0.0 to ~.75 */
+	XcmsFloat y; 	/* 0.0 to ~.85 */
+	XcmsFloat Y; 	/* 0.0 to 1.0 */
+} XcmsCIExyY;		/* CIE xyY */
+.De
+.IN "XcmsCIELab" "" "@DEF@"
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	XcmsFloat L_star; 	/* 0.0 to 100.0 */
+	XcmsFloat a_star;
+	XcmsFloat b_star;
+} XcmsCIELab;		/* CIE L*a*b* */
+.De
+.IN "XcmsCIELuv" "" "@DEF@"
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	XcmsFloat L_star; 	/* 0.0 to 100.0 */
+	XcmsFloat u_star;
+	XcmsFloat v_star;
+} XcmsCIELuv;		/* CIE L*u*v* */
+.De
+.IN "XcmsTekHVC" "" "@DEF@"
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	XcmsFloat H; 	/* 0.0 to 360.0 */
+	XcmsFloat V; 	/* 0.0 to 100.0 */
+	XcmsFloat C; 	/* 0.0 to 100.0 */
+} XcmsTekHVC;		/* TekHVC */
+.De
+.IN "XcmsPad" "" "@DEF@"
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	XcmsFloat pad0;
+	XcmsFloat pad1;
+	XcmsFloat pad2;
+	XcmsFloat pad3;
+} XcmsPad;		/* four doubles */
+.De
+.LP
+.eM
+The device-dependent formats provided allow color specification in:
+.IP \(bu 5
+RGB Intensity
+.Pn ( XcmsRGBi )
+.IP
+Red, green, and blue linear intensity values,
+floating-point values from 0.0 to 1.0,
+where 1.0 indicates full intensity, 0.5 half intensity, and so on.
+.IP \(bu 5
+RGB Device
+.Pn ( XcmsRGB )
+.IP
+Red, green, and blue values appropriate for the specified output device.
+.PN XcmsRGB
+values are of type unsigned short,
+scaled from 0 to 65535 inclusive,
+and are interchangeable with the red, green, and blue values in an 
+.PN XColor
+structure. 
+.LP
+It is important to note that RGB Intensity values are not gamma corrected
+values.
+In contrast,
+RGB Device values generated as a result of converting color specifications 
+are always gamma corrected, and
+RGB Device values acquired as a result of querying a colormap
+or passed in by the client are assumed by Xlib to be gamma corrected.
+The term \fIRGB value\fP in this manual always refers to an RGB Device value.
+.NH 2
+Color Strings
+.XS
+\*(SN Color Strings
+.XE
+.LP
+Xlib provides a mechanism for using string names for colors.
+A color string may either contain an abstract color name
+or a numerical color specification.
+Color strings are case-insensitive.
+.LP
+Color strings are used in the following functions:
+.IP \(bu 5
+.PN XAllocNamedColor
+.IP \(bu 5
+.PN XcmsAllocNamedColor
+.IP \(bu 5
+.PN XLookupColor
+.IP \(bu 5
+.PN XcmsLookupColor
+.IP \(bu 5
+.PN XParseColor
+.IP \(bu 5
+.PN XStoreNamedColor
+.LP
+Xlib supports the use of abstract color names, for example, red or blue.
+A value for this abstract name is obtained by searching one or more color
+name databases.
+Xlib first searches zero or more client-side databases;
+the number, location, and content of these databases is
+implementation-dependent and might depend on the current locale.
+If the name is not found, Xlib then looks for the color in the
+X server's database.
+If the color name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+.LP
+A numerical color specification
+consists of a color space name and a set of values in the following syntax:
+.LP
+.sM
+.Ds 0
+\fI<color_space_name>\fP:\fI<value>/.../<value>\fP
+.De
+.LP
+.eM
+The following are examples of valid color strings.
+.LP
+.Ds 0
+"CIEXYZ:0.3227/0.28133/0.2493"
+"RGBi:1.0/0.0/0.0"
+"rgb:00/ff/00"
+"CIELuv:50.0/0.0/0.0"
+.De
+The syntax and semantics of numerical specifications are given
+for each standard color space in the following sections.
+.NH 3
+RGB Device String Specification
+.XS
+\*(SN RGB Device String Specification
+.XE
+.LP
+An RGB Device specification is identified by
+the prefix ``rgb:'' and conforms to the following syntax:
+.LP
+.\" Start marker code here
+.Ds 0
+rgb:\fI<red>/<green>/<blue>\fP
+
+    \fI<red>\fP, \fI<green>\fP, \fI<blue>\fP := \fIh\fP | \fIhh\fP | \fIhhh\fP | \fIhhhh\fP
+    \fIh\fP := single hexadecimal digits (case insignificant)
+.De
+.\" End marker code here
+.LP
+Note that \fIh\fP indicates the value scaled in 4 bits, 
+\fIhh\fP the value scaled in 8 bits,
+\fIhhh\fP the value scaled in 12 bits,
+and \fIhhhh\fP the value scaled in 16 bits, respectively.
+.LP
+Typical examples are the strings ``rgb:ea/75/52'' and ``rgb:ccc/320/320'',
+but mixed numbers of hexadecimal digit strings 
+(``rgb:ff/a5/0'' and ``rgb:ccc/32/0'')
+are also allowed.
+.LP
+For backward compatibility, an older syntax for RGB Device is
+supported, but its continued use is not encouraged.
+The syntax is an initial sharp sign character followed by
+a numeric specification, in one of the following formats:
+.LP
+.\" Start marker code here
+.Ds 0
+.TA 2i
+.ta 2i
+#RGB	(4 bits each)
+#RRGGBB	(8 bits each)
+#RRRGGGBBB	(12 bits each)
+#RRRRGGGGBBBB	(16 bits each)
+.De
+.\" End marker code here
+.LP
+The R, G, and B represent single hexadecimal digits.
+When fewer than 16 bits each are specified, 
+they represent the most significant bits of the value
+(unlike the ``rgb:'' syntax, in which values are scaled).
+For example, the string ``#3a7'' is the same as ``#3000a0007000''.
+.NH 3
+RGB Intensity String Specification
+.XS
+\*(SN RGB Intensity String Specification
+.XE
+.LP
+An RGB intensity specification is identified
+by the prefix ``rgbi:'' and conforms to the following syntax:
+.LP
+.\" Start marker code here
+.Ds 0
+rgbi:\fI<red>/<green>/<blue>\fP
+.De
+.\" End marker code here
+.LP
+Note that red, green, and blue are floating-point values
+between 0.0 and 1.0, inclusive.
+The input format for these values is an optional sign,
+a string of numbers possibly containing a decimal point,
+and an optional exponent field containing an E or e 
+followed by a possibly signed integer string.
+.NH 3
+Device-Independent String Specifications
+.XS
+\*(SN Device-Independent String Specifications
+.XE
+.LP
+The standard device-independent string specifications have
+the following syntax:
+.LP
+.\" Start marker code here
+.Ds 0
+CIEXYZ:\fI<X>/<Y>/<Z>\fP
+CIEuvY:\fI<u>/<v>/<Y>\fP
+CIExyY:\fI<x>/<y>/<Y>\fP
+CIELab:\fI<L>/<a>/<b>\fP
+CIELuv:\fI<L>/<u>/<v>\fP
+TekHVC:\fI<H>/<V>/<C>\fP
+.De
+.\" End marker code here
+.LP
+All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are
+floating-point values.
+The syntax for these values is an optional plus or minus sign,
+a string of digits possibly containing a decimal point,
+and an optional exponent field consisting of an ``E'' or ``e''
+followed by an optional plus or minus followed by a string of digits.
+.NH 2
+Color Conversion Contexts and Gamut Mapping
+.XS
+\*(SN Color Conversion Contexts and Gamut Mapping
+.XE
+.LP
+When Xlib converts device-independent color specifications
+into device-dependent specifications and vice versa,
+it uses knowledge about the color limitations of the screen hardware.
+This information, typically called the device profile,
+.IN "Device profile"
+is available in a Color Conversion Context (CCC).
+.IN "Color Conversion Context"
+.IN "CCC"
+.LP
+Because a specified color may be outside the color gamut of the target screen
+and the white point associated with the color specification may differ
+from the white point inherent to the screen,
+Xlib applies gamut mapping when it encounters certain conditions:
+.IN "White point"
+.IP \(bu 5
+Gamut compression occurs when conversion of device-independent
+color specifications to device-dependent color specifications
+results in a color out of the target screen's gamut.
+.IP \(bu 5
+White adjustment occurs when the inherent white point of the screen
+differs from the white point assumed by the client.
+.LP
+Gamut handling methods are stored as callbacks in the CCC,
+which in turn are used by the color space conversion routines.
+Client data is also stored in the CCC for each callback.
+The CCC also contains the white point the client assumes to be
+associated with color specifications (that is, the Client White Point).
+.IN "Client White Point"
+.IN "Gamut compression"
+.IN "Gamut handling"
+.IN "White point adjustment"
+The client can specify the gamut handling callbacks and client data
+as well as the Client White Point.
+Xlib does not preclude the X client from performing other
+forms of gamut handling (for example, gamut expansion); 
+however, Xlib does not provide direct support for gamut handling
+other than white adjustment and gamut compression.
+.LP
+Associated with each colormap is an initial CCC transparently generated by
+Xlib.
+.IN "Color Conversion Context" "creation"
+Therefore,
+when you specify a colormap as an argument to an Xlib function,
+you are indirectly specifying a CCC.
+.IN "CCC" "of colormap"
+.IN "Color Conversion Context" "of colormap"
+There is a default CCC associated with each screen.
+Newly created CCCs inherit attributes from the default CCC,
+so the default CCC attributes can be modified to affect new CCCs.
+.IN "CCC" "default"
+.IN "Color Conversion Context" "default"
+.LP
+Xcms functions in which gamut mapping can occur return
+.PN Status 
+and have specific status values defined for them, 
+as follows:
+.IP \(bu 5
+.PN XcmsFailure
+indicates that the function failed.
+.IP \(bu 5
+.PN XcmsSuccess
+indicates that the function succeeded.
+In addition,
+if the function performed any color conversion,
+the colors did not need to be compressed.
+.IP \(bu 5
+.PN XcmsSuccessWithCompression
+indicates the function performed color conversion
+and at least one of the colors needed to be compressed.
+The gamut compression method is determined by the gamut compression
+procedure in the CCC that is specified directly as a function argument
+or in the CCC indirectly specified by means of the colormap argument.
+.NH 2
+Creating, Copying, and Destroying Colormaps
+.XS
+\*(SN Creating, Copying, and Destroying Colormaps
+.XE
+.LP
+To create a colormap for a screen, use
+.PN XCreateColormap .
+.IN "XCreateColormap" "" "@DEF@"
+.sM
+.FD 0
+Colormap XCreateColormap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIvisual\fP\^, \fIalloc\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Visual *\fIvisual\fP\^;
+.br
+      int \fIalloc\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Wi on whose screen you want to create a colormap
+.IP \fIw\fP 1i
+Specifies the window \*(Wi.
+.IP \fIvisual\fP 1i
+Specifies a visual type supported on the screen.
+If the visual type is not one supported by the screen, 
+a
+.PN BadMatch
+error results.
+.IP \fIalloc\fP 1i
+Specifies the colormap entries to be allocated.
+You can pass 
+.PN AllocNone 
+or 
+.PN AllocAll .
+.LP
+.eM
+The
+.PN XCreateColormap
+function creates a colormap of the specified visual type for the screen 
+on which the specified window resides and returns the colormap ID 
+associated with it.
+Note that the specified window is only used to determine the screen.
+.LP
+The initial values of the colormap entries are undefined for the 
+visual classes
+.PN GrayScale ,
+.PN PseudoColor ,
+and
+.PN DirectColor .
+For
+.PN StaticGray ,
+.PN StaticColor ,
+and
+.PN TrueColor ,
+the entries have defined values,
+but those values are specific to the visual and are not defined by X.
+For
+.PN StaticGray ,
+.PN StaticColor ,
+and
+.PN TrueColor ,
+alloc must be
+.PN AllocNone ,
+or a
+.PN BadMatch
+error results.
+For the other visual classes,
+if alloc is
+.PN AllocNone ,
+the colormap initially has no allocated entries,
+and clients can allocate them.
+For information about the visual types,
+see section 3.1.
+.LP
+If alloc is
+.PN AllocAll ,
+the entire colormap is allocated writable.
+The initial values of all allocated entries are undefined.
+For
+.PN GrayScale
+and
+.PN PseudoColor ,
+the effect is as if an
+.PN XAllocColorCells
+call returned all pixel values from zero to N \- 1,
+where N is the colormap entries value in the specified visual.
+For
+.PN DirectColor ,
+the effect is as if an
+.PN XAllocColorPlanes
+call returned a pixel value of zero and red_mask, green_mask, 
+and blue_mask values containing the same bits as the corresponding
+masks in the specified visual.
+However, in all cases,
+none of these entries can be freed by using
+.PN XFreeColors .
+.LP
+.PN XCreateColormap
+can generate
+.PN BadAlloc ,
+.PN BadMatch ,
+.PN BadValue ,
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To create a new colormap when the allocation out of a previously
+shared colormap has failed because of resource exhaustion, use
+.PN XCopyColormapAndFree .
+.IN "XCopyColormapAndFree" "" "@DEF@"
+.sM
+.FD 0
+Colormap XCopyColormapAndFree\^(\^\fIdisplay\fP, \fIcolormap\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.LP
+.eM
+The
+.PN XCopyColormapAndFree
+function creates a colormap of the same visual type and for the same screen
+as the specified colormap and returns the new colormap ID.
+It also moves all of the client's existing allocation from the specified
+colormap to the new colormap with their color values intact 
+and their read-only or writable characteristics intact and frees those entries 
+in the specified colormap.
+Color values in other entries in the new colormap are undefined.
+If the specified colormap was created by the client with alloc set to
+.PN AllocAll ,
+the new colormap is also created with 
+.PN AllocAll ,
+all color values for all entries are copied from the specified colormap,
+and then all entries in the specified colormap are freed.
+If the specified colormap was not created by the client with
+.PN AllocAll ,
+the allocations to be moved are all those pixels and planes
+that have been allocated by the client using
+.PN XAllocColor ,
+.PN XAllocNamedColor ,
+.PN XAllocColorCells ,
+or
+.PN XAllocColorPlanes
+and that have not been freed since they were allocated.
+.LP
+.PN XCopyColormapAndFree
+can generate
+.PN BadAlloc
+and
+.PN BadColor 
+errors.
+.LP
+.sp
+To destroy a colormap, use 
+.PN XFreeColormap .
+.IN "XFreeColormap" "" "@DEF@"
+.sM
+.FD 0
+XFreeColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Cm that you want to destroy
+.IP \fIcolormap\fP 1i
+Specifies the colormap \*(Cm.
+.LP
+.eM
+The
+.PN XFreeColormap
+function deletes the association between the colormap resource ID 
+and the colormap and frees the colormap storage.
+However, this function has no effect on the default colormap for a screen.
+If the specified colormap is an installed map for a screen,
+it is uninstalled (see
+.PN XUninstallColormap ).
+If the specified colormap is defined as the colormap for a window (by
+.PN XCreateWindow ,
+.PN XSetWindowColormap ,
+or
+.PN XChangeWindowAttributes ),
+.PN XFreeColormap
+changes the colormap associated with the window to
+.PN None 
+and generates a
+.PN ColormapNotify
+event.
+X does not define the colors displayed for a window with a colormap of
+.PN None .
+.LP
+.PN XFreeColormap
+can generate a
+.PN BadColor 
+error.
+.NH 2
+Mapping Color Names to Values
+.XS
+\*(SN Mapping Color Names to Values
+.XE
+.LP
+.sp
+To map a color name to an RGB value, use
+.PN XLookupColor .
+.IN "Color" "naming"
+.IN "XLookupColor" "" "@DEF@"
+.sM
+.FD 0
+Status XLookupColor\^(\^\fIdisplay\fP, \fIcolormap\fP, \fIcolor_name\fP, \
+\fIexact_def_return\fP\^, \fIscreen_def_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.br
+      char *\fIcolor_name\fP\^;
+.br
+      XColor *\fIexact_def_return\fP\^, *\fIscreen_def_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.IP \fIcolor_name\fP 1i
+Specifies the color name string (for example, red) whose color 
+definition structure you want returned.
+.IP \fIexact_def_return\fP 1i
+Returns the exact RGB values.
+.IP \fIscreen_def_return\fP 1i
+Returns the closest RGB values provided by the hardware.
+.LP
+.eM
+The
+.PN XLookupColor
+function looks up the string name of a color with respect to the screen
+associated with the specified colormap.
+It returns both the exact color values and
+the closest values provided by the screen 
+with respect to the visual type of the specified colormap.
+If the color name is not in the Host Portable Character Encoding, 
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+.PN XLookupColor
+returns nonzero if the name is resolved;
+otherwise, it returns zero.
+.LP
+.PN XLookupColor
+can generate a
+.PN BadColor 
+error.
+.LP
+.sp
+To map a color name to the exact RGB value, use
+.PN XParseColor .
+.IN "Color" "naming"
+.IN "XParseColor" "" "@DEF@"
+.sM
+.FD 0
+Status XParseColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \^\fIspec\fP\^, \fIexact_def_return\fP\^)
+.br
+        Display *\fIdisplay\fP\^;
+.br
+        Colormap \fIcolormap\fP\^;
+.br
+        char *\fIspec\fP\^;
+.br
+        XColor *\fIexact_def_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.IP \fIspec\fP 1i
+Specifies the color name string;
+case is ignored.
+.IP \fIexact_def_return\fP 1i
+Returns the exact color value for later use and sets the
+.PN DoRed ,
+.PN DoGreen ,
+and
+.PN DoBlue
+flags.
+.LP
+.eM 
+The
+.PN XParseColor
+function looks up the string name of a color with respect to the screen
+associated with the specified colormap.
+It returns the exact color value.
+If the color name is not in the Host Portable Character Encoding, 
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+.PN XParseColor
+returns nonzero if the name is resolved;
+otherwise, it returns zero.
+.LP
+.PN XParseColor
+can generate a
+.PN BadColor 
+error.
+.LP
+.sp
+To map a color name to a value in an arbitrary color space, use
+.PN XcmsLookupColor .
+.IN "Color" "naming"
+.IN "XcmsLookupColor" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsLookupColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor_string\fP\^, \fIcolor_exact_return\fP\^, \fIcolor_screen_return\fP\^,
+.br
+			 \fIresult_format\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.br
+      char *\fIcolor_string\fP\^;
+.br
+      XcmsColor *\fIcolor_exact_return\fP\^, *\fIcolor_screen_return\fP\^;
+.br
+      XcmsColorFormat \fIresult_format\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.ds St
+.IP \fIcolor_string\fP 1i
+Specifies the color string\*(St.
+.IP \fIcolor_exact_return\fP 1i
+Returns the color specification parsed from the color string
+or parsed from the corresponding string found in a color-name database.
+.IP \fIcolor_screen_return\fP 1i
+Returns the color that can be reproduced on the screen.
+.IP \fIresult_format\fP 1i
+Specifies the color format for the returned color
+specifications (color_screen_return and color_exact_return arguments).
+If the format is
+.PN XcmsUndefinedFormat
+and the color string contains a
+numerical color specification,
+the specification is returned in the format used in that numerical
+color specification.
+If the format is
+.PN XcmsUndefinedFormat
+and the color string contains a color name,
+the specification is returned in the format used 
+to store the color in the database.
+.LP
+.eM
+The
+.PN XcmsLookupColor
+function looks up the string name of a color with respect to the screen
+associated with the specified colormap.
+It returns both the exact color values and
+the closest values provided by the screen 
+with respect to the visual type of the specified colormap.
+The values are returned in the format specified by result_format.
+If the color name is not in the Host Portable Character Encoding, 
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+.PN XcmsLookupColor
+returns
+.PN XcmsSuccess
+or
+.PN XcmsSuccessWithCompression
+if the name is resolved; otherwise, it returns
+.PN XcmsFailure .
+If
+.PN XcmsSuccessWithCompression
+is returned, the color specification returned in 
+color_screen_return is the result of gamut compression.
+.NH 2
+Allocating and Freeing Color Cells
+.XS
+\*(SN Allocating and Freeing Color Cells
+.XE
+.LP
+There are two ways of allocating color cells: 
+explicitly as read-only entries, one pixel value at a time,
+or read/write,
+where you can allocate a number of color cells and planes simultaneously.
+.IN "Read-only colormap cells"
+A read-only cell has its RGB value set by the server.
+.IN "Read/write colormap cells"
+Read/write cells do not have defined colors initially;
+functions described in the next section must be used to store values into them.
+Although it is possible for any client to store values into a read/write
+cell allocated by another client,
+read/write cells normally should be considered private to the client
+that allocated them.
+.LP
+Read-only colormap cells are shared among clients.
+The server counts each allocation and freeing of the cell by clients.
+When the last client frees a shared cell, the cell is finally deallocated.
+If a single client allocates the same read-only cell multiple
+times, the server counts each such allocation, not just the first one.
+.LP
+.sp
+To allocate a read-only color cell with an RGB value, use
+.PN XAllocColor .
+.IN "Allocation" "read-only colormap cells"
+.IN "Read-only colormap cells" "allocating"
+.IN "Color" "allocation"
+.IN "XAllocColor" "" "@DEF@"
+.sM
+.FD 0
+Status XAllocColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIscreen_in_out\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.br
+      XColor *\fIscreen_in_out\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.IP \fIscreen_in_out\fP 1i
+Specifies and returns the values actually used in the colormap.
+.LP
+.eM
+The
+.PN XAllocColor
+function allocates a read-only colormap entry corresponding to the closest
+RGB value supported by the hardware.
+.PN XAllocColor
+returns the pixel value of the color closest to the specified
+RGB elements supported by the hardware
+and returns the RGB value actually used.
+The corresponding colormap cell is read-only.
+In addition,
+.PN XAllocColor
+returns nonzero if it succeeded or zero if it failed.
+.IN "Color map"
+.IN "Color" "allocation"
+.IN "Allocation" "colormap"
+.IN "read-only colormap cells"
+Multiple clients that request the same effective RGB value can be assigned
+the same read-only entry, thus allowing entries to be shared.
+When the last client deallocates a shared cell, it is deallocated.
+.PN XAllocColor
+does not use or affect the flags in the
+.PN XColor
+structure.
+.LP
+.PN XAllocColor
+can generate a
+.PN BadColor 
+error.
+.EQ
+delim %%
+.EN
+.LP
+.sp
+To allocate a read-only color cell with a color in arbitrary format, use
+.PN XcmsAllocColor .
+.IN "Allocation" "read-only colormap cells"
+.IN "Read-only colormap cells" "allocating"
+.IN "Color" "allocation"
+.IN "XcmsAllocColor" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsAllocColor\^(\^\fIdisplay\fP\^, \fIcolormap\fP\^, \fIcolor_in_out\fP\^, \fIresult_format\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.br
+      XcmsColor *\fIcolor_in_out\fP\^;
+.br
+      XcmsColorFormat \fIresult_format\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.IP \fIcolor_in_out\fP 1i
+Specifies the color to allocate and returns the pixel and color 
+that is actually used in the colormap.
+.IP \fIresult_format\fP 1i
+Specifies the color format for the returned color specification.
+.LP
+.eM
+The
+.PN XcmsAllocColor
+function is similar to
+.PN XAllocColor
+except the color can be specified in any format.
+The
+.PN XcmsAllocColor
+function ultimately calls 
+.PN XAllocColor
+to allocate a read-only color cell (colormap entry) with the specified color.
+.PN XcmsAllocColor
+first converts the color specified
+to an RGB value and then passes this to
+.PN XAllocColor .
+.PN XcmsAllocColor
+returns the pixel value of the color cell and the color specification
+actually allocated.
+This returned color specification is the result of converting the RGB value
+returned by 
+.PN XAllocColor 
+into the format specified with the result_format argument.
+If there is no interest in a returned color specification, 
+unnecessary computation can be bypassed if result_format is set to
+.PN XcmsRGBFormat .
+The corresponding colormap cell is read-only.
+If this routine returns 
+.PN XcmsFailure , 
+the color_in_out color specification is left unchanged.
+.LP
+.PN XcmsAllocColor
+can generate a
+.PN BadColor
+error.
+.LP
+.sp
+To allocate a read-only color cell using a color name and return the closest
+color supported by the hardware in RGB format, use
+.PN XAllocNamedColor .
+.IN "Allocation" "read-only colormap cells"
+.IN "Read-only colormap cells" "allocating"
+.IN "Color" "naming"
+.IN "Color" "allocation"
+.IN "XAllocNamedColor" "" "@DEF@"
+.sM
+.FD 0
+Status XAllocNamedColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \
+\fIcolor_name\fP\^, \fIscreen_def_return\fP\^, \fIexact_def_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.br
+      char *\fIcolor_name\fP\^;
+.br
+      XColor *\fIscreen_def_return\fP\^, *\fIexact_def_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.IP \fIcolor_name\fP 1i
+Specifies the color name string (for example, red) whose color 
+definition structure you want returned.
+.IP \fIscreen_def_return\fP 1i
+Returns the closest RGB values provided by the hardware.
+.IP \fIexact_def_return\fP 1i
+Returns the exact RGB values.
+.LP
+.eM 
+The
+.PN XAllocNamedColor
+function looks up the named color with respect to the screen that is
+associated with the specified colormap.
+It returns both the exact database definition and
+the closest color supported by the screen.
+The allocated color cell is read-only.
+The pixel value is returned in screen_def_return.
+If the color name is not in the Host Portable Character Encoding, 
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+If screen_def_return and exact_def_return
+point to the same structure, the pixel field will be set correctly,
+but the color values are undefined.
+.PN XAllocNamedColor
+returns nonzero if a cell is allocated;
+otherwise, it returns zero.
+.LP
+.PN XAllocNamedColor
+can generate a
+.PN BadColor
+error. 
+.LP
+.sp
+To allocate a read-only color cell using a color name and return the closest
+color supported by the hardware in an arbitrary format, use
+.PN XcmsAllocNamedColor .
+.IN "Allocation" "read-only colormap cells"
+.IN "Read-only colormap cells" "allocating"
+.IN "Color" "naming"
+.IN "Color" "allocation"
+.IN "XcmsAllocNamedColor" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsAllocNamedColor\^(\^\fIdisplay\fP\^, \fIcolormap\fP\^, \fIcolor_string\fP\^, \fIcolor_screen_return\fP\^, \fIcolor_exact_return\fP\^,
+.br
+                            \fIresult_format\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.br
+      char *\fIcolor_string\fP\^;
+.br
+      XcmsColor *\fIcolor_screen_return\fP\^;
+.br
+      XcmsColor *\fIcolor_exact_return\fP\^;
+.br
+      XcmsColorFormat \fIresult_format\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.ds St \ whose color definition structure is to be returned
+.IP \fIcolor_string\fP 1i
+Specifies the color string\*(St.
+.IP \fIcolor_screen_return\fP 1i
+Returns the pixel value of the color cell and color specification 
+that actually is stored for that cell.
+.IP \fIcolor_exact_return\fP 1i
+Returns the color specification parsed from the color string
+or parsed from the corresponding string found in a color-name database.
+.IP \fIresult_format\fP 1i
+Specifies the color format for the returned color
+specifications (color_screen_return and color_exact_return arguments).
+If the format is
+.PN XcmsUndefinedFormat
+and the color string contains a
+numerical color specification,
+the specification is returned in the format used in that numerical
+color specification.
+If the format is
+.PN XcmsUndefinedFormat
+and the color string contains a color name,
+the specification is returned in the format used 
+to store the color in the database.
+.LP
+.eM
+The
+.PN XcmsAllocNamedColor
+function is similar to
+.PN XAllocNamedColor
+except that the color returned can be in any format specified.
+This function
+ultimately calls
+.PN XAllocColor
+to allocate a read-only color cell with
+the color specified by a color string.
+The color string is parsed into an
+.PN XcmsColor
+structure (see
+.PN XcmsLookupColor ),
+converted
+to an RGB value, and finally passed to
+.PN XAllocColor .
+If the color name is not in the Host Portable Character Encoding, 
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+.LP
+This function returns both the color specification as a result
+of parsing (exact specification) and the actual color specification
+stored (screen specification).
+This screen specification is the result of converting the RGB value
+returned by
+.PN XAllocColor
+into the format specified in result_format.
+If there is no interest in a returned color specification,
+unnecessary computation can be bypassed if result_format is set to
+.PN XcmsRGBFormat .
+If color_screen_return and color_exact_return
+point to the same structure, the pixel field will be set correctly,
+but the color values are undefined.
+.LP
+.PN XcmsAllocNamedColor
+can generate a
+.PN BadColor
+error.
+.LP
+.sp
+To allocate read/write color cell and color plane combinations for a
+.PN PseudoColor
+model, use
+.PN XAllocColorCells .
+.IN "Read/write colormap cells" "allocating"
+.IN "Allocation" "read/write colormap cells"
+.IN "Color" "allocation"
+.IN "XAllocColorCells" "" "@DEF@"
+.sM
+.FD 0
+Status XAllocColorCells\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcontig\fP\^, \
+\fIplane_masks_return\fP\^, \fInplanes\fP\^, 
+.br
+                          \fIpixels_return\fP\^, \fInpixels\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.br
+      Bool \fIcontig\fP\^;
+.br
+      unsigned long \fIplane_masks_return\fP[\^]\^;
+.br
+      unsigned int \fInplanes\fP\^;
+.br
+      unsigned long \fIpixels_return\fP[\^]\^;
+.br
+      unsigned int \fInpixels\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.IP \fIcontig\fP 1i
+Specifies a Boolean value that indicates whether the planes must be contiguous.
+.IP \fIplane_mask_return\fP 1i
+Returns an array of plane masks.
+.\" *** JIM: NEED MORE INFO FOR THIS. ***
+.IP \fInplanes\fP 1i
+Specifies the number of plane masks that are to be returned in the plane masks 
+array. 
+.IP \fIpixels_return\fP 1i
+Returns an array of pixel values. 
+.IP \fInpixels\fP 1i
+Specifies the number of pixel values that are to be returned in the 
+pixels_return array. 
+.LP
+.eM
+.EQ
+delim %%
+.EN
+The
+.PN XAllocColorCells
+function allocates read/write color cells.
+The number of colors must be positive and the number of planes nonnegative,
+or a
+.PN BadValue
+error results.
+If ncolors and nplanes are requested, 
+then ncolors pixels
+and nplane plane masks are returned.
+No mask will have any bits set to 1 in common with
+any other mask or with any of the pixels.
+By ORing together each pixel with zero or more masks,
+ncolors * %2 sup nplanes% distinct pixels can be produced.
+All of these are
+allocated writable by the request.
+For 
+.PN GrayScale 
+or 
+.PN PseudoColor , 
+each mask has exactly one bit set to 1. 
+For 
+.PN DirectColor , 
+each has exactly three bits set to 1.
+If contig is 
+.PN True 
+and if all masks are ORed
+together, a single contiguous set of bits set to 1 will be formed for 
+.PN GrayScale
+or 
+.PN PseudoColor 
+and three contiguous sets of bits set to 1 (one within each
+pixel subfield) for 
+.PN DirectColor .
+The RGB values of the allocated
+entries are undefined.
+.PN XAllocColorCells
+returns nonzero if it succeeded or zero if it failed.
+.LP
+.PN XAllocColorCells
+can generate
+.PN BadColor
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To allocate read/write color resources for a
+.PN DirectColor
+model, use
+.PN XAllocColorPlanes .
+.IN "Read/write colormap planes" "allocating"
+.IN "Allocation" "read/write colormap planes"
+.IN "Color" "allocation"
+.IN "XAllocColorPlanes" "" "@DEF@"
+.sM
+.FD 0
+Status XAllocColorPlanes\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcontig\fP\^, \fIpixels_return\fP\^, \fIncolors\fP\^, \fInreds\fP\^, \fIngreens\fP\^, 
+.br
+                           \fInblues\fP\^, \fIrmask_return\fP\^, \fIgmask_return\fP\^, \fIbmask_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.br
+      Bool \fIcontig\fP\^;
+.br
+      unsigned long \fIpixels_return\fP[\^]\^;
+.br
+      int \fIncolors\fP\^;
+.br
+      int \fInreds\fP\^, \fIngreens\fP\^, \fInblues\fP\^;
+.br
+      unsigned long *\fIrmask_return\fP\^, *\fIgmask_return\fP\^, *\fIbmask_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.IP \fIcontig\fP 1i
+Specifies a Boolean value that indicates whether the planes must be contiguous.
+.IP \fIpixels_return\fP 1i
+Returns an array of pixel values. 
+.PN XAllocColorPlanes
+returns the pixel values in this array.
+.IP \fIncolors\fP 1i
+Specifies the number of pixel values that are to be returned in the 
+pixels_return array. 
+.IP \fInreds\fP 1i
+.br
+.ns
+.IP \fIngreens\fP 1i
+.br
+.ns
+.IP \fInblues\fP 1i
+.br
+.ns
+Specify the number of red, green, and blue planes.
+The value you pass must be nonnegative. 
+.IP \fIrmask_return\fP 1i
+.br
+.ns
+.IP \fIgmask_return\fP 1i
+.br
+.ns
+.IP \fIbmask_return\fP 1i
+Return bit masks for the red, green, and blue planes.
+.LP
+.eM
+.EQ
+delim %%
+.EN
+The specified ncolors must be positive; 
+and nreds, ngreens, and nblues must be nonnegative,
+or a
+.PN BadValue
+error results.
+If ncolors colors, nreds reds, ngreens greens, and nblues blues are requested, 
+ncolors pixels are returned; and the masks have nreds, ngreens, and 
+nblues bits set to 1, respectively.
+If contig is 
+.PN True , 
+each mask will have
+a contiguous set of bits set to 1.
+No mask will have any bits set to 1 in common with
+any other mask or with any of the pixels.
+For 
+.PN DirectColor , 
+each mask
+will lie within the corresponding pixel subfield.
+By ORing together
+subsets of masks with each pixel value, 
+ncolors * %2 sup (nreds+ngreens+nblues)% distinct pixel values can be produced. 
+All of these are allocated by the request.
+However, in the
+colormap, there are only ncolors * %2 sup nreds% independent red entries, 
+ncolors * %2 sup ngreens% independent green entries, 
+and ncolors * %2 sup nblues% independent blue entries. 
+This is true even for 
+.PN PseudoColor .
+When the colormap entry of a pixel
+value is changed (using 
+.PN XStoreColors ,
+.PN XStoreColor ,
+or 
+.PN XStoreNamedColor ),
+the pixel is decomposed according to the masks, 
+and the corresponding independent entries are updated.
+.PN XAllocColorPlanes
+returns nonzero if it succeeded or zero if it failed.
+.LP
+.PN XAllocColorPlanes
+can generate
+.PN BadColor
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+.IN "Freeing" "colors"
+To free colormap cells, use
+.PN XFreeColors .
+.IN "XFreeColors" "" "@DEF@"
+.IN "Color" "deallocation"
+.sM
+.FD 0
+XFreeColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIpixels\fP\^, \fInpixels\fP\^, \fIplanes\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.br
+      unsigned long \fIpixels\fP\^[\^];
+.br
+      int \fInpixels\fP\^;
+.br
+      unsigned long \fIplanes\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.ds Pi that map to the cells in the specified colormap
+.IP \fIpixels\fP 1i
+Specifies an array of pixel values \*(Pi. 
+.IP \fInpixels\fP 1i
+Specifies the number of pixels. 
+.IP \fIplanes\fP 1i
+Specifies the planes you want to free.
+.LP
+.eM
+The
+.PN XFreeColors
+function frees the cells represented by pixels whose values are in the
+pixels array.
+The planes argument should not have any bits set to 1 in common with any of the
+pixels. 
+The set of all pixels is produced by ORing together subsets of
+the planes argument with the pixels.
+The request frees all of these pixels that
+were allocated by the client (using 
+.IN XAllocColor
+.IN XAllocNamedColor
+.IN XAllocColorCells
+.IN XAllocColorPlanes
+.PN XAllocColor , 
+.PN XAllocNamedColor ,
+.PN XAllocColorCells ,
+and 
+.PN XAllocColorPlanes ).
+Note that freeing an
+individual pixel obtained from 
+.PN XAllocColorPlanes 
+may not actually allow
+it to be reused until all of its related pixels are also freed.
+Similarly,
+a read-only entry is not actually freed until it has been freed by all clients,
+and if a client allocates the same read-only entry multiple times,
+it must free the entry that many times before the entry is actually freed.
+.LP
+All specified pixels that are allocated by the client in the colormap are
+freed, even if one or more pixels produce an error. 
+If a specified pixel is not a valid index into the colormap, a 
+.PN BadValue 
+error results.
+If a specified pixel is not allocated by the
+client (that is, is unallocated or is only allocated by another client)
+or if the colormap was created with all entries writable (by passing
+.PN AllocAll
+to
+.PN XCreateColormap ),
+a
+.PN BadAccess
+error results. 
+If more than one pixel is in error, 
+the one that gets reported is arbitrary.
+.LP
+.PN XFreeColors
+can generate
+.PN BadAccess ,
+.PN BadColor ,
+and
+.PN BadValue 
+errors.
+.NH 2
+Modifying and Querying Colormap Cells
+.XS
+\*(SN Modifying and Querying Colormap Cells 
+.XE
+.LP
+.sp
+To store an RGB value in a single colormap cell, use
+.PN XStoreColor .
+.IN "Color" "storing"
+.IN "XStoreColor" "" "@DEF@"
+.sM
+.FD 0
+XStoreColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.br
+      XColor *\fIcolor\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.IP \fIcolor\fP 1i
+Specifies the pixel and RGB values.
+.LP
+.eM
+The
+.PN XStoreColor
+function changes the colormap entry of the pixel value specified in the
+pixel member of the
+.PN XColor
+structure.
+You specified this value in the
+pixel member of the
+.PN XColor
+structure.
+This pixel value must be a read/write cell and a valid index into the colormap.
+If a specified pixel is not a valid index into the colormap,
+a
+.PN BadValue
+error results.
+.PN XStoreColor
+also changes the red, green, and/or blue color components.
+You specify which color components are to be changed by setting
+.PN DoRed ,
+.PN DoGreen ,
+and/or
+.PN DoBlue
+in the flags member of the
+.PN XColor
+structure.
+If the colormap is an installed map for its screen, 
+the changes are visible immediately.
+.LP
+.PN XStoreColor
+can generate
+.PN BadAccess ,
+.PN BadColor ,
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To store multiple RGB values in multiple colormap cells, use
+.PN XStoreColors .
+.IN "Color" "storing"
+.IN "XStoreColors" "" "@DEF@"
+.sM
+.FD 0
+XStoreColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^, \fIncolors\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.br
+      XColor \fIcolor\fP\^[\^]\^;
+.br
+      int \fIncolors\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.IP \fIcolor\fP 1i
+Specifies an array of color definition structures to be stored.
+.IP \fIncolors\fP 1i
+.\"Specifies the number of color definition structures. 
+Specifies the number of 
+.PN XColor
+structures in the color definition array.
+.LP
+.eM
+The
+.PN XStoreColors
+function changes the colormap entries of the pixel values
+specified in the pixel members of the
+.PN XColor
+structures.
+You specify which color components are to be changed by setting 
+.PN DoRed ,
+.PN DoGreen ,
+and/or
+.PN DoBlue
+in the flags member of the
+.PN XColor
+structures.
+If the colormap is an installed map for its screen, the
+changes are visible immediately.
+.PN XStoreColors 
+changes the specified pixels if they are allocated writable in the colormap 
+by any client, even if one or more pixels generates an error.
+If a specified pixel is not a valid index into the colormap, a
+.PN BadValue
+error results.
+If a specified pixel either is unallocated or is allocated read-only, a
+.PN BadAccess
+error results.
+If more than one pixel is in error, 
+the one that gets reported is arbitrary.
+.LP
+.PN XStoreColors
+can generate
+.PN BadAccess ,
+.PN BadColor ,
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To store a color of arbitrary format in a single colormap cell, use
+.PN XcmsStoreColor .
+.IN "Color" "storing"
+.IN "XcmsStoreColor" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsStoreColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.br
+      XcmsColor *\fIcolor\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.IP \fIcolor\fP 1i
+Specifies the color cell and the color to store.
+Values specified in this
+.PN XcmsColor
+structure remain unchanged on return.
+.LP
+.eM
+The
+.PN XcmsStoreColor
+function converts the color specified in the
+.PN XcmsColor
+structure into RGB values.
+It then uses this RGB specification in an
+.PN XColor
+structure, whose three flags 
+.Pn ( DoRed , 
+.PN DoGreen ,
+and
+.PN DoBlue )
+are set, in a call to
+.PN XStoreColor
+to change the color cell specified by the pixel member of the
+.PN XcmsColor
+structure.
+This pixel value must be a valid index for the specified colormap,
+and the color cell specified by the pixel value must be a read/write cell.
+If the pixel value is not a valid index, a
+.PN BadValue
+error results.
+If the color cell is unallocated or is allocated read-only, a
+.PN BadAccess
+error results.
+If the colormap is an installed map for its screen, 
+the changes are visible immediately.
+.LP
+Note that 
+.PN XStoreColor
+has no return value; therefore, an
+.PN XcmsSuccess
+return value from this function indicates that the conversion 
+to RGB succeeded and the call to
+.PN XStoreColor
+was made.
+To obtain the actual color stored, use
+.PN XcmsQueryColor .
+Because of the screen's hardware limitations or gamut compression,
+the color stored in the colormap may not be identical
+to the color specified.
+.LP
+.PN XcmsStoreColor
+can generate
+.PN BadAccess ,
+.PN BadColor ,
+and
+.PN BadValue
+errors.
+.LP
+.sp
+To store multiple colors of arbitrary format in multiple colormap cells, use
+.PN XcmsStoreColors .
+.IN "Color" "storing"
+.IN "XcmsStoreColors" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsStoreColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolors\fP\^, \fIncolors\fP\^, \fIcompression_flags_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.br
+      XcmsColor \fIcolors\fP\^[\^]\^;
+.br
+      int \fIncolors\fP\^;
+.br
+      Bool \fIcompression_flags_return\fP\^[\^]\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.IP \fIcolors\fP 1i
+Specifies the color specification array of
+.PN XcmsColor
+structures, each specifying a color cell and the color to store in that
+cell.
+Values specified in the array remain unchanged upon return.
+.IP \fIncolors\fP 1i
+Specifies the number of 
+.PN XcmsColor
+structures in the color-specification array.
+.IP \fIcompression_flags_return\fP 1i
+Returns an array of Boolean values indicating compression status.
+If a non-NULL pointer is supplied,
+each element of the array is set to
+.PN True
+if the corresponding color was compressed and
+.PN False
+otherwise.
+Pass NULL if the compression status is not useful.
+.LP
+.eM
+The
+.PN XcmsStoreColors
+function converts the colors specified in the array of
+.PN XcmsColor
+structures into RGB values and then uses these RGB specifications in
+.PN XColor
+structures, whose three flags 
+.Pn ( DoRed , 
+.PN DoGreen ,
+and
+.PN DoBlue )
+are set, in a call to
+.PN XStoreColors
+to change the color cells specified by the pixel member of the corresponding
+.PN XcmsColor
+structure.
+Each pixel value must be a valid index for the specified colormap,
+and the color cell specified by each pixel value must be a read/write cell.
+If a pixel value is not a valid index, a
+.PN BadValue
+error results.
+If a color cell is unallocated or is allocated read-only, a
+.PN BadAccess
+error results.
+If more than one pixel is in error,
+the one that gets reported is arbitrary.
+If the colormap is an installed map for its screen, 
+the changes are visible immediately.
+.LP
+Note that 
+.PN XStoreColors
+has no return value; therefore, an
+.PN XcmsSuccess
+return value from this function indicates that conversions 
+to RGB succeeded and the call to
+.PN XStoreColors
+was made.
+To obtain the actual colors stored, use
+.PN XcmsQueryColors .
+Because of the screen's hardware limitations or gamut compression,
+the colors stored in the colormap may not be identical
+to the colors specified.
+.LP
+.PN XcmsStoreColors
+can generate
+.PN BadAccess ,
+.PN BadColor ,
+and
+.PN BadValue
+errors.
+.LP
+.sp
+To store a color specified by name in a single colormap cell, use
+.PN XStoreNamedColor .
+.IN "Color" "storing"
+.IN "Color" "naming"
+.IN "XStoreNamedColor" "" "@DEF@"
+.sM
+.FD 0
+XStoreNamedColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor\fP\^, \fIpixel\fP\^, \fIflags\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.br
+      char *\^\fIcolor\fP\^;
+.br
+      unsigned long \fIpixel\fP\^;
+.br
+      int \fIflags\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.IP \fIcolor\fP 1i
+Specifies the color name string (for example, red). 
+.IP \fIpixel\fP 1i
+Specifies the entry in the colormap. 
+.IP \fIflags\fP 1i
+Specifies which red, green, and blue components are set.
+.LP
+.eM 
+The
+.PN XStoreNamedColor
+function looks up the named color with respect to the screen associated with
+the colormap and stores the result in the specified colormap.
+The pixel argument determines the entry in the colormap.
+The flags argument determines which of the red, green, and blue components 
+are set. 
+You can set this member to the
+bitwise inclusive OR of the bits 
+.PN DoRed , 
+.PN DoGreen , 
+and 
+.PN DoBlue .
+If the color name is not in the Host Portable Character Encoding, 
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+If the specified pixel is not a valid index into the colormap, a
+.PN BadValue
+error results.
+If the specified pixel either is unallocated or is allocated read-only, a
+.PN BadAccess
+error results.
+.LP
+.PN XStoreNamedColor
+can generate
+.PN BadAccess ,
+.PN BadColor ,
+.PN BadName ,
+and 
+.PN BadValue 
+errors.
+.LP
+The
+.PN XQueryColor
+and
+.PN XQueryColors
+functions take pixel values in the pixel member of
+.PN XColor
+structures and store in the structures the RGB values for those
+pixels from the specified colormap.
+The values returned for an unallocated entry are undefined.
+These functions also set the flags member in the
+.PN XColor
+structure to all three colors.
+If a pixel is not a valid index into the specified colormap, a
+.PN BadValue
+error results.
+If more than one pixel is in error,
+the one that gets reported is arbitrary.
+.LP
+.sp
+To query the RGB value of a single colormap cell, use
+.PN XQueryColor .
+.IN "Color" "querying"
+.IN "XQueryColor" "" "@DEF@"
+.sM
+.FD 0
+XQueryColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIdef_in_out\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.br
+      XColor *\fIdef_in_out\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.IP \fIdef_in_out\fP 1i
+Specifies and returns the RGB values for the pixel specified in the structure.
+.LP
+.eM
+The
+.PN XQueryColor
+function returns the current RGB value for the pixel in the
+.PN XColor
+structure and sets the
+.PN DoRed ,
+.PN DoGreen ,
+and
+.PN DoBlue
+flags.
+.LP
+.PN XQueryColor
+can generate
+.PN BadColor
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To query the RGB values of multiple colormap cells, use
+.PN XQueryColors .
+.IN "Color" "querying"
+.IN "XQueryColors" "" "@DEF@"
+.sM
+.FD 0
+XQueryColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIdefs_in_out\fP\^, \fIncolors\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.br
+      XColor \fIdefs_in_out\fP[\^]\^;
+.br
+      int \fIncolors\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.IP \fIdefs_in_out\fP 1i
+Specifies and returns an array of color definition structures for the pixel
+specified in the structure.
+.IP \fIncolors\fP 1i
+.\"Specifies the number of color definition structures. 
+Specifies the number of 
+.PN XColor
+structures in the color definition array.
+.LP
+.eM
+The
+.PN XQueryColors
+function returns the RGB value for each pixel in each
+.PN XColor
+structure and sets the
+.PN DoRed ,
+.PN DoGreen ,
+and
+.PN DoBlue
+flags in each structure.
+
+.LP
+.PN XQueryColors
+can generate
+.PN BadColor
+and
+.PN BadValue 
+errors.
+.sp
+.LP
+To query the color of a single colormap cell in an arbitrary format, use
+.PN XcmsQueryColor .
+.IN "Color" "querying"
+.IN "XcmsQueryColor" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsQueryColor\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolor_in_out\fP\^, \fIresult_format\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.br
+      XcmsColor *\fIcolor_in_out\fP\^;
+.br
+      XcmsColorFormat \fIresult_format\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.IP \fIcolor_in_out\fP 1i
+Specifies the pixel member that indicates the color cell to query.
+The color specification stored for the color cell is returned in this
+.PN XcmsColor
+structure.
+.IP \fIresult_format\fP 1i
+Specifies the color format for the returned color specification.
+.LP
+.eM
+The
+.PN XcmsQueryColor
+function obtains the RGB value
+for the pixel value in the pixel member of the specified
+.PN XcmsColor
+structure and then
+converts the value to the target format as
+specified by the result_format argument.
+If the pixel is not a valid index in the specified colormap, a
+.PN BadValue
+error results.
+.LP
+.PN XcmsQueryColor
+can generate
+.PN BadColor
+and
+.PN BadValue
+errors.
+.sp
+.LP
+To query the color of multiple colormap cells in an arbitrary format, use
+.PN XcmsQueryColors .
+.IN "Color" "querying"
+.IN "XcmsQueryColors" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsQueryColors\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fIresult_format\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.br
+      XcmsColor \fIcolors_in_out\fP\^[\^]\^;
+.br
+      unsigned int \fIncolors\fP\^;
+.br
+      XcmsColorFormat \fIresult_format\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.IP \fIcolors_in_out\fP 1i
+Specifies an array of
+.PN XcmsColor
+structures, each pixel member indicating the color cell to query.
+The color specifications for the color cells are returned in these structures.
+.IP \fIncolors\fP 1i
+Specifies the number of 
+.PN XcmsColor
+structures in the color-specification array.
+.IP \fIresult_format\fP 1i
+Specifies the color format for the returned color specification.
+.LP
+.eM
+The
+.PN XcmsQueryColors
+function obtains the RGB values
+for pixel values in the pixel members of
+.PN XcmsColor
+structures and then
+converts the values to the target format as
+specified by the result_format argument.
+If a pixel is not a valid index into the specified colormap, a
+.PN BadValue
+error results.
+If more than one pixel is in error,
+the one that gets reported is arbitrary.
+.LP
+.PN XcmsQueryColors
+can generate
+.PN BadColor
+and
+.PN BadValue
+errors.
+.NH 2
+Color Conversion Context Functions
+.XS
+\*(SN Color Conversion Context Functions
+.XE
+.LP
+This section describes functions to create, modify,
+and query Color Conversion Contexts (CCCs).
+.LP
+Associated with each colormap is an initial CCC transparently generated by
+Xlib.
+.IN "Color Conversion Context" "creation"
+Therefore, when you specify a colormap as an argument to a function,
+you are indirectly specifying a CCC.
+.IN "CCC" "of colormap"
+.IN "Color Conversion Context" "of colormap"
+The CCC attributes that can be modified by the X client are:
+.IP \(bu 5
+Client White Point
+.IP \(bu 5
+Gamut compression procedure and client data
+.IP \(bu 5
+White point adjustment procedure and client data
+.LP
+The initial values for these attributes are implementation specific.
+The CCC attributes for subsequently created CCCs can be defined
+by changing the CCC attributes of the default CCC.
+.IN "CCC" "default"
+.IN "Color Conversion Context" "default"
+There is a default CCC associated with each screen.
+.NH 3
+Getting and Setting the Color Conversion Context of a Colormap
+.XS
+\*(SN Getting and Setting the Color Conversion Context of a Colormap
+.XE
+.LP
+.sp
+To obtain the CCC associated with a colormap, use
+.PN XcmsCCCOfColormap .
+.IN "XcmsCCCOfColormap" "" "@DEF@"
+.IN "Colormap" "CCC of"
+.IN "CCC" "of colormap"
+.IN "Color Conversion Context" "of colormap"
+.sM
+.FD 0
+XcmsCCC XcmsCCCOfColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.LP
+.eM
+The
+.PN XcmsCCCOfColormap
+function returns the CCC associated with the specified colormap.
+Once obtained, 
+the CCC attributes can be queried or modified.
+Unless the CCC associated with the specified colormap is changed with
+.PN XcmsSetCCCOfColormap ,
+this CCC is used when the specified colormap is used as an argument 
+to color functions.
+.sp
+.LP
+To change the CCC associated with a colormap, use
+.PN XcmsSetCCCOfColormap .
+.IN "XcmsSetCCCOfColormap" "" "@DEF@"
+.IN "Colormap" "CCC of"
+.IN "CCC" "of colormap"
+.IN "Color Conversion Context" "of colormap"
+.sM
+.FD 0
+XcmsCCC XcmsSetCCCOfColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^, \fIccc\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.br
+      XcmsCCC \fIccc\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.IP \fIccc\fP 1i
+Specifies the CCC.
+.LP
+.eM
+The
+.PN XcmsSetCCCOfColormap
+function changes the CCC associated with the specified colormap.
+It returns the CCC previously associated with the colormap.
+If they are not used again in the application,
+CCCs should be freed by calling
+.PN XcmsFreeCCC .
+Several colormaps may share the same CCC without restriction; this
+includes the CCCs generated by Xlib with each colormap.  Xlib, however,
+creates a new CCC with each new colormap.
+.NH 3
+Obtaining the Default Color Conversion Context
+.XS
+\*(SN Obtaining the Default Color Conversion Context
+.XE
+.LP
+You can change the default CCC attributes for subsequently created CCCs
+by changing the CCC attributes of the default CCC.
+.IN "CCC" "default"
+.IN "Color Conversion Context" "default"
+A default CCC is associated with each screen.
+.sp
+.LP
+To obtain the default CCC for a screen, use
+.PN XcmsDefaultCCC .
+.IN "XcmsDefaultCCC" "" "@DEF@"
+.IN "Color Conversion Context" "default"
+.IN "CCC" "default"
+.sM
+.FD 0
+XcmsCCC XcmsDefaultCCC\^(\^\fIdisplay\fP, \fIscreen_number\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen_number\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.LP
+.eM
+The
+.PN XcmsDefaultCCC
+function returns the default CCC for the specified screen.
+Its visual is the default visual of the screen.
+Its initial gamut compression and white point
+adjustment procedures as well as the associated client data are implementation
+specific.
+.NH 3
+Color Conversion Context Macros
+.XS
+\*(SN Color Conversion Context Macros
+.XE
+.LP
+Applications should not directly modify any part of the
+.PN XcmsCCC .
+The following lists the C language macros, their corresponding function
+equivalents for other language bindings, and what data they both
+can return.
+.sp
+.LP
+.IN "DisplayOfCCC" "" "@DEF@"
+.IN "XcmsDisplayOfCCC" "" "@DEF@"
+.sM
+.FD 0
+DisplayOfCCC\^(\^\fIccc\fP\^)
+.br
+     XcmsCCC \fIccc\fP\^;
+.sp
+Display *XcmsDisplayOfCCC\^(\^\fIccc\fP\^)
+.br
+     XcmsCCC \fIccc\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+.LP
+.eM
+Both return the display associated with the specified CCC.
+.LP
+.sp
+.IN "VisualOfCCC" "" "@DEF@"
+.IN "XcmsVisualOfCCC" "" "@DEF@"
+.sM
+.FD 0
+VisualOfCCC\^(\^\fIccc\fP\^)
+.br
+     XcmsCCC \fIccc\fP\^;
+.sp
+Visual *XcmsVisualOfCCC\^(\^\fIccc\fP\^)
+.br
+     XcmsCCC \fIccc\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+.LP
+.eM
+Both return the visual associated with the specified CCC.
+.sp
+.LP
+.IN "ScreenNumberOfCCC" "" "@DEF@"
+.IN "XcmsScreenNumberOfCCC" "" "@DEF@"
+.sM
+.FD 0
+ScreenNumberOfCCC\^(\^\fIccc\fP\^)
+.br
+     XcmsCCC \fIccc\fP\^;
+.sp
+int XcmsScreenNumberOfCCC\^(\^\fIccc\fP\^)
+.br
+     XcmsCCC \fIccc\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+.LP
+.eM
+Both return the number of the screen associated with the specified CCC.
+.sp
+.LP
+.IN "ScreenWhitePointOfCCC" "" "@DEF@"
+.IN "XcmsScreenWhitePointOfCCC" "" "@DEF@"
+.sM
+.FD 0
+ScreenWhitePointOfCCC\^(\^\fIccc\fP\^)
+.br
+     XcmsCCC \fIccc\fP\^;
+.sp
+XcmsColor *XcmsScreenWhitePointOfCCC\^(\^\fIccc\fP\^)
+.br
+     XcmsCCC \fIccc\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+.LP
+.eM
+Both return the white point of the screen associated with the specified CCC.
+.sp
+.LP
+.IN "ClientWhitePointOfCCC" "" "@DEF@"
+.IN "XcmsClientWhitePointOfCCC" "" "@DEF@"
+.sM
+.FD 0
+ClientWhitePointOfCCC\^(\^\fIccc\fP\^)
+.br
+     XcmsCCC \fIccc\fP\^;
+.sp
+XcmsColor *XcmsClientWhitePointOfCCC\^(\^\fIccc\fP\^)
+.br
+     XcmsCCC \fIccc\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+.LP
+.eM
+Both return the Client White Point of the specified CCC.
+.NH 3
+Modifying Attributes of a Color Conversion Context
+.XS
+\*(SN Modifying Attributes of a Color Conversion Context
+.XE
+.LP
+To set the Client White Point in the CCC, use
+.PN XcmsSetWhitePoint .
+.IN "XcmsSetWhitePoint" "" "@DEF@"
+.IN "Client White Point" "of Color Conversion Context"
+.sM
+.FD 0
+Status XcmsSetWhitePoint\^(\^\fIccc\fP\^, \fIcolor\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsColor *\fIcolor\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+.ds Co new Client White Point
+.IP \fIcolor\fP 1i
+Specifies the \*(Co.
+.LP
+.eM
+The
+.PN XcmsSetWhitePoint
+function changes the Client White Point in the specified CCC.
+Note that the pixel member is ignored 
+and that the color specification is left unchanged upon return.
+The format for the new white point must be
+.PN XcmsCIEXYZFormat ,
+.PN XcmsCIEuvYFormat ,
+.PN XcmsCIExyYFormat ,
+or
+.PN XcmsUndefinedFormat .
+If the color argument is NULL, this function sets the format component of the
+Client White Point specification to
+.PN XcmsUndefinedFormat ,
+indicating that the Client White Point is assumed to be the same as the
+Screen White Point.
+.LP
+This function returns nonzero status
+if the format for the new white point is valid;
+otherwise, it returns zero.
+
+.sp
+.LP
+To set the gamut compression procedure and corresponding client data
+in a specified CCC, use
+.PN XcmsSetCompressionProc .
+.IN "XcmsSetCompressionProc" "" "@DEF@"
+.IN "Gamut compression" "setting in Color Conversion Context"
+.IN "Gamut compression" "procedure"
+.IN "Gamut compression" "client data"
+.sM
+.FD 0
+XcmsCompressionProc XcmsSetCompressionProc\^(\^\fIccc\fP\^, \fIcompression_proc\fP\^, \fIclient_data\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsCompressionProc \fIcompression_proc\fP\^;
+.br
+      XPointer \fIclient_data\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+.IP \fIcompression_proc\fP 1i
+Specifies the gamut compression procedure that is to be applied 
+when a color lies outside the screen's color gamut.
+If NULL is specified and a function using this CCC must convert
+a color specification to a device-dependent format and encounters a color
+that lies outside the screen's color gamut, 
+that function will return
+.PN XcmsFailure .
+.ds Cd the gamut compression procedure
+.IP \fIclient_data\fP 1i
+Specifies client data for \*(Cd or NULL.
+.LP
+.eM
+The
+.PN XcmsSetCompressionProc
+function first sets the gamut compression procedure and client data 
+in the specified CCC with the newly specified procedure and client data
+and then returns the old procedure.
+.sp
+.LP
+To set the white point adjustment procedure and corresponding client data
+in a specified CCC, use
+.PN XcmsSetWhiteAdjustProc .
+.IN "XcmsSetWhiteAdjustProc" "" "@DEF@"
+.IN "White point adjustment" "setting in Color Conversion Context"
+.IN "White point adjustment" "procedure"
+.IN "White point adjustment" "client data"
+.FD 0
+.sM
+XcmsWhiteAdjustProc XcmsSetWhiteAdjustProc\^(\^\fIccc\fP\^, \fIwhite_adjust_proc\fP\^, \fIclient_data\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsWhiteAdjustProc \fIwhite_adjust_proc\fP\^;
+.br
+      XPointer \fIclient_data\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+.IP \fIwhite_adjust_proc\fP 1i
+Specifies the white point adjustment procedure.
+.ds Cd the white point adjustment procedure
+.IP \fIclient_data\fP 1i
+Specifies client data for \*(Cd or NULL.
+.LP
+.eM
+The
+.PN XcmsSetWhiteAdjustProc
+function first sets the white point adjustment procedure and client data 
+in the specified CCC with the newly specified procedure and client data
+and then returns the old procedure.
+.NH 3
+Creating and Freeing a Color Conversion Context
+.XS
+\*(SN Creating and Freeing a Color Conversion Context
+.XE
+.LP
+You can explicitly create a CCC within your application by calling
+.PN XcmsCreateCCC .
+These created CCCs can then be used by those functions that explicitly
+call for a CCC argument.
+Old CCCs that will not be used by the application should be freed using
+.PN XcmsFreeCCC .
+.sp
+.LP
+To create a CCC, use
+.PN XcmsCreateCCC .
+.IN "XcmsCreateCCC" "" "@DEF@"
+.IN "Color Conversion Context" "creation"
+.IN "CCC" "creation"
+.sM
+.FD 0
+XcmsCCC XcmsCreateCCC\^(\^\fIdisplay\fP, \fIscreen_number\fP\^, \fIvisual\fP\^, \fIclient_white_point\fP\^, \fIcompression_proc\fP\^,
+.br
+                    \fIcompression_client_data\fP\^, \fIwhite_adjust_proc\fP\^, \fIwhite_adjust_client_data\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen_number\fP\^;
+.br
+      Visual *\fIvisual\fP\^;
+.br
+      XcmsColor *\fIclient_white_point\fP\^;
+.br
+      XcmsCompressionProc \fIcompression_proc\fP\^;
+.br
+      XPointer \fIcompression_client_data\fP\^;
+.br
+      XcmsWhiteAdjustProc \fIwhite_adjust_proc\fP\^;
+.br
+      XPointer \fIwhite_adjust_client_data\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.IP \fIvisual\fP 1i
+Specifies the visual type.
+.IP \fIclient_white_point\fP 1i
+Specifies the Client White Point.
+If NULL is specified, 
+the Client White Point is to be assumed to be the same as the
+Screen White Point.
+Note that the pixel member is ignored.
+.IP \fIcompression_proc\fP 1i
+Specifies the gamut compression procedure that is to be applied 
+when a color lies outside the screen's color gamut.
+If NULL is specified and a function using this CCC must convert
+a color specification to a device-dependent format and encounters a color
+that lies outside the screen's color gamut, 
+that function will return
+.PN XcmsFailure .
+.IP \fIcompression_client_data\fP 1i
+Specifies client data for use by the gamut compression procedure or NULL.
+.IP \fIwhite_adjust_proc\fP 1i
+Specifies the white adjustment procedure that is to be applied
+when the Client White Point differs from the Screen White Point.
+NULL indicates that no white point adjustment is desired.
+.IP \fIwhite_adjust_client_data\fP 1i
+Specifies client data for use with the white point adjustment procedure or NULL.
+.LP
+.eM
+The
+.PN XcmsCreateCCC
+function creates a CCC for the specified display, screen, and visual.
+.LP
+.sp
+To free a CCC, use
+.PN XcmsFreeCCC .
+.IN "XcmsFreeCCC" "" "@DEF@"
+.IN "Color Conversion Context" "freeing"
+.IN "CCC" "freeing"
+.sM
+.FD 0
+void XcmsFreeCCC\^(\^\fIccc\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+.LP
+.eM
+The
+.PN XcmsFreeCCC
+function frees the memory used for the specified CCC.
+Note that default CCCs and those currently associated with colormaps
+are ignored.
+.NH 2
+Converting between Color Spaces
+.XS
+\*(SN Converting between Color Spaces
+.XE
+.LP
+.sp
+To convert an array of color specifications in arbitrary color formats
+to a single destination format, use
+.PN XcmsConvertColors .
+.IN "Color conversion"
+.IN "Color" "conversion"
+.IN "XcmsConvertColors" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsConvertColors\^(\^\fIccc\fP\^, \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fItarget_format\fP\^, \fIcompression_flags_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsColor \fIcolors_in_out\fP\^[\^]\^;
+.br
+      unsigned int \fIncolors\fP\^;
+.br
+      XcmsColorFormat \fItarget_format\fP\^;
+.br
+      Bool \fIcompression_flags_return\fP\^[\^]\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+If conversion is between device-independent color spaces only
+(for example, TekHVC to CIELuv),
+the CCC is necessary only to specify the Client White Point.
+.IP \fIcolors_in_out\fP 1i
+Specifies an array of color specifications.
+Pixel members are ignored and remain unchanged upon return.
+.IP \fIncolors\fP 1i
+Specifies the number of 
+.PN XcmsColor
+structures in the color-specification array.
+.IP \fItarget_format\fP 1i
+Specifies the target color specification format.
+.IP \fIcompression_flags_return\fP 1i
+Returns an array of Boolean values indicating compression status.
+If a non-NULL pointer is supplied,
+each element of the array is set to
+.PN True
+if the corresponding color was compressed and
+.PN False
+otherwise.
+Pass NULL if the compression status is not useful.
+.LP
+.eM
+The
+.PN XcmsConvertColors
+function converts the color specifications in the specified array of
+.PN XcmsColor
+structures from their current format to a single target format,
+using the specified CCC.
+When the return value is
+.PN XcmsFailure ,
+the contents of the color specification array are left unchanged.
+.LP
+The array may contain a mixture of color specification formats
+(for example, 3 CIE XYZ, 2 CIE Luv, and so on).
+When the array contains both device-independent and
+device-dependent color specifications and the target_format argument specifies
+a device-dependent format (for example,
+.PN XcmsRGBiFormat ,
+.PN XcmsRGBFormat ),
+all specifications are converted to CIE XYZ format and then to the target
+device-dependent format.
+.NH 2
+Callback Functions
+.XS
+\*(SN Callback Functions
+.XE
+.LP
+This section describes the gamut compression and white point
+adjustment callbacks.
+.LP
+The gamut compression procedure specified in the CCC
+is called when an attempt to convert a color specification from
+.PN XcmsCIEXYZ
+to a device-dependent format (typically
+.PN XcmsRGBi )
+results in a color that lies outside the screen's color gamut.
+If the gamut compression procedure requires client data, this data is passed
+via the gamut compression client data in the CCC.
+.LP
+During color specification conversion between device-independent
+and device-dependent color spaces,
+if a white point adjustment procedure is specified in the CCC,
+it is triggered when the Client White Point and Screen White Point differ.
+If required, the client data is obtained from the CCC.
+.NH 3
+Prototype Gamut Compression Procedure
+.XS
+\*(SN Prototype Gamut Compression Procedure
+.XE
+.LP
+The gamut compression callback interface must adhere to the
+following:
+.IN "XcmsCompressionProc" "" "@DEF@"
+.sM
+.FD 0
+typedef Status (*\^XcmsCompressionProc\^)\^(\^\fIccc\fP\^, \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fIindex\fP\^, \fIcompression_flags_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsColor \fIcolors_in_out[]\fP\^;
+.br
+      unsigned int \fIncolors\fP\^;
+.br
+      unsigned int \fIindex\fP\^;
+.br
+      Bool \fIcompression_flags_return[]\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+.IP \fIcolors_in_out\fP 1i
+Specifies an array of color specifications.
+Pixel members should be ignored and must remain unchanged upon return.
+.IP \fIncolors\fP 1i
+Specifies the number of 
+.PN XcmsColor
+structures in the color-specification array.
+.IP \fIindex\fP 1i
+Specifies the index into the array of
+.PN XcmsColor
+structures for the encountered color specification that lies outside the 
+screen's color gamut.
+Valid values are 0 (for the first element) to ncolors \- 1.
+.IP \fIcompression_flags_return\fP 1i
+Returns an array of Boolean values for indicating compression status.
+If a non-NULL pointer is supplied
+and a color at a given index is compressed, then
+.PN True
+should be stored at the corresponding index in this array;
+otherwise, the array should not be modified.
+.LP
+.eM
+When implementing a gamut compression procedure, consider the following
+rules and assumptions:
+.IP \(bu 5
+The gamut compression procedure can attempt to compress one or multiple
+specifications at a time.
+.IP \(bu 5
+When called, elements 0 to index \- 1 in the color specification
+array can be assumed to fall within the screen's color gamut.
+In addition, these color specifications are already in some device-dependent
+format (typically
+.PN XcmsRGBi ).
+If any modifications are made to these color specifications,
+they must be in their initial device-dependent format upon return.
+.IP \(bu 5
+When called, the element in the color specification array specified
+by the index argument contains the color specification outside the 
+screen's color gamut encountered by the calling routine.
+In addition, this color specification can be assumed to be in
+.PN XcmsCIEXYZ .
+Upon return, this color specification must be in
+.PN XcmsCIEXYZ .
+.IP \(bu 5
+When called, elements from index to ncolors \- 1 
+in the color specification array may or may not fall within the
+screen's color gamut.
+In addition, these color specifications can be assumed to be in
+.PN XcmsCIEXYZ .
+If any modifications are made to these color specifications, 
+they must be in
+.PN XcmsCIEXYZ
+upon return.
+.IP \(bu 5
+The color specifications passed to the gamut compression procedure
+have already been adjusted to the Screen White Point.
+This means that at this point the color specification's white point
+is the Screen White Point.
+.IP \(bu 5
+If the gamut compression procedure uses a device-independent color space not
+initially accessible for use in the color management system, use 
+.PN XcmsAddColorSpace
+to ensure that it is added.
+.NH 3
+Supplied Gamut Compression Procedures
+.XS
+\*(SN Supplied Gamut Compression Procedures
+.XE
+.LP
+The following equations are useful in describing gamut compression
+functions:
+.EQ
+delim %%
+.EN
+.LP
+.Ds 0
+%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%
+
+%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]%
+
+%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%
+
+%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]%
+.De
+.LP
+The gamut compression callback procedures provided by Xlib are as follows:
+.IP \(bu 5
+.PN XcmsCIELabClipL
+.IP
+This brings the encountered out-of-gamut color specification into the 
+screen's color gamut by reducing or increasing CIE metric lightness (L*) 
+in the CIE L*a*b* color space until the color is within the gamut.
+If the Psychometric Chroma of the color specification 
+is beyond maximum for the Psychometric Hue Angle,
+then while maintaining the same Psychometric Hue Angle,
+the color will be clipped to the CIE L*a*b* coordinates of maximum
+Psychometric Chroma.
+See
+.PN XcmsCIELabQueryMaxC .
+No client data is necessary.
+.IP \(bu 5
+.PN XcmsCIELabClipab
+.IP
+This brings the encountered out-of-gamut color specification into the 
+screen's color gamut by reducing Psychometric Chroma,
+while maintaining Psychometric Hue Angle,
+until the color is within the gamut.
+No client data is necessary.
+.IP \(bu 5
+.PN XcmsCIELabClipLab
+.IP
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by replacing it with CIE L*a*b* coordinates
+that fall within the color gamut while maintaining the original
+Psychometric Hue
+Angle and whose vector to the original coordinates is the shortest attainable.
+No client data is necessary.
+.IP \(bu 5
+.PN XcmsCIELuvClipL
+.IP
+This brings the encountered out-of-gamut color specification into the 
+screen's color gamut by reducing or increasing CIE metric lightness (L*)
+in the CIE L*u*v* color space until the color is within the gamut.
+If the Psychometric Chroma of the color specification
+is beyond maximum for the Psychometric Hue Angle,
+then, while maintaining the same Psychometric Hue Angle,
+the color will be clipped to the CIE L*u*v* coordinates of maximum
+Psychometric Chroma.
+See
+.PN XcmsCIELuvQueryMaxC .
+No client data is necessary.
+.IP \(bu 5
+.PN XcmsCIELuvClipuv
+.IP
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by reducing
+Psychometric Chroma, while maintaining Psychometric Hue Angle,
+until the color is within the gamut.
+No client data is necessary.
+.IP \(bu 5
+.PN XcmsCIELuvClipLuv
+.IP
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by replacing it with CIE L*u*v* coordinates
+that fall within the color gamut while maintaining the original
+Psychometric Hue
+Angle and whose vector to the original coordinates is the shortest attainable.
+No client data is necessary.
+.IP \(bu 5
+.PN XcmsTekHVCClipV
+.IP
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by reducing or increasing the Value dimension
+in the TekHVC color space until the color is within the gamut.
+If Chroma of the color specification is beyond maximum for the particular Hue,
+then, while maintaining the same Hue,
+the color will be clipped to the Value and Chroma coordinates
+that represent maximum Chroma for that particular Hue.
+No client data is necessary.
+.IP \(bu 5
+.PN XcmsTekHVCClipC
+.IP
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by reducing the Chroma dimension
+in the TekHVC color space until the color is within the gamut.
+No client data is necessary.
+.IP \(bu 5
+.PN XcmsTekHVCClipVC
+.IP
+This brings the encountered out-of-gamut color specification into the
+screen's color gamut by replacing it with TekHVC coordinates
+that fall within the color gamut while maintaining the original Hue
+and whose vector to the original coordinates is the shortest attainable.
+No client data is necessary.
+.NH 3
+Prototype White Point Adjustment Procedure
+.XS
+\*(SN Prototype White Point Adjustment Procedure
+.XE
+.LP
+The white point adjustment procedure interface must adhere to the following:
+.IN "XcmsWhiteAdjustProc" "" "@DEF@"
+.sM
+.FD 0
+typedef Status (*\^XcmsWhiteAdjustProc\^)\^(\^\fIccc\fP\^, \fIinitial_white_point\fP\^, \fItarget_white_point\fP\^, \fItarget_format\fP\^,
+.br
+                \fIcolors_in_out\fP\^, \fIncolors\fP\^, \fIcompression_flags_return\fP\^)
+.br
+       XcmsCCC \fIccc\fP\^;
+.br
+       XcmsColor *\fIinitial_white_point\fP\^;
+.br
+       XcmsColor *\fItarget_white_point\fP\^;
+.br
+       XcmsColorFormat \fItarget_format\fP\^;
+.br
+       XcmsColor \fIcolors_in_out[]\fP\^;
+.br
+       unsigned int \fIncolors\fP\^;
+.br
+       Bool \fIcompression_flags_return[]\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+.IP \fIinitial_white_point\fP 1i
+Specifies the initial white point.
+.IP \fItarget_white_point\fP 1i
+Specifies the target white point.
+.IP \fItarget_format\fP 1i
+Specifies the target color specification format.
+.IP \fIcolors_in_out\fP 1i
+Specifies an array of color specifications.
+Pixel members should be ignored and must remain unchanged upon return.
+.IP \fIncolors\fP 1i
+Specifies the number of 
+.PN XcmsColor
+structures in the color-specification array.
+.IP \fIcompression_flags_return\fP 1i
+Returns an array of Boolean values for indicating compression status.
+If a non-NULL pointer is supplied
+and a color at a given index is compressed, then
+.PN True
+should be stored at the corresponding index in this array;
+otherwise, the array should not be modified.
+.LP
+.eM
+.NH 3
+Supplied White Point Adjustment Procedures
+.XS
+\*(SN Supplied White Point Adjustment Procedures
+.XE
+.LP
+White point adjustment procedures provided by Xlib are as follows:
+.IP \(bu 5
+.PN XcmsCIELabWhiteShiftColors
+.IP
+This uses the CIE L*a*b* color space for adjusting the chromatic character
+of colors to compensate for the chromatic differences between the source
+and destination white points.
+This procedure simply converts the color specifications to 
+.PN XcmsCIELab
+using the source white point and then converts to the target specification
+format using the destination's white point.
+No client data is necessary.
+.IP \(bu 5
+.PN XcmsCIELuvWhiteShiftColors
+.IP
+This uses the CIE L*u*v* color space for adjusting the chromatic character
+of colors to compensate for the chromatic differences between the source
+and destination white points.
+This procedure simply converts the color specifications to 
+.PN XcmsCIELuv
+using the source white point and then converts to the target specification
+format using the destination's white point.
+No client data is necessary.
+.IP \(bu 5
+.PN XcmsTekHVCWhiteShiftColors
+.IP
+This uses the TekHVC color space for adjusting the chromatic character
+of colors to compensate for the chromatic differences between the source
+and destination white points.
+This procedure simply converts the color specifications to
+.PN XcmsTekHVC
+using the source white point and then converts to the target specification
+format using the destination's white point.
+An advantage of this procedure over those previously described
+is an attempt to minimize hue shift.
+No client data is necessary.
+.LP
+From an implementation point of view,
+these white point adjustment procedures convert the color specifications
+to a device-independent but white-point-dependent color space 
+(for example, CIE L*u*v*, CIE L*a*b*, TekHVC) using one white point
+and then converting those specifications to the target color space 
+using another white point.
+In other words,
+the specification goes in the color space with one white point 
+but comes out with another white point, 
+resulting in a chromatic shift based on the chromatic displacement
+between the initial white point and target white point.
+The CIE color spaces that are assumed to be white-point-independent
+are CIE u'v'Y, CIE XYZ, and CIE xyY.
+When developing a custom white point adjustment procedure that uses a
+device-independent color space not initially accessible for use in the
+color management system, use
+.PN XcmsAddColorSpace
+to ensure that it is added.
+.LP
+As an example, 
+if the CCC specifies a white point adjustment procedure
+and if the Client White Point and Screen White Point differ, the
+.PN XcmsAllocColor
+function will use the white point adjustment
+procedure twice: 
+.IP \(bu 5
+Once to convert to
+.PN XcmsRGB
+.IP \(bu  5
+A second time to convert from
+.PN XcmsRGB 
+.LP
+For example, assume the specification is in
+.PN XcmsCIEuvY
+and the adjustment procedure is
+.PN XcmsCIELuvWhiteShiftColors .
+During conversion to
+.PN XcmsRGB ,
+the call to 
+.PN XcmsAllocColor 
+results in the following series of color specification conversions:
+.\" Do these need to be font coded?
+.IP \(bu 5
+From 
+.PN XcmsCIEuvY
+to
+.PN XcmsCIELuv
+using the Client White Point
+.IP \(bu 5
+From 
+.PN XcmsCIELuv
+to
+.PN XcmsCIEuvY
+using the Screen White Point
+.IP \(bu 5
+From
+.PN XcmsCIEuvY
+to
+.PN XcmsCIEXYZ
+(CIE u'v'Y and XYZ are white-point-independent color spaces)
+.IP \(bu 5
+From 
+.PN XcmsCIEXYZ
+to 
+.PN XcmsRGBi
+.IP \(bu 5
+From 
+.PN XcmsRGBi
+to
+.PN XcmsRGB
+.LP
+The resulting RGB specification is passed to
+.PN XAllocColor ,
+and the RGB
+specification returned by
+.PN XAllocColor
+is converted back to 
+.PN XcmsCIEuvY
+by reversing the color conversion sequence.
+.NH 2
+Gamut Querying Functions
+.XS
+\*(SN Gamut Querying Functions
+.XE
+.LP
+This section describes the gamut querying functions that Xlib provides.
+These functions allow the client to query the boundary 
+of the screen's color gamut in terms of the CIE L*a*b*, CIE L*u*v*, 
+and TekHVC color spaces.
+.IN "Gamut querying"
+Functions are also provided that allow you to query 
+the color specification of:
+.IP \(bu 5
+White (full-intensity red, green, and blue)
+.IP \(bu 5
+Red (full-intensity red while green and blue are zero)
+.IP \(bu 5
+Green (full-intensity green while red and blue are zero)
+.IP \(bu 5
+Blue (full-intensity blue while red and green are zero)
+.IP \(bu 5
+Black (zero-intensity red, green, and blue)
+.LP
+The white point associated with color specifications passed to 
+and returned from these gamut querying
+functions is assumed to be the Screen White Point.
+.IN "Screen White Point"
+This is a reasonable assumption,
+because the client is trying to query the screen's color gamut.
+.LP
+The following naming convention is used for the Max and Min functions:
+.LP
+.Ds 0
+Xcms\fI<color_space>\fPQueryMax\fI<dimensions>\fP
+
+Xcms\fI<color_space>\fPQueryMin\fI<dimensions>\fP
+.De
+.LP
+The <dimensions> consists of a letter or letters 
+that identify the dimensions of the color space 
+that are not fixed.
+For example, 
+.PN XcmsTekHVCQueryMaxC
+is given a fixed Hue and Value for which maximum Chroma is found.
+.NH 3
+Red, Green, and Blue Queries
+.XS
+\*(SN Red, Green, and Blue Queries
+.XE
+.LP
+To obtain the color specification for black 
+(zero-intensity red, green, and blue), use
+.PN XcmsQueryBlack .
+.IN "XcmsQueryBlack" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsQueryBlack\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsColorFormat \fItarget_format\fP\^;
+.br
+      XcmsColor *\fIcolor_return\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+.IP \fItarget_format\fP 1i
+Specifies the target color specification format.
+.ds Cs zero-intensity red, green, and blue
+.IP \fIcolor_return\fP 1i
+Returns the color specification in the specified target format
+for \*(Cs.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+.LP
+.eM 
+The
+.PN XcmsQueryBlack
+function returns the color specification in the specified target format
+for zero-intensity red, green, and blue.
+.sp
+.LP
+To obtain the color specification for blue 
+(full-intensity blue while red and green are zero), use
+.PN XcmsQueryBlue .
+.IN "XcmsQueryBlue" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsQueryBlue\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsColorFormat \fItarget_format\fP\^;
+.br
+      XcmsColor *\fIcolor_return\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+.IP \fItarget_format\fP 1i
+Specifies the target color specification format.
+.ds Cs full-intensity blue while red and green are zero
+.IP \fIcolor_return\fP 1i
+Returns the color specification in the specified target format
+for \*(Cs.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+.LP
+.eM 
+The
+.PN XcmsQueryBlue
+function returns the color specification in the specified target format
+for full-intensity blue while red and green are zero.
+.sp
+.LP
+To obtain the color specification for green
+(full-intensity green while red and blue are zero), use
+.PN XcmsQueryGreen .
+.IN "XcmsQueryGreen" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsQueryGreen\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsColorFormat \fItarget_format\fP\^;
+.br
+      XcmsColor *\fIcolor_return\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+.IP \fItarget_format\fP 1i
+Specifies the target color specification format.
+.ds Cs full-intensity green while red and blue are zero
+.IP \fIcolor_return\fP 1i
+Returns the color specification in the specified target format
+for \*(Cs.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+.LP
+.eM 
+The
+.PN XcmsQueryGreen
+function returns the color specification in the specified target format
+for full-intensity green while red and blue are zero.
+.sp
+.LP
+To obtain the color specification for red
+(full-intensity red while green and blue are zero), use
+.PN XcmsQueryRed .
+.IN "XcmsQueryRed" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsQueryRed\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsColorFormat \fItarget_format\fP\^;
+.br
+      XcmsColor *\fIcolor_return\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+.IP \fItarget_format\fP 1i
+Specifies the target color specification format.
+.ds Cs full-intensity red while green and blue are zero
+.IP \fIcolor_return\fP 1i
+Returns the color specification in the specified target format
+for \*(Cs.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+.LP
+.eM 
+The
+.PN XcmsQueryRed
+function returns the color specification in the specified target format
+for full-intensity red while green and blue are zero.
+.LP
+.sp
+To obtain the color specification for white
+(full-intensity red, green, and blue), use
+.PN XcmsQueryWhite .
+.IN "XcmsQueryWhite" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsQueryWhite\^(\^\fIccc\fP\^, \fItarget_format\fP\^, \fIcolor_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsColorFormat \fItarget_format\fP\^;
+.br
+      XcmsColor *\fIcolor_return\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+.IP \fItarget_format\fP 1i
+Specifies the target color specification format.
+.ds Cs full-intensity red, green, and blue
+.IP \fIcolor_return\fP 1i
+Returns the color specification in the specified target format
+for \*(Cs.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+.LP
+.eM 
+The
+.PN XcmsQueryWhite
+function returns the color specification in the specified target format
+for full-intensity red, green, and blue.
+.NH 3
+CIELab Queries
+.XS
+\*(SN CIELab Queries
+.XE
+.LP
+The following equations are useful in describing the CIELab query functions:
+.EQ
+delim %%
+.EN
+.LP
+.IN "Psychometric Hue Angle"
+.IN "CIE metric lightness"
+.IN "Psychometric Chroma"
+.IN "Psychometric Chroma" "maximum"
+.Ds 0
+%CIELab~Psychometric~Chroma ~=~ sqrt(a_star sup 2 ~+~ b_star sup 2 )%
+
+%CIELab~Psychometric~Hue ~=~ tan sup -1 left [ b_star over a_star right ]%
+.De
+.sp
+To obtain the CIE L*a*b* coordinates of maximum Psychometric Chroma
+for a given Psychometric Hue Angle and CIE metric lightness (L*), use
+.PN XcmsCIELabQueryMaxC .
+.IN "XcmsCIELabQueryMaxC" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsCIELabQueryMaxC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIL_star\fP\^, \fIcolor_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsFloat \fIhue_angle\fP\^;
+.br
+      XcmsFloat \fIL_star\fP\^;
+.br
+      XcmsColor *\fIcolor_return\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+.ds Ha maximum chroma
+.IP \fIhue_angle\fP 1i
+Specifies the hue angle (in degrees) at which to find \*(Ha.
+.ds Ls maximum chroma
+.IP \fIL_star\fP 1i
+Specifies the lightness (L*) at which to find \*(Ls.
+.ds Lc maximum chroma
+.ds lC hue angle and lightness
+.IP \fIcolor_return\fP 1i
+Returns the CIE L*a*b* coordinates of \*(Lc
+displayable by the screen for the given \*(lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+.LP
+.eM 
+The
+.PN XcmsCIELabQueryMaxC
+function, given a hue angle and lightness,
+finds the point of maximum chroma displayable by the screen.
+It returns this point in CIE L*a*b* coordinates.
+.LP
+.sp
+To obtain the CIE L*a*b* coordinates of maximum CIE metric lightness (L*)
+for a given Psychometric Hue Angle and Psychometric Chroma, use
+.PN XcmsCIELabQueryMaxL .
+.IN "Psychometric Hue Angle"
+.IN "CIE metric lightness"
+.IN "CIE metric lightness" "maximum"
+.IN "XcmsCIELabQueryMaxL" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsCIELabQueryMaxL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsFloat \fIhue_angle\fP\^;
+.br
+      XcmsFloat \fIchroma\fP\^;
+.br
+      XcmsColor *\fIcolor_return\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+.ds Ha maximum lightness
+.IP \fIhue_angle\fP 1i
+Specifies the hue angle (in degrees) at which to find \*(Ha.
+.ds Ch maximum lightness
+.IP \fIchroma\fP 1i
+Specifies the chroma at which to find \*(Ch.
+.ds Lc maximum lightness
+.ds lC hue angle and chroma
+.IP \fIcolor_return\fP 1i
+Returns the CIE L*a*b* coordinates of \*(Lc
+displayable by the screen for the given \*(lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+.LP
+.eM 
+The
+.PN XcmsCIELabQueryMaxL
+function, given a hue angle and chroma,
+finds the point in CIE L*a*b* color space of maximum 
+lightness (L*) displayable by the screen.
+It returns this point in CIE L*a*b* coordinates.
+An 
+.PN XcmsFailure
+return value usually indicates that the given chroma
+is beyond maximum for the given hue angle.
+.sp
+.LP
+To obtain the CIE L*a*b* coordinates of maximum Psychometric Chroma
+for a given Psychometric Hue Angle, use
+.PN XcmsCIELabQueryMaxLC .
+.IN "Psychometric Hue Angle"
+.IN "Psychometric Chroma"
+.IN "CIE metric lightness"
+.IN "Psychometric Chroma" "maximum"
+.IN "CIE metric lightness" "maximum"
+.IN "XcmsCIELabQueryMaxLC" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsCIELabQueryMaxLC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIcolor_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsFloat \fIhue_angle\fP\^;
+.br
+      XcmsColor *\fIcolor_return\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+.ds Ha maximum chroma
+.IP \fIhue_angle\fP 1i
+Specifies the hue angle (in degrees) at which to find \*(Ha.
+.ds Lc maximum chroma
+.ds lC hue angle
+.IP \fIcolor_return\fP 1i
+Returns the CIE L*a*b* coordinates of \*(Lc
+displayable by the screen for the given \*(lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+.LP
+.eM 
+The
+.PN XcmsCIELabQueryMaxLC
+function, given a hue angle,
+finds the point of maximum chroma displayable by the screen.
+It returns this point in CIE L*a*b* coordinates.
+.sp
+.LP
+To obtain the CIE L*a*b* coordinates of minimum CIE metric lightness (L*)
+for a given Psychometric Hue Angle and Psychometric Chroma, use
+.PN XcmsCIELabQueryMinL .
+.IN "Psychometric Hue Angle"
+.IN "CIE metric lightness"
+.IN "CIE metric lightness" "minimum"
+.IN "XcmsCIELabQueryMinL" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsCIELabQueryMinL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsFloat \fIhue_angle\fP\^;
+.br
+      XcmsFloat \fIchroma\fP\^;
+.br
+      XcmsColor *\fIcolor_return\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+.ds Ha minimum lightness
+.IP \fIhue_angle\fP 1i
+Specifies the hue angle (in degrees) at which to find \*(Ha.
+.ds Ch minimum lightness
+.IP \fIchroma\fP 1i
+Specifies the chroma at which to find \*(Ch.
+.ds Lc minimum lightness
+.ds lC hue angle and chroma
+.IP \fIcolor_return\fP 1i
+Returns the CIE L*a*b* coordinates of \*(Lc
+displayable by the screen for the given \*(lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+.LP
+.eM 
+The
+.PN XcmsCIELabQueryMinL
+function, given a hue angle and chroma,
+finds the point of minimum lightness (L*) displayable by the screen.
+It returns this point in CIE L*a*b* coordinates.
+An 
+.PN XcmsFailure
+return value usually indicates that the given chroma
+is beyond maximum for the given hue angle.
+.NH 3
+CIELuv Queries
+.XS
+\*(SN CIELuv Queries
+.XE
+.LP
+The following equations are useful in describing the CIELuv query functions:
+.EQ
+delim %%
+.EN
+.LP
+.IN "Psychometric Hue Angle"
+.IN "CIE metric lightness"
+.IN "Psychometric Chroma"
+.IN "Psychometric Chroma" "maximum"
+.Ds 0
+%CIELuv~Psychometric~Chroma ~=~ sqrt(u_star sup 2 ~+~ v_star sup 2 )%
+
+%CIELuv~Psychometric~Hue ~=~ tan sup -1 left [ v_star over u_star right ]%
+.De
+.sp
+.LP
+To obtain the CIE L*u*v* coordinates of maximum Psychometric Chroma
+for a given Psychometric Hue Angle and CIE metric lightness (L*), use
+.PN XcmsCIELuvQueryMaxC .
+.IN "XcmsCIELuvQueryMaxC" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsCIELuvQueryMaxC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIL_star\fP\^, \fIcolor_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsFloat \fIhue_angle\fP\^;
+.br
+      XcmsFloat \fIL_star\fP\^;
+.br
+      XcmsColor *\fIcolor_return\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+.ds Ha maximum chroma
+.IP \fIhue_angle\fP 1i
+Specifies the hue angle (in degrees) at which to find \*(Ha.
+.ds Ls maximum chroma
+.IP \fIL_star\fP 1i
+Specifies the lightness (L*) at which to find \*(Ls.
+.ds Lc maximum chroma
+.ds lC hue angle and lightness
+.IP \fIcolor_return\fP 1i
+Returns the CIE L*u*v* coordinates of \*(Lc
+displayable by the screen for the given \*(lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+.LP
+.eM 
+The
+.PN XcmsCIELuvQueryMaxC
+function, given a hue angle and lightness,
+finds the point of maximum chroma displayable by the screen.
+It returns this point in CIE L*u*v* coordinates.
+.sp
+.LP
+To obtain the CIE L*u*v* coordinates of maximum CIE metric lightness (L*)
+for a given Psychometric Hue Angle and Psychometric Chroma, use
+.PN XcmsCIELuvQueryMaxL .
+.IN "Psychometric Hue Angle"
+.IN "CIE metric lightness"
+.IN "CIE metric lightness" "maximum"
+.IN "XcmsCIELuvQueryMaxL" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsCIELuvQueryMaxL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsFloat \fIhue_angle\fP\^;
+.br
+      XcmsFloat \fIchroma\fP\^;
+.br
+      XcmsColor *\fIcolor_return\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+.ds Ha maximum lightness
+.IP \fIhue_angle\fP 1i
+Specifies the hue angle (in degrees) at which to find \*(Ha.
+.ds Ls maximum lightness
+.IP \fIL_star\fP 1i
+Specifies the lightness (L*) at which to find \*(Ls.
+.ds Lc maximum lightness
+.ds lC hue angle and chroma
+.IP \fIcolor_return\fP 1i
+Returns the CIE L*u*v* coordinates of \*(Lc
+displayable by the screen for the given \*(lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+.LP
+.eM 
+The
+.PN XcmsCIELuvQueryMaxL
+function, given a hue angle and chroma,
+finds the point in CIE L*u*v* color space of maximum 
+lightness (L*) displayable by the screen.
+It returns this point in CIE L*u*v* coordinates.
+An 
+.PN XcmsFailure
+return value usually indicates that the given chroma
+is beyond maximum for the given hue angle.
+.sp
+.LP
+To obtain the CIE L*u*v* coordinates of maximum Psychometric Chroma
+for a given Psychometric Hue Angle, use
+.PN XcmsCIELuvQueryMaxLC .
+.IN "Psychometric Hue Angle"
+.IN "Psychometric Chroma"
+.IN "CIE metric lightness"
+.IN "Psychometric Chroma" "maximum"
+.IN "CIE metric lightness" "maximum"
+.IN "XcmsCIELuvQueryMaxLC" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsCIELuvQueryMaxLC\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIcolor_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsFloat \fIhue_angle\fP\^;
+.br
+      XcmsColor *\fIcolor_return\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+.ds Ha maximum chroma
+.IP \fIhue_angle\fP 1i
+Specifies the hue angle (in degrees) at which to find \*(Ha.
+.ds Lc maximum chroma
+.ds lC hue angle
+.IP \fIcolor_return\fP 1i
+Returns the CIE L*u*v* coordinates of \*(Lc
+displayable by the screen for the given \*(lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+.LP
+.eM 
+The
+.PN XcmsCIELuvQueryMaxLC
+function, given a hue angle,
+finds the point of maximum chroma displayable by the screen.
+It returns this point in CIE L*u*v* coordinates.
+.sp
+.LP
+To obtain the CIE L*u*v* coordinates of minimum CIE metric lightness (L*)
+for a given Psychometric Hue Angle and Psychometric Chroma, use
+.PN XcmsCIELuvQueryMinL .
+.IN "Psychometric Hue Angle"
+.IN "CIE metric lightness"
+.IN "CIE metric lightness" "minimum"
+.IN "XcmsCIELuvQueryMinL" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsCIELuvQueryMinL\^(\^\fIccc\fP\^, \fIhue_angle\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsFloat \fIhue_angle\fP\^;
+.br
+      XcmsFloat \fIchroma\fP\^;
+.br
+      XcmsColor *\fIcolor_return\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+.ds Ha minimum lightness
+.IP \fIhue_angle\fP 1i
+Specifies the hue angle (in degrees) at which to find \*(Ha.
+.ds Ch minimum lightness
+.IP \fIchroma\fP 1i
+Specifies the chroma at which to find \*(Ch.
+.ds Lc minimum lightness
+.ds lC hue angle and chroma
+.IP \fIcolor_return\fP 1i
+Returns the CIE L*u*v* coordinates of \*(Lc
+displayable by the screen for the given \*(lC.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+.LP
+.eM
+The
+.PN XcmsCIELuvQueryMinL
+function, given a hue angle and chroma,
+finds the point of minimum lightness (L*) displayable by the screen.
+It returns this point in CIE L*u*v* coordinates.
+An 
+.PN XcmsFailure
+return value usually indicates that the given chroma
+is beyond maximum for the given hue angle.
+.NH 3
+TekHVC Queries
+.XS
+\*(SN TekHVC Queries
+.XE
+.LP
+To obtain the maximum Chroma for a given Hue and Value, use
+.PN XcmsTekHVCQueryMaxC .
+.IN "Chroma"
+.IN "Chroma" "maximum"
+.IN "XcmsTekHVCQueryMaxC" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsTekHVCQueryMaxC\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIvalue\fP\^, \fIcolor_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsFloat \fIhue\fP\^;
+.br
+      XcmsFloat \fIvalue\fP\^;
+.br
+      XcmsColor *\fIcolor_return\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+.ds Hu in which to find the maximum Chroma
+.IP \fIhue\fP 1i
+Specifies the Hue \*(Hu.
+.ds Va maximum Chroma
+.IP \fIvalue\fP 1i
+Specifies the Value in which to find the \*(Va.
+.ds Lc maximum Chroma along with the actual Hue and Value 
+.ds lC maximum Chroma
+.IP \fIcolor_return\fP 1i
+Returns the \*(Lc at which the \*(lC was found.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+.LP
+.eM 
+The
+.PN XcmsTekHVCQueryMaxC
+function, given a Hue and Value,
+determines the maximum Chroma in TekHVC color space
+displayable by the screen.
+It returns the maximum Chroma along with the actual Hue
+and Value at which the maximum Chroma was found.
+.sp
+.LP
+To obtain the maximum Value for a given Hue and Chroma, use
+.PN XcmsTekHVCQueryMaxV .
+.IN "Value"
+.IN "Value" "maximum"
+.IN "XcmsTekHVCQueryMaxV" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsTekHVCQueryMaxV\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsFloat \fIhue\fP\^;
+.br
+      XcmsFloat \fIchroma\fP\^;
+.br
+      XcmsColor *\fIcolor_return\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+.ds Hu in which to find the maximum Value
+.IP \fIhue\fP 1i
+Specifies the Hue \*(Hu.
+.ds Ch maximum Value
+.IP \fIchroma\fP 1i
+Specifies the chroma at which to find \*(Ch.
+.ds Lc maximum Value along with the Hue and Chroma
+.ds lC maximum Value
+.IP \fIcolor_return\fP 1i
+Returns the \*(Lc at which the \*(lC was found.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+.LP
+.eM 
+The
+.PN XcmsTekHVCQueryMaxV
+function, given a Hue and Chroma,
+determines the maximum Value in TekHVC color space
+displayable by the screen.
+It returns the maximum Value and the actual Hue and Chroma
+at which the maximum Value was found.
+.sp
+.LP
+To obtain the maximum Chroma and Value at which it is reached
+for a specified Hue, use
+.PN XcmsTekHVCQueryMaxVC .
+.IN "Chroma"
+.IN "Value"
+.IN "Chroma"  "maximum"
+.IN "Value" "maximum"
+.IN "XcmsTekHVCQueryMaxVC" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsTekHVCQueryMaxVC\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIcolor_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsFloat \fIhue\fP\^;
+.br
+      XcmsColor *\fIcolor_return\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+.ds Hu in which to find the maximum Chroma
+.IP \fIhue\fP 1i
+Specifies the Hue \*(Hu.
+.ds Lc color specification in \
+XcmsTekHVC for the maximum Chroma, the Value at which \
+that maximum Chroma is reached, and the actual Hue
+.ds lC maximum Chroma
+.IP \fIcolor_return\fP 1i
+Returns the \*(Lc at which the \*(lC was found.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+.LP
+.eM 
+The
+.PN XcmsTekHVCQueryMaxVC
+function, given a Hue,
+determines the maximum Chroma in TekHVC color space displayable by the screen
+and the Value at which that maximum Chroma is reached.
+It returns the maximum Chroma,
+the Value at which that maximum Chroma is reached,
+and the actual Hue for which the maximum Chroma was found.
+.sp
+.LP
+To obtain a specified number of TekHVC specifications such that they
+contain maximum Values for a specified Hue and the
+Chroma at which the maximum Values are reached, use
+.PN XcmsTekHVCQueryMaxVSamples .
+.IN "Chroma"
+.IN "Value"
+.IN "Chroma"  "maximum"
+.IN "Value" "maximum"
+.IN "XcmsTekHVCQueryMaxVSamples" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsTekHVCQueryMaxVSamples\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIcolors_return\fP\^, \fInsamples\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsFloat \fIhue\fP\^;
+.br
+      XcmsColor \fIcolors_return[]\fP\^;
+.br
+      unsigned int \fInsamples\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+.ds Hu for maximum Chroma/Value samples
+.IP \fIhue\fP 1i
+Specifies the Hue \*(Hu.
+.IP \fInsamples\fP 1i
+Specifies the number of samples.
+.IP \fIcolors_return\fP 1i
+Returns nsamples of color specifications in XcmsTekHVC
+such that the Chroma is the maximum attainable for the Value and Hue.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+.LP
+.eM 
+The
+.PN XcmsTekHVCQueryMaxVSamples
+returns nsamples of maximum Value, the Chroma at which that maximum Value
+is reached, and the actual Hue for which the maximum Chroma was found.
+These sample points may then be used to plot the maximum Value/Chroma
+boundary of the screen's color gamut for the specified Hue in TekHVC color
+space.
+.sp
+.LP
+To obtain the minimum Value for a given Hue and Chroma, use
+.PN XcmsTekHVCQueryMinV .
+.IN "Value"
+.IN "Value" "minimum"
+.IN "XcmsTekHVCQueryMinV" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsTekHVCQueryMinV\^(\^\fIccc\fP\^, \fIhue\fP\^, \fIchroma\fP\^, \fIcolor_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsFloat \fIhue\fP\^;
+.br
+      XcmsFloat \fIchroma\fP\^;
+.br
+      XcmsColor *\fIcolor_return\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+The CCC's Client White Point and white point adjustment procedures
+are ignored.
+.ds Hu in which to find the minimum Value
+.IP \fIhue\fP 1i
+Specifies the Hue \*(Hu.
+.ds Va minimum Value
+.IP \fIvalue\fP 1i
+Specifies the Value in which to find the \*(Va.
+.ds Lc minimum Value and the actual Hue and Chroma
+.ds lC minimum Value
+.IP \fIcolor_return\fP 1i
+Returns the \*(Lc at which the \*(lC was found.
+The white point associated with the returned
+color specification is the Screen White Point.
+The value returned in the pixel member is undefined.
+.LP
+.eM 
+The
+.PN XcmsTekHVCQueryMinV
+function, given a Hue and Chroma,
+determines the minimum Value in TekHVC color space displayable by the screen.
+It returns the minimum Value and the actual Hue and Chroma at which
+the minimum Value was found.
+.NH 2
+Color Management Extensions
+.XS
+\*(SN Color Management Extensions
+.XE
+.LP
+The Xlib color management facilities can be extended in two ways:
+.IP \(bu 5
+Device-Independent Color Spaces
+.IP
+Device-independent color spaces that are derivable to CIE XYZ
+space can be added using the
+.PN XcmsAddColorSpace
+function.
+.IP \(bu 5
+Color Characterization Function Set
+.IP
+A Color Characterization Function Set consists of
+device-dependent color spaces and their functions that
+convert between these color spaces and the CIE XYZ
+color space, bundled together for a specific class of output devices.
+A function set can be added using the
+.PN XcmsAddFunctionSet
+function.
+.NH 3
+Color Spaces
+.XS
+\*(SN Color Spaces
+.XE
+.LP
+The CIE XYZ color space serves as the hub for all
+conversions between device-independent and device-dependent color spaces.
+Therefore, the knowledge to convert an 
+.PN XcmsColor
+structure to and from CIE XYZ format is associated with each color space.
+For example, conversion from CIE L*u*v* to RGB requires the knowledge
+to convert from CIE L*u*v* to CIE XYZ and from CIE XYZ to RGB.
+This knowledge is stored as an array of functions that,
+when applied in series, will convert the 
+.PN XcmsColor
+structure to or from CIE XYZ format.
+This color specification conversion mechanism facilitates
+the addition of color spaces.
+.LP
+Of course, when converting between only device-independent color spaces
+or only device-dependent color spaces,
+shortcuts are taken whenever possible.
+For example, conversion from TekHVC to CIE L*u*v* is performed 
+by intermediate conversion to CIE u*v*Y and then to CIE L*u*v*, 
+thus bypassing conversion between CIE u*v*Y and CIE XYZ.
+.NH 3
+Adding Device-Independent Color Spaces
+.XS
+\*(SN Adding Device-Independent Color Spaces
+.XE
+.LP
+To add a device-independent color space, use
+.PN XcmsAddColorSpace .
+.IN  "XcmsAddColorSpace" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsAddColorSpace\^(\^\fIcolor_space\fP\^)
+.br
+      XcmsColorSpace *\fIcolor_space\fP\^;
+.FN
+.IP \fIcolor_space\fP 1i
+Specifies the device-independent color space to add.
+.LP
+.eM
+The
+.PN XcmsAddColorSpace
+function makes a device-independent color space (actually an
+.PN XcmsColorSpace
+structure) accessible by the color management system.
+Because format values for unregistered color spaces are assigned at run time,
+they should be treated as private to the client.
+If references to an unregistered color space must be made
+outside the client (for example, storing color specifications 
+in a file using the unregistered color space), 
+then reference should be made by color space prefix
+(see
+.PN XcmsFormatOfPrefix
+and
+.PN XcmsPrefixOfFormat ).
+.LP
+If the 
+.PN XcmsColorSpace
+structure is already accessible in the color management system, 
+.PN XcmsAddColorSpace
+returns 
+.PN XcmsSuccess .
+.LP
+Note that added 
+.PN XcmsColorSpaces
+must be retained for reference by Xlib.
+.NH 3
+Querying Color Space Format and Prefix
+.XS
+\*(SN Querying Color Space Format and Prefix
+.XE
+.LP
+To obtain the format associated with the color space
+associated with a specified color string prefix, use
+.PN XcmsFormatOfPrefix .
+.IN  "XcmsFormatOfPrefix" "" "@DEF@"
+.sM
+.FD 0
+XcmsColorFormat XcmsFormatOfPrefix\^(\^\fIprefix\fP\^)
+.br
+      char *\fIprefix\fP\^;
+.FN
+.IP \fIprefix\fP 1i
+Specifies the string that contains the color space prefix.
+.LP
+.eM
+The
+.PN XcmsFormatOfPrefix
+function returns the format for the specified color space prefix
+(for example, the string ``CIEXYZ'').
+The prefix is case-insensitive.
+If the color space is not accessible in the color management system,
+.PN XcmsFormatOfPrefix
+returns 
+.PN XcmsUndefinedFormat .
+.LP
+.sp
+To obtain the color string prefix associated with the color space
+specified by a color format, use
+.PN XcmsPrefixOfFormat .
+.IN  "XcmsPrefixOfFormat" "" "@DEF@"
+.sM
+.FD 0
+char *XcmsPrefixOfFormat\^(\^\fIformat\fP\^)
+.br
+      XcmsColorFormat \fIformat\fP\^;
+.FN
+.IP \fIformat\fP 1i
+Specifies the color specification format.
+.LP
+.eM
+The
+.PN XcmsPrefixOfFormat
+function returns the string prefix associated with the color specification
+encoding specified by the format argument.
+Otherwise, if no encoding is found, it returns NULL.
+The returned string must be treated as read-only.
+.NH 3
+Creating Additional Color Spaces
+.XS
+\*(SN Creating Additional Color Spaces
+.XE
+.LP
+Color space specific information necessary 
+for color space conversion and color string parsing is stored in an
+.PN XcmsColorSpace
+structure.
+Therefore, a new structure containing this information is required
+for each additional color space.
+In the case of device-independent color spaces,
+a handle to this new structure (that is, by means of a global variable)
+is usually made accessible to the client program for use with the
+.PN XcmsAddColorSpace
+function.
+.LP
+If a new 
+.PN XcmsColorSpace
+structure specifies a color space not registered with the X Consortium,
+they should be treated as private to the client
+because format values for unregistered color spaces are assigned at run time.
+If references to an unregistered color space must be made outside the
+client (for example, storing color specifications in a file using the
+unregistered color space), then reference should be made by color space prefix
+(see
+.PN XcmsFormatOfPrefix
+and
+.PN XcmsPrefixOfFormat ).
+.sM
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef (*XcmsConversionProc)();
+typedef XcmsConversionProc *XcmsFuncListPtr;
+		/* A NULL terminated list of function pointers*/
+
+typedef struct _XcmsColorSpace {
+	char *prefix;
+	XcmsColorFormat format;
+	XcmsParseStringProc parseString;
+	XcmsFuncListPtr to_CIEXYZ;
+	XcmsFuncListPtr from_CIEXYZ;
+	int inverse_flag;
+} XcmsColorSpace;
+.De
+.LP
+.eM
+The prefix member specifies the prefix that indicates a color string 
+is in this color space's string format.
+For example, the strings ``ciexyz'' or ``CIEXYZ'' for CIE XYZ,
+and ``rgb'' or ``RGB'' for RGB.
+The prefix is case insensitive.
+The format member specifies the color specification format.
+Formats for unregistered color spaces are assigned at run time.
+The parseString member contains a pointer to the function 
+that can parse a color string into an 
+.PN XcmsColor
+structure.
+This function returns an integer (int): nonzero if it succeeded
+and zero otherwise.
+The to_CIEXYZ and from_CIEXYZ members contain pointers,
+each to a NULL terminated list of function pointers.
+When the list of functions is executed in series,
+it will convert the color specified in an 
+.PN XcmsColor
+structure from/to the current color space format to/from the CIE XYZ format.
+Each function returns an integer (int): nonzero if it succeeded
+and zero otherwise.
+The white point to be associated with the colors is specified
+explicitly, even though white points can be found in the CCC.
+The inverse_flag member, if nonzero, specifies that for each function listed 
+in to_CIEXYZ,
+its inverse function can be found in from_CIEXYZ such that:
+.LP
+.Ds 0
+Given:  n = number of functions in each list
+
+for each i, such that 0 <= i < n
+    from_CIEXYZ[n - i - 1] is the inverse of to_CIEXYZ[i].
+.De
+.LP
+This allows Xlib to use the shortest conversion path,
+thus bypassing CIE XYZ if possible (for example, TekHVC to CIE L*u*v*).
+.NH 3
+Parse String Callback
+.XS
+\*(SN Parse String Callback
+.XE
+.LP
+The callback in the
+.PN XcmsColorSpace
+structure for parsing a color string for the particular color space must
+adhere to the following software interface specification:
+.IN  "XcmsParseStringProc" "" "@DEF@"
+.sM
+.FD 0
+typedef int (*XcmsParseStringProc)\^(\^\fIcolor_string\fP, \fIcolor_return\fP\^)
+.br
+      char *\fIcolor_string\fP\^;
+.br
+      XcmsColor *\fIcolor_return\fP\^;
+.FN
+.IP \fIcolor_string\fP 1i
+Specifies the color string to parse.
+.IP \fIcolor_return\fP 1i
+Returns the color specification in the color space's format.
+.LP
+.eM
+.NH 3
+Color Specification Conversion Callback
+.XS
+\*(SN Color Specification Conversion Callback
+.XE
+.LP
+Callback functions in the
+.PN XcmsColorSpace
+structure for converting a color specification between device-independent
+spaces must adhere to the
+following software interface specification:
+.sM
+.FD 0
+Status ConversionProc\^(\^\fIccc\fP, \fIwhite_point\fP, \fIcolors_in_out\fP, \fIncolors\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsColor *\fIwhite_point\fP\^;
+.br
+      XcmsColor *\fIcolors_in_out\fP\^;
+.br
+      unsigned int \fIncolors\fP\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+.IP \fIwhite_point\fP 1i
+Specifies the white point associated with color specifications.
+The pixel member should be ignored,
+and the entire structure remain unchanged upon return.
+.IP \fIcolors_in_out\fP 1i
+Specifies an array of color specifications.
+Pixel members should be ignored and must remain unchanged upon return.
+.IP \fIncolors\fP 1i
+Specifies the number of 
+.PN XcmsColor
+structures in the color-specification array.
+.LP
+.eM
+.sp
+Callback functions in the
+.PN XcmsColorSpace
+structure for converting a color specification to or from a device-dependent
+space must adhere to the
+following software interface specification:
+.sM
+.FD 0
+Status ConversionProc\^(\^\fIccc\fP, \fIcolors_in_out\fP, \fIncolors\fP, \fIcompression_flags_return\fP\^)
+.br
+      XcmsCCC \fIccc\fP\^;
+.br
+      XcmsColor *\fIcolors_in_out\fP\^;
+.br
+      unsigned int \fIncolors\fP\^;
+.br
+      Bool \fIcompression_flags_return\fP\^[\^]\^;
+.FN
+.IP \fIccc\fP 1i
+Specifies the CCC.
+.IP \fIcolors_in_out\fP 1i
+Specifies an array of color specifications.
+Pixel members should be ignored and must remain unchanged upon return.
+.IP \fIncolors\fP 1i
+Specifies the number of 
+.PN XcmsColor
+structures in the color-specification array.
+.IP \fIcompression_flags_return\fP 1i
+Returns an array of Boolean values for indicating compression status.
+If a non-NULL pointer is supplied
+and a color at a given index is compressed, then
+.PN True
+should be stored at the corresponding index in this array;
+otherwise, the array should not be modified.
+.LP
+.eM
+Conversion functions are available globally for use by other color
+spaces.
+The conversion functions provided by Xlib are:
+.TS H
+lw(1.8i) lw(1.8i) lw(1.8i).
+_
+.sp 6p
+.B
+Function	Converts from	Converts to
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+T{
+.PN XcmsCIELabToCIEXYZ
+T}	T{
+.PN XcmsCIELabFormat
+T}	T{
+.PN XcmsCIEXYZFormat
+T}
+T{
+.PN XcmsCIELuvToCIEuvY
+T}	T{
+.PN XcmsCIELuvFormat
+T}	T{
+.PN XcmsCIEuvYFormat
+T}
+T{
+.PN XcmsCIEXYZToCIELab
+T}	T{
+.PN XcmsCIEXYZFormat
+T}	T{
+.PN XcmsCIELabFormat
+T}
+T{
+.PN XcmsCIEXYZToCIEuvY
+T}	T{
+.PN XcmsCIEXYZFormat
+T}	T{
+.PN XcmsCIEuvYFormat
+T}
+T{
+.PN XcmsCIEXYZToCIExyY
+T}	T{
+.PN XcmsCIEXYZFormat
+T}	T{
+.PN XcmsCIExyYFormat
+T}
+T{
+.PN XcmsCIEXYZToRGBi
+T}	T{
+.PN XcmsCIEXYZFormat
+T}	T{
+.PN XcmsRGBiFormat
+T}
+T{
+.PN XcmsCIEuvYToCIELuv
+T}	T{
+.PN XcmsCIEuvYFormat
+T}	T{
+.PN XcmsCIELabFormat
+T}
+T{
+.PN XcmsCIEuvYToCIEXYZ
+T}	T{
+.PN XcmsCIEuvYFormat
+T}	T{
+.PN XcmsCIEXYZFormat
+T}
+T{
+.PN XcmsCIEuvYToTekHVC
+T}	T{
+.PN XcmsCIEuvYFormat
+T}	T{
+.PN XcmsTekHVCFormat
+T}
+T{
+.PN XcmsCIExyYToCIEXYZ
+T}	T{
+.PN XcmsCIExyYFormat
+T}	T{
+.PN XcmsCIEXYZFormat
+T}
+T{
+.PN XcmsRGBToRGBi
+T}	T{
+.PN XcmsRGBFormat
+T}	T{
+.PN XcmsRGBiFormat
+T}
+T{
+.PN XcmsRGBiToCIEXYZ
+T}	T{
+.PN XcmsRGBiFormat
+T}	T{
+.PN XcmsCIEXYZFormat
+T}
+T{
+.PN XcmsRGBiToRGB
+T}	T{
+.PN XcmsRGBiFormat
+T}	T{
+.PN XcmsRGBFormat
+T}
+T{
+.PN XcmsTekHVCToCIEuvY
+T}	T{
+.PN XcmsTekHVCFormat
+T}	T{
+.PN XcmsCIEuvYFormat
+T}
+.sp 6p
+_
+.TE
+.NH 3
+Function Sets
+.XS
+\*(SN Function Sets
+.XE
+.IN "Function set"
+.IN "Function set" "LINEAR_RGB"
+.LP
+Functions to convert between device-dependent color spaces
+and CIE XYZ may differ for different classes of output devices
+(for example, color versus gray monitors).
+Therefore, the notion of a Color Characterization Function Set
+has been developed.
+A function set consists of device-dependent color spaces
+and the functions that convert color specifications 
+between these device-dependent color spaces and the CIE XYZ color space
+appropriate for a particular class of output devices.
+The function set also contains a function that reads
+color characterization data off root window properties.
+It is this characterization data that will differ between devices within
+a class of output devices.
+.IN "Device Color Characterization"
+For details about how color characterization data is
+stored in root window properties,
+see the section on Device Color Characterization in the
+\fIInter-Client Communication Conventions Manual\fP.
+The LINEAR_RGB function set is provided by Xlib
+and will support most color monitors.
+Function sets may require data that differs
+from those needed for the LINEAR_RGB function set.
+In that case, 
+its corresponding data may be stored on different root window properties.
+.NH 3
+Adding Function Sets
+.XS
+\*(SN Adding Function Sets
+.XE
+.LP
+To add a function set, use
+.PN XcmsAddFunctionSet .
+.IN  "XcmsAddFunctionSet" "" "@DEF@"
+.sM
+.FD 0
+Status XcmsAddFunctionSet\^(\^\fIfunction_set\fP\^)
+.br
+      XcmsFunctionSet *\fIfunction_set\fP\^;
+.FN
+.IP \fIfunction_set\fP 1i
+Specifies the function set to add.
+.LP
+.eM
+The
+.PN XcmsAddFunctionSet
+function adds a function set to the color management system.
+If the function set uses device-dependent 
+.PN XcmsColorSpace
+structures not accessible in the color management system,
+.PN XcmsAddFunctionSet
+adds them.
+If an added
+.PN XcmsColorSpace
+structure is for a device-dependent color space not registered
+with the X Consortium,
+they should be treated as private to the client
+because format values for unregistered color spaces are assigned at run time.
+If references to an unregistered color space must be made outside the
+client (for example, storing color specifications in a file
+using the unregistered color space),
+then reference should be made by color space prefix
+(see 
+.PN XcmsFormatOfPrefix
+and
+.PN XcmsPrefixOfFormat ).
+.LP
+Additional function sets should be added before any calls to other
+Xlib routines are made.
+If not, the 
+.PN XcmsPerScrnInfo
+member of a previously created 
+.PN XcmsCCC
+does not have the opportunity to initialize
+with the added function set.
+.NH 3
+Creating Additional Function Sets
+.XS
+\*(SN Creating Additional Function Sets
+.XE
+.LP
+The creation of additional function sets should be
+required only when an output device does not conform to existing 
+function sets or when additional device-dependent color spaces are necessary.
+A function set consists primarily of a collection of device-dependent
+.PN XcmsColorSpace
+structures and a means to read and store a 
+screen's color characterization data.
+This data is stored in an
+.PN XcmsFunctionSet
+structure.
+A handle to this structure (that is, by means of global variable)
+is usually made accessible to the client program for use with
+.PN XcmsAddFunctionSet .
+.LP
+If a function set uses new device-dependent 
+.PN XcmsColorSpace
+structures,
+they will be transparently processed into the color management system.
+Function sets can share an 
+.PN XcmsColorSpace
+structure for a device-dependent color space.
+In addition, multiple 
+.PN XcmsColorSpace
+structures are allowed for a device-dependent color space;
+however, a function set can reference only one of them.
+These 
+.PN XcmsColorSpace
+structures will differ in the functions to convert to and from CIE XYZ,
+thus tailored for the specific function set.
+.sM
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct _XcmsFunctionSet {
+	XcmsColorSpace **DDColorSpaces;
+	XcmsScreenInitProc screenInitProc;
+	XcmsScreenFreeProc screenFreeProc;
+} XcmsFunctionSet;
+.De
+.LP
+.eM
+The DDColorSpaces member is a pointer to a NULL terminated list
+of pointers to 
+.PN XcmsColorSpace
+structures for the device-dependent color spaces that are supported
+by the function set.
+The screenInitProc member is set to the callback procedure (see the following
+interface specification) that initializes the 
+.PN XcmsPerScrnInfo
+structure for a particular screen.
+.LP
+The screen initialization callback must adhere to the following software
+interface specification:
+.IN  "XcmsScreenInitProc" "" "@DEF@"
+.sM
+.FD 0
+typedef Status (*XcmsScreenInitProc)\^(\^\fIdisplay\fP, \fIscreen_number\fP, \fIscreen_info\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen_number\fP\^;
+.br
+      XcmsPerScrnInfo *\fIscreen_info\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.IP \fIscreen_info\fP 1i
+Specifies the 
+.PN XcmsPerScrnInfo 
+structure, which contains the per screen information.
+.LP
+.eM
+The screen initialization callback in the
+.PN XcmsFunctionSet
+structure fetches the color characterization data (device profile) for
+the specified screen,
+typically off properties on the 
+screen's root window.
+It then initializes the specified
+.PN XcmsPerScrnInfo
+structure.
+.IN "Device profile"
+.IN "Color Characterization Data"
+If successful, the procedure fills in the 
+.PN XcmsPerScrnInfo
+structure as follows:
+.IP \(bu 5
+It sets the screenData member to the address 
+of the created device profile data structure 
+(contents known only by the function set).
+.IP \(bu 5
+It next sets the screenWhitePoint member.
+.IP \(bu 5
+It next sets the functionSet member to the address of the
+.PN XcmsFunctionSet
+structure.
+.IP \(bu 5
+It then sets the state member to 
+.PN XcmsInitSuccess 
+and finally returns
+.PN XcmsSuccess .
+.LP
+If unsuccessful, the procedure sets the state member to 
+.PN XcmsInitFailure
+and returns
+.PN XcmsFailure .
+.LP
+The
+.PN XcmsPerScrnInfo
+structure contains:
+.sM
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct _XcmsPerScrnInfo {
+	XcmsColor screenWhitePoint;
+	XPointer functionSet;
+	XPointer screenData;
+	unsigned char state;
+	char pad[3];
+} XcmsPerScrnInfo;
+.De
+.LP
+.eM
+The screenWhitePoint member specifies the white point inherent to
+the screen.
+The functionSet member specifies the appropriate function set.
+The screenData member specifies the device profile.
+The state member is set to one of the following:
+.IP \(bu 5
+.PN XcmsInitNone
+indicates initialization has not been previously attempted.
+.IP \(bu 5
+.PN XcmsInitFailure
+indicates initialization has been previously attempted but failed.
+.IP \(bu 5
+.PN XcmsInitSuccess
+indicates initialization has been previously attempted and succeeded.
+.LP
+The screen free callback must adhere to the following software
+interface specification:
+.IN  "XcmsScreenFreeProc" "" "@DEF@"
+.sM
+.FD 0
+typedef void (*XcmsScreenFreeProc)\^(\^\fIscreenData\fP\^)
+.br
+      XPointer \fIscreenData\fP\^;
+.FN
+.IP \fIscreenData\fP 1i
+Specifies the data to be freed.
+.LP
+.eM
+This function is called to free the screenData stored in an
+.PN XcmsPerScrnInfo
+structure.
+.bp
diff --git a/specs/libX11/CH07 b/specs/libX11/CH07
new file mode 100644
index 00000000..d6f67228
--- /dev/null
+++ b/specs/libX11/CH07
@@ -0,0 +1,2357 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 7\fP\s-1
+
+\s+1\fBGraphics Context Functions\fP\s-1
+.sp 2
+.nr H1 7
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.na
+.LP
+.XS
+Chapter 7: Graphics Context Functions 
+.XE
+A number of resources are used when performing graphics operations in X.
+Most information about performing graphics (for example, foreground
+color, background color, line style, and so on) is stored in
+resources called graphics contexts (GCs).
+.IN "Graphics context"
+Most graphics operations (see chapter 8) take a 
+GC as an argument.
+Although in theory the X protocol permits sharing of GCs between applications, 
+it is expected that applications will use their own
+GCs when performing operations. 
+Sharing of GCs is highly discouraged because the library may cache GC state.
+.LP
+Graphics operations can be performed to either windows or pixmaps, 
+which collectively are called drawables.
+.IN "Root"
+Each drawable exists on a single screen.
+A GC is created for a specific screen and drawable depth
+and can only be used with drawables of matching
+screen and depth.
+.LP
+This chapter discusses how to:
+.IP \(bu 5
+Manipulate graphics context/state
+.IP \(bu 5
+Use graphics context convenience functions
+.NH 2
+Manipulating Graphics Context/State
+.XS
+\*(SN Manipulating Graphics Context/State 
+.XE
+.LP
+Most attributes of graphics operations are stored in GCs.
+These include line width, line style, plane mask, foreground, background,
+tile, stipple, clipping region, end style, join style, and so on.
+Graphics operations (for example, drawing lines) use these values
+to determine the actual drawing operation.
+Extensions to X may add additional components to GCs.
+The contents of a GC are private to Xlib.
+.LP
+Xlib implements a write-back cache for all elements of a GC that are not
+resource IDs to allow Xlib to implement the transparent coalescing of changes 
+to GCs.
+For example,
+a call to
+.PN XSetForeground
+of a GC followed by a call to
+.PN XSetLineAttributes
+results in only a single-change GC protocol request to the server.
+GCs are neither expected nor encouraged to be shared between client 
+applications, so this write-back caching should present no problems.
+Applications cannot share GCs without external synchronization.
+Therefore,
+sharing GCs between applications is highly discouraged. 
+.LP
+To set an attribute of a GC,
+set the appropriate member of the
+.PN XGCValues
+structure and OR in the corresponding value bitmask in your subsequent calls to
+.PN XCreateGC .
+The symbols for the value mask bits and the
+.PN XGCValues
+structure are:
+.sM
+.LP
+/* GC attribute value mask bits */
+.TS
+lw(.5i) lw(2.5i) lw(.75i).
+#define\
+	T{
+.PN GCFunction
+T}	T{
+(1L<<0)
+T}
+#define\
+	T{
+.PN GCPlaneMask
+T}	T{
+(1L<<1)
+T}
+#define\
+	T{
+.PN GCForeground
+T}	T{
+(1L<<2)
+T}
+#define\
+	T{
+.PN GCBackground
+T}	T{
+(1L<<3)
+T}
+#define\
+	T{
+.PN GCLineWidth
+T}	T{
+(1L<<4)
+T}
+#define\
+	T{
+.PN GCLineStyle
+T}	T{
+(1L<<5)
+T}
+#define\
+	T{
+.PN GCCapStyle
+T}	T{
+(1L<<6)
+T}
+#define\
+	T{
+.PN GCJoinStyle
+T}	T{
+(1L<<7)
+T}
+#define\
+	T{
+.PN GCFillStyle
+T}	T{
+(1L<<8)
+T}
+#define\
+	T{
+.PN GCFillRule
+T}	T{
+(1L<<9)
+T}
+#define\
+	T{
+.PN GCTile
+T}	T{
+(1L<<10)
+T}
+#define\
+	T{
+.PN GCStipple
+T}	T{
+(1L<<11)
+T}
+#define\
+	T{
+.PN GCTileStipXOrigin
+T}	T{
+(1L<<12)
+T}
+#define\
+	T{
+.PN GCTileStipYOrigin
+T}	T{
+(1L<<13)
+T}
+#define\
+	T{
+.PN GCFont
+T}	T{
+(1L<<14)
+T}
+#define\
+	T{
+.PN GCSubwindowMode
+T}	T{
+(1L<<15)
+T}
+#define\
+	T{
+.PN GCGraphicsExposures
+T}	T{
+(1L<<16)
+T}
+#define\
+	T{
+.PN GCClipXOrigin
+T}	T{
+(1L<<17)
+T}
+#define\
+	T{
+.PN GCClipYOrigin
+T}	T{
+(1L<<18)
+T}
+#define\
+	T{
+.PN GCClipMask
+T}	T{
+(1L<<19)
+T}
+#define\
+	T{
+.PN GCDashOffset
+T}	T{
+(1L<<20)
+T}
+#define\
+	T{
+.PN GCDashList
+T}	T{
+(1L<<21)
+T}
+#define\
+	T{
+.PN GCArcMode
+T}	T{
+(1L<<22)
+T}
+.TE
+.IN "XGCValues" "" "@DEF@"
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+/* Values */
+
+typedef struct {
+	int function;	/* logical operation */
+	unsigned long plane_mask;	/* plane mask */
+	unsigned long foreground;	/* foreground pixel */
+	unsigned long background;	/* background pixel */
+	int line_width;	/* line width (in pixels) */
+	int line_style;	/* LineSolid, LineOnOffDash, LineDoubleDash */
+	int cap_style;	/* CapNotLast, CapButt, CapRound, CapProjecting */
+	int join_style;	/* JoinMiter, JoinRound, JoinBevel */
+	int fill_style;	/* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/
+	int fill_rule;	/* EvenOddRule, WindingRule */
+	int arc_mode;	/* ArcChord, ArcPieSlice */
+	Pixmap tile;	/* tile pixmap for tiling operations */
+	Pixmap stipple;	/* stipple 1 plane pixmap for stippling */
+	int ts_x_origin;	/* offset for tile or stipple operations */
+	int ts_y_origin;
+	Font font;	/* default text font for text operations */
+	int subwindow_mode;	/* ClipByChildren, IncludeInferiors */
+	Bool graphics_exposures;	/* boolean, should exposures be generated */
+	int clip_x_origin;	/* origin for clipping */
+	int clip_y_origin;
+	Pixmap clip_mask;	/* bitmap clipping; other calls for rects */
+	int dash_offset;	/* patterned/dashed line information */
+	char dashes;
+} XGCValues;
+.De
+.LP
+.eM 
+The default GC values are:
+.TS H
+l l.
+_
+.sp 6p
+.B
+Component	Default
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+T{
+function
+T}	T{
+.PN GXcopy
+T}
+plane_mask	All ones
+foreground	0
+background	1
+line_width	0
+T{
+line_style
+T}	T{
+.PN LineSolid
+T}
+T{
+cap_style
+T}	T{
+.PN CapButt
+T}
+T{
+join_style
+T}	T{
+.PN JoinMiter
+T}
+T{
+fill_style
+T}	T{
+.PN FillSolid
+T}
+T{
+fill_rule
+T}	T{
+.PN EvenOddRule
+T}
+T{
+arc_mode
+T}	T{
+.PN ArcPieSlice
+T}
+tile	Pixmap of unspecified size filled with foreground pixel
+	(that is, client specified pixel if any, else 0)
+	(subsequent changes to foreground do not affect this pixmap)
+stipple	Pixmap of unspecified size filled with ones
+ts_x_origin	0
+ts_y_origin	0
+font	<implementation dependent>
+T{
+subwindow_mode
+T}	T{
+.PN ClipByChildren
+T}
+T{
+graphics_exposures
+T}	T{
+.PN True
+T}
+clip_x_origin	0
+clip_y_origin	0
+T{
+clip_mask
+T}	T{
+.PN None
+T}
+dash_offset	0
+dashes	4 (that is, the list [4, 4])
+.sp 6p
+_
+.TE
+.LP
+Note that foreground and background are not set to any values likely
+to be useful in a window.
+.LP
+.IN "Display Functions" "" "@DEF@"
+.IN "Source" "" "@DEF@"
+.IN "Destination" "" "@DEF@"
+The function attributes of a GC are used when you update a section of
+a drawable (the destination) with bits from somewhere else (the source).  
+The function in a GC defines how the new destination bits are to be
+computed from the source bits and the old destination bits.
+.PN GXcopy
+is typically the most useful because it will work on a color display,
+but special applications may use other functions,
+particularly in concert with particular planes of a color display.
+The 16 GC functions, defined in 
+.hN X11/X.h ,
+are:
+.\" are listed in Table 5-1 along with the 
+.\"the associated hexadecimal code
+.\" and operation.
+.\".CP T 1
+.\"Display Functions
+.TS H
+lw(1.5i) cw(.5i) lw(2i).
+_
+.sp 6p
+.B
+Function Name	Value	Operation
+.sp 6p
+_
+.sp 6p
+.TH
+T{
+.PN GXclear
+T}	T{
+0x0
+T}	T{
+0
+T}
+T{
+.PN GXand
+T}	T{
+0x1
+T}	T{
+src AND dst
+T}
+T{
+.PN GXandReverse
+T}	T{
+0x2
+T}	T{
+src AND NOT dst
+T}
+T{
+.PN GXcopy
+T}	T{
+0x3
+T}	T{
+src
+T}
+T{
+.PN GXandInverted
+T}	T{
+0x4
+T}	T{
+(NOT src) AND dst
+T}
+T{
+.PN GXnoop
+T}	T{
+0x5
+T}	T{
+dst
+T}
+T{
+.PN GXxor
+T}	T{
+0x6
+T}	T{
+src XOR dst
+T}
+T{
+.PN GXor
+T}	T{
+0x7
+T}	T{
+src OR dst
+T}
+T{
+.PN GXnor
+T}	T{
+0x8
+T}	T{
+(NOT src) AND (NOT dst)
+T}
+T{
+.PN GXequiv
+T}	T{
+0x9
+T}	T{
+(NOT src) XOR dst
+T}
+T{
+.PN GXinvert
+T}	T{
+0xa
+T}	T{
+NOT dst
+T}
+T{
+.PN GXorReverse
+T}	T{
+0xb
+T}	T{
+src OR (NOT dst)
+T}
+T{
+.PN GXcopyInverted
+T}	T{
+0xc
+T}	T{
+NOT src
+T}
+T{
+.PN GXorInverted
+T}	T{
+0xd
+T}	T{
+(NOT src) OR dst
+T}
+T{
+.PN GXnand
+T}	T{
+0xe
+T}	T{
+(NOT src) OR (NOT dst)
+T}
+T{
+.PN GXset
+T}	T{
+0xf
+T}	T{
+1
+T}
+.sp 6p
+_
+.TE
+.LP
+Many graphics operations depend on either pixel values or planes in a GC.
+.IN "Pixel value"
+The planes attribute is of type long, and it specifies which planes of the
+destination are to be modified, one bit per plane.
+.IN "Plane" "mask"
+A monochrome display has only one plane and
+will be the least significant bit of the word.
+As planes are added to the display hardware, they will occupy more
+significant bits in the plane mask.
+.LP
+In graphics operations, given a source and destination pixel, 
+the result is computed bitwise on corresponding bits of the pixels.
+That is, a Boolean operation is performed in each bit plane.  
+The plane_mask restricts the operation to a subset of planes.
+A macro constant
+.PN AllPlanes
+can be used to refer to all planes of the screen simultaneously.
+The result is computed by the following:
+.LP
+.Ds 
+((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask))
+.De
+.LP
+Range checking is not performed on the values for foreground,
+background, or plane_mask.
+They are simply truncated to the appropriate
+number of bits.
+The line-width is measured in pixels and either can be greater than or equal to
+one (wide line) or can be the special value zero (thin line).
+.LP
+Wide lines are drawn centered on the path described by the graphics request.
+Unless otherwise specified by the join-style or cap-style,
+the bounding box of a wide line with endpoints [x1, y1], [x2, y2] and
+width w is a rectangle with vertices at the following real coordinates:
+.LP
+.Ds
+.TA .5i 2.5i
+.ta .5i 2.5i
+[x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)],
+[x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)]
+.De
+.LP
+Here sn is the sine of the angle of the line,
+and cs is the cosine of the angle of the line.
+A pixel is part of the line and so is drawn
+if the center of the pixel is fully inside the bounding box
+(which is viewed as having infinitely thin edges).
+If the center of the pixel is exactly on the bounding box,
+it is part of the line if and only if the interior is immediately to its right
+(x increasing direction).
+Pixels with centers on a horizontal edge are a special case and are part of
+the line if and only if the interior or the boundary is immediately below 
+(y increasing direction) and the interior or the boundary is immediately
+to the right (x increasing direction).
+.LP
+Thin lines (zero line-width) are one-pixel-wide lines drawn using an
+unspecified, device-dependent algorithm.
+There are only two constraints on this algorithm. 
+.IP 1. 5
+If a line is drawn unclipped from [x1,y1] to [x2,y2] and
+if another line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy],
+a point [x,y] is touched by drawing the first line 
+if and only if the point [x+dx,y+dy] is touched by drawing the second line.
+.IP 2. 5
+The effective set of points comprising a line cannot be affected by clipping.
+That is, a point is touched in a clipped line if and only if the point 
+lies inside the clipping region and the point would be touched
+by the line when drawn unclipped.
+.LP
+A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels 
+as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style 
+and join-style.
+It is recommended that this property be true for thin lines, 
+but this is not required.
+A line-width of zero may differ from a line-width of one in which pixels are
+drawn.
+This permits the use of many manufacturers' line drawing hardware,
+which may run many times faster than the more precisely specified
+wide lines.
+.LP
+In general, 
+drawing a thin line will be faster than drawing a wide line of width one.
+However, because of their different drawing algorithms,
+thin lines may not mix well aesthetically with wide lines.
+If it is desirable to obtain precise and uniform results across all displays,
+a client should always use a line-width of one rather than a line-width of zero.
+.LP
+The line-style defines which sections of a line are drawn:
+.TS
+lw(1.3i) lw(4.5i).
+T{
+.PN LineSolid
+T}	T{
+The full path of the line is drawn.
+T}
+.sp 6p
+T{
+.PN LineDoubleDash
+T}	T{
+The full path of the line is drawn, 
+but the even dashes are filled differently 
+from the odd dashes (see fill-style) with
+.PN CapButt 
+style used where even and odd dashes meet.
+T}
+.sp 6p
+T{
+.PN LineOnOffDash
+T}	T{
+Only the even dashes are drawn,
+and cap-style applies to 
+all internal ends of the individual dashes,
+except 
+.PN CapNotLast
+is treated as 
+.PN CapButt . 
+T}
+.TE
+.LP
+The cap-style defines how the endpoints of a path are drawn:
+.IN "Graphics context" "path"
+.TS
+lw(1.3i) lw(4.5i).
+T{
+.PN CapNotLast
+T}	T{
+This is equivalent to 
+.PN CapButt  
+except that for a line-width of zero the final endpoint is not drawn.
+T}
+.sp 6p
+T{
+.PN CapButt
+T}	T{
+The line is square at the endpoint (perpendicular to the slope of the line)
+with no projection beyond.
+T}
+.sp 6p
+T{
+.PN CapRound
+T}	T{
+The line has a circular arc with the diameter equal to the line-width,
+centered on the endpoint.
+(This is equivalent to 
+.PN CapButt 
+for line-width of zero).
+T}
+.sp 6p
+T{
+.PN CapProjecting
+T}	T{
+The line is square at the end, but the path continues beyond the endpoint 
+for a distance equal to half the line-width.
+(This is equivalent to 
+.PN CapButt 
+for line-width of zero).
+T}
+.TE
+.LP
+The join-style defines how corners are drawn for wide lines:
+.TS
+lw(1.3i) lw(4.5i).
+T{
+.PN JoinMiter
+T}	T{
+The outer edges of two lines extend to meet at an angle.
+However, if the angle is less than 11 degrees,
+then a
+.PN JoinBevel
+join-style is used instead.
+T}
+.sp 6p
+T{
+.PN JoinRound
+T}	T{
+The corner is a circular arc with the diameter equal to the line-width, 
+centered on the joinpoint.
+T}
+.sp 6p
+T{
+.PN JoinBevel
+T}	T{
+The corner has
+.PN CapButt 
+endpoint styles with the triangular notch filled.
+T}
+.TE
+.LP
+For a line with coincident endpoints (x1=x2, y1=y2), 
+when the cap-style is applied to both endpoints, 
+the semantics depends on the line-width and the cap-style:
+.TS
+lw(1.3i) lw(.5i) lw(4i).
+T{
+.PN CapNotLast
+T}	T{
+thin
+T}	T{
+The results are device dependent, 
+but the desired effect is that nothing is drawn.
+T}
+.sp 6p
+T{
+.PN CapButt
+T}	T{
+thin
+T}	T{
+The results are device dependent, 
+but the desired effect is that a single pixel is drawn.
+T}
+.sp 6p
+T{
+.PN CapRound
+T}	T{
+thin
+T}	T{
+The results are the same as for
+.PN CapButt /thin.
+T}
+.sp 6p
+T{
+.PN CapProjecting
+T}	T{
+thin
+T}	T{
+The results are the same as for
+.PN CapButt /thin.
+T}
+.sp 6p
+T{
+.PN CapButt
+T}	T{
+wide
+T}	T{
+Nothing is drawn.
+T}
+.sp 6p
+T{
+.PN CapRound
+T}	T{
+wide
+T}	T{
+The closed path is a circle, centered at the endpoint, and
+with the diameter equal to the line-width.
+T}
+.sp 6p
+T{
+.PN CapProjecting
+T}	T{
+wide
+T}	T{
+The closed path is a square, aligned with the coordinate axes, centered at the
+endpoint, and with the sides equal to the line-width.
+T}
+.TE
+.LP
+For a line with coincident endpoints (x1=x2, y1=y2), 
+when the join-style is applied at one or both endpoints, 
+the effect is as if the line was removed from the overall path.
+However, if the total path consists of or is reduced to a single point joined
+with itself, the effect is the same as when the cap-style is applied at both
+endpoints.
+.LP
+The tile/stipple represents an infinite two-dimensional plane,
+with the tile/stipple replicated in all dimensions.
+When that plane is superimposed on the drawable
+for use in a graphics operation, the upper-left corner
+of some instance of the tile/stipple is at the coordinates within
+the drawable specified by the tile/stipple origin.
+The tile/stipple and clip origins are interpreted relative to the
+origin of whatever destination drawable is specified in a graphics
+request.
+The tile pixmap must have the same root and depth as the GC,
+or a
+.PN BadMatch 
+error results.
+The stipple pixmap must have depth one and must have the same root as the
+GC, or a 
+.PN BadMatch 
+error results.  
+For stipple operations where the fill-style is
+.PN FillStippled
+but not 
+.PN FillOpaqueStippled ,
+the stipple pattern is tiled in a
+single plane and acts as an additional clip mask to be ANDed with the clip-mask.
+Although some sizes may be faster to use than others,
+any size pixmap can be used for tiling or stippling.
+.LP
+The fill-style defines the contents of the source for line, text, and
+fill requests.  
+For all text and fill requests (for example,
+.PN XDrawText , 
+.PN XDrawText16 ,
+.PN XFillRectangle , 
+.PN XFillPolygon , 
+and
+.PN XFillArc );
+for line requests 
+with line-style 
+.PN LineSolid 
+(for example,
+.PN XDrawLine ,
+.PN XDrawSegments , 
+.PN XDrawRectangle ,
+.PN XDrawArc );
+and for the even dashes for line requests with line-style 
+.PN LineOnOffDash 
+or 
+.PN LineDoubleDash ,
+the following apply:
+.TS
+lw(1.8i) lw(4i).
+T{
+.PN FillSolid
+T}	T{
+Foreground
+T}
+.sp 6p
+T{
+.PN FillTiled
+T}	T{
+Tile
+T}
+.sp 6p
+T{
+.PN FillOpaqueStippled
+T}	T{
+A tile with the same width and height as stipple,
+but with background everywhere stipple has a zero
+and with foreground everywhere stipple has a one
+T}
+.sp 6p
+T{
+.PN FillStippled
+T}	T{
+Foreground masked by stipple
+T}
+.TE
+.LP
+When drawing lines with line-style
+.PN LineDoubleDash ,
+the odd dashes are controlled by the fill-style in the following manner:
+.TS
+lw(1.8i) lw(4i).
+T{
+.PN FillSolid
+T}	T{
+Background
+T}
+.sp 6p
+T{
+.PN FillTiled
+T}	T{
+Same as for even dashes
+T}
+.sp 6p
+T{
+.PN FillOpaqueStippled
+T}	T{
+Same as for even dashes
+T}
+.sp 6p
+T{
+.PN FillStippled
+T}	T{
+Background masked by stipple
+T}
+.TE
+.LP
+Storing a pixmap in a GC might or might not result in a copy
+being made.
+If the pixmap is later used as the destination for a graphics request,
+the change might or might not be reflected in the GC.
+If the pixmap is used simultaneously in a graphics request both as
+a destination and as a tile or stipple,
+the results are undefined.
+.LP
+For optimum performance,
+you should draw as much as possible with the same GC 
+(without changing its components).
+The costs of changing GC components relative to using different GCs
+depend on the display hardware and the server implementation.
+It is quite likely that some amount of GC information will be
+cached in display hardware and that such hardware can only cache a small number
+of GCs.
+.LP
+The dashes value is actually a simplified form of the
+more general patterns that can be set with 
+.PN XSetDashes .  
+Specifying a
+value of N is equivalent to specifying the two-element list [N, N] in 
+.PN XSetDashes . 
+The value must be nonzero,
+or a
+.PN BadValue
+error results.
+.LP
+The clip-mask restricts writes to the destination drawable.  
+If the clip-mask is set to a pixmap,
+it must have depth one and have the same root as the GC,
+or a
+.PN BadMatch 
+error results.
+If clip-mask is set to
+.PN None ,
+the pixels are always drawn regardless of the clip origin.
+The clip-mask also can be set by calling the
+.PN XSetClipRectangles
+or
+.PN XSetRegion
+functions.
+Only pixels where the clip-mask has a bit set to 1 are drawn.  
+Pixels are not drawn outside the area covered by the clip-mask 
+or where the clip-mask has a bit set to 0.
+The clip-mask affects all graphics requests.
+The clip-mask does not clip sources.
+The clip-mask origin is interpreted relative to the origin of whatever
+destination drawable is specified in a graphics request.
+.LP
+You can set the subwindow-mode to
+.PN ClipByChildren
+or
+.PN IncludeInferiors .
+For 
+.PN ClipByChildren , 
+both source and destination windows are
+additionally clipped by all viewable 
+.PN InputOutput
+children.  
+For 
+.PN IncludeInferiors ,
+neither source nor destination window is clipped by inferiors. 
+This will result in including subwindow contents in the source
+and drawing through subwindow boundaries of the destination.
+The use of 
+.PN IncludeInferiors 
+on a window of one depth with mapped
+inferiors of differing depth is not illegal, but the semantics are
+undefined by the core protocol.
+.LP
+The fill-rule defines what pixels are inside (drawn) for
+paths given in 
+.PN XFillPolygon 
+requests and can be set to 
+.PN EvenOddRule 
+or
+.PN WindingRule .
+For
+.PN EvenOddRule ,
+a point is inside if
+an infinite ray with the point as origin crosses the path an odd number
+of times.  
+For 
+.PN WindingRule , 
+a point is inside if an infinite ray with the
+point as origin crosses an unequal number of clockwise and
+counterclockwise directed path segments.
+A clockwise directed path segment is one that crosses the ray from left to
+right as observed from the point.
+A counterclockwise segment is one that crosses the ray from right to left
+as observed from the point.
+The case where a directed line segment is coincident with the ray is
+uninteresting because you can simply choose a different ray that is not
+coincident with a segment.
+.LP
+For both 
+.PN EvenOddRule
+and
+.PN WindingRule ,
+a point is infinitely small, 
+and the path is an infinitely thin line.  
+A pixel is inside if the center point of the pixel is inside
+and the center point is not on the boundary.  
+If the center point is on the boundary,
+the pixel is inside if and only if the polygon interior is immediately to
+its right (x increasing direction).  
+Pixels with centers on a horizontal edge are a special case 
+and are inside if and only if the polygon interior is immediately below 
+(y increasing direction).
+.LP
+The arc-mode controls filling in the 
+.PN XFillArcs
+function and can be set to
+.PN ArcPieSlice
+or
+.PN ArcChord .
+For
+.PN ArcPieSlice ,
+the arcs are pie-slice filled.
+For
+.PN ArcChord ,
+the arcs are chord filled.
+.LP
+The graphics-exposure flag controls 
+.PN GraphicsExpose 
+event generation
+for 
+.PN XCopyArea 
+and 
+.PN XCopyPlane
+requests (and any similar requests defined by extensions).
+.LP
+.sp
+To create a new GC that is usable on a given screen with a 
+depth of drawable, use
+.PN XCreateGC .
+.IN "Graphics context" "initializing"
+.IN "XCreateGC" "" "@DEF@"
+.sM
+.FD 0
+GC XCreateGC\^(\^\fIdisplay\fP, \fId\fP\^, \fIvaluemask\fP\^, \fIvalues\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      unsigned long \fIvaluemask\fP\^;
+.br
+      XGCValues *\^\fIvalues\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.ds Vm set using the information in the specified values structure
+.IP \fIvaluemask\fP 1i
+Specifies which components in the GC are to be \*(Vm. 
+This argument is the bitwise inclusive OR of zero or more of the valid
+GC component mask bits.
+.IP \fIvalues\fP 1i
+Specifies any values as specified by the valuemask.
+.LP
+.eM
+The
+.PN XCreateGC
+function creates a graphics context and returns a GC.
+The GC can be used with any destination drawable having the same root
+and depth as the specified drawable.
+Use with other drawables results in a
+.PN BadMatch
+error.
+.LP
+.PN XCreateGC
+can generate
+.PN BadAlloc ,
+.PN BadDrawable ,
+.PN BadFont ,
+.PN BadMatch ,
+.PN BadPixmap ,
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To copy components from a source GC to a destination GC, use
+.PN XCopyGC .
+.IN "XCopyGC" "" "@DEF@"
+.sM
+.FD 0
+XCopyGC\^(\^\fIdisplay\fP, \fIsrc\fP\^, \fIvaluemask\fP\^, \fIdest\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIsrc\fP\^, \fIdest\fP\^;
+.br
+      unsigned long \fIvaluemask\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIsrc\fP 1i
+Specifies the components of the source GC.
+.ds Vm copied to the destination GC
+.IP \fIvaluemask\fP 1i
+Specifies which components in the GC are to be \*(Vm. 
+This argument is the bitwise inclusive OR of zero or more of the valid
+GC component mask bits.
+.IP \fIdest\fP 1i
+Specifies the destination GC.
+.LP
+.eM 
+The
+.PN XCopyGC
+function copies the specified components from the source GC
+to the destination GC.
+The source and destination GCs must have the same root and depth,
+or a
+.PN BadMatch
+error results.
+The valuemask specifies which component to copy, as for
+.PN XCreateGC .
+.LP
+.PN XCopyGC
+can generate
+.PN BadAlloc , 
+.PN BadGC ,
+and
+.PN BadMatch
+errors.
+.LP
+.sp
+To change the components in a given GC, use
+.PN XChangeGC .
+.IN "XChangeGC" "" "@DEF@"
+.sM
+.FD 0
+XChangeGC\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIvaluemask\fP\^, \fIvalues\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      unsigned long \fIvaluemask\fP\^;
+.br
+      XGCValues *\^\fIvalues\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.ds Vm changed using information in the specified values structure
+.IP \fIvaluemask\fP 1i
+Specifies which components in the GC are to be \*(Vm. 
+This argument is the bitwise inclusive OR of zero or more of the valid
+GC component mask bits.
+.IP \fIvalues\fP 1i
+Specifies any values as specified by the valuemask.
+.LP
+.eM
+The
+.PN XChangeGC
+function changes the components specified by valuemask for
+the specified GC.
+The values argument contains the values to be set.
+The values and restrictions are the same as for 
+.PN XCreateGC .
+Changing the clip-mask overrides any previous 
+.PN XSetClipRectangles
+request on the context. 
+Changing the dash-offset or dash-list
+overrides any previous 
+.PN XSetDashes
+request on the context.
+The order in which components are verified and altered is server dependent.
+If an error is generated, a subset of the components may have been altered.
+.LP
+.PN XChangeGC
+can generate
+.PN BadAlloc ,
+.PN BadFont ,
+.PN BadGC ,
+.PN BadMatch ,
+.PN BadPixmap ,
+and
+.PN BadValue
+errors.
+.LP
+.sp
+To obtain components of a given GC, use
+.PN XGetGCValues .
+.IN "XGetGCValues" "" "@DEF@"
+.sM
+.FD 0
+Status XGetGCValues\^(\^\fIdisplay\fP, \fIgc\fP, \fIvaluemask\fP, \
+\fIvalues_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      unsigned long \fIvaluemask\fP\^;
+.br
+      XGCValues *\fIvalues_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.ds Vm returned in the values_return argument
+.IP \fIvaluemask\fP 1i
+Specifies which components in the GC are to be \*(Vm. 
+This argument is the bitwise inclusive OR of zero or more of the valid
+GC component mask bits.
+.IP \fIvalues_return\fP 1i
+Returns the GC values in the specified
+.PN XGCValues 
+structure.
+.LP
+.eM
+The
+.PN XGetGCValues
+function returns the components specified by valuemask for the specified GC.
+If the valuemask contains a valid set of GC mask bits
+.Pn ( GCFunction ,
+.PN GCPlaneMask ,
+.PN GCForeground ,
+.PN GCBackground ,
+.PN GCLineWidth ,
+.PN GCLineStyle ,
+.PN GCCapStyle ,
+.PN GCJoinStyle ,
+.PN GCFillStyle ,
+.PN GCFillRule ,
+.PN GCTile ,
+.PN GCStipple ,
+.PN GCTileStipXOrigin ,
+.PN GCTileStipYOrigin ,
+.PN GCFont ,
+.PN GCSubwindowMode ,
+.PN GCGraphicsExposures ,
+.PN GCClipXOrigin ,
+.PN GCCLipYOrigin ,
+.PN GCDashOffset ,
+or
+.PN GCArcMode )
+and no error occurs,
+.PN XGetGCValues
+sets the requested components in values_return and returns a nonzero status.
+Otherwise, it returns a zero status.
+Note that the clip-mask and dash-list (represented by the
+.PN GCClipMask
+and 
+.PN GCDashList
+bits, respectively, in the valuemask)
+cannot be requested.
+Also note that an invalid resource ID (with one or more of the three
+most significant bits set to 1) will be returned for
+.PN GCFont ,
+.PN GCTile ,
+and
+.PN GCStipple
+if the component has never been explicitly set by the client.
+.LP
+.sp
+To free a given GC, use
+.PN XFreeGC .
+.IN "XFreeGC" "" "@DEF@"
+.sM
+.FD 0
+XFreeGC\^(\^\fIdisplay\fP, \fIgc\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.LP
+.eM
+The
+.PN XFreeGC
+function destroys the specified GC as well as all the associated storage.
+.LP
+.PN XFreeGC
+can generate a
+.PN BadGC 
+error.
+.LP
+.sp
+To obtain the 
+.PN GContext 
+resource ID for a given GC, use 
+.PN XGContextFromGC .
+.IN "XGContextFromGC" "" "@DEF@"
+.sM
+.FD 0
+GContext XGContextFromGC\^(\^\fIgc\fP\^)
+.br
+      GC \fIgc\fP\^;
+.FN
+.ds Gc for which you want the resource ID
+.IP \fIgc\fP 1i
+Specifies the GC \*(Gc.
+.LP
+.eM
+.sp
+Xlib usually defers sending changes to the components of a GC to the server
+until a graphics function is actually called with that GC.
+This permits batching of component changes into a single server request.
+In some circumstances, however, it may be necessary for the client
+to explicitly force sending the changes to the server.
+An example might be when a protocol extension uses the GC indirectly,
+in such a way that the extension interface cannot know what GC will be used.
+To force sending GC component changes, use
+.PN XFlushGC .
+.IN "XFlushGC" "" "@DEF@"
+.sM
+.FD 0
+void XFlushGC\^(\^\fIdisplay\fP, \fIgc\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.LP
+.eM
+.NH 2
+Using Graphics Context Convenience Routines
+.XS
+\*(SN Using Graphics Context Convenience Routines 
+.XE
+.LP
+This section discusses how to set the:
+.IP \(bu 5
+Foreground, background, plane mask, or function components
+.IP \(bu 5
+Line attributes and dashes components
+.IP \(bu 5
+Fill style and fill rule components
+.IP \(bu 5
+Fill tile and stipple components
+.IP \(bu 5
+Font component
+.IP \(bu 5
+Clip region component
+.IP \(bu 5
+Arc mode, subwindow mode, and graphics exposure components
+.NH 3
+Setting the Foreground, Background, Function, or Plane Mask
+.XS
+\*(SN Setting the Foreground, Background, Function, or Plane Mask
+.XE
+.LP
+To set the foreground, background, plane mask, and function components
+for a given GC, use
+.PN XSetState .
+.IN "XSetState" "" "@DEF@"
+.sM
+.FD 0
+XSetState\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIforeground\fP\^, \fIbackground\fP\^, \fIfunction\fP\^, \fIplane_mask\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      unsigned long \fIforeground\fP\^, \fIbackground\fP\^;
+.br
+      int \fIfunction\fP\^;
+.br
+      unsigned long \fIplane_mask\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIforeground\fP 1i
+Specifies the foreground you want to set for the specified GC.
+.IP \fIbackground\fP 1i
+Specifies the background you want to set for the specified GC.
+.IP \fIfunction\fP 1i
+Specifies the function you want to set for the specified GC.
+.IP \fIplane_mask\fP 1i
+Specifies the plane mask.
+.\" *** JIM: NEED MORE INFO FOR THIS. ***
+.LP
+.eM
+.PN XSetState
+can generate
+.PN BadAlloc ,
+.PN BadGC ,
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To set the foreground of a given GC, use
+.PN XSetForeground .
+.IN "XSetForeground" "" "@DEF@"
+.sM
+.FD 0
+XSetForeground\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIforeground\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      unsigned long \fIforeground\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIforeground\fP 1i
+Specifies the foreground you want to set for the specified GC.
+.LP
+.eM
+.PN XSetForeground
+can generate
+.PN BadAlloc
+and
+.PN BadGC 
+errors.
+.LP
+.sp
+To set the background of a given GC, use
+.PN XSetBackground .
+.IN "XSetBackground" "" "@DEF@"
+.sM
+.FD 0
+XSetBackground\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIbackground\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      unsigned long \fIbackground\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIbackground\fP 1i
+Specifies the background you want to set for the specified GC.
+.LP
+.eM
+.PN XSetBackground
+can generate
+.PN BadAlloc
+and
+.PN BadGC 
+errors.
+.LP
+.sp
+To set the display function in a given GC, use
+.PN XSetFunction .
+.IN "XSetFunction" "" "@DEF@"
+.sM
+.FD 0
+XSetFunction\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfunction\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIfunction\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIfunction\fP 1i
+Specifies the function you want to set for the specified GC.
+.LP
+.eM
+.PN XSetFunction
+can generate
+.PN BadAlloc ,
+.PN BadGC ,
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To set the plane mask of a given GC, use
+.PN XSetPlaneMask .
+.IN "XSetPlaneMask" "" "@DEF@"
+.sM
+.FD 0
+XSetPlaneMask\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIplane_mask\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      unsigned long \fIplane_mask\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIplane_mask\fP 1i
+Specifies the plane mask.
+.\" *** JIM: NEED MORE INFO FOR THIS. ***
+.LP
+.eM
+.PN XSetPlaneMask
+can generate
+.PN BadAlloc
+and
+.PN BadGC 
+errors.
+.NH 3
+Setting the Line Attributes and Dashes
+.XS
+\*(SN Setting the Line Attributes and Dashes 
+.XE
+.LP
+To set the line drawing components of a given GC, use
+.PN XSetLineAttributes .
+.IN "XSetLineAttributes" "" "@DEF@"
+.sM
+.FD 0
+XSetLineAttributes\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIline_width\fP\^, \fIline_style\fP\^, \fIcap_style\fP\^, \fIjoin_style\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      unsigned int \fIline_width\fP\^;
+.br
+      int \fIline_style\fP\^;
+.br
+      int \fIcap_style\fP\^;
+.br
+      int \fIjoin_style\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIline_width\fP 1i
+Specifies the line-width you want to set for the specified GC.
+.IP \fIline_style\fP 1i
+Specifies the line-style you want to set for the specified GC.
+You can pass
+.PN LineSolid ,
+.PN LineOnOffDash ,
+or
+.PN LineDoubleDash .
+.IP \fIcap_style\fP 1i
+Specifies the line-style and cap-style you want to set for the specified GC.
+You can pass
+.PN CapNotLast ,
+.PN CapButt ,
+.PN CapRound ,
+or
+.PN CapProjecting .
+.IP \fIjoin_style\fP 1i
+Specifies the line join-style you want to set for the specified GC.
+You can pass
+.PN JoinMiter ,
+.PN JoinRound ,
+or
+.PN JoinBevel .
+.LP
+.eM
+.PN XSetLineAttributes
+can generate
+.PN BadAlloc ,
+.PN BadGC ,
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To set the dash-offset and dash-list for dashed line styles of a given GC, use
+.PN XSetDashes .
+.IN "XSetDashes" "" "@DEF@"
+.sM
+.FD 0
+XSetDashes\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIdash_offset\fP\^, \fIdash_list\fP\^, \fIn\fP\^)
+.br
+        Display *\fIdisplay\fP\^;
+.br
+        GC \fIgc\fP\^;
+.br
+        int \fIdash_offset\fP\^;
+.br
+        char \fIdash_list\fP[]\^;
+.br
+        int \fIn\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIdash_offset\fP 1i
+Specifies the phase of the pattern for the dashed line-style you want to set
+for the specified GC. 
+.IP \fIdash_list\fP 1i
+Specifies the dash-list for the dashed line-style
+you want to set for the specified GC. 
+.IP \fIn\fP 1i
+Specifies the number of elements in dash_list. 
+.LP
+.eM 
+The
+.PN XSetDashes
+function sets the dash-offset and dash-list attributes for dashed line styles
+in the specified GC.
+There must be at least one element in the specified dash_list,
+or a
+.PN BadValue
+error results. 
+The initial and alternating elements (second, fourth, and so on) 
+of the dash_list are the even dashes, and
+the others are the odd dashes.
+Each element specifies a dash length in pixels.
+All of the elements must be nonzero,
+or a
+.PN BadValue
+error results.
+Specifying an odd-length list is equivalent to specifying the same list
+concatenated with itself to produce an even-length list.
+.LP
+The dash-offset defines the phase of the pattern,
+specifying how many pixels into the dash-list the pattern
+should actually begin in any single graphics request.
+Dashing is continuous through path elements combined with a join-style
+but is reset to the dash-offset between each sequence of joined lines.
+.LP
+The unit of measure for dashes is the same for the ordinary coordinate system.
+Ideally, a dash length is measured along the slope of the line, but implementations
+are only required to match this ideal for horizontal and vertical lines.
+Failing the ideal semantics, it is suggested that the length be measured along the
+major axis of the line.
+The major axis is defined as the x axis for lines drawn at an angle of between
+\-45 and +45 degrees or between 135 and 225 degrees from the x axis.
+For all other lines, the major axis is the y axis.
+.LP
+.PN XSetDashes
+can generate
+.PN BadAlloc ,
+.PN BadGC ,
+and
+.PN BadValue 
+errors.
+.NH 3
+Setting the Fill Style and Fill Rule 
+.XS
+\*(SN Setting the Fill Style and Fill Rule 
+.XE
+.LP
+To set the fill-style of a given GC, use
+.PN XSetFillStyle .
+.IN "XSetFillStyle" "" "@DEF@"
+.sM
+.FD 0
+XSetFillStyle\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfill_style\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIfill_style\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIfill_style\fP 1i
+Specifies the fill-style you want to set for the specified GC.
+You can pass
+.PN FillSolid ,
+.PN FillTiled ,
+.PN FillStippled ,
+or
+.PN FillOpaqueStippled .
+.LP
+.eM
+.PN XSetFillStyle
+can generate
+.PN BadAlloc ,
+.PN BadGC ,
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To set the fill-rule of a given GC, use
+.PN XSetFillRule .
+.IN "XSetFillRule" "" "@DEF@"
+.sM
+.FD 0
+XSetFillRule\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfill_rule\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIfill_rule\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIfill_rule\fP 1i
+Specifies the fill-rule you want to set for the specified GC.
+You can pass 
+.PN EvenOddRule
+or
+.PN WindingRule .
+.LP
+.eM
+.PN XSetFillRule
+can generate
+.PN BadAlloc ,
+.PN BadGC ,
+and
+.PN BadValue 
+errors.
+.NH 3
+Setting the Fill Tile and Stipple 
+.XS
+\*(SN Setting the Fill Tile and Stipple 
+.XE
+.LP
+Some displays have hardware support for tiling or
+stippling with patterns of specific sizes.
+Tiling and stippling operations that restrict themselves to those specific
+sizes run much faster than such operations with arbitrary size patterns.
+Xlib provides functions that you can use to determine the best size, 
+tile, or stipple for the display
+as well as to set the tile or stipple shape and the tile or stipple origin.
+.LP
+.sp
+To obtain the best size of a tile, stipple, or cursor, use
+.PN XQueryBestSize .
+.IN "XQueryBestSize" "" "@DEF@"
+.sM
+.FD 0
+Status XQueryBestSize\^(\^\fIdisplay\fP, \fIclass\fP, \fIwhich_screen\fP, \fIwidth\fP, \fIheight\fP, \fIwidth_return\fP, \fIheight_return\fP\^) 
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIclass\fP\^;
+.br
+      Drawable \fIwhich_screen\fP\^;
+.br
+      unsigned int \fIwidth\fP, \fIheight\fP\^;
+.br
+      unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIclass\fP 1i
+Specifies the class that you are interested in.
+You can pass 
+.PN TileShape , 
+.PN CursorShape , 
+or 
+.PN StippleShape .
+.IP \fIwhich_screen\fP 1i
+Specifies any drawable on the screen.
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height.
+.IP \fIwidth_return\fP 1i
+.br
+.ns
+.IP \fIheight_return\fP 1i
+Return the width and height of the object best supported 
+by the display hardware.
+.LP
+.eM
+The
+.PN XQueryBestSize
+function returns the best or closest size to the specified size.
+For 
+.PN CursorShape ,
+this is the largest size that can be fully displayed on the screen specified by
+which_screen.
+For 
+.PN TileShape ,
+this is the size that can be tiled fastest.
+For 
+.PN StippleShape ,
+this is the size that can be stippled fastest.
+For 
+.PN CursorShape ,
+the drawable indicates the desired screen.
+For 
+.PN TileShape 
+and 
+.PN StippleShape ,
+the drawable indicates the screen and possibly the window class and depth.
+An 
+.PN InputOnly 
+window cannot be used as the drawable for 
+.PN TileShape
+or 
+.PN StippleShape ,
+or a
+.PN BadMatch 
+error results.
+.LP
+.PN XQueryBestSize
+can generate
+.PN BadDrawable ,
+.PN BadMatch ,
+and 
+.PN BadValue 
+errors.
+.LP
+.sp
+To obtain the best fill tile shape, use
+.PN XQueryBestTile .
+.IN "XQueryBestTile" "" "@DEF@"
+.sM
+.FD 0
+Status XQueryBestTile\^(\^\fIdisplay\fP, \fIwhich_screen\fP, \fIwidth\fP, \fIheight\fP, \fIwidth_return\fP, \fIheight_return\fP\^) 
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fIwhich_screen\fP\^;
+.br
+      unsigned int \fIwidth\fP, \fIheight\fP\^;
+.br
+      unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIwhich_screen\fP 1i
+Specifies any drawable on the screen.
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height.
+.IP \fIwidth_return\fP 1i
+.br
+.ns
+.IP \fIheight_return\fP 1i
+Return the width and height of the object best supported 
+by the display hardware.
+.LP
+.eM
+The
+.PN XQueryBestTile
+function returns the best or closest size, that is, the size that can be
+tiled fastest on the screen specified by which_screen.
+The drawable indicates the screen and possibly the window class and depth.
+If an 
+.PN InputOnly 
+window is used as the drawable, a 
+.PN BadMatch 
+error results.
+.LP
+.PN XQueryBestTile
+can generate
+.PN BadDrawable
+and
+.PN BadMatch 
+errors.
+.LP
+.sp
+To obtain the best stipple shape, use
+.PN XQueryBestStipple .
+.IN "XQueryBestStipple" "" "@DEF@"
+.sM
+.FD 0
+Status XQueryBestStipple\^(\^\fIdisplay\fP, \fIwhich_screen\fP, \fIwidth\fP, \fIheight\fP, \fIwidth_return\fP, \fIheight_return\fP\^) 
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fIwhich_screen\fP\^;
+.br
+      unsigned int \fIwidth\fP, \fIheight\fP\^;
+.br
+      unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIwhich_screen\fP 1i
+Specifies any drawable on the screen.
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height.
+.IP \fIwidth_return\fP 1i
+.br
+.ns
+.IP \fIheight_return\fP 1i
+Return the width and height of the object best supported 
+by the display hardware.
+.LP
+.eM
+The
+.PN XQueryBestStipple
+function returns the best or closest size, that is, the size that can be
+stippled fastest on the screen specified by which_screen.
+The drawable indicates the screen and possibly the window class and depth.
+If an
+.PN InputOnly
+window is used as the drawable, a
+.PN BadMatch
+error results.
+.LP
+.PN XQueryBestStipple
+can generate
+.PN BadDrawable
+and
+.PN BadMatch 
+errors.
+.LP
+.sp
+To set the fill tile of a given GC, use
+.PN XSetTile .
+.IN "XSetTile" "" "@DEF@"
+.sM
+.FD 0
+XSetTile\^(\^\fIdisplay\fP, \fIgc\fP\^, \fItile\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      Pixmap \fItile\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fItile\fP 1i
+Specifies the fill tile you want to set for the specified GC. 
+.LP
+.eM
+The tile and GC must have the same depth,
+or a
+.PN BadMatch
+error results.
+.LP
+.PN XSetTile
+can generate
+.PN BadAlloc ,
+.PN BadGC ,
+.PN BadMatch ,
+and
+.PN BadPixmap 
+errors.
+.LP
+.sp
+To set the stipple of a given GC, use
+.PN XSetStipple .
+.IN "XSetStipple" "" "@DEF@"
+.sM
+.FD 0
+XSetStipple\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIstipple\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      Pixmap \fIstipple\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIstipple\fP 1i
+Specifies the stipple you want to set for the specified GC.
+.LP
+.eM
+The stipple must have a depth of one,
+or a
+.PN BadMatch
+error results.
+.LP
+.PN XSetStipple
+can generate
+.PN BadAlloc ,
+.PN BadGC ,
+.PN BadMatch ,
+and
+.PN BadPixmap 
+errors.
+.LP
+.sp
+To set the tile or stipple origin of a given GC, use
+.PN XSetTSOrigin .
+.IN "XSetTSOrigin" "" "@DEF@"
+.sM
+.FD 0
+XSetTSOrigin\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIts_x_origin\fP\^, \fIts_y_origin\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIts_x_origin\fP\^, \fIts_y_origin\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIts_x_origin\fP 1i
+.br
+.ns
+.IP \fIts_y_origin\fP 1i
+Specify the x and y coordinates of the tile and stipple origin.
+.LP
+.eM
+When graphics requests call for tiling or stippling,
+the parent's origin will be interpreted relative to whatever destination 
+drawable is specified in the graphics request.
+.LP
+.PN XSetTSOrigin
+can generate
+.PN BadAlloc
+and
+.PN BadGC 
+errors.
+.NH 3
+Setting the Current Font 
+.XS
+\*(SN Setting the Current Font 
+.XE
+.LP
+To set the current font of a given GC, use
+.PN XSetFont .
+.IN "XSetFont" "" "@DEF@"
+.sM
+.FD 0
+XSetFont\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIfont\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      Font \fIfont\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIfont\fP 1i
+Specifies the font.
+.LP
+.eM
+.PN XSetFont
+can generate
+.PN BadAlloc ,
+.PN BadFont ,
+and 
+.PN BadGC 
+errors.
+.NH 3
+Setting the Clip Region
+.XS
+\*(SN Setting the Clip Region 
+.XE
+.LP
+Xlib provides functions that you can use to set the clip-origin 
+and the clip-mask or set the clip-mask to a list of rectangles.
+.LP
+.sp
+To set the clip-origin of a given GC, use
+.PN XSetClipOrigin .
+.IN "XSetClipOrigin" "" "@DEF@"
+.sM
+.FD 0
+XSetClipOrigin\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIclip_x_origin\fP 1i
+.br
+.ns
+.IP \fIclip_y_origin\fP 1i
+Specify the x and y coordinates of the clip-mask origin.
+.LP
+.eM
+The clip-mask origin is interpreted relative to the origin of whatever 
+destination drawable is specified in the graphics request.
+.LP
+.PN XSetClipOrigin
+can generate
+.PN BadAlloc
+and
+.PN BadGC 
+errors.
+.LP
+.sp
+To set the clip-mask of a given GC to the specified pixmap, use
+.PN XSetClipMask .
+.IN "XSetClipMask" "" "@DEF@"
+.sM
+.FD 0
+XSetClipMask\^(\^\fIdisplay\fP, \fIgc\fP, \fIpixmap\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      Pixmap \fIpixmap\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIpixmap\fP 1i
+Specifies the pixmap or
+.PN None .
+.LP
+.eM
+If the clip-mask is set to
+.PN None ,
+the pixels are always drawn (regardless of the clip-origin).
+.LP
+.PN XSetClipMask
+can generate
+.PN BadAlloc ,
+.PN BadGC ,
+.PN BadMatch ,
+and
+.PN BadPixmap 
+errors.
+.LP
+.sp
+To set the clip-mask of a given GC to the specified list of rectangles, use
+.PN XSetClipRectangles .
+.IN "XSetClipRectangles" "" "@DEF@"
+.sM
+.FD 0
+XSetClipRectangles\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^, \fIrectangles\fP\^, \fIn\fP\^, \fIordering\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIclip_x_origin\fP\^, \fIclip_y_origin\fP\^;
+.br
+      XRectangle \fIrectangles\fP[]\^;
+.br
+      int \fIn\fP\^;
+.br
+      int \fIordering\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIclip_x_origin\fP 1i
+.br
+.ns
+.IP \fIclip_y_origin\fP 1i
+Specify the x and y coordinates of the clip-mask origin.
+.IP \fIrectangles\fP 1i
+Specifies an array of rectangles that define the clip-mask.
+.IP \fIn\fP 1i
+Specifies the number of rectangles. 
+.IP \fIordering\fP 1i
+Specifies the ordering relations on the rectangles.
+You can pass
+.PN Unsorted ,
+.PN YSorted ,
+.PN YXSorted ,
+or
+.PN YXBanded .
+.LP
+.eM
+The
+.PN XSetClipRectangles
+function changes the clip-mask in the specified GC 
+to the specified list of rectangles and sets the clip origin.
+The output is clipped to remain contained within the
+rectangles.
+The clip-origin is interpreted relative to the origin of
+whatever destination drawable is specified in a graphics request.  
+The rectangle coordinates are interpreted relative to the clip-origin.  
+The rectangles should be nonintersecting, or the graphics results will be
+undefined.
+Note that the list of rectangles can be empty, 
+which effectively disables output.
+This is the opposite of passing
+.PN None
+as the clip-mask in
+.PN XCreateGC ,
+.PN XChangeGC ,
+and
+.PN XSetClipMask .
+.LP
+If known by the client, ordering relations on the rectangles can be
+specified with the ordering argument. 
+This may provide faster operation
+by the server. 
+If an incorrect ordering is specified, the X server may generate a
+.PN BadMatch
+error, but it is not required to do so.
+If no error is generated, the graphics
+results are undefined.
+.PN Unsorted 
+means the rectangles are in arbitrary order.
+.PN YSorted 
+means that the rectangles are nondecreasing in their Y origin.
+.PN YXSorted 
+additionally constrains 
+.PN YSorted 
+order in that all
+rectangles with an equal Y origin are nondecreasing in their X
+origin.  
+.PN YXBanded 
+additionally constrains 
+.PN YXSorted 
+by requiring that,
+for every possible Y scanline, all rectangles that include that
+scanline have an identical Y origins and Y extents.
+.LP
+.PN XSetClipRectangles
+can generate
+.PN BadAlloc , 
+.PN BadGC ,
+.PN BadMatch ,
+and
+.PN BadValue 
+errors.
+.LP
+Xlib provides a set of basic functions for performing
+region arithmetic.
+For information about these functions,
+see section 16.5.
+.NH 3
+Setting the Arc Mode, Subwindow Mode, and Graphics Exposure 
+.XS
+\*(SN Setting the Arc Mode, Subwindow Mode, and Graphics Exposure 
+.XE
+.LP
+To set the arc mode of a given GC, use
+.PN XSetArcMode .
+.IN "XSetArcMode" "" "@DEF@"
+.sM
+.FD 0
+XSetArcMode\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIarc_mode\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIarc_mode\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIarc_mode\fP 1i
+Specifies the arc mode.
+You can pass
+.PN ArcChord
+or
+.PN ArcPieSlice .
+.LP
+.eM
+.PN XSetArcMode
+can generate
+.PN BadAlloc ,
+.PN BadGC ,
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To set the subwindow mode of a given GC, use
+.PN XSetSubwindowMode .
+.IN "XSetSubwindowMode" "" "@DEF@"
+.sM
+.FD 0
+XSetSubwindowMode\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIsubwindow_mode\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIsubwindow_mode\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIsubwindow_mode\fP 1i
+Specifies the subwindow mode.
+You can pass
+.PN ClipByChildren
+or
+.PN IncludeInferiors .
+.LP
+.eM
+.PN XSetSubwindowMode
+can generate
+.PN BadAlloc ,
+.PN BadGC ,
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To set the graphics-exposures flag of a given GC, use
+.PN XSetGraphicsExposures .
+.IN "XSetGraphicsExposures" "" "@DEF@"
+.sM
+.FD 0
+XSetGraphicsExposures\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIgraphics_exposures\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      Bool \fIgraphics_exposures\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIgraphics_exposures\fP 1i
+Specifies a Boolean value that indicates whether you want
+.PN GraphicsExpose
+and
+.PN NoExpose
+events to be reported when calling
+.PN XCopyArea
+and
+.PN XCopyPlane
+with this GC.
+.LP
+.eM
+.PN XSetGraphicsExposures
+can generate
+.PN BadAlloc ,
+.PN BadGC ,
+and
+.PN BadValue 
+errors.
+.bp
diff --git a/specs/libX11/CH08 b/specs/libX11/CH08
new file mode 100644
index 00000000..3d2161fb
--- /dev/null
+++ b/specs/libX11/CH08
@@ -0,0 +1,3468 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 8\fP\s-1
+
+\s+1\fBGraphics Functions\fP\s-1
+.sp 2
+.nr H1 8
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.na
+.LP
+.XS
+Chapter 8: Graphics Functions 
+.XE
+Once you have established a connection to a display,
+you can use the Xlib graphics functions to:
+.IP \(bu 5
+Clear and copy areas
+.IP \(bu 5
+Draw points, lines, rectangles, and arcs
+.IP \(bu 5
+Fill areas
+.IP \(bu 5
+Manipulate fonts
+.IP \(bu 5
+Draw text
+.IP \(bu 5
+Transfer images between clients and the server
+.LP
+If the same drawable and GC is used for each call,
+Xlib batches back-to-back calls to
+.PN XDrawPoint ,
+.PN XDrawLine ,
+.PN XDrawRectangle ,
+.PN XFillArc ,
+and
+.PN XFillRectangle .
+Note that this reduces the total number of requests sent to the server.
+.NH 2
+Clearing Areas
+.XS
+\*(SN Clearing Areas 
+.XE
+.LP
+Xlib provides functions that you can use to clear an area or the entire window.
+Because pixmaps do not have defined backgrounds, 
+they cannot be filled by using the functions described in this section.
+Instead, to accomplish an analogous operation on a pixmap,
+you should use 
+.PN XFillRectangle ,
+which sets the pixmap to a known value.
+.LP
+.sp
+To clear a rectangular area of a given window, use
+.PN XClearArea .
+.IN "Areas" "clearing"
+.IN "Clearing" "areas"
+.IN "XClearArea" "" "@DEF@"
+.sM
+.FD 0
+XClearArea\^(\^\fIdisplay\fP, \fIw\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIexposures\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
+.br
+      Bool \fIexposures\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.ds Xy , which are relative to the origin of the window \
+and specify the upper-left corner of the rectangle
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.ds Wh , which are the dimensions of the rectangle
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height\*(Wh.
+.IP \fIexposures\fP 1i
+Specifies a Boolean value that indicates if
+.PN Expose
+events are to be generated.
+.LP
+.eM
+The
+.PN XClearArea
+function paints a rectangular area in the specified window according to the
+specified dimensions with the window's background pixel or pixmap.
+The subwindow-mode effectively is
+.PN ClipByChildren . 
+If width is zero, it
+is replaced with the current width of the window minus x.
+If height is
+zero, it is replaced with the current height of the window minus y.
+If the window has a defined background tile, 
+the rectangle clipped by any children is filled with this tile.
+If the window has
+background 
+.PN None , 
+the contents of the window are not changed.  
+In either
+case, if exposures is 
+.PN True , 
+one or more 
+.PN Expose 
+events are generated for regions of the rectangle that are either visible or are
+being retained in a backing store.
+If you specify a window whose class is
+.PN InputOnly ,
+a
+.PN BadMatch
+error results.
+.LP
+.PN XClearArea
+can generate
+.PN BadMatch ,
+.PN BadValue ,
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To clear the entire area in a given window, use
+.PN XClearWindow .
+.IN "Window" "clearing"
+.IN "Clearing" "windows"
+.IN "XClearWindow" "" "@DEF@"
+.sM
+.FD 0
+XClearWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.LP
+.eM
+The
+.PN XClearWindow
+function clears the entire area in the specified window and is
+equivalent to
+.PN XClearArea
+(display, w, 0, 0, 0, 0, 
+.PN False ).
+If the window has a defined background tile, the rectangle is tiled with a
+plane-mask of all ones and 
+.PN GXcopy
+function.
+If the window has
+background 
+.PN None , 
+the contents of the window are not changed.  
+If you specify a window whose class is
+.PN InputOnly ,
+a
+.PN BadMatch
+error results. 
+.LP
+.PN XClearWindow
+can generate
+.PN BadMatch
+and
+.PN BadWindow 
+errors.
+.NH 2
+Copying Areas
+.XS
+\*(SN Copying Areas 
+.XE
+.LP
+Xlib provides functions that you can use to copy an area or a bit plane.
+.LP
+.sp
+To copy an area between drawables of the same
+root and depth, use
+.PN XCopyArea .
+.IN "Areas" "copying"
+.IN "Copying" "areas"
+.IN "XCopyArea" "" "@DEF@"
+.sM
+.FD 0
+XCopyArea\^(\^\fIdisplay\fP, \fIsrc\fP\^, \fIdest\fP\^, \fIgc\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIwidth\fP\^, \fIheight\fP\^,  \fIdest_x\fP\^, \fIdest_y\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fIsrc\fP\^, \fIdest\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
+.br
+      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
+.br
+      int \fIdest_x\fP\^, \fIdest_y\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIsrc\fP 1i
+.br
+.ns
+.IP \fIdest\fP 1i
+Specify the source and destination rectangles to be combined. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIsrc_x\fP 1i
+.br
+.ns
+.IP \fIsrc_y\fP 1i
+Specify the x and y coordinates, 
+which are relative to the origin of the source rectangle
+and specify its upper-left corner.
+.ds Wh , which are the dimensions of both the source \
+and destination rectangles
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height\*(Wh.
+.ds Dx , which are relative to the origin of the destination rectangle \
+and specify its upper-left corner
+.IP \fIdest_x\fP 1i
+.br
+.ns
+.IP \fIdest_y\fP 1i
+Specify the x and y coordinates\*(Dx. 
+.LP
+.eM
+The
+.PN XCopyArea
+function combines the specified rectangle of src with the specified rectangle 
+of dest.
+The drawables must have the same root and depth,
+or a
+.PN BadMatch
+error results.
+.LP
+If regions of the source rectangle are obscured and have not been
+retained in backing store 
+or if regions outside the boundaries of the source drawable are specified, 
+those regions are not copied. 
+Instead, the 
+following occurs on all corresponding destination regions that are either
+visible or are retained in backing store.  
+If the destination is a window with a background other than 
+.PN None , 
+corresponding regions
+of the destination are tiled with that background
+(with plane-mask of all ones and
+.PN GXcopy 
+function).
+Regardless of tiling or whether the destination is a window or a pixmap,
+if graphics-exposures is 
+.PN True ,
+then
+.PN GraphicsExpose
+events for all corresponding destination regions are generated.
+If graphics-exposures is 
+.PN True 
+but no
+.PN GraphicsExpose
+events are generated, a
+.PN NoExpose 
+event is generated.
+Note that by default graphics-exposures is
+.PN True
+in new GCs.
+.LP
+This function uses these GC components: function, plane-mask, 
+subwindow-mode, graphics-exposures, clip-x-origin,
+clip-y-origin, and clip-mask.
+.LP
+.PN XCopyArea
+can generate
+.PN BadDrawable ,
+.PN BadGC ,
+and
+.PN BadMatch 
+errors.
+.sp
+.LP
+To copy a single bit plane of a given drawable, use
+.PN XCopyPlane .
+.IN "Plane" "copying"
+.IN "Copying" "planes"
+.IN "XCopyPlane" "" "@DEF@"
+.sM
+.FD 0
+XCopyPlane\^(\^\fIdisplay\fP, \fIsrc\fP\^, \fIdest\fP\^, \fIgc\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIdest_x\fP\^, \fIdest_y\fP\^, \fIplane\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fIsrc\fP\^, \fIdest\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
+.br
+      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
+.br
+      int \fIdest_x\fP\^, \fIdest_y\fP\^;
+.br
+      unsigned long \fIplane\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIsrc\fP 1i
+.br
+.ns
+.IP \fIdest\fP 1i
+Specify the source and destination rectangles to be combined. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIsrc_x\fP 1i
+.br
+.ns
+.IP \fIsrc_y\fP 1i
+Specify the x and y coordinates, 
+which are relative to the origin of the source rectangle
+and specify its upper-left corner.
+.ds Wh , which are the dimensions of both the source and destination rectangles
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height\*(Wh.
+.ds Dx , which are relative to the origin of the destination rectangle \
+and specify its upper-left corner
+.IP \fIdest_x\fP 1i
+.br
+.ns
+.IP \fIdest_y\fP 1i
+Specify the x and y coordinates\*(Dx. 
+.IP \fIplane\fP 1i
+Specifies the bit plane.
+You must set exactly one bit to 1.
+.LP
+.eM
+The
+.PN XCopyPlane
+function uses a single bit plane of the specified source rectangle
+combined with the specified GC to modify the specified rectangle of dest.
+The drawables must have the same root but need not have the same depth.
+If the drawables do not have the same root, a
+.PN BadMatch
+error results.
+If plane does not have exactly one bit set to 1 and the value of plane
+is not less than %2 sup n%, where \fIn\fP is the depth of src, a
+.PN BadValue
+error results.
+.LP
+Effectively, 
+.PN XCopyPlane
+forms a pixmap of the same depth as the rectangle of dest and with a
+size specified by the source region. 
+It uses the foreground/background pixels in the GC (foreground
+everywhere the bit plane in src contains a bit set to 1,
+background everywhere the bit plane in src contains a bit set to 0)
+and the equivalent of a 
+.PN CopyArea
+protocol request is performed with all the same exposure semantics.
+This can also be thought of as using the specified region of the source 
+bit plane as a stipple with a fill-style of
+.PN FillOpaqueStippled
+for filling a rectangular area of the destination.
+.LP
+This function uses these GC components: function, plane-mask, foreground,
+background, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin,
+and clip-mask.
+.LP
+.PN XCopyPlane
+can generate
+.PN BadDrawable ,
+.PN BadGC ,
+.PN BadMatch ,
+and 
+.PN BadValue 
+errors.
+.NH 2
+Drawing Points, Lines, Rectangles, and Arcs
+.XS
+\*(SN Drawing Points, Lines, Rectangles, and Arcs 
+.XE
+.LP
+Xlib provides functions that you can use to draw:
+.IP \(bu 5
+A single point or multiple points
+.IP \(bu 5
+A single line or multiple lines
+.IP \(bu 5
+A single rectangle or multiple rectangles
+.IP \(bu 5
+A single arc or multiple arcs
+.LP
+Some of the functions described in the following sections
+use these structures:
+.LP
+.IN "XSegment" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i
+.ta .5i
+typedef struct {
+	short x1, y1, x2, y2;
+} XSegment;
+.De
+.LP
+.eM
+.IN "XPoint" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i
+.ta .5i
+typedef struct {
+	short x, y;
+} XPoint;
+.De
+.LP
+.eM
+.IN "XRectangle" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i
+.ta .5i
+typedef struct {
+	short x, y;
+	unsigned short width, height;
+} XRectangle;
+.De
+.LP
+.eM
+.IN "XArc" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	short x, y;
+	unsigned short width, height;
+	short angle1, angle2;             /* Degrees * 64 */
+} XArc;
+.De
+.LP
+.eM
+All x and y members are signed integers.
+The width and height members are 16-bit unsigned integers.
+You should be careful not to generate coordinates and sizes
+out of the 16-bit ranges, because the protocol only has 16-bit fields
+for these values.
+.NH 3
+Drawing Single and Multiple Points
+.XS
+\*(SN Drawing Single and Multiple Points 
+.XE
+.LP
+.IN "Points" "drawing"
+.IN "Drawing" "points"
+.IN "XDrawPoints"
+.IN "XDrawPoint"
+.LP
+To draw a single point in a given drawable, use
+.PN XDrawPoint .
+.IN "XDrawPoint" "" "@DEF@"
+.sM
+.FD 0
+XDrawPoint\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates where you want the point drawn.
+.LP
+.eM
+.sp
+To draw multiple points in a given drawable, use
+.PN XDrawPoints .
+.IN "XDrawPoints" "" "@DEF@"
+.sM
+.FD 0
+XDrawPoints\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIpoints\fP\^, \fInpoints\fP\^, \fImode\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      XPoint *\fIpoints\fP\^;
+.br
+      int \fInpoints\fP\^;
+.br
+      int \fImode\fP\^; 
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIpoints\fP 1i
+Specifies an array of points.
+.IP \fInpoints\fP 1i
+Specifies the number of points in the array.
+.IP \fImode\fP 1i
+Specifies the coordinate mode. 
+You can pass
+.PN CoordModeOrigin
+or
+.PN CoordModePrevious .
+.LP
+.eM
+The
+.PN XDrawPoint
+function uses the foreground pixel and function components of the
+GC to draw a single point into the specified drawable; 
+.PN XDrawPoints
+draws multiple points this way.
+.PN CoordModeOrigin
+treats all coordinates as relative to the origin,
+and
+.PN CoordModePrevious
+treats all coordinates after the first as relative to the previous point.
+.PN XDrawPoints
+draws the points in the order listed in the array.
+.LP
+Both functions use these GC components: function, plane-mask,
+foreground, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
+.LP
+.PN XDrawPoint
+can generate
+.PN BadDrawable ,
+.PN BadGC ,
+and 
+.PN BadMatch 
+errors.
+.PN XDrawPoints
+can generate
+.PN BadDrawable ,
+.PN BadGC ,
+.PN BadMatch ,
+and
+.PN BadValue 
+errors.
+.NH 3
+Drawing Single and Multiple Lines
+.XS
+\*(SN Drawing Single and Multiple Lines
+.XE
+.LP
+.IN "Lines" "drawing"
+.IN "Drawing" "lines"
+.IN "XDrawLine"
+.IN "XDrawLines"
+.IN "Polygons" "drawing"
+.IN "Drawing" "polygons"
+.IN "XDrawSegments"
+.LP
+To draw a single line between two points in a given drawable, use
+.PN XDrawLine .
+.IN "XDrawLine" "" "@DEF@"
+.sM
+.FD 0
+XDrawLine\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx1\fP\^, \fIy1\fP\^, \fIx2\fP\^, \fIy2\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIx1\fP\^, \fIy1\fP\^, \fIx2\fP\^, \fIy2\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIx1\fP 1i
+.br
+.ns
+.IP \fIy1\fP 1i
+.br
+.ns
+.IP \fIx2\fP 1i
+.br
+.ns
+.IP \fIy2\fP 1i
+Specify the points (x1, y1) and (x2, y2) to be connected.
+.LP
+.eM
+.sp
+To draw multiple lines in a given drawable, use
+.PN XDrawLines .
+.IN "XDrawLines" "" "@DEF@"
+.sM
+.FD 0
+XDrawLines\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIpoints\fP\^, \fInpoints\fP\^, \fImode\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      XPoint *\fIpoints\fP\^;
+.br
+      int \fInpoints\fP\^;
+.br
+      int \fImode\fP\^; 
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIpoints\fP 1i
+Specifies an array of points.
+.IP \fInpoints\fP 1i
+Specifies the number of points in the array.
+.IP \fImode\fP 1i
+Specifies the coordinate mode. 
+You can pass
+.PN CoordModeOrigin
+or
+.PN CoordModePrevious .
+.LP
+.eM
+.sp
+To draw multiple, unconnected lines in a given drawable,
+use
+.PN XDrawSegments .
+.IN "XDrawSegments" "" "@DEF@"
+.sM
+.FD 0
+XDrawSegments\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIsegments\fP\^, \fInsegments\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      XSegment *\fIsegments\fP\^;
+.br
+      int \fInsegments\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIsegments\fP 1i
+Specifies an array of segments.
+.IP \fInsegments\fP 1i
+Specifies the number of segments in the array.
+.LP
+.eM
+The
+.PN XDrawLine
+function uses the components of the specified GC to
+draw a line between the specified set of points (x1, y1) and (x2, y2).
+It does not perform joining at coincident endpoints.
+For any given line, 
+.PN XDrawLine 
+does not draw a pixel more than once.
+If lines intersect, the intersecting pixels are drawn multiple times.  
+.LP
+The
+.PN XDrawLines
+function uses the components of the specified GC to draw 
+npoints\-1 lines between each pair of points (point[i], point[i+1]) 
+in the array of
+.PN XPoint
+structures.
+It draws the lines in the order listed in the array.
+The lines join correctly at all intermediate points, and if the first and last
+points coincide, the first and last lines also join correctly.
+For any given line, 
+.PN XDrawLines
+does not draw a pixel more than once.
+If thin (zero line-width) lines intersect, 
+the intersecting pixels are drawn multiple times.
+If wide lines intersect, the intersecting pixels are drawn only once, as though
+the entire 
+.PN PolyLine 
+protocol request were a single, filled shape.
+.PN CoordModeOrigin
+treats all coordinates as relative to the origin,
+and
+.PN CoordModePrevious
+treats all coordinates after the first as relative to the previous point.
+.LP
+The
+.PN XDrawSegments 
+function draws multiple, unconnected lines. 
+For each segment, 
+.PN XDrawSegments 
+draws a
+line between (x1, y1) and (x2, y2).
+It draws the lines in the order listed in the array of
+.PN XSegment
+structures and does not perform joining at coincident endpoints.
+For any given line, 
+.PN XDrawSegments
+does not draw a pixel more than once.  
+If lines intersect, the intersecting pixels are drawn multiple times.  
+.LP
+All three functions use these GC components:
+function, plane-mask, line-width,
+line-style, cap-style, fill-style, subwindow-mode,
+clip-x-origin, clip-y-origin, and clip-mask.
+The
+.PN XDrawLines
+function also uses the join-style GC component.
+All three functions also use these GC mode-dependent components:
+foreground, background, tile, stipple, tile-stipple-x-origin, 
+tile-stipple-y-origin, dash-offset, and dash-list.
+.LP
+.PN XDrawLine ,
+.PN XDrawLines ,
+and
+.PN XDrawSegments
+can generate
+.PN BadDrawable ,
+.PN BadGC ,
+and
+.PN BadMatch 
+errors.
+.PN XDrawLines
+also can generate
+.PN BadValue 
+errors.
+.NH 3
+Drawing Single and Multiple Rectangles 
+.XS
+\*(SN Drawing Single and Multiple Rectangles 
+.XE
+.LP
+.IN "Rectangles" "drawing"
+.IN "Drawing" "rectangles"
+.IN "XDrawRectangle"
+.IN "XDrawRectangles"
+.LP
+To draw the outline of a single rectangle in a given drawable, use
+.PN XDrawRectangle .
+.IN "XDrawRectangle" "" "@DEF@"
+.sM
+.FD 0
+XDrawRectangle\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.ds Xy , which specify the upper-left corner of the rectangle
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.ds Wh , which specify the dimensions of the rectangle
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height\*(Wh.
+.LP
+.eM
+.sp
+To draw the outline of multiple rectangles
+in a given drawable, use
+.PN XDrawRectangles .
+.IN "XDrawRectangles" "" "@DEF@"
+.sM
+.FD 0
+XDrawRectangles\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIrectangles\fP\^, \fInrectangles\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      XRectangle \fIrectangles\fP\^[\^]\^;
+.br
+      int \fInrectangles\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIrectangles\fP 1i
+Specifies an array of rectangles.
+.IP \fInrectangles\fP 1i
+Specifies the number of rectangles in the array.
+.LP
+.eM
+The
+.PN XDrawRectangle
+and
+.PN XDrawRectangles
+functions draw the outlines of the specified rectangle or rectangles as
+if a five-point 
+.PN PolyLine 
+protocol request were specified for each rectangle:
+.IP
+[x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y]
+.LP 
+For the specified rectangle or rectangles, 
+these functions do not draw a pixel more than once.
+.PN XDrawRectangles
+draws the rectangles in the order listed in the array.
+If rectangles intersect,
+the intersecting pixels are drawn multiple times.
+.LP
+Both functions use these GC components: 
+function, plane-mask, line-width,
+line-style, cap-style, join-style, fill-style, 
+subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
+They also use these GC mode-dependent components: 
+foreground, background, tile, stipple, tile-stipple-x-origin, 
+tile-stipple-y-origin, dash-offset, and dash-list.
+.LP
+.PN XDrawRectangle
+and
+.PN XDrawRectangles
+can generate
+.PN BadDrawable ,
+.PN BadGC ,
+and
+.PN BadMatch 
+errors.
+.NH 3
+Drawing Single and Multiple Arcs
+.XS
+\*(SN Drawing Single and Multiple Arcs 
+.XE
+.LP
+.IN "Drawing" "arcs"
+.IN "XDrawArc"
+.IN "Arcs" "drawing"
+.IN "XDrawArcs"
+.LP
+.sp
+To draw a single arc in a given drawable, use
+.PN XDrawArc .
+.IN "XDrawArc" "" "@DEF@"
+.sM
+.FD 0
+XDrawArc\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIangle1\fP\^, \fIangle2\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
+.br
+      int \fIangle1\fP\^, \fIangle2\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.ds Xy , which are relative to the origin of the drawable \
+and specify the upper-left corner of the bounding rectangle
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.ds Wh , which are the major and minor axes of the arc
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height\*(Wh.
+.IP \fIangle1\fP 1i
+Specifies the start of the arc relative to the three-o'clock position
+from the center, in units of degrees * 64.
+.IP \fIangle2\fP 1i
+Specifies the path and extent of the arc relative to the start of the
+arc, in units of degrees * 64.
+.LP
+.eM
+.sp
+To draw multiple arcs in a given drawable, use
+.PN XDrawArcs .
+.IN "XDrawArcs" "" "@DEF@"
+.sM
+.FD 0
+XDrawArcs\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIarcs\fP\^, \fInarcs\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      XArc *\fIarcs\fP\^;
+.br
+      int \fInarcs\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIarcs\fP 1i
+Specifies an array of arcs.
+.IP \fInarcs\fP 1i
+Specifies the number of arcs in the array.
+.LP
+.eM
+.EQ
+delim %%
+.EN
+.PN XDrawArc
+draws a single circular or elliptical arc, and 
+.PN XDrawArcs
+draws multiple circular or elliptical arcs.
+Each arc is specified by a rectangle and two angles.  
+The center of the circle or ellipse is the center of the
+rectangle, and the major and minor axes are specified by the width and height.
+Positive angles indicate counterclockwise motion, 
+and negative angles indicate clockwise motion.  
+If the magnitude of angle2 is greater than 360 degrees, 
+.PN XDrawArc
+or 
+.PN XDrawArcs
+truncates it to 360 degrees.
+.LP
+For an arc specified as %[ ~x, ~y, ~width , ~height, ~angle1, ~angle2 ]%, 
+the origin of the major and minor axes is at 
+% [ x +^ {width over 2} , ~y +^ {height over 2}  ]%, 
+and the infinitely thin path describing the entire circle or ellipse 
+intersects the horizontal axis at % [ x, ~y +^ {height over 2}  ]% and 
+% [ x +^ width , ~y +^ { height over 2 }] %
+and intersects the vertical axis at % [ x +^ { width over 2 } , ~y ]% and 
+% [ x +^ { width over 2 }, ~y +^ height ]%.
+These coordinates can be fractional
+and so are not truncated to discrete coordinates.
+The path should be defined by the ideal mathematical path.  
+For a wide line with line-width lw, 
+the bounding outlines for filling are given        
+by the two infinitely thin paths consisting of all points whose perpendicular
+distance from the path of the circle/ellipse is equal to lw/2
+(which may be a fractional value).
+The cap-style and join-style are applied the same as for a line
+corresponding to the tangent of the circle/ellipse at the endpoint.
+.LP
+For an arc specified as % [ ~x, ~y, ~width, ~height, ~angle1, ~angle2  ]%,
+the angles must be specified
+in the effectively skewed coordinate system of the ellipse (for a
+circle, the angles and coordinate systems are identical).  The
+relationship between these angles and angles expressed in the normal
+coordinate system of the screen (as measured with a protractor) is as
+follows:
+.LP
+.Ds
+% roman "skewed-angle" ~ = ~ atan left ( tan ( roman "normal-angle" )
+ * width over height right ) +^ adjust%
+.De
+.LP
+The skewed-angle and normal-angle are expressed in radians (rather
+than in degrees scaled by 64) in the range % [ 0 , ~2 pi  ]% and where atan
+returns a value in the range % [ - pi over 2 , ~pi over 2  ] %
+and adjust is:
+.LP
+.Ds
+.TA 1i 2i
+.ta 1i 2i
+%0%	for normal-angle in the range % [ 0 , ~pi over 2  ]%
+%pi%	for normal-angle in the range % [ pi over 2 , ~{3 pi} over 2  ]%
+%2 pi%	for normal-angle in the range % [ {3 pi} over 2 , ~2 pi  ]%
+.De
+.LP
+For any given arc, 
+.PN XDrawArc
+and
+.PN XDrawArcs
+do not draw a pixel more than once.  
+If two arcs join correctly and if the line-width is greater than zero 
+and the arcs intersect, 
+.PN XDrawArc
+and
+.PN XDrawArcs
+do not draw a pixel more than once.
+Otherwise, 
+the intersecting pixels of intersecting arcs are drawn multiple times.
+Specifying an arc with one endpoint and a clockwise extent draws the same pixels
+as specifying the other endpoint and an equivalent counterclockwise extent,
+except as it affects joins.
+.LP
+If the last point in one arc coincides with the first point in the following 
+arc, the two arcs will join correctly.  
+If the first point in the first arc coincides with the last point in the last 
+arc, the two arcs will join correctly.
+By specifying one axis to be zero, a horizontal or vertical line can be
+drawn.
+Angles are computed based solely on the coordinate system and ignore the
+aspect ratio.
+.LP
+Both functions use these GC components: 
+function, plane-mask, line-width, line-style, cap-style, join-style, 
+fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
+They also use these GC mode-dependent components: 
+foreground, background, tile, stipple, tile-stipple-x-origin, 
+tile-stipple-y-origin, dash-offset, and dash-list.
+.LP
+.PN XDrawArc
+and
+.PN XDrawArcs
+can generate
+.PN BadDrawable ,
+.PN BadGC ,
+and
+.PN BadMatch 
+errors.
+.NH 2
+Filling Areas
+.XS
+\*(SN Filling Areas 
+.XE
+.LP
+Xlib provides functions that you can use to fill:
+.IP \(bu 5
+A single rectangle or multiple rectangles
+.IP \(bu 5
+A single polygon
+.IP \(bu 5
+A single arc or multiple arcs
+.NH 3
+Filling Single and Multiple Rectangles
+.XS
+\*(SN Filling Single and Multiple Rectangles 
+.XE
+.LP
+.IN "Filling" "rectangles"
+.IN "XFillRectangle"
+.IN "Rectangle" "filling"
+.IN "XFillRectangles"
+.LP
+.sp
+To fill a single rectangular area in a given drawable, use
+.PN XFillRectangle .
+.IN "XFillRectangle" "" "@DEF@"
+.sM
+.FD 0 
+XFillRectangle\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.ds Xy , which are relative to the origin of the drawable \
+and specify the upper-left corner of the rectangle
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.ds Wh , which are the dimensions of the rectangle to be filled
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height\*(Wh.
+.LP
+.eM
+.sp
+To fill multiple rectangular areas in a given drawable, use
+.PN XFillRectangles .
+.IN "XFillRectangles" "" "@DEF@"
+.sM
+.FD 0 
+XFillRectangles\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIrectangles\fP\^, \fInrectangles\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      XRectangle *\fIrectangles\fP\^;
+.br
+      int \fInrectangles\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIrectangles\fP 1i
+Specifies an array of rectangles.
+.IP \fInrectangles\fP 1i
+Specifies the number of rectangles in the array.
+.LP
+.eM
+The
+.PN XFillRectangle
+and
+.PN XFillRectangles
+functions fill the specified rectangle or rectangles
+as if a four-point 
+.PN FillPolygon
+protocol request were specified for each rectangle:
+.LP
+.Ds
+[x,y] [x+width,y] [x+width,y+height] [x,y+height]
+.De
+.LP
+Each function uses the x and y coordinates,
+width and height dimensions, and GC you specify.
+.LP
+.PN XFillRectangles
+fills the rectangles in the order listed in the array.  
+For any given rectangle,
+.PN XFillRectangle
+and
+.PN XFillRectangles
+do not draw a pixel more than once.  
+If rectangles intersect, the intersecting pixels are
+drawn multiple times.
+.LP
+Both functions use these GC components: 
+function, plane-mask, fill-style, subwindow-mode, 
+clip-x-origin, clip-y-origin, and clip-mask.
+They also use these GC mode-dependent components: 
+foreground, background, tile, stipple, tile-stipple-x-origin, 
+and tile-stipple-y-origin.
+.LP
+.PN XFillRectangle
+and
+.PN XFillRectangles
+can generate
+.PN BadDrawable ,
+.PN BadGC ,
+and
+.PN BadMatch 
+errors.
+.NH 3
+Filling a Single Polygon
+.XS
+\*(SN Filling a Single Polygon 
+.XE
+.LP
+.sp
+To fill a polygon area in a given drawable, use
+.PN XFillPolygon .
+.IN "Polygons" "filling"
+.IN "Filling" "polygon"
+.IN "XFillPolygon" "" "@DEF@"
+.sM
+.FD 0 
+XFillPolygon\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIpoints\fP\^, \fInpoints\fP\^, \fIshape\fP\^, \fImode\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      XPoint *\fIpoints\fP\^;
+.br
+      int \fInpoints\fP\^;
+.br
+      int \fIshape\fP\^; 
+.br
+      int \fImode\fP\^; 
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIpoints\fP 1i
+Specifies an array of points.
+.IP \fInpoints\fP 1i
+Specifies the number of points in the array.
+.IP \fIshape\fP 1i
+Specifies a shape that helps the server to improve performance.
+You can pass 
+.PN Complex , 
+.PN Convex , 
+or 
+.PN Nonconvex .
+.IP \fImode\fP 1i
+Specifies the coordinate mode. 
+You can pass
+.PN CoordModeOrigin
+or
+.PN CoordModePrevious .
+.LP
+.eM
+.PN XFillPolygon 
+fills the region closed by the specified path.
+The path is closed
+automatically if the last point in the list does not coincide with the
+first point.
+.PN XFillPolygon
+does not draw a pixel of the region more than once.
+.PN CoordModeOrigin
+treats all coordinates as relative to the origin,
+and
+.PN CoordModePrevious
+treats all coordinates after the first as relative to the previous point.
+.LP
+Depending on the specified shape, the following occurs: 
+.IP \(bu 5
+If shape is
+.PN Complex , 
+the path may self-intersect. 
+Note that contiguous coincident points in the path are not treated 
+as self-intersection.
+.IP \(bu 5
+If shape is
+.PN Convex , 
+for every pair of points inside the polygon,
+the line segment connecting them does not intersect the path.
+If known by the client,
+specifying 
+.PN Convex 
+can improve performance.  
+If you specify
+.PN Convex 
+for a path that is not convex, 
+the graphics results are undefined.
+.IP \(bu 5
+If shape is
+.PN Nonconvex , 
+the path does not self-intersect, but the shape is not
+wholly convex. 
+If known by the client, 
+specifying 
+.PN Nonconvex 
+instead of
+.PN Complex 
+may improve performance.  
+If you specify
+.PN Nonconvex 
+for a self-intersecting path, the graphics results are undefined.
+.LP
+The fill-rule of the GC controls the filling behavior of 
+self-intersecting polygons.
+.LP
+This function uses these GC components: 
+function, plane-mask, fill-style, fill-rule, subwindow-mode, clip-x-origin, 
+clip-y-origin, and clip-mask.
+It also uses these GC mode-dependent components: 
+foreground, background, tile, stipple, tile-stipple-x-origin, 
+and tile-stipple-y-origin.
+.LP
+.PN XFillPolygon
+can generate
+.PN BadDrawable ,
+.PN BadGC ,
+.PN BadMatch ,
+and
+.PN BadValue 
+errors.
+.NH 3
+Filling Single and Multiple Arcs
+.XS
+\*(SN Filling Single and Multiple Arcs 
+.XE
+.LP
+.IN "XFillArc"
+.IN "Arcs" "filling"
+.IN "Filling" "arcs"
+To fill a single arc in a given drawable, use
+.PN XFillArc .
+.IN "XFillArc" "" "@DEF@"
+.sM
+.FD 0
+XFillArc\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^,  \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIangle1\fP\^, \fIangle2\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
+.br
+      int \fIangle1\fP\^, \fIangle2\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.ds Xy , which are relative to the origin of the drawable \
+and specify the upper-left corner of the bounding rectangle
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.ds Wh , which are the major and minor axes of the arc
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height\*(Wh.
+.IP \fIangle1\fP 1i
+Specifies the start of the arc relative to the three-o'clock position
+from the center, in units of degrees * 64.
+.IP \fIangle2\fP 1i
+Specifies the path and extent of the arc relative to the start of the
+arc, in units of degrees * 64.
+.LP
+.eM
+.sp
+To fill multiple arcs in a given drawable, use
+.PN XFillArcs .
+.IN "XFillArcs" "" "@DEF@"
+.sM
+.FD 0
+XFillArcs\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIarcs\fP\^, \fInarcs\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      XArc *\fIarcs\fP\^;
+.br
+      int \fInarcs\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIarcs\fP 1i
+Specifies an array of arcs.
+.IP \fInarcs\fP 1i
+Specifies the number of arcs in the array.
+.LP
+.eM
+For each arc, 
+.PN XFillArc
+or
+.PN XFillArcs
+fills the region closed by the infinitely thin path
+described by the specified arc and, depending on the 
+arc-mode specified in the GC, one or two line segments. 
+For 
+.PN ArcChord , 
+the single line segment joining the endpoints of the arc is used.  
+For 
+.PN ArcPieSlice ,
+the two line segments joining the endpoints of the arc with the center
+point are used.  
+.PN XFillArcs
+fills the arcs in the order listed in the array.  
+For any given arc,  
+.PN XFillArc
+and
+.PN XFillArcs
+do not draw a pixel more than once.  
+If regions intersect, 
+the intersecting pixels are drawn multiple times.
+.LP
+Both functions use these GC components: 
+function, plane-mask, fill-style, arc-mode, subwindow-mode, clip-x-origin, 
+clip-y-origin, and clip-mask.
+They also use these GC mode-dependent components: 
+foreground, background, tile, stipple, tile-stipple-x-origin, 
+and tile-stipple-y-origin.
+.LP
+.PN XFillArc
+and
+.PN XFillArcs
+can generate
+.PN BadDrawable ,
+.PN BadGC ,
+and
+.PN BadMatch 
+errors.
+.NH 2
+Font Metrics
+.XS
+\*(SN Font Metrics 
+.XE
+.LP
+.IN "Font"
+A font is a graphical description of a set of characters that are used to 
+increase efficiency whenever a set of small, similar sized patterns are 
+repeatedly used.
+.LP
+This section discusses how to:
+.IP \(bu 5
+Load and free fonts
+.IP \(bu 5
+Obtain and free font names
+.IP \(bu 5
+Compute character string sizes
+.IP \(bu 5
+Compute logical extents
+.IP \(bu 5
+Query character string sizes
+.LP
+The X server loads fonts whenever a program requests a new font.
+The server can cache fonts for quick lookup.
+Fonts are global across all screens in a server.
+Several levels are possible when dealing with fonts.
+Most applications simply use 
+.PN XLoadQueryFont
+to load a font and query the font metrics.
+.LP
+Characters in fonts are regarded as masks.
+Except for image text requests,
+the only pixels modified are those in which bits are set to 1 in the character.
+This means that it makes sense to draw text using stipples or tiles
+(for example, many menus gray-out unusable entries).
+.LP
+.sM
+The
+.PN XFontStruct
+structure contains all of the information for the font
+and consists of the font-specific information as well as
+a pointer to an array of
+.PN XCharStruct
+structures for the
+characters contained in the font.
+The
+.PN XFontStruct ,
+.PN XFontProp ,
+and
+.PN XCharStruct
+structures contain:
+.LP
+.IN "XCharStruct" "" "@DEF@"
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	short lbearing;	/* origin to left edge of raster */
+	short rbearing;	/* origin to right edge of raster */
+	short width;	/* advance to next char's origin */
+	short ascent;	/* baseline to top edge of raster */
+	short descent;	/* baseline to bottom edge of raster */
+	unsigned short attributes;	/* per char flags (not predefined) */
+} XCharStruct;
+.De
+.LP
+.IN "XFontProp" "" "@DEF@"
+.Ds 0
+.TA .5i 1i 3i
+.ta .5i 1i 3i
+typedef struct {
+	Atom	name;
+	unsigned long card32;
+} XFontProp;
+.De
+.LP
+.IN "XChar2b" "" "@DEF@"
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {	/* normal 16 bit characters are two bytes */
+    unsigned char byte1;
+    unsigned char byte2;
+} XChar2b;
+.De
+.LP
+.IN "XFontStruct" "" "@DEF@"
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	XExtData *ext_data;	/* hook for extension to hang data */
+	Font fid;	/* Font id for this font */
+	unsigned direction;	/* hint about the direction font is painted */
+	unsigned min_char_or_byte2;	/* first character */
+	unsigned max_char_or_byte2;	/* last character */
+	unsigned min_byte1;	/* first row that exists */
+	unsigned max_byte1;	/* last row that exists */
+	Bool all_chars_exist;	/* flag if all characters have nonzero size */
+	unsigned default_char;	/* char to print for undefined character */
+	int n_properties;	/* how many properties there are */
+	XFontProp *properties;	/* pointer to array of additional properties */
+	XCharStruct min_bounds;	/* minimum bounds over all existing char */
+	XCharStruct max_bounds;	/* maximum bounds over all existing char */
+	XCharStruct *per_char;	/* first_char to last_char information */
+	int ascent;	/* logical extent above baseline for spacing */
+	int descent;	/* logical descent below baseline for spacing */
+} XFontStruct;
+.De
+.LP
+.eM
+X supports single byte/character, two bytes/character matrix,
+and 16-bit character text operations.
+Note that any of these forms can be used with a font, but a
+single byte/character text request can only specify a single byte
+(that is, the first row of a 2-byte font).
+You should view 2-byte fonts as a two-dimensional matrix of defined
+characters: byte1 specifies the range of defined rows and
+byte2 defines the range of defined columns of the font.
+Single byte/character fonts have one row defined, and the byte2 range
+specified in the structure defines a range of characters.
+.LP
+The bounding box of a character is defined by the 
+.PN XCharStruct 
+of that character.
+When characters are absent from a font,
+the default_char is used.
+When fonts have all characters of the same size,
+only the information in the
+.PN XFontStruct
+min and max bounds are used.
+.LP
+The members of the 
+.PN XFontStruct 
+have the following semantics:
+.IP \(bu 5
+The direction member can be either 
+.PN FontLeftToRight 
+or 
+.PN FontRightToLeft . 
+It is just a hint as to whether most 
+.PN XCharStruct 
+elements 
+have a positive 
+.Pn ( FontLeftToRight ) 
+or a negative 
+.Pn ( FontRightToLeft )
+character width 
+metric.
+The core protocol defines no support for vertical text.
+.IP \(bu 5
+If the min_byte1 and max_byte1 members are both zero, min_char_or_byte2
+specifies the linear character index corresponding to the first element
+of the per_char array, and max_char_or_byte2 specifies the linear character
+index of the last element.
+.IP
+If either min_byte1 or max_byte1 are nonzero, both
+min_char_or_byte2 and max_char_or_byte2 are less than 256, 
+and the 2-byte character index values corresponding to the
+per_char array element N (counting from 0) are:
+.IP
+.nf
+	byte1 = N/D + min_byte1
+.br
+	byte2 = N\\D + min_char_or_byte2
+.IP
+.fi
+where:
+.IP
+.nf
+        D = max_char_or_byte2 \- min_char_or_byte2 + 1
+        / = integer division
+        \\ = integer modulus
+.fi
+.IP \(bu 5
+If the per_char pointer is NULL, 
+all glyphs between the first and last character indexes
+inclusive have the same information,
+as given by both min_bounds and max_bounds.
+.IP \(bu 5
+If all_chars_exist is 
+.PN True ,
+all characters in the per_char array have nonzero bounding boxes.
+.IP \(bu 5
+The default_char member specifies the character that will be used when an
+undefined or nonexistent character is printed.  
+The default_char is a 16-bit character (not a 2-byte character).
+For a font using 2-byte matrix format, 
+the default_char has byte1 in the most-significant byte
+and byte2 in the least significant byte.
+If the default_char itself specifies an undefined or nonexistent character, 
+no printing is performed for an undefined or nonexistent character.
+.IP \(bu 5
+The min_bounds and max_bounds members contain the most extreme values of
+each individual 
+.PN XCharStruct 
+component over all elements of this array
+(and ignore nonexistent characters).
+The bounding box of the font (the smallest
+rectangle enclosing the shape obtained by superimposing all of the
+characters at the same origin [x,y]) has its upper-left coordinate at:
+.Ds
+	[x + min_bounds.lbearing, y \- max_bounds.ascent]
+.De
+.IP
+Its width is:
+.Ds
+	max_bounds.rbearing \- min_bounds.lbearing
+.De
+.IP
+Its height is:
+.Ds
+	max_bounds.ascent + max_bounds.descent
+.De
+.IP \(bu 5
+The ascent member is the logical extent of the font above the baseline that is
+used for determining line spacing.
+Specific characters may extend beyond
+this.
+.IP \(bu 5
+The descent member is the logical extent of the font at or below the
+baseline that is used for determining line spacing.
+Specific characters may extend beyond this.
+.IP \(bu 5
+If the baseline is at Y-coordinate y,
+the logical extent of the font is inclusive between the Y-coordinate 
+values (y \- font.ascent) and (y + font.descent \- 1).
+Typically,
+the minimum interline spacing between rows of text is given
+by ascent + descent.
+.LP
+For a character origin at [x,y],
+the bounding box of a character (that is, 
+the smallest rectangle that encloses the character's shape)
+described in terms of 
+.PN XCharStruct 
+components is a rectangle with its upper-left corner at:
+.LP
+.Ds
+[x + lbearing, y \- ascent]
+.De
+.LP
+Its width is:
+.LP
+.Ds
+rbearing \- lbearing
+.De
+.LP
+Its height is:
+.LP
+.Ds
+ascent + descent
+.De
+.LP
+The origin for the next character is defined to be:
+.LP
+.Ds
+[x + width, y]
+.De
+.LP
+The lbearing member defines the extent of the left edge of the character ink
+from the origin.
+The rbearing member defines the extent of the right edge of the character ink
+from the origin.
+The ascent member defines the extent of the top edge of the character ink
+from the origin.
+The descent member defines the extent of the bottom edge of the character ink
+from the origin.
+The width member defines the logical width of the character.
+.LP
+Note that the baseline (the y position of the character origin) 
+is logically viewed as being the scanline just below nondescending characters. 
+When descent is zero,
+only pixels with Y-coordinates less than y are drawn,
+and the origin is logically viewed as being coincident with the left edge of
+a nonkerned character. 
+When lbearing is zero,
+no pixels with X-coordinate less than x are drawn.
+Any of the
+.PN XCharStruct
+metric members could be negative.
+If the width is negative,
+the next character will be placed to the left of the current origin.
+.LP
+The X protocol does not define the interpretation of the attributes member 
+in the
+.PN XCharStruct
+structure.
+A nonexistent character is represented with all members of its
+.PN XCharStruct
+set to zero.
+.LP
+A font is not guaranteed to have any properties.
+The interpretation of the property value (for example, long or unsigned long)
+must be derived from \fIa priori\fP knowledge of the property. 
+A basic set of font properties is specified in the X Consortium standard
+\fIX Logical Font Description Conventions\fP.
+.NH 3
+Loading and Freeing Fonts
+.XS
+\*(SN Loading and Freeing Fonts 
+.XE
+.LP
+Xlib provides functions that you can use to load fonts, get font information,
+unload fonts, and free font information.
+.IN "Fonts" "getting information"
+.IN "Fonts" "unloading"
+.IN "Fonts" "freeing font information"
+A few font functions use a 
+.PN GContext 
+resource ID or a font ID interchangeably.
+.LP
+.sp
+To load a given font, use
+.PN XLoadFont .
+.IN "XLoadFont" "" "@DEF@"
+.sM
+.FD 0
+Font XLoadFont\^(\^\fIdisplay\fP, \fIname\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      char *\fIname\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIname\fP 1i
+Specifies the name of the font,
+which is a null-terminated string.
+.LP
+.eM
+The
+.PN XLoadFont
+function loads the specified font and returns its associated font ID.
+If the font name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+When the characters ``?'' and ``*'' are used in a font name, a
+pattern match is performed and any matching font is used.
+In the pattern, 
+the ``?'' character will match any single character, 
+and the ``*'' character will match any number of characters.
+A structured format for font names is specified in the X Consortium standard 
+\fIX Logical Font Description Conventions\fP.
+If 
+.PN XLoadFont
+was unsuccessful at loading the specified font, 
+a 
+.PN BadName 
+error results.
+Fonts are not associated with a particular screen 
+and can be stored as a component
+of any GC.
+When the font is no longer needed, call 
+.PN XUnloadFont .
+.LP
+.PN XLoadFont
+can generate
+.PN BadAlloc
+and
+.PN BadName 
+errors.
+.LP
+.sp
+To return information about an available font, use
+.PN XQueryFont .
+.IN "XQueryFont" "" "@DEF@"
+.sM
+.FD 0
+XFontStruct *XQueryFont\^(\^\fIdisplay\fP, \fIfont_ID\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XID \fIfont_ID\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIfont_ID\fP 1i
+Specifies the font ID or the 
+.PN GContext
+ID.
+.LP
+.eM
+The
+.PN XQueryFont
+function returns a pointer to the
+.PN XFontStruct
+structure, which contains information associated with the font.
+You can query a font or the font stored in a GC.
+The font ID stored in the 
+.PN XFontStruct
+structure will be the 
+.PN GContext 
+ID, and you need to be careful when using this ID in other functions
+(see
+.PN XGContextFromGC ).
+If the font does not exist,
+.PN XQueryFont
+returns NULL.
+To free this data, use
+.PN XFreeFontInfo .
+.LP
+.sp
+To perform a
+.PN XLoadFont
+and
+.PN XQueryFont
+in a single operation, use
+.PN XLoadQueryFont .
+.IN "XLoadQueryFont" "" "@DEF@"
+.sM
+.FD 0
+XFontStruct *XLoadQueryFont\^(\^\fIdisplay\fP, \fIname\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      char *\fIname\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIname\fP 1i
+Specifies the name of the font,
+which is a null-terminated string.
+.LP
+.eM
+The
+.PN XLoadQueryFont
+function provides the most common way for accessing a font.
+.PN XLoadQueryFont
+both opens (loads) the specified font and returns a pointer to the
+appropriate
+.PN XFontStruct
+structure.
+If the font name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+If the font does not exist,
+.PN XLoadQueryFont
+returns NULL.
+.LP
+.PN XLoadQueryFont
+can generate a
+.PN BadAlloc 
+error.
+.LP
+.sp
+To unload the font and free the storage used by the font structure
+that was allocated by
+.PN XQueryFont
+or
+.PN XLoadQueryFont ,
+use
+.PN XFreeFont .
+.IN "XFreeFont" "" "@DEF@"
+.sM
+.FD 0
+XFreeFont\^(\^\fIdisplay\fP, \fIfont_struct\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XFontStruct *\fIfont_struct\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIfont_struct\fP 1i
+Specifies the storage associated with the font.
+.LP
+.eM 
+The
+.PN XFreeFont
+function deletes the association between the font resource ID and the specified 
+font and frees the
+.PN XFontStruct
+structure.
+The font itself will be freed when no other resource references it.
+The data and the font should not be referenced again.
+.LP
+.PN XFreeFont
+can generate a
+.PN BadFont 
+error.
+.LP
+.sp
+To return a given font property, use
+.PN XGetFontProperty .
+.IN "XGetFontProperty" "" "@DEF@"
+.sM
+.FD 0
+Bool XGetFontProperty\^(\^\fIfont_struct\fP\^, \^\fIatom\fP\^, \^\fIvalue_return\fP\^)
+.br
+      XFontStruct *\fIfont_struct\fP\^;
+.br
+      Atom \fIatom\fP\^;
+.br
+      unsigned long *\fIvalue_return\fP\^;
+.FN
+.IP \fIfont_struct\fP 1i
+Specifies the storage associated with the font.
+.IP \fIatom\fP 1i
+Specifies the atom for the property name you want returned.
+.IP \fIvalue_return\fP 1i
+Returns the value of the font property.
+.LP
+.eM
+Given the atom for that property,
+the
+.PN XGetFontProperty
+function returns the value of the specified font property. 
+.PN XGetFontProperty
+also returns 
+.PN False
+if the property was not defined or 
+.PN True
+if it was defined.
+A set of predefined atoms exists for font properties,
+which can be found in
+.hN X11/Xatom.h .
+This set contains the standard properties associated with
+a font.
+Although it is not guaranteed,
+it is likely that the predefined font properties will be present.
+.LP
+.sp
+To unload a font that was loaded by
+.PN XLoadFont , 
+use
+.PN XUnloadFont .
+.IN "XUnloadFont" "" "@DEF@"
+.sM
+.FD 0
+XUnloadFont\^(\^\fIdisplay\fP, \fIfont\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Font \fIfont\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIfont\fP 1i
+Specifies the font.
+.LP
+.eM
+The
+.PN XUnloadFont
+function deletes the association between the font resource ID and the specified font.
+The font itself will be freed when no other resource references it.
+The font should not be referenced again.
+.LP
+.PN XUnloadFont
+can generate a
+.PN BadFont 
+error.
+.NH 3
+Obtaining and Freeing Font Names and Information
+.XS
+\*(SN Obtaining and Freeing Font Names and Information
+.XE
+.LP
+You obtain font names and information by matching a wildcard specification
+when querying a font type for a list of available sizes and so on.
+.LP
+.sp
+To return a list of the available font names, use
+.PN XListFonts .
+.IN "XListFonts" "" "@DEF@"
+.sM
+.FD 0
+char **XListFonts\^(\^\fIdisplay\fP, \fIpattern\fP\^, \fImaxnames\fP, \fIactual_count_return\fP\^)
+.br
+      Display *\^\fIdisplay\fP\^;
+.br
+      char *\^\fIpattern\fP\^;
+.br
+      int \fImaxnames\fP\^;
+.br
+      int *\^\fIactual_count_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIpattern\fP 1i
+Specifies the null-terminated pattern string that can contain wildcard 
+characters.
+.IP \fImaxnames\fP 1i
+Specifies the maximum number of names to be returned.
+.IP \fIactual_count_return\fP 1i
+Returns the actual number of font names.
+.LP
+.eM
+The
+.PN XListFonts
+function returns an array of available font names 
+(as controlled by the font search path; see
+.PN XSetFontPath )
+that match the string you passed to the pattern argument.
+The pattern string can contain any characters,
+but each asterisk (*) is a wildcard for any number of characters,
+and each question mark (?) is a wildcard for a single character.
+If the pattern string is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+Each returned string is null-terminated.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned strings are in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+If there are no matching font names,
+.PN XListFonts
+returns NULL.
+The client should call
+.PN XFreeFontNames
+when finished with the result to free the memory.
+.LP
+.sp
+To free a font name array, use
+.PN XFreeFontNames .
+.IN "XFreeFontNames" "" "@DEF@"
+.sM
+.FD 0
+XFreeFontNames\^(\^\fIlist\fP\^)
+.br
+      char *\fIlist\fP\^[\^]\^;
+.FN
+.IP \fIlist\fP 1i
+Specifies the array of strings you want to free.
+.LP
+.eM
+The
+.PN XFreeFontNames
+function frees the array and strings returned by
+.PN XListFonts 
+or
+.PN XListFontsWithInfo .
+.LP
+.sp
+To obtain the names and information about available fonts, use
+.PN XListFontsWithInfo .
+.IN "XListFontsWithInfo" "" "@DEF@"
+.sM
+.FD 0
+char **XListFontsWithInfo\^(\^\fIdisplay\fP, \fIpattern\fP, \fImaxnames\fP, \fIcount_return\fP, \fIinfo_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      char *\fIpattern\fP\^;
+.br
+      int \fImaxnames\fP\^;
+.br
+      int *\fIcount_return\fP\^;
+.br
+      XFontStruct **\fIinfo_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIpattern\fP 1i
+Specifies the null-terminated pattern string that can contain wildcard 
+characters.
+.IP \fImaxnames\fP 1i
+Specifies the maximum number of names to be returned.
+.IP \fIcount_return\fP 1i
+Returns the actual number of matched font names.
+.IP \fIinfo_return\fP 1i
+Returns the font information.
+.LP
+.eM
+The
+.PN XListFontsWithInfo
+function returns a list of font names that match the specified pattern and their
+associated font information.
+The list of names is limited to size specified by maxnames.
+The information returned for each font is identical to what
+.PN XLoadQueryFont
+would return except that the per-character metrics are not returned.
+The pattern string can contain any characters,
+but each asterisk (*) is a wildcard for any number of characters,
+and each question mark (?) is a wildcard for a single character.
+If the pattern string is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Use of uppercase or lowercase does not matter.
+Each returned string is null-terminated.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned strings are in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+If there are no matching font names,
+.PN XListFontsWithInfo
+returns NULL.
+.LP
+To free only the allocated name array,
+the client should call
+.PN XFreeFontNames .
+To free both the name array and the font information array
+or to free just the font information array,
+the client should call
+.PN XFreeFontInfo .
+.LP
+.sp
+To free font structures and font names, use
+.PN XFreeFontInfo .
+.IN "XFreeFontInfo" "" "@DEF@"
+.sM
+.FD 0
+XFreeFontInfo(\^\fInames\fP, \fIfree_info\fP, \fIactual_count\fP\^)
+.br
+      char **\fInames\fP\^;
+.br
+      XFontStruct *\fIfree_info\fP;
+.br
+      int \fIactual_count\fP\^;
+.FN
+.IP \fInames\fP 1i
+Specifies the list of font names.
+
+.IP \fIfree_info\fP 1i
+Specifies the font information.
+
+.IP \fIactual_count\fP 1i
+Specifies the actual number of font names.
+
+.LP
+.eM
+The
+.PN XFreeFontInfo
+function frees a font structure or an array of font structures
+and optionally an array of font names.
+If NULL is passed for names, no font names are freed.
+If a font structure for an open font (returned by
+.PN XLoadQueryFont )
+is passed, the structure is freed,
+but the font is not closed; use
+.PN XUnloadFont
+to close the font.
+.NH 3
+Computing Character String Sizes
+.XS
+\*(SN Computing Character String Sizes 
+.XE
+.LP
+Xlib provides functions that you can use to compute the width,
+the logical extents, 
+and the server information about 8-bit and 2-byte text strings.
+.IN "XTextWidth"
+.IN "XTextWidth16"
+The width is computed by adding the character widths of all the characters.
+It does not matter if the font is an 8-bit or 2-byte font.
+These functions return the sum of the character metrics in pixels.
+.LP
+.sp
+To determine the width of an 8-bit character string, use
+.PN XTextWidth .
+.IN "XTextWidth" "" "@DEF@"
+.sM
+.FD 0
+int XTextWidth\^(\^\fIfont_struct\fP\^, \fIstring\fP, \fIcount\fP\^)
+.br
+      XFontStruct *\fIfont_struct\fP\^;
+.br
+      char *\fIstring\fP\^;
+.br
+      int \fIcount\fP\^;
+.FN
+.IP \fIfont_struct\fP 1i
+Specifies the font used for the width computation.
+.IP \fIstring\fP 1i
+Specifies the character string.
+.IP \fIcount\fP 1i
+Specifies the character count in the specified string.
+.LP
+.eM
+.sp
+To determine the width of a 2-byte character string, use
+.PN XTextWidth16 .
+.IN "XTextWidth16" "" "@DEF@"
+.sM
+.FD 0
+int XTextWidth16\^(\^\fIfont_struct\fP\^, \fIstring\fP, \fIcount\fP\^)
+.br
+      XFontStruct *\fIfont_struct\fP\^;
+.br
+      XChar2b *\fIstring\fP\^;
+.br
+      int \fIcount\fP\^;
+.FN
+.IP \fIfont_struct\fP 1i
+Specifies the font used for the width computation.
+.IP \fIstring\fP 1i
+Specifies the character string.
+.IP \fIcount\fP 1i
+Specifies the character count in the specified string.
+.LP
+.eM
+.NH 3
+Computing Logical Extents
+.XS
+\*(SN Computing Logical Extents 
+.XE
+.LP
+To compute the bounding box of an 8-bit character string in a given font, use
+.PN XTextExtents .
+.IN "XTextExtents" "" "@DEF@"
+.sM
+.FD 0
+XTextExtents\^(\^\fIfont_struct\fP\^, \fIstring\fP\^, \fInchars\fP\^, \
+\fIdirection_return\fP, \fIfont_ascent_return\fP,
+.br
+              \fIfont_descent_return\fP, \fIoverall_return\fP\^)
+.br
+      XFontStruct *\fIfont_struct\fP\^;
+.br
+      char *\fIstring\fP\^;
+.br
+      int \fInchars\fP\^;
+.br
+      int *\fIdirection_return\fP\^;
+.br
+      int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^;
+.br
+      XCharStruct *\fIoverall_return\fP\^;
+
+.FN
+.IP \fIfont_struct\fP 1i
+Specifies the 
+.PN XFontStruct 
+structure.
+.IP \fIstring\fP 1i
+Specifies the character string.
+.IP \fInchars\fP 1i
+Specifies the number of characters in the character string.
+.IP \fIdirection_return\fP 1i
+Returns the value of the direction hint
+.Pn ( FontLeftToRight
+or
+.PN FontRightToLeft ).
+.IP \fIfont_ascent_return\fP 1i
+Returns the font ascent.
+.IP \fIfont_descent_return\fP 1i
+Returns the font descent.
+.IP \fIoverall_return\fP 1i
+Returns the overall size in the specified
+.PN XCharStruct 
+structure.
+.LP
+.eM
+.sp
+To compute the bounding box of a 2-byte character string in a given font, use
+.PN XTextExtents16 .
+.IN "XTextExtents16" "" "@DEF@"
+.sM
+.FD 0
+XTextExtents16\^(\^\fIfont_struct\fP\^, \fIstring\fP\^, \fInchars\fP\^, \
+\fIdirection_return\fP, \fIfont_ascent_return\fP, 
+.br
+                \fIfont_descent_return\fP, \fIoverall_return\fP\^)
+.br
+      XFontStruct *\fIfont_struct\fP\^;
+.br
+      XChar2b *\fIstring\fP\^;
+.br
+      int \fInchars\fP\^;
+.br
+      int *\fIdirection_return\fP\^;
+.br
+      int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^;
+.br
+      XCharStruct *\fIoverall_return\fP\^;
+
+.FN
+.IP \fIfont_struct\fP 1i
+Specifies the 
+.PN XFontStruct 
+structure.
+.IP \fIstring\fP 1i
+Specifies the character string.
+.IP \fInchars\fP 1i
+Specifies the number of characters in the character string.
+.IP \fIdirection_return\fP 1i
+Returns the value of the direction hint
+.Pn ( FontLeftToRight
+or
+.PN FontRightToLeft ).
+.IP \fIfont_ascent_return\fP 1i
+Returns the font ascent.
+.IP \fIfont_descent_return\fP 1i
+Returns the font descent.
+.IP \fIoverall_return\fP 1i
+Returns the overall size in the specified
+.PN XCharStruct 
+structure.
+.LP
+.eM
+The
+.PN XTextExtents
+and
+.PN XTextExtents16
+functions 
+perform the size computation locally and, thereby,
+avoid the round-trip overhead of
+.PN XQueryTextExtents 
+and
+.PN XQueryTextExtents16 .
+Both functions return an
+.PN XCharStruct
+structure, whose members are set to the values as follows.
+.LP
+The ascent member is set to the maximum of the ascent metrics of all
+characters in the string.
+The descent member is set to the maximum of the descent metrics.
+The width member is set to the sum of the character-width metrics of all
+characters in the string.
+For each character in the string,
+let W be the sum of the character-width metrics of all characters preceding 
+it in the string.
+Let L be the left-side-bearing metric of the character plus W.
+Let R be the right-side-bearing metric of the character plus W.
+The lbearing member is set to the minimum L of all characters in the string.
+The rbearing member is set to the maximum R.
+.LP
+For fonts defined with linear indexing rather than 2-byte matrix indexing,
+each 
+.PN XChar2b 
+structure is interpreted as a 16-bit number with byte1 as the 
+most significant byte.
+If the font has no defined default character,
+undefined characters in the string are taken to have all zero metrics.
+.NH 3
+Querying Character String Sizes
+.XS
+\*(SN Querying Character String Sizes 
+.XE
+.LP
+To query the server for the bounding box of an 8-bit character string in a 
+given font, use 
+.PN XQueryTextExtents .
+.IN "XQueryTextExtents" "" "@DEF@"
+.sM
+.FD 0
+XQueryTextExtents\^(\^\fIdisplay\fP, \fIfont_ID\fP, \fIstring\fP, \
+\fInchars\fP, \fIdirection_return\fP, \fIfont_ascent_return\fP, 
+.br
+                    \fIfont_descent_return\fP, \fIoverall_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XID \fIfont_ID\fP\^;
+.br
+      char *\fIstring\fP\^;
+.br
+      int \fInchars\fP\^;
+.br
+      int *\fIdirection_return\fP\^;
+.br
+      int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^;
+.br
+      XCharStruct *\fIoverall_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIfont_ID\fP 1i
+Specifies either the font ID or the 
+.PN GContext
+ID that contains the font.
+.IP \fIstring\fP 1i
+Specifies the character string.
+.IP \fInchars\fP 1i
+Specifies the number of characters in the character string.
+.IP \fIdirection_return\fP 1i
+Returns the value of the direction hint
+.Pn ( FontLeftToRight
+or
+.PN FontRightToLeft ).
+.IP \fIfont_ascent_return\fP 1i
+Returns the font ascent.
+.IP \fIfont_descent_return\fP 1i
+Returns the font descent.
+.IP \fIoverall_return\fP 1i
+Returns the overall size in the specified
+.PN XCharStruct 
+structure.
+.LP
+.eM
+.sp
+To query the server for the bounding box of a 2-byte character string
+in a given font, use
+.PN XQueryTextExtents16 .
+.IN "XQueryTextExtents16" "" "@DEF@"
+.sM
+.FD 0
+XQueryTextExtents16\^(\^\fIdisplay\fP, \fIfont_ID\fP, \fIstring\fP, \
+\fInchars\fP, \fIdirection_return\fP, \fIfont_ascent_return\fP, 
+.br
+                        \fIfont_descent_return\fP, \fIoverall_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XID \fIfont_ID\fP\^;
+.br
+      XChar2b *\fIstring\fP\^;
+.br
+      int \fInchars\fP\^;
+.br
+      int *\fIdirection_return\fP\^;
+.br
+      int *\fIfont_ascent_return\fP, *\fIfont_descent_return\fP\^;
+.br
+      XCharStruct *\fIoverall_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIfont_ID\fP 1i
+Specifies either the font ID or the 
+.PN GContext
+ID that contains the font.
+.IP \fIstring\fP 1i
+Specifies the character string.
+.IP \fInchars\fP 1i
+Specifies the number of characters in the character string.
+.IP \fIdirection_return\fP 1i
+Returns the value of the direction hint
+.Pn ( FontLeftToRight
+or
+.PN FontRightToLeft ).
+.IP \fIfont_ascent_return\fP 1i
+Returns the font ascent.
+.IP \fIfont_descent_return\fP 1i
+Returns the font descent.
+.IP \fIoverall_return\fP 1i
+Returns the overall size in the specified
+.PN XCharStruct 
+structure.
+.LP
+.eM
+The
+.PN XQueryTextExtents
+and
+.PN XQueryTextExtents16
+functions return the bounding box of the specified 8-bit and 16-bit
+character string in the specified font or the font contained in the
+specified GC.
+These functions query the X server and, therefore, suffer the round-trip
+overhead that is avoided by
+.PN XTextExtents
+and 
+.PN XTextExtents16 .
+Both functions return a
+.PN XCharStruct 
+structure, whose members are set to the values as follows.
+.LP
+The ascent member is set to the maximum of the ascent metrics 
+of all characters in the string.
+The descent member is set to the maximum of the descent metrics.
+The width member is set to the sum of the character-width metrics 
+of all characters in the string.
+For each character in the string,
+let W be the sum of the character-width metrics of all characters preceding
+it in the string.
+Let L be the left-side-bearing metric of the character plus W.
+Let R be the right-side-bearing metric of the character plus W.
+The lbearing member is set to the minimum L of all characters in the string.
+The rbearing member is set to the maximum R.
+.LP
+For fonts defined with linear indexing rather than 2-byte matrix indexing,
+each 
+.PN XChar2b 
+structure is interpreted as a 16-bit number with byte1 as the 
+most significant byte.
+If the font has no defined default character,
+undefined characters in the string are taken to have all zero metrics.
+.LP
+Characters with all zero metrics are ignored.
+If the font has no defined default_char,
+the undefined characters in the string are also ignored.
+.LP
+.PN XQueryTextExtents
+and
+.PN XQueryTextExtents16
+can generate
+.PN BadFont
+and
+.PN BadGC 
+errors.
+.NH 2
+Drawing Text
+.XS
+\*(SN Drawing Text
+.XE
+.LP
+This section discusses how to draw:
+.IP \(bu 5
+Complex text 
+.IP \(bu 5
+Text characters
+.IP \(bu 5
+Image text characters
+.LP
+The fundamental text functions
+.PN XDrawText
+and
+.PN XDrawText16
+use the following structures:
+.LP
+.IN "XTextItem" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	char *chars;	/* pointer to string */
+	int nchars;	/* number of characters */
+	int delta;	/* delta between strings */
+	Font font;	/* Font to print it in, None don't change */
+} XTextItem;
+.De
+.LP
+.IN "XTextItem16" "" "@DEF@"
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	XChar2b *chars;	/* pointer to two-byte characters */
+	int nchars;	/* number of characters */
+	int delta;	/* delta between strings */
+	Font font;	/* font to print it in, None don't change */
+} XTextItem16;
+.De
+.LP
+.eM
+If the font member is not
+.PN None ,
+the font is changed before printing and also is stored in the GC.
+If an error was generated during text drawing,
+the previous items may have been drawn.
+The baseline of the characters are drawn starting at the x and y
+coordinates that you pass in the text drawing functions.
+.LP
+For example, consider the background rectangle drawn by
+.PN XDrawImageString .
+If you want the upper-left corner of the background rectangle
+to be at pixel coordinate (x,y), pass the (x,y + ascent)
+as the baseline origin coordinates to the text functions.
+The ascent is the font ascent, as given in the
+.PN XFontStruct
+structure.
+If you want the lower-left corner of the background rectangle
+to be at pixel coordinate (x,y), pass the (x,y \- descent + 1)
+as the baseline origin coordinates to the text functions.
+The descent is the font descent, as given in the
+.PN XFontStruct
+structure.
+.NH 3
+Drawing Complex Text
+.XS
+\*(SN Drawing Complex Text 
+.XE
+.LP
+.IN "Text" "drawing"
+.IN "Drawing" "text items"
+.LP
+To draw 8-bit characters in a given drawable, use
+.PN XDrawText .
+.IN "XDrawText" "" "@DEF@"
+.sM
+.FD 0
+XDrawText\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      XTextItem *\fIitems\fP\^;
+.br
+      int \fInitems\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.ds Xy , which are relative to the origin of the specified drawable \
+and define the origin of the first character
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.IP \fIitems\fP 1i
+Specifies an array of text items.
+.IP \fInitems\fP 1i
+Specifies the number of text items in the array.
+.LP
+.eM
+.sp
+To draw 2-byte characters in a given drawable, use
+.PN XDrawText16 .
+.IN "XDrawText16" "" "@DEF@"
+.sM
+.FD 0
+XDrawText16\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      XTextItem16 *\fIitems\fP\^;
+.br
+      int \fInitems\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.ds Xy , which are relative to the origin of the specified drawable \
+and define the origin of the first character
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.IP \fIitems\fP 1i
+Specifies an array of text items.
+.IP \fInitems\fP 1i
+Specifies the number of text items in the array.
+.LP
+.eM
+The
+.PN XDrawText16
+function is similar to
+.PN XDrawText 
+except that it uses 2-byte or 16-bit characters.
+Both functions allow complex spacing and font shifts between counted strings.
+.LP
+Each text item is processed in turn.
+A font member other than 
+.PN None
+in an item causes the font to be stored in the GC
+and used for subsequent text.  
+A text element delta specifies an additional change
+in the position along the x axis before the string is drawn. 
+The delta is always added to the character origin
+and is not dependent on any characteristics of the font.
+Each character image, as defined by the font in the GC, is treated as an
+additional mask for a fill operation on the drawable.
+The drawable is modified only where the font character has a bit set to 1.
+If a text item generates a
+.PN BadFont
+error, the previous text items may have been drawn.
+.LP
+For fonts defined with linear indexing rather than 2-byte matrix indexing,
+each 
+.PN XChar2b
+structure is interpreted as a 16-bit number with byte1 as the 
+most significant byte.
+.LP
+Both functions use these GC components:
+function, plane-mask, fill-style, font, subwindow-mode, 
+clip-x-origin, clip-y-origin, and clip-mask.
+They also use these GC mode-dependent components: 
+foreground, background, tile, stipple, tile-stipple-x-origin, 
+and tile-stipple-y-origin.
+.LP
+.PN XDrawText
+and
+.PN XDrawText16
+can generate
+.PN BadDrawable ,
+.PN BadFont ,
+.PN BadGC ,
+and
+.PN BadMatch 
+errors.
+.NH 3
+Drawing Text Characters
+.XS
+\*(SN Drawing Text Characters 
+.XE
+.LP
+.IN "Strings" "drawing"
+.IN "Drawing" "strings"
+To draw 8-bit characters in a given drawable, use
+.PN XDrawString .
+.IN "XDrawString" "" "@DEF@"
+.sM
+.FD 0
+XDrawString\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      char *\fIstring\fP\^;
+.br
+      int \fIlength\fP\^; 
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.ds Xy , which are relative to the origin of the specified drawable \
+and define the origin of the first character
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.IP \fIstring\fP 1i
+Specifies the character string.
+.IP \fIlength\fP 1i
+Specifies the number of characters in the string argument.
+.LP
+.eM
+.sp
+To draw 2-byte characters in a given drawable, use
+.PN XDrawString16 .
+.IN "XDrawString16" "" "@DEF@"
+.sM
+.FD 0
+XDrawString16\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      XChar2b *\fIstring\fP\^;
+.br
+      int \fIlength\fP\^; 
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.ds Xy , which are relative to the origin of the specified drawable \
+and define the origin of the first character
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.IP \fIstring\fP 1i
+Specifies the character string.
+.IP \fIlength\fP 1i
+Specifies the number of characters in the string argument.
+.LP
+.eM
+Each character image, as defined by the font in the GC, is treated as an
+additional mask for a fill operation on the drawable.
+The drawable is modified only where the font character has a bit set to 1.
+For fonts defined with 2-byte matrix indexing
+and used with
+.PN XDrawString16 ,
+each byte is used as a byte2 with a byte1 of zero.
+.LP
+Both functions use these GC components: 
+function, plane-mask, fill-style, font, subwindow-mode, clip-x-origin, 
+clip-y-origin, and clip-mask.
+They also use these GC mode-dependent components: 
+foreground, background, tile, stipple, tile-stipple-x-origin, 
+and tile-stipple-y-origin.
+.LP
+.PN XDrawString
+and
+.PN XDrawString16
+can generate
+.PN BadDrawable ,
+.PN BadGC ,
+and
+.PN BadMatch 
+errors.
+.NH 3
+Drawing Image Text Characters
+.XS
+\*(SN Drawing Image Text Characters 
+.XE
+.LP
+.IN "Image text" "drawing"
+.IN "Drawing" "image text"
+Some applications, in particular terminal emulators, need to
+print image text in which both the foreground and background bits of
+each character are painted.
+This prevents annoying flicker on many displays.
+.IN "XDrawImageString"
+.IN "XDrawImageString16"
+.LP
+.sp
+To draw 8-bit image text characters in a given drawable, use
+.PN XDrawImageString .
+.IN "XDrawImageString" "" "@DEF@"
+.sM
+.FD 0
+XDrawImageString\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      char *\fIstring\fP\^;
+.br
+      int \fIlength\fP\^; 
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.ds Xy , which are relative to the origin of the specified drawable \
+and define the origin of the first character
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.IP \fIstring\fP 1i
+Specifies the character string.
+.IP \fIlength\fP 1i
+Specifies the number of characters in the string argument.
+.LP
+.eM
+.sp
+To draw 2-byte image text characters in a given drawable, use
+.PN XDrawImageString16 .
+.IN "XDrawImageString16" "" "@DEF@"
+.sM
+.FD 0
+XDrawImageString16\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fIlength\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      XChar2b *\fIstring\fP\^;
+.br
+      int \fIlength\fP\^; 
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.ds Xy , which are relative to the origin of the specified drawable \
+and define the origin of the first character
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.IP \fIstring\fP 1i
+Specifies the character string.
+.IP \fIlength\fP 1i
+Specifies the number of characters in the string argument.
+.LP
+.eM
+The
+.PN XDrawImageString16
+function is similar to
+.PN XDrawImageString 
+except that it uses 2-byte or 16-bit characters.
+Both functions also use both the foreground and background pixels 
+of the GC in the destination.
+.LP
+The effect is first to fill a
+destination rectangle with the background pixel defined in the GC and then
+to paint the text with the foreground pixel.
+The upper-left corner of the filled rectangle is at:
+.LP
+.Ds
+[x, y \- font-ascent]
+.De
+.LP
+The width is:
+.LP
+.Ds
+overall-width
+.De
+.LP
+The height is:
+.LP
+.Ds
+font-ascent + font-descent
+.De
+.LP
+The overall-width, font-ascent, and font-descent
+are as would be returned by 
+.PN XQueryTextExtents 
+using gc and string.
+The function and fill-style defined in the GC are ignored for these functions. 
+The effective function is 
+.PN GXcopy ,
+and the effective fill-style is
+.PN FillSolid .
+.LP
+For fonts defined with 2-byte matrix indexing
+and used with
+.PN XDrawImageString ,
+each byte is used as a byte2 with a byte1 of zero.
+.LP
+Both functions use these GC components: 
+plane-mask, foreground, background, font, subwindow-mode, clip-x-origin, 
+clip-y-origin, and clip-mask.
+.LP
+.PN XDrawImageString
+and
+.PN XDrawImageString16
+can generate
+.PN BadDrawable ,
+.PN BadGC ,
+and
+.PN BadMatch 
+errors.
+.LP
+.NH 2
+Transferring Images between Client and Server
+.XS
+\*(SN Transferring Images between Client and Server 
+.XE
+.LP
+Xlib provides functions that you can use to transfer images between a client 
+and the server.
+Because the server may require diverse data formats, 
+Xlib provides an image object that fully describes the data in memory 
+and that provides for basic operations on that data.  
+You should reference the data 
+through the image object rather than referencing the data directly.
+However, some implementations of the Xlib library may efficiently deal with 
+frequently used data formats by replacing
+functions in the procedure vector with special case functions.
+Supported operations include destroying the image, getting a pixel,
+storing a pixel, extracting a subimage of an image, and adding a constant
+to an image (see section 16.8).
+.LP
+All the image manipulation functions discussed in this section make use of 
+the 
+.PN XImage 
+structure,
+which describes an image as it exists in the client's memory.
+.LP
+.IN "XImage" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 1i 3i
+.ta .5i 1i 3i
+typedef struct _XImage {
+	int width, height;		/* size of image */
+	int xoffset;		/* number of pixels offset in X direction */
+	int format;		/* XYBitmap, XYPixmap, ZPixmap */
+	char *data;		/* pointer to image data */
+	int byte_order;		/* data byte order, LSBFirst, MSBFirst */
+	int bitmap_unit;		/* quant. of scanline 8, 16, 32 */
+	int bitmap_bit_order;		/* LSBFirst, MSBFirst */
+	int bitmap_pad;		/* 8, 16, 32 either XY or ZPixmap */
+	int depth;		/* depth of image */
+	int bytes_per_line;		/* accelerator to next scanline */
+	int bits_per_pixel;		/* bits per pixel (ZPixmap) */
+	unsigned long red_mask;		/* bits in z arrangement */
+	unsigned long green_mask;
+	unsigned long blue_mask;
+	XPointer obdata;	/* hook for the object routines to hang on */
+	struct funcs {		/* image manipulation routines */
+		struct _XImage *(*create_image)();
+		int (*destroy_image)();
+		unsigned long (*get_pixel)();
+		int (*put_pixel)();
+		struct _XImage *(*sub_image)();
+		int (*add_pixel)();
+	} f;
+} XImage;
+.De
+.LP
+.eM
+.sp
+To initialize the image manipulation routines of an image structure, use
+.PN XInitImage .
+.IN "XInitImage" "" "@DEF@"
+.sM
+.FD 0
+Status XInitImage\^(\^\fIimage\fP\^)
+.br
+      XImage *\fIimage\fP\^;
+.FN
+.IP \fIximage\fP 1i
+Specifies the image.
+.LP
+.eM
+The
+.PN XInitImage
+function initializes the internal image manipulation routines of an
+image structure, based on the values of the various structure members.
+All fields other than the manipulation routines must already be initialized.
+If the bytes_per_line member is zero,
+.PN XInitImage
+will assume the image data is contiguous in memory and set the
+bytes_per_line member to an appropriate value based on the other
+members; otherwise, the value of bytes_per_line is not changed.
+All of the manipulation routines are initialized to functions
+that other Xlib image manipulation functions need to operate on the
+type of image specified by the rest of the structure.
+.LP
+This function must be called for any image constructed by the client
+before passing it to any other Xlib function.
+Image structures created or returned by Xlib do not need to be
+initialized in this fashion.
+.LP
+This function returns a nonzero status if initialization of the
+structure is successful.  It returns zero if it detected some error
+or inconsistency in the structure, in which case the image is not changed.
+.LP
+.sp
+To combine an image with a rectangle of a drawable on the display,
+use
+.PN XPutImage .
+.IN "XPutImage" "" "@DEF@"
+.sM
+.FD 0
+XPutImage\^(\^\fIdisplay\fP, \fId\fP\^, \fIgc\fP\^, \fIimage\fP\^, \fIsrc_x\fP, \fIsrc_y\fP, \fIdest_x\fP\^, \fIdest_y\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
+.br
+        Display *\fIdisplay\fP\^;
+.br
+        Drawable \fId\fP\^;
+.br
+        GC \fIgc\fP\^;
+.br
+        XImage *\fIimage\fP\^;
+.br
+        int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
+.br
+        int \fIdest_x\fP\^, \fIdest_y\fP\^;
+.br
+        unsigned int \fIwidth\fP\^, \fIheight\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIimage\fP 1i
+Specifies the image you want combined with the rectangle. 
+.IP \fIsrc_x\fP 1i
+Specifies the offset in X from the left edge of the image defined
+by the 
+.PN XImage 
+structure.
+.IP \fIsrc_y\fP 1i
+Specifies the offset in Y from the top edge of the image defined
+by the 
+.PN XImage 
+structure.
+.ds Dx , which are relative to the origin of the drawable \
+and are the coordinates of the subimage
+.IP \fIdest_x\fP 1i
+.br
+.ns
+.IP \fIdest_y\fP 1i
+Specify the x and y coordinates\*(Dx. 
+.ds Wh \ of the subimage, which define the dimensions of the rectangle
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height\*(Wh.
+.LP
+.eM
+The
+.PN XPutImage
+function
+combines an image with a rectangle of the specified drawable.
+The section of the image defined by the src_x, src_y, width, and height 
+arguments is drawn on the specified part of the drawable.
+If 
+.PN XYBitmap 
+format is used, the depth of the image must be one,
+or a
+.PN BadMatch 
+error results.
+The foreground pixel in the GC defines the source for the one bits in the image,
+and the background pixel defines the source for the zero bits.
+For 
+.PN XYPixmap 
+and 
+.PN ZPixmap , 
+the depth of the image must match the depth of the drawable,
+or a
+.PN BadMatch
+error results.
+.LP
+If the characteristics of the image (for example, byte_order and bitmap_unit)
+differ from what the server requires,
+.PN XPutImage 
+automatically makes the appropriate
+conversions.
+.LP
+This function uses these GC components: 
+function, plane-mask, subwindow-mode, clip-x-origin, clip-y-origin, 
+and clip-mask.
+It also uses these GC mode-dependent components:
+foreground and background.
+.LP
+.PN XPutImage
+can generate
+.PN BadDrawable ,
+.PN BadGC ,
+.PN BadMatch ,
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To return the contents of a rectangle in a given drawable on the display,
+use
+.PN XGetImage .
+This function specifically supports rudimentary screen dumps.
+.IN "XGetImage" "" "@DEF@"
+.sM
+.FD 0
+XImage *XGetImage\^(\^\fIdisplay\fP, \fId\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIplane_mask\fP, \fIformat\fP\^)
+.br
+        Display *\fIdisplay\fP\^;
+.br
+        Drawable \fId\fP\^;
+.br
+        int \fIx\fP\^, \fIy\fP\^;
+.br
+        unsigned int \fIwidth\fP\^, \fIheight\fP\^;
+.br
+        unsigned long \fIplane_mask\fP\^;
+.br
+        int \fIformat\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.ds Xy , which are relative to the origin of the drawable \
+and define the upper-left corner of the rectangle
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.ds Wh \ of the subimage, which define the dimensions of the rectangle
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height\*(Wh.
+.IP \fIplane_mask\fP 1i
+Specifies the plane mask.
+.\" *** JIM: NEED MORE INFO FOR THIS. ***
+.IP \fIformat\fP 1i
+Specifies the format for the image.
+You can pass
+.PN XYPixmap
+or 
+.PN ZPixmap .
+.LP
+.eM
+The
+.PN XGetImage
+function returns a pointer to an
+.PN XImage
+structure.
+This structure provides you with the contents of the specified rectangle of
+the drawable in the format you specify.
+If the format argument is 
+.PN XYPixmap ,
+the image contains only the bit planes you passed to the plane_mask argument.
+If the plane_mask argument only requests a subset of the planes of the
+display, the depth of the returned image will be the number of planes
+requested.
+If the format argument is 
+.PN ZPixmap ,
+.PN XGetImage
+returns as zero the bits in all planes not 
+specified in the plane_mask argument.
+The function performs no range checking on the values in plane_mask and ignores
+extraneous bits.
+.LP
+.PN XGetImage
+returns the depth of the image to the depth member of the
+.PN XImage
+structure.
+The depth of the image is as specified when the drawable was created,
+except when getting a subset of the planes in 
+.PN XYPixmap
+format, when the depth is given by the number of bits set to 1 in plane_mask.
+.LP
+If the drawable is a pixmap, 
+the given rectangle must be wholly contained within the pixmap, 
+or a
+.PN BadMatch
+error results.
+If the drawable is a window, 
+the window must be viewable, 
+and it must be the case that if there were no inferiors or overlapping windows,
+the specified rectangle of the window would be fully visible on the screen
+and wholly contained within the outside edges of the window,
+or a
+.PN BadMatch
+error results.
+Note that the borders of the window can be included and read with
+this request.
+If the window has backing-store, the backing-store contents are
+returned for regions of the window that are obscured by noninferior
+windows. 
+If the window does not have backing-store,
+the returned contents of such obscured regions are undefined.
+The returned contents of visible regions of inferiors
+of a different depth than the specified window's depth are also undefined.
+The pointer cursor image is not included in the returned contents.
+If a problem occurs,
+.PN XGetImage
+returns NULL.
+.LP
+.PN XGetImage
+can generate
+.PN BadDrawable ,
+.PN BadMatch ,
+and
+.PN BadValue 
+errors.
+.sp
+.LP
+To copy the contents of a rectangle on the display
+to a location within a preexisting image structure, use
+.PN XGetSubImage .
+.IN "XGetSubImage" "" "@DEF@"
+.sM
+.FD 0
+XImage *XGetSubImage\^(\^\fIdisplay\fP, \fId\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIplane_mask\fP, \fIformat\fP\^, \fIdest_image\fP\^, \fIdest_x\fP\^, 
+.br
+                     \fIdest_y\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
+.br
+      unsigned long \fIplane_mask\fP\^;
+.br
+      int \fIformat\fP\^;
+.br
+      XImage *\fIdest_image\fP\^;
+.br
+      int \fIdest_x\fP\^, \fIdest_y\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.ds Xy , which are relative to the origin of the drawable \
+and define the upper-left corner of the rectangle
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.ds Wh \ of the subimage, which define the dimensions of the rectangle
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height\*(Wh.
+.IP \fIplane_mask\fP 1i
+Specifies the plane mask.
+.\" *** JIM: NEED MORE INFO FOR THIS. ***
+.IP \fIformat\fP 1i
+Specifies the format for the image.
+You can pass
+.PN XYPixmap
+or 
+.PN ZPixmap .
+.IP \fIdest_image\fP 1i
+Specifies the destination image.
+.ds Dx , which are relative to the origin of the destination rectangle, \
+specify its upper-left corner, and determine where the subimage \
+is placed in the destination image
+.IP \fIdest_x\fP 1i
+.br
+.ns
+.IP \fIdest_y\fP 1i
+Specify the x and y coordinates\*(Dx. 
+.LP
+.eM
+The 
+.PN XGetSubImage 
+function updates dest_image with the specified subimage in the same manner as 
+.PN XGetImage . 
+If the format argument is 
+.PN XYPixmap ,
+the image contains only the bit planes you passed to the plane_mask argument.
+If the format argument is 
+.PN ZPixmap ,
+.PN XGetSubImage
+returns as zero the bits in all planes not 
+specified in the plane_mask argument.
+The function performs no range checking on the values in plane_mask and ignores
+extraneous bits.
+As a convenience,
+.PN XGetSubImage
+returns a pointer to the same
+.PN XImage
+structure specified by dest_image.
+.LP
+The depth of the destination
+.PN XImage
+structure must be the same as that of the drawable.
+If the specified subimage does not fit at the specified location
+on the destination image, the right and bottom edges are clipped.
+If the drawable is a pixmap,
+the given rectangle must be wholly contained within the pixmap,
+or a
+.PN BadMatch
+error results.
+If the drawable is a window, 
+the window must be viewable, 
+and it must be the case that if there were no inferiors or overlapping windows,
+the specified rectangle of the window would be fully visible on the screen
+and wholly contained within the outside edges of the window,
+or a
+.PN BadMatch
+error results.
+If the window has backing-store, 
+then the backing-store contents are returned for regions of the window 
+that are obscured by noninferior windows. 
+If the window does not have backing-store, 
+the returned contents of such obscured regions are undefined.
+The returned contents of visible regions of inferiors
+of a different depth than the specified window's depth are also undefined.
+If a problem occurs,
+.PN XGetSubImage
+returns NULL.
+.LP
+.PN XGetSubImage
+can generate
+.PN BadDrawable ,
+.PN BadGC ,
+.PN BadMatch ,
+and
+.PN BadValue 
+errors.
+.bp
diff --git a/specs/libX11/CH09 b/specs/libX11/CH09
new file mode 100644
index 00000000..2b79d388
--- /dev/null
+++ b/specs/libX11/CH09
@@ -0,0 +1,1290 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996, 2002 The Open Group
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" Except as contained in this notice, the name of The Open Group 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 Open Group.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 9\fP\s-1
+
+\s+1\fBWindow and Session Manager Functions\fP\s-1
+.sp 2
+.nr H1 9
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.na
+.LP
+.XS
+Chapter 9: Window and Session Manager Functions 
+.XE
+Although it is difficult to categorize functions as exclusively
+for an application, a window manager, or a session manager,
+the functions in this chapter are most often used by window managers
+and session managers.
+It is not expected that these functions will be used by most 
+application programs.
+Xlib provides management functions to:
+.IP \(bu 5
+Change the parent of a window
+.IP \(bu 5
+Control the lifetime of a window
+.IP \(bu 5
+Manage installed colormaps
+.IP \(bu 5
+Set and retrieve the font search path
+.IP \(bu 5
+Grab the server
+.IP \(bu 5
+Kill a client
+.IP \(bu 5
+Control the screen saver
+.IP \(bu 5
+Control host access
+.NH 2
+Changing the Parent of a Window
+.XS
+\*(SN Changing the Parent of a Window 
+.XE
+.LP
+To change a window's parent to another window on the same screen, use
+.PN XReparentWindow .
+There is no way to move a window between screens.
+.IN "XReparentWindow" "" "@DEF@"
+.sM
+.FD 0
+XReparentWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIparent\fP\^, \fIx\fP\^, \fIy\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Window \fIparent\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIparent\fP 1i
+Specifies the parent window.
+.ds Xy \ of the position in the new parent window
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.LP
+.eM
+If the specified window is mapped,
+.PN XReparentWindow
+automatically performs an
+.PN UnmapWindow
+request on it, removes it from its current position in the hierarchy,
+and inserts it as the child of the specified parent.
+The window is placed in the stacking order on top with respect to
+sibling windows.
+.LP
+After reparenting the specified window,
+.PN XReparentWindow
+causes the X server to generate a
+.PN ReparentNotify
+event.
+The override_redirect member returned in this event is
+set to the window's corresponding attribute.
+Window manager clients usually should ignore this window if this member
+is set to
+.PN True .
+Finally, if the specified window was originally mapped,
+the X server automatically performs a
+.PN MapWindow
+request on it.
+.LP
+The X server performs normal exposure processing on formerly obscured
+windows.
+The X server might not generate 
+.PN Expose 
+events for regions from the initial
+.PN UnmapWindow
+request that are immediately obscured by the final
+.PN MapWindow
+request.
+A
+.PN BadMatch
+error results if:
+.IP \(bu 5
+The new parent window is not on the same screen as
+the old parent window.
+.IP \(bu 5
+The new parent window is the specified window or an inferior of the
+specified window.
+.IP \(bu 5
+The new parent is
+.PN InputOnly ,
+and the window is not.
+.IP \(bu 5
+The specified window has a
+.PN ParentRelative
+background, and the new parent window is not the same depth as the
+specified window.
+.LP
+.PN XReparentWindow
+can generate
+.PN BadMatch
+and
+.PN BadWindow 
+errors.
+.NH 2
+Controlling the Lifetime of a Window
+.XS
+\*(SN Controlling the Lifetime of a Window 
+.XE
+.LP
+The save-set of a client is a list of other clients' windows that,
+if they are inferiors of one of the client's windows at connection close,
+should not be destroyed and should be remapped if they are unmapped.
+For further information about close-connection processing,
+see section 2.6.
+To allow an application's window to survive when a window manager that
+has reparented a window fails,
+Xlib provides the save-set functions that you can 
+use to control the longevity of subwindows
+that are normally destroyed when the parent is destroyed.
+For example, a window manager that wants to add decoration
+to a window by adding a frame might reparent an application's
+window. 
+When the frame is destroyed,
+the application's window should not be destroyed 
+but be returned to its previous place in the window hierarchy.
+.LP
+The X server automatically removes windows from the save-set
+when they are destroyed.
+.LP
+.sp
+To add or remove a window from the client's save-set, use
+.PN XChangeSaveSet .
+.IN "XChangeSaveSet" "" "@DEF@"
+.sM
+.FD 0
+XChangeSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^, \fIchange_mode\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      int \fIchange_mode\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Wi that you want to add to or delete from the client's save-set
+.IP \fIw\fP 1i
+Specifies the window \*(Wi.
+.IP \fIchange_mode\fP 1i
+Specifies the mode.
+You can pass
+.PN SetModeInsert 
+or
+.PN SetModeDelete .
+.LP
+.eM
+Depending on the specified mode,
+.PN XChangeSaveSet
+either inserts or deletes the specified window from the client's save-set. 
+The specified window must have been created by some other client,
+or a
+.PN BadMatch
+error results.
+.LP
+.PN XChangeSaveSet
+can generate
+.PN BadMatch ,
+.PN BadValue ,
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To add a window to the client's save-set, use
+.PN XAddToSaveSet .
+.IN "XAddToSaveSet" "" "@DEF@"
+.sM
+.FD 0
+XAddToSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Wi that you want to add to the client's save-set
+.IP \fIw\fP 1i
+Specifies the window \*(Wi.
+.LP
+.eM
+The
+.PN XAddToSaveSet
+function adds the specified window to the client's save-set.
+The specified window must have been created by some other client,
+or a
+.PN BadMatch
+error results.
+.LP
+.PN XAddToSaveSet
+can generate
+.PN BadMatch
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To remove a window from the client's save-set, use
+.PN XRemoveFromSaveSet .
+.IN "XRemoveFromSaveSet" "" "@DEF@"
+.sM
+.FD 0
+XRemoveFromSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Wi that you want to delete from the client's save-set
+.IP \fIw\fP 1i
+Specifies the window \*(Wi.
+.LP
+.eM
+The
+.PN XRemoveFromSaveSet
+function removes the specified window from the client's save-set.
+The specified window must have been created by some other client,
+or a
+.PN BadMatch
+error results.
+.LP
+.PN XRemoveFromSaveSet
+can generate
+.PN BadMatch 
+and
+.PN BadWindow 
+errors.
+.NH 2
+Managing Installed Colormaps
+.XS
+\*(SN Managing Installed Colormaps
+.XE
+.LP
+The X server maintains a list of installed colormaps.
+Windows using these colormaps are guaranteed to display with
+correct colors; windows using other colormaps may or may not display
+with correct colors.
+Xlib provides functions that you can use to install a colormap, 
+uninstall a colormap, and obtain a list of installed colormaps.
+.LP
+At any time,
+there is a subset of the installed maps that is viewed as an ordered list
+and is called the required list.
+The length of the required list is at most M,
+where M is the minimum number of installed colormaps specified for the screen
+in the connection setup.
+The required list is maintained as follows.
+When a colormap is specified to
+.PN XInstallColormap ,
+it is added to the head of the list;
+the list is truncated at the tail, if necessary, to keep its length to 
+at most M.
+When a colormap is specified to
+.PN XUninstallColormap
+and it is in the required list,
+it is removed from the list.
+A colormap is not added to the required list when it is implicitly installed
+by the X server,
+and the X server cannot implicitly uninstall a colormap that is in the
+required list.
+.LP
+.sp
+To install a colormap, use
+.PN XInstallColormap .
+.IN "XInstallColormap" "" "@DEF@"
+.sM
+.FD 0
+XInstallColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.LP
+.eM
+The
+.PN XInstallColormap
+function installs the specified colormap for its associated screen.
+All windows associated with this colormap immediately display with
+true colors.
+You associated the windows with this colormap when you created them by calling
+.PN XCreateWindow ,
+.PN XCreateSimpleWindow ,
+.PN XChangeWindowAttributes ,
+or
+.PN XSetWindowColormap .
+.LP
+If the specified colormap is not already an installed colormap, 
+the X server generates a
+.PN ColormapNotify
+event on each window that has that colormap.
+In addition, for every other colormap that is installed as 
+a result of a call to
+.PN XInstallColormap ,
+the X server generates a
+.PN ColormapNotify
+event on each window that has that colormap.
+.LP
+.PN XInstallColormap
+can generate a
+.PN BadColor 
+error.
+.LP
+.sp
+To uninstall a colormap, use
+.PN XUninstallColormap .
+.IN "XUninstallColormap" "" "@DEF@"
+.sM
+.FD 0
+XUninstallColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Colormap \fIcolormap\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcolormap\fP 1i
+Specifies the colormap.
+.LP
+.eM
+The
+.PN XUninstallColormap
+function removes the specified colormap from the required
+list for its screen.
+As a result,
+the specified colormap might be uninstalled, 
+and the X server might implicitly install or uninstall additional colormaps.
+Which colormaps get installed or uninstalled is server dependent
+except that the required list must remain installed.
+.LP
+If the specified colormap becomes uninstalled, 
+the X server generates a
+.PN ColormapNotify
+event on each window that has that colormap.
+In addition, for every other colormap that is installed or uninstalled as a 
+result of a call to 
+.PN XUninstallColormap ,
+the X server generates a
+.PN ColormapNotify
+event on each window that has that colormap.
+.LP
+.PN XUninstallColormap
+can generate a
+.PN BadColor 
+error.
+.LP
+.sp
+To obtain a list of the currently installed colormaps for a given screen, use
+.PN XListInstalledColormaps .
+.IN "XListInstalledColormaps" "" "@DEF@"
+.sM
+.FD 0
+Colormap *XListInstalledColormaps\^(\^\fIdisplay\fP, \fIw\fP, \fInum_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      int *\fInum_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Wi that determines the screen
+.IP \fIw\fP 1i
+Specifies the window \*(Wi.
+.IP \fInum_return\fP 1i
+Returns the number of currently installed colormaps.
+.LP
+.eM
+The
+.PN XListInstalledColormaps
+function returns a list of the currently installed colormaps for the screen 
+of the specified window.
+The order of the colormaps in the list is not significant
+and is no explicit indication of the required list.
+When the allocated list is no longer needed,
+free it by using
+.PN XFree .
+.LP
+.PN XListInstalledColormaps
+can generate a
+.PN BadWindow 
+error.
+.NH 2
+Setting and Retrieving the Font Search Path
+.XS
+\*(SN Setting and Retrieving the Font Search Path 
+.XE
+.LP
+The set of fonts available from a server depends on a font
+search path.  Xlib provides functions to set and retrieve the
+search path for a server.
+.LP
+.sp
+To set the font search path, use
+.PN XSetFontPath .
+.IN "XSetFontPath" "" "@DEF@"
+.sM
+.FD 0
+XSetFontPath\^(\^\fIdisplay\fP, \fIdirectories\fP\^, \fIndirs\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      char **\fIdirectories\fP\^;
+.br
+      int \fIndirs\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIdirectories\fP 1i
+Specifies the directory path used to look for a font.
+Setting the path to the empty list restores the default path defined
+for the X server.
+.IP \fIndirs\fP 1i
+Specifies the number of directories in the path.
+.LP
+.eM
+The
+.PN XSetFontPath
+function defines the directory search path for font lookup.
+There is only one search path per X server, not one per client.
+The encoding and interpretation of the strings are implementation-dependent,
+but typically they specify directories or font servers to be searched 
+in the order listed.
+An X server is permitted to cache font information internally;
+for example, it might cache an entire font from a file and not
+check on subsequent opens of that font to see if the underlying
+font file has changed.
+However,
+when the font path is changed,
+the X server is guaranteed to flush all cached information about fonts 
+for which there currently are no explicit resource IDs allocated.
+The meaning of an error from this request is implementation-dependent.
+.LP
+.PN XSetFontPath
+can generate a
+.PN BadValue 
+error.
+.LP
+.sp
+To get the current font search path, use
+.PN XGetFontPath .
+.IN "XGetFontPath" "" "@DEF@"
+.sM
+.FD 0
+char **XGetFontPath\^(\^\fIdisplay\fP, \fInpaths_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int *\fInpaths_return\fP\^;
+
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fInpaths_return\fP 1i
+Returns the number of strings in the font path array.
+.LP
+.eM
+The
+.PN XGetFontPath
+function allocates and returns an array of strings containing the search path.
+The contents of these strings are implementation-dependent
+and are not intended to be interpreted by client applications.
+When it is no longer needed,
+the data in the font path should be freed by using
+.PN XFreeFontPath .
+.LP
+.sp
+To free data returned by
+.PN XGetFontPath ,
+use
+.PN XFreeFontPath .
+.IN "XFreeFontPath" "" "@DEF@"
+.sM
+.FD 0
+XFreeFontPath\^(\^\fIlist\fP\^)
+.br
+      char **\fIlist\fP\^;
+
+.FN
+.IP \fIlist\fP 1i
+Specifies the array of strings you want to free.
+.LP
+.eM
+The
+.PN XFreeFontPath
+function
+frees the data allocated by
+.PN XGetFontPath .
+.NH 2
+Grabbing the Server 
+.XS
+\*(SN Grabbing the Server 
+.XE
+.LP
+Xlib provides functions that you can use to grab and ungrab the server.
+These functions can be used to control processing of output on other
+connections by the window system server.
+While the server is grabbed,
+no processing of requests or close downs on any other connection will occur.
+A client closing its connection automatically ungrabs the server.
+.IN "Menus"
+.IN "Window" "managers"
+Although grabbing the server is highly discouraged, it is sometimes necessary.
+.LP
+.sp
+To grab the server, use
+.PN XGrabServer .
+.IN "Server" "grabbing"
+.IN "Grabbing" "server"
+.IN "XGrabServer" "" "@DEF@"
+.sM
+.FD 0
+XGrabServer\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+The
+.PN XGrabServer
+function disables processing of requests and close downs on all other 
+connections than the one this request arrived on.
+You should not grab the X server any more than is absolutely necessary.
+.LP
+.sp
+To ungrab the server, use
+.PN XUngrabServer .
+.IN "XUngrabServer" "" "@DEF@"
+.sM
+.FD 0
+XUngrabServer\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+The
+.PN XUngrabServer
+function restarts processing of requests and close downs on other connections.
+You should avoid grabbing the X server as much as possible.
+.NH 2
+Killing Clients
+.XS
+\*(SN Killing Clients 
+.XE
+.LP
+Xlib provides a function to cause the connection to
+a client to be closed and its resources to be destroyed.
+To destroy a client, use
+.PN XKillClient .
+.IN "XKillClient" "" "@DEF@"
+.sM
+.FD 0
+XKillClient\^(\^\fIdisplay\fP, \fIresource\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XID \fIresource\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIresource\fP 1i
+Specifies any resource associated with the client that you want to destroy or
+.PN AllTemporary .
+.LP
+.eM
+The
+.PN XKillClient
+function
+forces a close down of the client
+that created the resource
+if a valid resource is specified.
+If the client has already terminated in
+either 
+.PN RetainPermanent 
+or 
+.PN RetainTemporary 
+mode, all of the client's
+resources are destroyed.
+If 
+.PN AllTemporary 
+is specified, the resources of all clients that have terminated in
+.PN RetainTemporary 
+are destroyed (see section 2.5).
+This permits implementation of window manager facilities that aid debugging.
+A client can set its close-down mode to
+.PN RetainTemporary .
+If the client then crashes,
+its windows would not be destroyed. 
+The programmer can then inspect the application's window tree 
+and use the window manager to destroy the zombie windows.
+.LP
+.PN XKillClient
+can generate a
+.PN BadValue 
+error.
+.NH 2
+Controlling the Screen Saver 
+.XS
+\*(SN Controlling the Screen Saver 
+.XE
+.LP
+Xlib provides functions that you can use to set or reset the mode 
+of the screen saver, to force or activate the screen saver,
+or to obtain the current screen saver values.
+.LP
+.sp
+To set the screen saver mode, use
+.PN XSetScreenSaver .
+.IN "XSetScreenSaver" "" "@DEF@"
+.sM
+.FD 0
+XSetScreenSaver\^(\^\fIdisplay\fP, \fItimeout\fP\^, \fIinterval\fP\^, \fIprefer_blanking\fP\^, \fIallow_exposures\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fItimeout\fP\^, \fIinterval\fP\^;
+.br
+      int \fIprefer_blanking\fP\^; 
+.br
+      int \fIallow_exposures\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fItimeout\fP 1i
+Specifies the timeout, in seconds, until the screen saver turns on.
+.IP \fIinterval\fP 1i
+Specifies the interval, in seconds, between screen saver alterations.
+.IP \fIprefer_blanking\fP 1i
+Specifies how to enable screen blanking.
+You can pass
+.PN DontPreferBlanking ,
+.PN PreferBlanking ,
+or
+.PN DefaultBlanking .
+.IP \fIallow_exposures\fP 1i
+Specifies the screen save control values.
+You can pass
+.PN DontAllowExposures ,
+.PN AllowExposures ,
+or
+.PN DefaultExposures .
+.LP
+.eM
+Timeout and interval are specified in seconds. 
+A timeout of 0 disables the screen saver 
+(but an activated screen saver is not deactivated),
+and a timeout of \-1 restores the default.
+Other negative values generate a
+.PN BadValue
+error.
+If the timeout value is nonzero, 
+.PN XSetScreenSaver
+enables the screen saver.
+An interval of 0 disables the random-pattern motion.
+If no input from devices (keyboard, mouse, and so on) is generated 
+for the specified number of timeout seconds once the screen saver is enabled,
+the screen saver is activated.
+.LP
+For each screen, 
+if blanking is preferred and the hardware supports video blanking, 
+the screen simply goes blank.  
+Otherwise, if either exposures are allowed or the screen can be regenerated 
+without sending 
+.PN Expose 
+events to clients, 
+the screen is tiled with the root window background tile randomly 
+re-origined each interval seconds.
+Otherwise, the screens' state do not change, 
+and the screen saver is not activated.
+The screen saver is deactivated,
+and all screen states are restored at the next
+keyboard or pointer input or at the next call to
+.PN XForceScreenSaver
+with mode
+.PN ScreenSaverReset .  
+.LP
+If the server-dependent screen saver method supports periodic change,
+the interval argument serves as a hint about how long the change period
+should be, and zero hints that no periodic change should be made.
+Examples of ways to change the screen include scrambling the colormap
+periodically, moving an icon image around the screen periodically, or tiling
+the screen with the root window background tile, randomly re-origined
+periodically.
+.LP
+.PN XSetScreenSaver
+can generate a
+.PN BadValue 
+error.
+.LP
+.sp
+To force the screen saver on or off, use
+.PN XForceScreenSaver .
+.IN "XForceScreenSaver" "" "@DEF@"
+.sM
+.FD 0
+XForceScreenSaver\^(\^\fIdisplay\fP\^, \fImode\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fImode\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fImode\fP 1i
+Specifies the mode that is to be applied.
+You can pass
+.PN ScreenSaverActive
+or
+.PN ScreenSaverReset .
+.LP
+.eM
+If the specified mode is 
+.PN ScreenSaverActive 
+and the screen saver currently is deactivated,
+.PN XForceScreenSaver
+activates the screen saver even if the screen saver had been disabled
+with a timeout of zero.
+If the specified mode is 
+.PN ScreenSaverReset 
+and the screen saver currently is enabled,
+.PN XForceScreenSaver
+deactivates the screen saver if it was activated,
+and the activation timer is reset to its initial state 
+(as if device input had been received).
+.LP
+.PN XForceScreenSaver
+can generate a
+.PN BadValue 
+error.
+.LP
+.sp
+To activate the screen saver, use
+.PN XActivateScreenSaver .
+.IN "XActivateScreenSaver" "" "@DEF@"
+.sM
+.FD 0
+XActivateScreenSaver\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.sp
+To reset the screen saver, use
+.PN XResetScreenSaver .
+.IN "XResetScreenSaver" "" "@DEF@"
+.sM
+.FD 0
+XResetScreenSaver\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+.sp
+To get the current screen saver values, use
+.PN XGetScreenSaver .
+.IN "XGetScreenSaver" "" "@DEF@"
+.sM
+.FD 0
+XGetScreenSaver\^(\^\fIdisplay\fP, \fItimeout_return\fP\^, \fIinterval_return\fP\^, \fIprefer_blanking_return\fP\^, 
+.br
+                  \fIallow_exposures_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int *\fItimeout_return\fP\^, *\fIinterval_return\fP\^;
+.br
+      int *\fIprefer_blanking_return\fP\^;
+.br
+      int *\fIallow_exposures_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fItimeout_return\fP 1i
+Returns the timeout, in seconds, until the screen saver turns on.
+.IP \fIinterval_return\fP 1i
+Returns the interval between screen saver invocations.
+.IP \fIprefer_blanking_return\fP 1i
+Returns the current screen blanking preference
+.Pn ( DontPreferBlanking ,
+.PN PreferBlanking ,
+or
+.PN DefaultBlanking ).
+.IP \fIallow_exposures_return\fP 1i
+Returns the current screen save control value
+.Pn ( DontAllowExposures ,
+.PN AllowExposures ,
+or
+.PN DefaultExposures ).
+.LP
+.eM
+.NH 2
+Controlling Host Access
+.XS
+\*(SN Controlling Host Access 
+.XE
+.LP
+This section discusses how to:
+.IP \(bu 5
+Add, get, or remove hosts from the access control list
+.IP \(bu 5
+Change, enable, or disable access
+.LP
+.IN "Access control list"
+.IN "Authentication"
+X does not provide any protection on a per-window basis.
+If you find out the resource ID of a resource, you can manipulate it.
+To provide some minimal level of protection, however,
+connections are permitted only from machines you trust.
+This is adequate on single-user workstations but obviously
+breaks down on timesharing machines.
+Although provisions exist in the X protocol for proper connection
+authentication, the lack of a standard authentication server
+leaves host-level access control as the only common mechanism.
+.LP
+.IN "Default Protection"
+The initial set of hosts allowed to open connections typically consists of:
+.IP \(bu 5
+The host the window system is running on.
+.IP \(bu 5
+On POSIX-conformant systems, each host listed in the
+.PN /etc/X?.hosts 
+file.
+The ? indicates the number of the
+display.
+.IN "Files" "/etc/X?.hosts"
+This file should consist of host names separated by newlines.
+DECnet nodes must terminate in :: to distinguish them from Internet hosts.
+.LP
+If a host is not in the access control list when the access control 
+mechanism is enabled and if the host attempts to establish a connection,
+the server refuses the connection.
+To change the access list,
+the client must reside on the same host as the server and/or must
+have been granted permission in the initial authorization at connection
+setup.
+.LP
+Servers also can implement other access control policies in addition to
+or in place of this host access facility.
+For further information about other access control implementations,
+see ``X Window System Protocol.''
+.NH 3
+Adding, Getting, or Removing Hosts
+.XS
+\*(SN Adding, Getting, or Removing Hosts 
+.XE
+.LP
+Xlib provides functions that you can use to add, get, or remove hosts
+from the access control list.
+All the host access control functions use the 
+.PN XHostAddress 
+structure, which contains:
+.LP
+.IN "XHostAddress" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int family;	/* for example FamilyInternet */
+	int length;	/* length of address, in bytes */
+	char *address;	/* pointer to where to find the address */
+} XHostAddress;
+.De
+.LP
+.eM
+The family member specifies which protocol address family to use 
+(for example, TCP/IP or DECnet) and can be
+.PN FamilyInternet ,
+.PN FamilyInternet6 ,
+.PN FamilyServerInterpreted ,
+.PN FamilyDECnet ,
+or
+.PN FamilyChaos .
+The length member specifies the length of the address in bytes.
+The address member specifies a pointer to the address.
+.LP
+For TCP/IP, the address should be in network byte order.
+For IP version 4 addresses, the family should be FamilyInternet
+and the length should be 4 bytes.  For IP version 6 addresses, the
+family should be FamilyInternet6 and the length should be 16 bytes.
+.LP
+For the DECnet family, 
+the server performs no automatic swapping on the address bytes.
+A Phase IV address is 2 bytes long.
+The first byte contains the least significant 8 bits of the node number.
+The second byte contains the most significant 2 bits of the
+node number in the least significant 2 bits of the byte
+and the area in the most significant 6 bits of the byte.
+.LP
+For the ServerInterpreted family, the length is ignored and the address 
+member is a pointer to a 
+.PN XServerInterpretedAddress
+structure, which contains:
+.LP
+.IN "XServerInterpretedAddress" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int typelength;	/* length of type string, in bytes */
+	int valuelength;/* length of value string, in bytes */
+	char *type;	/* pointer to where to find the type string */
+	char *value;	/* pointer to where to find the address */
+} XServerInterpretedAddress;
+.De
+.LP
+.eM
+The type and value members point to strings representing the type and value of
+the server interpreted entry.  These strings may not be NULL-terminated so care
+should be used when accessing them.  The typelength and valuelength members
+specify the length in byte of the type and value strings.
+.LP
+.sp
+To add a single host, use
+.PN XAddHost .
+.IN "XAddHost" "" "@DEF@"
+.sM
+.FD 0
+XAddHost\^(\^\fIdisplay\fP, \fIhost\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XHostAddress *\fIhost\fP\^;	
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Ho added
+.IP \fIhost\fP 1i
+Specifies the host that is to be \*(Ho.
+.LP
+.eM
+The
+.PN XAddHost
+function adds the specified host to the access control list for that display.
+The server must be on the same host as the client issuing the command, or a
+.PN BadAccess
+error results.
+.LP
+.PN XAddHost
+can generate
+.PN BadAccess
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To add multiple hosts at one time, use
+.PN XAddHosts .
+.IN "XAddHosts" "" "@DEF@"
+.sM
+.FD 0
+XAddHosts\^(\^\fIdisplay\fP, \fIhosts\fP, \fInum_hosts\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XHostAddress *\fIhosts\fP\^;
+.br
+      int \fInum_hosts\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Ho added
+.IP \fIhosts\fP 1i
+Specifies each host that is to be \*(Ho.
+.IP \fInum_hosts\fP 1i
+Specifies the number of hosts.
+.LP
+.eM
+The
+.PN XAddHosts
+function adds each specified host to the access control list for that display.
+The server must be on the same host as the client issuing the command, or a
+.PN BadAccess
+error results.
+.LP
+.PN XAddHosts
+can generate
+.PN BadAccess
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To obtain a host list, use
+.PN XListHosts .
+.IN "XListHosts" "" "@DEF@"
+.sM
+.FD 0
+XHostAddress *XListHosts\^(\^\fIdisplay\fP, \fInhosts_return\fP, \fIstate_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int *\fInhosts_return\fP\^;
+.br
+      Bool *\fIstate_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fInhosts_return\fP 1i
+Returns the number of hosts currently in the access control list.
+.IP \fIstate_return\fP 1i
+Returns the state of the access control.
+.LP
+.eM
+The
+.PN XListHosts
+function returns the current access control list as well as whether the use 
+of the list at connection setup was enabled or disabled.
+.PN XListHosts
+allows a program to find out what machines can make connections.
+It also returns a pointer to a list of host structures that
+were allocated by the function. 
+When no longer needed,
+this memory should be freed by calling
+.PN XFree .
+.LP
+.sp
+To remove a single host, use
+.PN XRemoveHost .
+.IN "XRemoveHost" "" "@DEF@"
+.sM
+.FD 0
+XRemoveHost\^(\^\fIdisplay\fP, \fIhost\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XHostAddress *\fIhost\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Ho removed
+.IP \fIhost\fP 1i
+Specifies the host that is to be \*(Ho.
+.LP
+.eM
+The
+.PN XRemoveHost
+function removes the specified host from the access control list 
+for that display.
+The server must be on the same host as the client process, or a
+.PN BadAccess
+error results.
+If you remove your machine from the access list,
+you can no longer connect to that server,
+and this operation cannot be reversed unless you reset the server.
+.LP
+.PN XRemoveHost
+can generate
+.PN BadAccess
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To remove multiple hosts at one time, use
+.PN XRemoveHosts .
+.IN "XRemoveHosts" "" "@DEF@"
+.sM
+.FD 0
+XRemoveHosts\^(\^\fIdisplay\fP, \fIhosts\fP, \fInum_hosts\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XHostAddress *\fIhosts\fP\^;
+.br
+      int \fInum_hosts\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Ho removed
+.IP \fIhosts\fP 1i
+Specifies each host that is to be \*(Ho.
+.IP \fInum_hosts\fP 1i
+Specifies the number of hosts.
+.LP
+.eM
+The
+.PN XRemoveHosts
+function removes each specified host from the access control list for that 
+display.  
+The X server must be on the same host as the client process, or a
+.PN BadAccess
+error results.
+If you remove your machine from the access list, 
+you can no longer connect to that server,
+and this operation cannot be reversed unless you reset the server.
+.LP
+.PN XRemoveHosts
+can generate
+.PN BadAccess
+and
+.PN BadValue 
+errors.
+.NH 3
+Changing, Enabling, or Disabling Access Control
+.XS
+\*(SN Changing, Enabling, or Disabling Access Control 
+.XE
+.LP
+Xlib provides functions that you can use to enable, disable, 
+or change access control.
+.LP
+For these functions to execute successfully,
+the client application must reside on the same host as the X server
+and/or have been given permission in the initial authorization
+at connection setup.
+.LP
+.sp
+To change access control, use
+.PN XSetAccessControl .
+.IN "XSetAccessControl" "" "@DEF@"
+.sM
+.FD 0
+XSetAccessControl\^(\^\fIdisplay\fP, \fImode\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fImode\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fImode\fP 1i
+Specifies the mode.
+You can pass
+.PN EnableAccess
+or
+.PN DisableAccess .
+.LP
+.eM
+The
+.PN XSetAccessControl
+function either enables or disables the use of the access control list 
+at each connection setup.
+.LP
+.PN XSetAccessControl
+can generate
+.PN BadAccess
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To enable access control, use
+.PN XEnableAccessControl .
+.IN "XEnableAccessControl" "" "@DEF@"
+.sM
+.FD 0
+XEnableAccessControl\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+The
+.PN XEnableAccessControl
+function enables the use of the access control list at each connection setup.
+.LP
+.PN XEnableAccessControl
+can generate a
+.PN BadAccess 
+error.
+.LP
+.sp
+To disable access control, use
+.PN XDisableAccessControl .
+.IN "XDisableAccessControl" "" "@DEF@"
+.sM
+.FD 0
+XDisableAccessControl\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+The
+.PN XDisableAccessControl
+function disables the use of the access control list at each connection setup.
+.LP
+.PN XDisableAccessControl
+can generate a
+.PN BadAccess 
+error.
+.bp
diff --git a/specs/libX11/CH10 b/specs/libX11/CH10
new file mode 100644
index 00000000..76502fb9
--- /dev/null
+++ b/specs/libX11/CH10
@@ -0,0 +1,3886 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 10\fP\s-1
+
+\s+1\fBEvents\fP\s-1
+.sp 2
+.nr H1 10
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.na
+.LP
+.XS
+Chapter 10: Events
+.XE
+A client application communicates with the X server through the connection you
+establish with the 
+.PN XOpenDisplay 
+.IN "XOpenDisplay"
+function.
+A client application sends requests to the X server over this connection.
+.IN "Requests" "" "@DEF@"
+These requests are made by the Xlib functions that are 
+called in the client application.
+Many Xlib functions cause the X server to generate events,
+and the user's typing or moving the pointer can generate events asynchronously.
+The X server returns events to the client on the same connection.
+.LP
+This chapter discusses the following topics associated with events:
+.IP \(bu 5
+Event types
+.IP \(bu 5
+Event structures
+.IP \(bu 5
+Event masks
+.IP \(bu 5
+Event processing
+.LP
+Functions for handling events are dealt with in the next chapter.
+.NH 2
+Event Types
+.XS
+\*(SN Event Types 
+.XE
+.LP
+.IN "Event" "types"
+An event is data generated asynchronously by the X server as a result of some 
+device activity or as side effects of a request sent by an Xlib function.
+.IN "Event" 
+Device-related events propagate from the source window to ancestor windows
+until some client application has selected that event type 
+or until the event is explicitly discarded.
+The X server generally sends an event to a client application
+only if the client has specifically asked to be informed of that event type, 
+typically by setting the event-mask attribute of the window.
+The mask can also be set when you create a window
+or by changing the window's
+event-mask.
+You can also mask out events that would propagate to ancestor windows
+by manipulating the
+do-not-propagate mask of the window's attributes.
+However,
+.PN MappingNotify
+events are always sent to all clients.
+.IN "Input Control"
+.IN "Output Control"
+.LP
+An event type describes a specific event generated by the X server.
+For each event type, 
+a corresponding constant name is defined in
+.hN X11/X.h ,
+which is used when referring to an event type.
+.IN "Event" "categories"
+The following table lists the event category 
+and its associated event type or types. 
+The processing associated with these events is discussed in section 10.5.
+.LP
+.\".CP T 1
+.\"Event Categories and Event Types
+.LP
+.TS H
+lw(2.25i) lw(3.5i).
+_
+.sp 6p
+.B
+Event Category	Event Type
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+T{
+Keyboard events
+T}	T{
+.PN KeyPress ,
+.PN KeyRelease
+T}
+.sp 6p
+T{
+Pointer events
+T}	T{
+.PN ButtonPress , 
+.PN ButtonRelease  ,
+.PN MotionNotify
+T}
+.sp 6p
+T{
+Window crossing events
+T}	T{
+.PN EnterNotify , 
+.PN LeaveNotify
+T}
+.sp 6p
+T{
+Input focus events
+T}	T{
+.PN FocusIn , 
+.PN FocusOut
+T}
+.sp 6p
+T{
+Keymap state notification event
+T}	T{
+.PN KeymapNotify
+T}
+.sp 6p
+T{
+Exposure events	
+T}	T{
+.PN Expose , 
+.PN GraphicsExpose , 
+.PN NoExpose
+T}
+.sp 6p
+T{
+Structure control events
+T}	T{
+.PN CirculateRequest , 
+.PN ConfigureRequest , 
+.PN MapRequest ,
+.PN ResizeRequest
+T}
+.sp 6p
+T{
+Window state notification events
+T}	T{
+.PN CirculateNotify , 
+.PN ConfigureNotify , 
+.PN CreateNotify , 
+.PN DestroyNotify , 
+.PN GravityNotify , 
+.PN MapNotify ,
+.PN MappingNotify , 
+.PN ReparentNotify , 
+.PN UnmapNotify , 
+.br
+.PN VisibilityNotify
+T}
+.sp 6p
+T{
+Colormap state notification event
+T}	T{
+.PN ColormapNotify
+T}
+.sp 6p
+T{
+Client communication events
+T}	T{
+.PN ClientMessage , 
+.PN PropertyNotify , 
+.PN SelectionClear , 
+.PN SelectionNotify , 
+.PN SelectionRequest
+T}
+.sp 6p
+_
+.TE
+.\".LP
+.\"Table 8-1 lists the event types and the Xlib functions that could cause
+.\"the X server to generate that event type.
+.\"The event types are listed alphabetically.
+.\"Note that the error event is not listed in this table.
+.\"For a list of the constants associated with an error event, see the Handling
+.\"Errors section in this chapter.
+.\".LP
+.\".so eventtable
+.NH 2
+Event Structures
+.XS
+\*(SN Event Structures 
+.XE
+.LP
+For each event type,
+a corresponding structure is declared in
+.hN X11/Xlib.h .
+All the event structures have the following common members:
+.LP
+.IN "XAnyEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window window;
+} XAnyEvent;
+.De
+.LP
+.eM
+The type member is set to the event type constant name that uniquely identifies
+it.
+For example, when the X server reports a
+.PN GraphicsExpose
+event to a client application, it sends an
+.PN XGraphicsExposeEvent
+structure with the type member set to
+.PN GraphicsExpose .
+The display member is set to a pointer to the display the event was read on.
+The send_event member is set to
+.PN True
+if the event came from a
+.PN SendEvent
+protocol request.
+The serial member is set from the serial number reported in the protocol
+but expanded from the 16-bit least-significant bits to a full 32-bit value.
+The window member is set to the window that is most useful to toolkit
+dispatchers.
+.LP
+The X server can send events at any time in the input stream. 
+Xlib stores any events received while waiting for a reply in an event queue 
+for later use.
+Xlib also provides functions that allow you to check events 
+in the event queue (see section 11.3).
+.LP
+In addition to the individual structures declared for each event type, the
+.PN XEvent
+structure is a union of the individual structures declared for each event type.
+Depending on the type,
+you should access members of each event by using the 
+.PN XEvent
+union.
+.LP
+.IN "XEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef union _XEvent {
+	int type;	/* must not be changed */
+	XAnyEvent xany;
+	XKeyEvent xkey;
+	XButtonEvent xbutton;
+	XMotionEvent xmotion;
+	XCrossingEvent xcrossing;
+	XFocusChangeEvent xfocus;
+	XExposeEvent xexpose;
+	XGraphicsExposeEvent xgraphicsexpose;
+	XNoExposeEvent xnoexpose;
+	XVisibilityEvent xvisibility;
+	XCreateWindowEvent xcreatewindow;
+	XDestroyWindowEvent xdestroywindow;
+	XUnmapEvent xunmap;
+	XMapEvent xmap;
+	XMapRequestEvent xmaprequest;
+	XReparentEvent xreparent;
+	XConfigureEvent xconfigure;
+	XGravityEvent xgravity;
+	XResizeRequestEvent xresizerequest;
+	XConfigureRequestEvent xconfigurerequest;
+	XCirculateEvent xcirculate;
+	XCirculateRequestEvent xcirculaterequest;
+	XPropertyEvent xproperty;
+	XSelectionClearEvent xselectionclear;
+	XSelectionRequestEvent xselectionrequest;
+	XSelectionEvent xselection;
+	XColormapEvent xcolormap;
+	XClientMessageEvent xclient;
+	XMappingEvent xmapping;
+	XErrorEvent xerror;
+	XKeymapEvent xkeymap;
+	long pad[24];
+} XEvent;
+.De
+.LP
+.eM
+An
+.PN XEvent
+structure's first entry always is the type member,
+which is set to the event type.
+The second member always is the serial number of the protocol request
+that generated the event.
+The third member always is send_event,
+which is a
+.PN Bool
+that indicates if the event was sent by a different client.
+The fourth member always is a display,
+which is the display that the event was read from.
+Except for keymap events,
+the fifth member always is a window,
+which has been carefully selected to be useful to toolkit dispatchers.
+To avoid breaking toolkits,
+the order of these first five entries is not to change.
+Most events also contain a time member,
+which is the time at which an event occurred.
+In addition, a pointer to the generic event must be cast before it
+is used to access any other information in the structure.
+.NH 2
+Event Masks
+.XS
+\*(SN Event Masks
+.XE
+.LP
+.IN "Event mask" "" "@DEF@"
+Clients select event reporting of most events relative to a window.
+To do this, pass an event mask to an Xlib event-handling
+function that takes an event_mask argument.
+The bits of the event mask are defined in
+.hN X11/X.h .
+Each bit in the event mask maps to an event mask name,
+which describes the event or events you want the X server to
+return to a client application.
+.LP
+Unless the client has specifically asked for them,
+most events are not reported to clients when they are generated. 
+Unless the client suppresses them by setting graphics-exposures in the GC to
+.PN False ,
+.PN GraphicsExpose 
+and 
+.PN NoExpose 
+are reported by default as a result of
+.PN XCopyPlane
+and
+.PN XCopyArea .
+.PN SelectionClear ,
+.PN SelectionRequest ,
+.PN SelectionNotify ,
+or
+.PN ClientMessage
+cannot be masked.
+Selection-related events are only sent to clients cooperating
+with selections (see section 4.5).
+When the keyboard or pointer mapping is changed,
+.PN MappingNotify
+is always sent to clients.
+.LP
+.\"Table 8-2 
+The following table 
+lists the event mask constants you can pass to
+the event_mask argument and
+the circumstances in which you would want to specify the
+event mask:
+.LP
+.\" .CP T 2
+.\"Event Mask Definitions
+.TS H
+lw(2i) lw(3.5i).
+_
+.sp 6p
+.B
+Event Mask	Circumstances
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+T{
+.PN NoEventMask
+T}	T{
+No events wanted
+T}
+T{
+.PN KeyPressMask
+T}	T{
+Keyboard down events wanted
+T}
+T{
+.PN KeyReleaseMask
+T}	T{
+Keyboard up events wanted
+T}
+T{
+.PN ButtonPressMask
+T}	T{
+Pointer button down events wanted
+T}
+T{
+.PN ButtonReleaseMask
+T}	T{
+Pointer button up events wanted
+T}
+T{
+.PN EnterWindowMask
+T}	T{
+Pointer window entry events wanted
+T}
+T{
+.PN LeaveWindowMask
+T}	T{
+Pointer window leave events wanted
+T}
+T{
+.PN PointerMotionMask
+T}	T{
+Pointer motion events wanted
+T}
+T{
+.PN PointerMotionHintMask
+T}	T{
+Pointer motion hints wanted
+T}
+T{
+.PN Button1MotionMask
+T}	T{
+Pointer motion while button 1 down
+T}
+T{
+.PN Button2MotionMask
+T}	T{
+Pointer motion while button 2 down
+T}
+T{
+.PN Button3MotionMask
+T}	T{
+Pointer motion while button 3 down
+T}
+T{
+.PN Button4MotionMask
+T}	T{
+Pointer motion while button 4 down
+T}
+T{
+.PN Button5MotionMask
+T}	T{
+Pointer motion while button 5 down
+T}
+T{
+.PN ButtonMotionMask
+T}	T{
+Pointer motion while any button down
+T}
+T{
+.PN KeymapStateMask
+T}	T{
+Keyboard state wanted at window entry and focus in
+T}
+T{
+.PN ExposureMask
+T}	T{
+Any exposure wanted
+T}
+T{
+.PN VisibilityChangeMask
+T}	T{
+Any change in visibility wanted
+T}
+T{
+.PN StructureNotifyMask
+T}	T{
+Any change in window structure wanted
+T}
+T{
+.PN ResizeRedirectMask
+T}	T{
+Redirect resize of this window
+T}
+T{
+.PN SubstructureNotifyMask
+T}	T{
+Substructure notification wanted
+T}
+T{
+.PN SubstructureRedirectMask
+T}	T{
+Redirect structure requests on children
+T}
+T{
+.PN FocusChangeMask
+T}	T{
+Any change in input focus wanted
+T}
+T{
+.PN PropertyChangeMask
+T}	T{
+Any change in property wanted
+T}
+T{
+.PN ColormapChangeMask
+T}	T{
+Any change in colormap wanted
+T}
+T{
+.PN OwnerGrabButtonMask
+T}	T{
+Automatic grabs should activate with owner_events set to 
+.PN True
+T}
+.sp 6p
+_
+.TE
+.LP
+.NH 2
+Event Processing Overview
+.XS
+\*(SN Event Processing Overview
+.XE
+.LP
+The event reported to a client application during event processing
+depends on which event masks you provide as the event-mask attribute 
+for a window.
+For some event masks, there is a one-to-one correspondence between
+the event mask constant and the event type constant.
+For example, if you pass the event mask
+.PN ButtonPressMask ,
+the X server sends back only
+.PN ButtonPress
+events.
+.IN "CurrentTime"
+Most events contain a time member,
+which is the time at which an event occurred.
+.LP
+In other cases, one event mask constant can map to several event type constants.
+For example, if you pass the event mask
+.PN SubstructureNotifyMask ,
+the X server can send back
+.PN CirculateNotify ,
+.PN ConfigureNotify ,
+.PN CreateNotify ,
+.PN DestroyNotify ,
+.PN GravityNotify ,
+.PN MapNotify ,
+.PN ReparentNotify ,
+or
+.PN UnmapNotify
+events.
+.LP
+In another case, 
+two event masks can map to one event type.
+For example, 
+if you pass either
+.PN PointerMotionMask 
+or
+.PN ButtonMotionMask ,
+the X server sends back
+a
+.PN MotionNotify
+event.
+.LP
+The following table 
+lists the event mask, 
+its associated event type or types, 
+and the structure name associated with the event type.
+Some of these structures actually are typedefs to a generic structure
+that is shared between two event types.
+Note that N.A. appears in columns for which the information is not applicable.
+.LP
+.ps 9
+.nr PS 9
+.TS H
+lw(1.5i) lw(1i) lw(1.5i) lw(1.5i).
+_
+.sp 6p
+.B
+Event Mask	Event Type	Structure	Generic Structure
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+ButtonMotionMask	MotionNotify	XPointerMovedEvent	XMotionEvent
+Button1MotionMask		
+Button2MotionMask		
+Button3MotionMask		
+Button4MotionMask		
+Button5MotionMask		
+.sp 6p
+ButtonPressMask	ButtonPress	XButtonPressedEvent	XButtonEvent
+.sp 6p
+ButtonReleaseMask	ButtonRelease	XButtonReleasedEvent	XButtonEvent
+.sp 6p
+ColormapChangeMask	ColormapNotify	XColormapEvent
+.sp 6p
+EnterWindowMask	EnterNotify	XEnterWindowEvent	XCrossingEvent
+.sp 6p
+LeaveWindowMask	LeaveNotify	XLeaveWindowEvent	XCrossingEvent
+.sp 6p
+ExposureMask	Expose	XExposeEvent 
+GCGraphicsExposures in GC	GraphicsExpose	XGraphicsExposeEvent
+	NoExpose	XNoExposeEvent
+.sp 6p
+FocusChangeMask	FocusIn	XFocusInEvent	XFocusChangeEvent
+	FocusOut	XFocusOutEvent	XFocusChangeEvent
+.sp 6p
+KeymapStateMask	KeymapNotify	XKeymapEvent
+.sp 6p
+KeyPressMask	KeyPress	XKeyPressedEvent	XKeyEvent
+KeyReleaseMask	KeyRelease	XKeyReleasedEvent	XKeyEvent
+.sp 6p
+OwnerGrabButtonMask	N.A.	N.A.
+.sp 6p
+PointerMotionMask	MotionNotify	XPointerMovedEvent	XMotionEvent
+PointerMotionHintMask	N.A.	N.A.
+.sp 6p
+PropertyChangeMask	PropertyNotify	XPropertyEvent
+.sp 6p
+ResizeRedirectMask	ResizeRequest	XResizeRequestEvent
+.sp 6p
+StructureNotifyMask	CirculateNotify	XCirculateEvent
+	ConfigureNotify	XConfigureEvent
+	DestroyNotify	XDestroyWindowEvent
+	GravityNotify	XGravityEvent
+	MapNotify	XMapEvent
+	ReparentNotify	XReparentEvent
+	UnmapNotify	XUnmapEvent
+.sp 6p
+SubstructureNotifyMask	CirculateNotify	XCirculateEvent
+	ConfigureNotify	XConfigureEvent
+	CreateNotify	XCreateWindowEvent
+	DestroyNotify	XDestroyWindowEvent
+	GravityNotify	XGravityEvent
+	MapNotify	XMapEvent
+	ReparentNotify	XReparentEvent
+	UnmapNotify	XUnmapEvent
+.sp 6p
+SubstructureRedirectMask	CirculateRequest	XCirculateRequestEvent
+	ConfigureRequest	XConfigureRequestEvent
+	MapRequest	XMapRequestEvent
+.sp 6p
+N.A.	ClientMessage	XClientMessageEvent
+.sp 6p
+N.A.	MappingNotify	XMappingEvent
+.sp 6p
+N.A.	SelectionClear	XSelectionClearEvent
+.sp 6p
+N.A.	SelectionNotify	XSelectionEvent
+.sp 6p
+N.A.	SelectionRequest	XSelectionRequestEvent
+.sp 6p
+VisibilityChangeMask	VisibilityNotify	XVisibilityEvent
+.sp 6p
+_
+.TE
+.ps 11
+.nr PS 11
+.LP
+The sections that follow describe the processing that occurs 
+when you select the different event masks.
+The sections are organized according to these processing categories:
+.IP \(bu 5
+Keyboard and pointer events
+.IP \(bu 5
+Window crossing events
+.IP \(bu 5
+Input focus events
+.IP \(bu 5
+Keymap state notification events
+.IP \(bu 5
+Exposure events
+.IP \(bu 5
+Window state notification events
+.IP \(bu 5
+Structure control events
+.IP \(bu 5
+Colormap state notification events
+.IP \(bu 5
+Client communication events
+.NH 2
+Keyboard and Pointer Events
+.XS
+\*(SN Keyboard and Pointer Events
+.XE
+.LP
+This section discusses:
+.IP \(bu 5
+Pointer button events
+.IP \(bu 5
+Keyboard and pointer events
+.NH 3
+Pointer Button Events
+.XS
+\*(SN Pointer Button Events
+.XE
+.LP
+The following describes the event processing that occurs when a pointer button 
+press is processed with the pointer in some window w and 
+when no active pointer grab is in progress.
+.LP
+The X server searches the ancestors of w from the root down,
+looking for a passive grab to activate.
+If no matching passive grab on the button exists,
+the X server automatically starts an active grab for the client receiving
+the event and sets the last-pointer-grab time to the current server time.
+The effect is essentially equivalent to an
+.PN XGrabButton
+with these client passed arguments:
+.TS H
+lw(1.5i) lw(3.5i).
+_
+.sp 6p
+.B
+Argument	Value
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+T{
+\fIw\fP
+T}	T{
+The event window 
+T}
+T{
+\fIevent_mask\fP
+T}	T{
+The client's selected pointer events on the event window
+T}
+T{
+\fIpointer_mode\fP
+T}	T{
+.PN GrabModeAsync
+T}
+T{
+\fIkeyboard_mode\fP
+T}	T{
+.PN GrabModeAsync 
+T}
+T{
+\fIowner_events\fP
+T}	T{
+.PN True ,
+if the client has selected
+.PN OwnerGrabButtonMask
+on the event window,
+otherwise
+.PN False 
+T}
+T{
+\fIconfine_to\fP
+T}	T{
+.PN None 
+T}
+T{
+\fIcursor\fP
+T}	T{
+.PN None 
+T}
+.sp 6p
+_
+.TE
+.LP
+The active grab is automatically terminated when 
+the logical state of the pointer has all buttons released.
+Clients can modify the active grab by calling
+.PN XUngrabPointer
+and
+.PN XChangeActivePointerGrab .
+.NH 3
+Keyboard and Pointer Events
+.XS
+\*(SN Keyboard and Pointer Events
+.XE
+.LP
+.IN "Events" "ButtonPress"
+.IN "Events" "ButtonRelease"
+.IN "Events" "KeyPress"
+.IN "Events" "KeyRelease"
+.IN "Events" "MotionNotify"
+This section discusses the processing that occurs for the
+keyboard events
+.PN KeyPress
+and 
+.PN KeyRelease 
+and the pointer events
+.PN ButtonPress ,
+.PN ButtonRelease ,
+and
+.PN MotionNotify .
+For information about the keyboard event-handling utilities,
+see chapter 11.
+.LP
+.IN "KeyPress" "" "@DEF@"
+.IN "KeyRelease" "" "@DEF@"
+The X server reports
+.PN KeyPress
+or
+.PN KeyRelease
+events to clients wanting information about keys that logically change state.
+Note that these events are generated for all keys, 
+even those mapped to modifier bits.
+.IN "ButtonPress" "" "@DEF@"
+.IN "ButtonRelease" "" "@DEF@"
+The X server reports
+.PN ButtonPress
+or
+.PN ButtonRelease
+events to clients wanting information about buttons that logically change state.
+.LP
+.IN "MotionNotify" "" "@DEF@"
+The X server reports
+.PN MotionNotify
+events to clients wanting information about when the pointer logically moves.
+The X server generates this event whenever the pointer is moved 
+and the pointer motion begins and ends in the window.
+The granularity of
+.PN MotionNotify
+events is not guaranteed, 
+but a client that selects this event type is guaranteed
+to receive at least one event when the pointer moves and then rests.
+.LP
+The generation of the logical changes lags the physical changes 
+if device event processing is frozen.
+.LP
+To receive
+.PN KeyPress ,
+.PN KeyRelease ,
+.PN ButtonPress ,
+and
+.PN ButtonRelease 
+events, set 
+.PN KeyPressMask ,
+.PN KeyReleaseMask ,
+.PN ButtonPressMask ,
+and
+.PN ButtonReleaseMask 
+bits in the event-mask attribute of the window.
+.LP
+To receive 
+.PN MotionNotify
+events, set one or more of the following event 
+masks bits in the event-mask attribute of the window.
+.IP \(bu 5
+.PN Button1MotionMask \ \-
+.PN Button5MotionMask
+.IP
+The client application receives
+.PN MotionNotify
+events only when one or more of the specified buttons is pressed.
+.IP \(bu 5
+.PN ButtonMotionMask
+.IP
+The client application receives
+.PN MotionNotify
+events only when at least one button is pressed.
+.IP \(bu 5
+.PN PointerMotionMask
+.IP
+The client application receives 
+.PN MotionNotify
+events independent of the state of
+the pointer buttons.
+.IP \(bu 5
+.PN PointerMotionHintMask
+.IP
+If
+.PN PointerMotionHintMask
+is selected in combination with one or more of the above masks, 
+the X server is free to send only one
+.PN MotionNotify
+event (with the is_hint member  of the
+.PN XPointerMovedEvent
+structure set to
+.PN NotifyHint )
+to the client for the event window, 
+until either the key or button state changes,
+the pointer leaves the event window, or the client calls
+.PN XQueryPointer
+or
+.PN XGetMotionEvents .
+The server still may send
+.PN MotionNotify
+events without is_hint set to
+.PN NotifyHint .
+.LP
+The source of the event is the viewable window that the pointer is in.
+The window used by the X server to report these events depends on 
+the window's position in the window hierarchy 
+and whether any intervening window prohibits the generation of these events.
+Starting with the source window, 
+the X server searches up the window hierarchy until it locates the first 
+window specified by a client as having an interest in these events.
+If one of the intervening windows has its do-not-propagate-mask
+set to prohibit generation of the event type,
+the events of those types will be suppressed.
+Clients can modify the actual window used for reporting by performing
+active grabs and, in the case of keyboard events, by using the focus window.
+.LP
+The structures for these event types contain:
+.LP
+.IN "XButtonEvent" "" "@DEF@"
+.IN "XButtonPressedEvent" "" "@DEF@"
+.IN "XButtonReleasedEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* ButtonPress or ButtonRelease */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window window;	/* ``event'' window it is reported relative to */
+	Window root;	/* root window that the event occurred on */
+	Window subwindow;	/* child window */
+	Time time;	/* milliseconds */
+	int x, y;	/* pointer x, y coordinates in event window */
+	int x_root, y_root;	/* coordinates relative to root */
+	unsigned int state;	/* key or button mask */
+	unsigned int button;	/* detail */
+	Bool same_screen;	/* same screen flag */
+} XButtonEvent;
+typedef XButtonEvent XButtonPressedEvent;
+typedef XButtonEvent XButtonReleasedEvent;
+.De
+.LP
+.IN "XKeyEvent" "" "@DEF@"
+.IN "XKeyPressedEvent" "" "@DEF@"
+.IN "XKeyReleasedEvent" "" "@DEF@"
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* KeyPress or KeyRelease */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window window;	/* ``event'' window it is reported relative to */
+	Window root;	/* root window that the event occurred on */
+	Window subwindow;	/* child window */
+	Time time;	/* milliseconds */
+	int x, y;	/* pointer x, y coordinates in event window */
+	int x_root, y_root;	/* coordinates relative to root */
+	unsigned int state;	/* key or button mask */
+	unsigned int keycode;	/* detail */
+	Bool same_screen;	/* same screen flag */
+} XKeyEvent;
+typedef XKeyEvent XKeyPressedEvent;
+typedef XKeyEvent XKeyReleasedEvent;
+.De
+.LP
+.IN "XMotionEvent" "" "@DEF@"
+.IN "XPointerMovedEvent" "" "@DEF@"
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* MotionNotify */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window window;	/* ``event'' window reported relative to */
+	Window root;	/* root window that the event occurred on */
+	Window subwindow;	/* child window */
+	Time time;	/* milliseconds */
+	int x, y;	/* pointer x, y coordinates in event window */
+	int x_root, y_root;	/* coordinates relative to root */
+	unsigned int state;	/* key or button mask */
+	char is_hint;	/* detail */
+	Bool same_screen;	/* same screen flag */
+} XMotionEvent;
+typedef XMotionEvent XPointerMovedEvent;
+.De
+.LP
+.eM
+These structures have the following common members:
+window, root, subwindow, time, x, y, x_root, y_root, state, and same_screen.
+The window member is set to the window on which the
+event was generated and is referred to as the event window. 
+As long as the conditions previously discussed are met,
+this is the window used by the X server to report the event.
+The root member is set to the source window's root window.
+The x_root and y_root members are set to the pointer's coordinates
+relative to the root window's origin at the time of the event.
+.LP
+The same_screen member is set to indicate whether the event 
+window is on the same screen
+as the root window and can be either
+.PN True 
+or
+.PN False .
+If
+.PN True ,
+the event and root windows are on the same screen.
+If
+.PN False ,
+the event and root windows are not on the same screen.
+.LP
+If the source window is an inferior of the event window, 
+the subwindow member of the structure is set to the child of the event window
+that is the source window or the child of the event window that is
+an ancestor of the source window.
+Otherwise, the X server sets the subwindow member to
+.PN None .
+The time member is set to the time when the event was generated 
+and is expressed in milliseconds.
+.LP
+If the event window is on the same screen as the root window, 
+the x and y members
+are set to the coordinates relative to the event window's origin.
+Otherwise, these members are set to zero.
+.LP
+The state member is set to indicate the logical state of the pointer buttons 
+and modifier keys just prior to the event,
+which is the bitwise inclusive OR of one or more of the
+button or modifier key masks:
+.PN Button1Mask ,
+.PN Button2Mask ,
+.PN Button3Mask ,
+.PN Button4Mask ,
+.PN Button5Mask ,
+.PN ShiftMask ,
+.PN LockMask ,
+.PN ControlMask ,
+.PN Mod1Mask ,
+.PN Mod2Mask ,
+.PN Mod3Mask ,
+.PN Mod4Mask ,
+and
+.PN Mod5Mask .
+.LP
+Each of these structures also has a member that indicates the detail.
+For the
+.PN XKeyPressedEvent
+and
+.PN XKeyReleasedEvent
+structures, this member is called a keycode.
+It is set to a number that represents a physical key on the keyboard.
+The keycode is an arbitrary representation for any key on the keyboard
+(see sections 12.7 and 16.1).
+.LP
+For the
+.PN XButtonPressedEvent
+and
+.PN XButtonReleasedEvent
+structures, this member is called button.
+It represents the pointer button that changed state and can be the
+.PN Button1 ,
+.PN Button2 ,
+.PN Button3 ,
+.PN Button4 ,
+or
+.PN Button5 
+value.
+For the
+.PN XPointerMovedEvent
+structure, this member is called is_hint.
+It can be set to 
+.PN NotifyNormal
+or
+.PN NotifyHint .
+.LP
+Some of the symbols mentioned in this section have fixed values, as
+follows:
+.TS H
+lw(2i) lw(3.5i).
+_
+.sp 6p
+.B
+Symbol	Value
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+T{
+.PN Button1MotionMask
+T}	T{
+(1L<<8)
+T}
+T{
+.PN Button2MotionMask
+T}	T{
+(1L<<9)
+T}
+T{
+.PN Button3MotionMask
+T}	T{
+(1L<<10)
+T}
+T{
+.PN Button4MotionMask
+T}	T{
+(1L<<11)
+T}
+T{
+.PN Button5MotionMask
+T}	T{
+(1L<<12)
+T}
+T{
+.PN Button1Mask
+T}	T{
+(1<<8)
+T}
+T{
+.PN Button2Mask
+T}	T{
+(1<<9)
+T}
+T{
+.PN Button3Mask
+T}	T{
+(1<<10)
+T}
+T{
+.PN Button4Mask
+T}	T{
+(1<<11)
+T}
+T{
+.PN Button5Mask
+T}	T{
+(1<<12)
+T}
+T{
+.PN ShiftMask
+T}	T{
+(1<<0)
+T}
+T{
+.PN LockMask
+T}	T{
+(1<<1)
+T}
+T{
+.PN ControlMask
+T}	T{
+(1<<2)
+T}
+T{
+.PN Mod1Mask
+T}	T{
+(1<<3)
+T}
+T{
+.PN Mod2Mask
+T}	T{
+(1<<4)
+T}
+T{
+.PN Mod3Mask
+T}	T{
+(1<<5)
+T}
+T{
+.PN Mod4Mask
+T}	T{
+(1<<6)
+T}
+T{
+.PN Mod5Mask
+T}	T{
+(1<<7)
+T}
+T{
+.PN Button1
+T}	T{
+1
+T}
+T{
+.PN Button2
+T}	T{
+2
+T}
+T{
+.PN Button3
+T}	T{
+3
+T}
+T{
+.PN Button4
+T}	T{
+4
+T}
+T{
+.PN Button5
+T}	T{
+5
+T}
+.sp 6p
+_
+.TE
+.NH 2
+Window Entry/Exit Events
+.XS
+\*(SN Window Entry/Exit Events
+.XE
+.LP
+.IN "Events" "EnterNotify"
+.IN "Events" "LeaveNotify"
+This section describes the processing that 
+occurs for the window crossing events
+.PN EnterNotify
+and
+.PN LeaveNotify .
+.IN "EnterNotify" "" "@DEF@"
+.IN "LeaveNotify" "" "@DEF@"
+If a pointer motion or a window hierarchy change causes the
+pointer to be in a different window than before, the X server reports
+.PN EnterNotify
+or
+.PN LeaveNotify
+events to clients who have selected for these events.
+All 
+.PN EnterNotify
+and 
+.PN LeaveNotify
+events caused by a hierarchy change are
+generated after any hierarchy event
+.Pn ( UnmapNotify ,
+.PN MapNotify ,
+.PN ConfigureNotify ,
+.PN GravityNotify ,
+.PN CirculateNotify )
+caused by that change;
+however, the X protocol does not constrain the ordering of 
+.PN EnterNotify 
+and 
+.PN LeaveNotify 
+events with respect to
+.PN FocusOut , 
+.PN VisibilityNotify ,
+and 
+.PN Expose 
+events.
+.LP
+This contrasts with
+.PN MotionNotify
+events, which are also generated when the pointer moves
+but only when the pointer motion begins and ends in a single window.
+An
+.PN EnterNotify
+or
+.PN LeaveNotify
+event also can be generated when some client application calls
+.PN XGrabPointer
+and
+.PN XUngrabPointer .
+.LP
+To receive
+.PN EnterNotify
+or
+.PN LeaveNotify
+events, set the
+.PN EnterWindowMask
+or
+.PN LeaveWindowMask
+bits of the event-mask attribute of the window.
+.LP
+The structure for these event types contains:
+.LP
+.IN "XCrossingEvent" "" "@DEF@"
+.IN "XEnterWindowEvent" "" "@DEF@"
+.IN "XLeaveWindowEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* EnterNotify or LeaveNotify */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window window;	/* ``event'' window reported relative to */
+	Window root;	/* root window that the event occurred on */
+	Window subwindow;	/* child window */
+	Time time;	/* milliseconds */
+	int x, y;	/* pointer x, y coordinates in event window */
+	int x_root, y_root;	/* coordinates relative to root */
+	int mode;	/* NotifyNormal, NotifyGrab, NotifyUngrab */
+	int detail;
+		/*
+	 	* NotifyAncestor, NotifyVirtual, NotifyInferior, 
+	 	* NotifyNonlinear,NotifyNonlinearVirtual
+	 	*/
+	Bool same_screen;	/* same screen flag */
+	Bool focus;	/* boolean focus */
+	unsigned int state;	/* key or button mask */
+} XCrossingEvent;
+typedef XCrossingEvent XEnterWindowEvent;
+typedef XCrossingEvent XLeaveWindowEvent;
+.De
+.LP
+.eM
+The window member is set to the window on which the
+.PN EnterNotify
+or
+.PN LeaveNotify
+event was generated and is referred to as the event window. 
+This is the window used by the X server to report the event, 
+and is relative to the root
+window on which the event occurred. 
+The root member is set to the root window of the screen
+on which the event occurred.
+.LP
+For a
+.PN LeaveNotify 
+event,
+if a child of the event window contains the initial position of the pointer,
+the subwindow component is set to that child.
+Otherwise, the X server sets the subwindow member to
+.PN None .
+For an
+.PN EnterNotify 
+event, if a child of the event window contains the final pointer position, 
+the subwindow component is set to that child or
+.PN None .
+.LP
+The time member is set to the time when the event was generated
+and is expressed in milliseconds.
+The x and y members are set to the coordinates of the pointer position in 
+the event window.
+This position is always the pointer's final position,
+not its initial position.
+If the event window is on the same
+screen as the root window, x and y are the pointer coordinates
+relative to the event window's origin. 
+Otherwise, x and y are set to zero.
+The x_root and y_root members are set to the pointer's coordinates relative to the
+root window's origin at the time of the event.
+.LP
+The same_screen member is set to indicate whether the event window is on the same screen
+as the root window and can be either
+.PN True 
+or
+.PN False .
+If
+.PN True ,
+the event and root windows are on the same screen.
+If
+.PN False ,
+the event and root windows are not on the same screen.
+.LP
+The focus member is set to indicate whether the event window is the focus window or an
+inferior of the focus window.
+The X server can set this member to either
+.PN True 
+or
+.PN False .
+If
+.PN True ,
+the event window is the focus window or an inferior of the focus window.
+If
+.PN False ,
+the event window is not the focus window or an inferior of the focus window.
+.LP
+The state member is set to indicate the state of the pointer buttons and
+modifier keys just prior to the
+event.
+The X server can set this member to the bitwise inclusive OR of one 
+or more of the button or modifier key masks:
+.PN Button1Mask ,
+.PN Button2Mask ,
+.PN Button3Mask ,
+.PN Button4Mask ,
+.PN Button5Mask ,
+.PN ShiftMask ,
+.PN LockMask ,
+.PN ControlMask ,
+.PN Mod1Mask ,
+.PN Mod2Mask ,
+.PN Mod3Mask ,
+.PN Mod4Mask ,
+.PN Mod5Mask .
+.LP
+The mode member is set to indicate whether the events are normal events, 
+pseudo-motion events
+when a grab activates, or pseudo-motion events when a grab deactivates.
+The X server can set this member to 
+.PN NotifyNormal ,
+.PN NotifyGrab ,
+or
+.PN NotifyUngrab .
+.LP
+The detail member is set to indicate the notify detail and can be
+.PN NotifyAncestor ,
+.PN NotifyVirtual ,
+.PN NotifyInferior ,
+.PN NotifyNonlinear ,
+or
+.PN NotifyNonlinearVirtual .
+.NH 3 
+Normal Entry/Exit Events
+.XS
+\*(SN Normal Entry/Exit Events
+.XE
+.LP
+.PN EnterNotify
+and
+.PN LeaveNotify
+events are generated when the pointer moves from
+one window to another window.
+Normal events are identified by
+.PN XEnterWindowEvent
+or
+.PN XLeaveWindowEvent
+structures whose mode member is set to
+.PN NotifyNormal .
+.IP \(bu 5
+When the pointer moves from window A to window B and A is an inferior of B, 
+the X server does the following:
+.RS
+.IP \- 5
+It generates a
+.PN LeaveNotify
+event on window A, with the detail member of the
+.PN XLeaveWindowEvent
+structure set to
+.PN NotifyAncestor .
+.IP \- 5
+It generates a
+.PN LeaveNotify
+event on each window between window A and window B, exclusive,
+with the detail member of each
+.PN XLeaveWindowEvent
+structure set to
+.PN NotifyVirtual .
+.IP \- 5
+It generates an
+.PN EnterNotify
+event on window B, with the detail member of the 
+.PN XEnterWindowEvent
+structure set to
+.PN NotifyInferior .
+.RE
+.IP \(bu 5
+When the pointer moves from window A to window B and B is an inferior of A,
+the X server does the following:
+.RS
+.IP \- 5
+It generates a
+.PN LeaveNotify
+event on window A,
+with the detail member of the
+.PN XLeaveWindowEvent
+structure set to
+.PN NotifyInferior .
+.IP \- 5
+It generates an
+.PN EnterNotify
+event on each window between window A and window B, exclusive, with the 
+detail member of each 
+.PN XEnterWindowEvent
+structure set to
+.PN NotifyVirtual . 
+.IP \- 5
+It generates an
+.PN EnterNotify
+event on window B, with the detail member of the 
+.PN XEnterWindowEvent
+structure set to
+.PN NotifyAncestor .
+.RE
+.IP \(bu 5
+When the pointer moves from window A to window B 
+and window C is their least common ancestor, 
+the X server does the following:
+.RS
+.IP \- 5
+It generates a
+.PN LeaveNotify
+event on window A,
+with the detail member of the
+.PN XLeaveWindowEvent
+structure set to 
+.PN NotifyNonlinear .
+.IP \- 5
+It generates a
+.PN LeaveNotify
+event on each window between window A and window C, exclusive,
+with the detail member of each
+.PN XLeaveWindowEvent
+structure set to
+.PN NotifyNonlinearVirtual .
+.IP \- 5
+It generates an
+.PN EnterNotify
+event on each window between window C and window B, exclusive, 
+with the detail member of each
+.PN XEnterWindowEvent
+structure set to
+.PN NotifyNonlinearVirtual .
+.IP \- 5
+It generates an
+.PN EnterNotify
+event on window B, with the detail member of the 
+.PN XEnterWindowEvent
+structure set to 
+.PN NotifyNonlinear .
+.RE
+.IP \(bu 5
+When the pointer moves from window A to window B on different screens, 
+the X server does the following:
+.RS
+.IP \- 5
+It generates a
+.PN LeaveNotify
+event on window A,
+with the detail member of the
+.PN XLeaveWindowEvent
+structure set to 
+.PN NotifyNonlinear .
+.IP \- 5
+If window A is not a root window,
+it generates a
+.PN LeaveNotify
+event on each window above window A up to and including its root,
+with the detail member of each
+.PN XLeaveWindowEvent
+structure set to 
+.PN NotifyNonlinearVirtual .
+.IP \- 5
+If window B is not a root window,
+it generates an
+.PN EnterNotify
+event on each window from window B's root down to but not including
+window B, with the detail member of each
+.PN XEnterWindowEvent
+structure set to 
+.PN NotifyNonlinearVirtual .
+.IP \- 5
+It generates an
+.PN EnterNotify
+event on window B, with the detail member of the
+.PN XEnterWindowEvent
+structure set to 
+.PN NotifyNonlinear .
+.RE
+.\".SH 3
+.NH 3 
+Grab and Ungrab Entry/Exit Events
+.XS
+\*(SN Grab and Ungrab Entry/Exit Events
+.XE
+.LP
+Pseudo-motion mode
+.PN EnterNotify
+and
+.PN LeaveNotify
+events are generated when a pointer grab activates or deactivates.
+Events in which the pointer grab activates
+are identified by
+.PN XEnterWindowEvent
+or
+.PN XLeaveWindowEvent
+structures whose mode member is set to 
+.PN NotifyGrab .
+Events in which the pointer grab deactivates
+are identified by
+.PN XEnterWindowEvent
+or
+.PN XLeaveWindowEvent
+structures whose mode member is set to 
+.PN NotifyUngrab
+(see
+.PN XGrabPointer ).
+.IP \(bu 5
+When a pointer grab activates after any initial warp into a confine_to
+window and before generating any actual
+.PN ButtonPress
+event that activates the grab, 
+G is the grab_window for the grab, 
+and P is the window the pointer is in, 
+the X server does the following:
+.RS
+.IP \- 5
+It generates
+.PN EnterNotify
+and
+.PN LeaveNotify
+events (see section 10.6.1)
+with the mode members of the 
+.PN XEnterWindowEvent
+and
+.PN XLeaveWindowEvent
+structures set to 
+.PN NotifyGrab .
+These events are generated
+as if the pointer were to suddenly warp from
+its current position in P to some position in G.
+However, the pointer does not warp, and the X server uses the pointer position 
+as both the initial and final positions for the events.
+.RE
+.IP \(bu 5
+When a pointer grab deactivates after generating any actual
+.PN ButtonRelease
+event that deactivates the grab, 
+G is the grab_window for the grab,
+and P is the window the pointer is in, 
+the X server does the following:
+.RS
+.IP \- 5
+It generates
+.PN EnterNotify
+and
+.PN LeaveNotify
+events (see section 10.6.1)
+with the mode members of the
+.PN XEnterWindowEvent
+and
+.PN XLeaveWindowEvent
+structures set to 
+.PN NotifyUngrab .
+These events are generated as if the pointer were to suddenly warp from
+some position in G to its current position in P.
+However, the pointer does not warp, and the X server uses the
+current pointer position as both the
+initial and final positions for the events.
+.RE
+.NH 2
+Input Focus Events
+.XS
+\*(SN Input Focus Events 
+.XE
+.LP
+.IN "Events" "FocusIn"
+.IN "Events" "FocusOut"
+This section describes the processing that occurs for the input focus events
+.PN FocusIn
+and
+.PN FocusOut .
+.IN "FocusIn" "" "@DEF@"
+.IN "FocusOut" "" "@DEF@"
+The X server can report
+.PN FocusIn
+or
+.PN FocusOut
+events to clients wanting information about when the input focus changes.
+The keyboard is always attached to some window 
+(typically, the root window or a top-level window), 
+which is called the focus window.
+The focus window and the position of the pointer determine the window that
+receives keyboard input.
+Clients may need to know when the input focus changes
+to control highlighting of areas on the screen.
+.LP
+To receive
+.PN FocusIn
+or
+.PN FocusOut
+events, set the
+.PN FocusChangeMask
+bit in the event-mask attribute of the window. 
+.LP
+The structure for these event types contains:
+.LP
+.IN "XFocusChangeEvent" "" "@DEF@"
+.IN "XFocusInEvent" "" "@DEF@"
+.IN "XFocusOutEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* FocusIn or FocusOut */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window window;	/* window of event */
+	int mode;	/* NotifyNormal, NotifyGrab, NotifyUngrab */
+	int detail;
+		/*
+	 	* NotifyAncestor, NotifyVirtual, NotifyInferior, 
+	 	* NotifyNonlinear,NotifyNonlinearVirtual, NotifyPointer,
+	 	* NotifyPointerRoot, NotifyDetailNone 
+	 	*/
+} XFocusChangeEvent;
+typedef XFocusChangeEvent XFocusInEvent;
+typedef XFocusChangeEvent XFocusOutEvent;
+.De
+.LP
+.eM
+The window member is set to the window on which the
+.PN FocusIn
+or
+.PN FocusOut
+event was generated.
+This is the window used by the X server to report the event. 
+The mode member is set to indicate whether the focus events 
+are normal focus events, 
+focus events while grabbed,
+focus events
+when a grab activates, or focus events when a grab deactivates.
+The X server can set the mode member to 
+.PN NotifyNormal ,
+.PN NotifyWhileGrabbed ,
+.PN NotifyGrab ,
+or
+.PN NotifyUngrab .
+.LP
+All 
+.PN FocusOut
+events caused by a window unmap are generated after any
+.PN UnmapNotify
+event; however, the X protocol does not constrain the ordering of 
+.PN FocusOut
+events with respect to
+generated 
+.PN EnterNotify ,
+.PN LeaveNotify ,
+.PN VisibilityNotify ,
+and
+.PN Expose
+events.
+.LP
+Depending on the event mode,
+the detail member is set to indicate the notify detail and can be
+.PN NotifyAncestor ,
+.PN NotifyVirtual ,
+.PN NotifyInferior ,
+.PN NotifyNonlinear ,
+.PN NotifyNonlinearVirtual ,
+.PN NotifyPointer ,
+.PN NotifyPointerRoot ,
+or
+.PN NotifyDetailNone .
+.NH 3 
+Normal Focus Events and Focus Events While Grabbed 
+.XS
+\*(SN Normal Focus Events and Focus Events While Grabbed 
+.XE
+.LP
+Normal focus events are identified by
+.PN XFocusInEvent
+or
+.PN XFocusOutEvent
+structures whose mode member is set to 
+.PN NotifyNormal .
+Focus events while grabbed are identified by
+.PN XFocusInEvent
+or
+.PN XFocusOutEvent
+structures whose mode member is set to 
+.PN NotifyWhileGrabbed .
+The X server processes normal focus and focus events while grabbed according to 
+the following:
+.IP \(bu 5
+When the focus moves from window A to window B, A is an inferior of B, 
+and the pointer is in window P, 
+the X server does the following:
+.RS
+.IP \- 5
+It generates a
+.PN FocusOut
+event on window A, with the detail member of the
+.PN XFocusOutEvent
+structure set to 
+.PN NotifyAncestor . 
+.IP \- 5
+It generates a
+.PN FocusOut
+event on each window between window A and window B, exclusive,
+with the detail member of each
+.PN XFocusOutEvent
+structure set to 
+.PN NotifyVirtual .
+.IP \- 5
+It generates a
+.PN FocusIn
+event on window B, with the detail member of the 
+.PN XFocusOutEvent
+structure set to 
+.PN NotifyInferior .
+.IP \- 5
+If window P is an inferior of window B
+but window P is not window A or an inferior or ancestor of window A,
+it generates a
+.PN FocusIn
+event on each window below window B, down to and including window P, 
+with the detail member of each 
+.PN XFocusInEvent
+structure set to 
+.PN NotifyPointer .
+.RE
+.IP \(bu 5
+When the focus moves from window A to window B, B is an inferior of A, 
+and the pointer is in window P, 
+the X server does the following:
+.RS
+.IP \- 5
+If window P is an inferior of window A
+but P is not an inferior of window B or an ancestor of B,
+it generates a
+.PN FocusOut
+event on each window from window P up to but not including window A,
+with the detail member of each 
+.PN XFocusOutEvent
+structure set to  
+.PN NotifyPointer .
+.IP \- 5
+It generates a
+.PN FocusOut
+event on window A,
+with the detail member of the
+.PN XFocusOutEvent
+structure set to  
+.PN NotifyInferior . 
+.IP \- 5
+It generates a
+.PN FocusIn
+event on each window between window A and window B, exclusive, with the 
+detail member of each 
+.PN XFocusInEvent
+structure set to  
+.PN NotifyVirtual . 
+.IP \- 5
+It generates a
+.PN FocusIn
+event on window B, with the detail member of the 
+.PN XFocusInEvent
+structure set to  
+.PN NotifyAncestor .
+.RE
+.IP \(bu 5
+When the focus moves from window A to window B, 
+window C is their least common ancestor, 
+and the pointer is in window P, 
+the X server does the following:
+.RS
+.IP \- 5
+If window P is an inferior of window A,
+it generates a
+.PN FocusOut
+event on each window from window P up to but not including window A, 
+with the detail member of the 
+.PN XFocusOutEvent
+structure set to  
+.PN NotifyPointer .
+.IP \- 5
+It generates a
+.PN FocusOut
+event on window A,
+with the detail member of the
+.PN XFocusOutEvent
+structure set to  
+.PN NotifyNonlinear .
+.IP \- 5
+It generates a
+.PN FocusOut
+event on each window between window A and window C, exclusive,
+with the detail member of each
+.PN XFocusOutEvent
+structure set to  
+.PN NotifyNonlinearVirtual .
+.IP \- 5
+It generates a
+.PN FocusIn
+event on each window between C and B, exclusive,
+with the detail member of each
+.PN XFocusInEvent
+structure set to  
+.PN NotifyNonlinearVirtual .
+.IP \- 5
+It generates a
+.PN FocusIn
+event on window B, with the detail member of the 
+.PN XFocusInEvent
+structure set to  
+.PN NotifyNonlinear .
+.IP \- 5
+If window P is an inferior of window B, it generates a
+.PN FocusIn
+event on each window below window B down to and including window P, 
+with the detail member of the 
+.PN XFocusInEvent
+structure set to  
+.PN NotifyPointer .
+.RE
+.IP \(bu 5
+When the focus moves from window A to window B on different screens 
+and the pointer is in window P, 
+the X server does the following:
+.RS
+.IP \- 5
+If window P is an inferior of window A, it generates a
+.PN FocusOut
+event on each window from window P up to but not including window A, 
+with the detail member of each 
+.PN XFocusOutEvent
+structure set to  
+.PN NotifyPointer .
+.IP \- 5
+It generates a
+.PN FocusOut
+event on window A,
+with the detail member of the
+.PN XFocusOutEvent
+structure set to  
+.PN NotifyNonlinear .
+.IP \- 5
+If window A is not a root window,
+it generates a
+.PN FocusOut
+event on each window above window A up to and including its root, 
+with the detail member of each
+.PN XFocusOutEvent
+structure set to  
+.PN NotifyNonlinearVirtual .
+.IP \- 5
+If window B is not a root window,
+it generates a
+.PN FocusIn
+event on each window from window B's root down to but not including
+window B, with the detail member of each
+.PN XFocusInEvent
+structure set to  
+.PN NotifyNonlinearVirtual .
+.IP \- 5
+It generates a
+.PN FocusIn
+event on window B, with the detail member of each 
+.PN XFocusInEvent
+structure set to  
+.PN NotifyNonlinear .
+.IP \- 5
+If window P is an inferior of window B, it generates a
+.PN FocusIn
+event on each window below window B down to and including window P, 
+with the detail member of each 
+.PN XFocusInEvent
+structure set to  
+.PN NotifyPointer .
+.RE
+.IP \(bu 5
+When the focus moves from window A to 
+.PN PointerRoot
+(events sent to the window under the pointer)
+or
+.PN None 
+(discard), and the pointer is in window P,
+the X server does the following:
+.RS
+.IP \- 5
+If window P is an inferior of window A, it generates a
+.PN FocusOut
+event on each window from window P up to but not including window A, 
+with the detail member of each 
+.PN XFocusOutEvent
+structure set to  
+.PN NotifyPointer .
+.IP \- 5
+It generates a
+.PN FocusOut
+event on window A, with the detail member of the
+.PN XFocusOutEvent
+structure set to
+.PN NotifyNonlinear .
+.IP \- 5
+If window A is not a root window,
+it generates a
+.PN FocusOut
+event on each window above window A up to and including its root, 
+with the detail member of each
+.PN XFocusOutEvent
+structure set to
+.PN NotifyNonlinearVirtual .
+.IP \- 5
+It generates a
+.PN FocusIn
+event on the root window of all screens, with the detail member of each
+.PN XFocusInEvent
+structure set to
+.PN NotifyPointerRoot
+(or
+.PN NotifyDetailNone ).
+.IP \- 5
+If the new focus is
+.PN PointerRoot ,
+it generates a
+.PN FocusIn
+event on each window from window P's root down to and including window P, 
+with the detail member of each
+.PN XFocusInEvent
+structure set to
+.PN NotifyPointer .
+.RE
+.IP \(bu 5
+When the focus moves from 
+.PN PointerRoot
+(events sent to the window under the pointer)
+or
+.PN None 
+to window A, and the pointer is in window P, 
+the X server does the following: 
+.RS
+.IP \- 5
+If the old focus is
+.PN PointerRoot ,
+it generates a
+.PN FocusOut
+event on each window from window P up to and including window P's root, 
+with the detail member of each
+.PN XFocusOutEvent
+structure set to
+.PN NotifyPointer .
+.IP \- 5
+It generates a
+.PN FocusOut
+event on all root windows,
+with the detail member of each
+.PN XFocusOutEvent
+structure set to
+.PN NotifyPointerRoot
+(or
+.PN NotifyDetailNone ).
+.IP \- 5
+If window A is not a root window,
+it generates a
+.PN FocusIn
+event on each window from window A's root down to but not including window A,
+with the detail member of each
+.PN XFocusInEvent
+structure set to
+.PN NotifyNonlinearVirtual .
+.IP \- 5
+It generates a
+.PN FocusIn
+event on window A,
+with the detail member of the 
+.PN XFocusInEvent
+structure set to  
+.PN NotifyNonlinear .
+.IP \- 5
+If window P is an inferior of window A, it generates a
+.PN FocusIn
+event on each window below window A down to and including window P, 
+with the detail member of each 
+.PN XFocusInEvent
+structure set to  
+.PN NotifyPointer .
+.RE
+.IP \(bu 5
+When the focus moves from 
+.PN PointerRoot
+(events sent to the window under the pointer)
+to
+.PN None
+(or vice versa), and the pointer is in window P, 
+the X server does the following:
+.RS
+.IP \- 5
+If the old focus is
+.PN PointerRoot ,
+it generates a
+.PN FocusOut
+event on each window from window P up to and including window P's root, 
+with the detail member of each
+.PN XFocusOutEvent
+structure set to
+.PN NotifyPointer .
+.IP \- 5
+It generates a
+.PN FocusOut
+event on all root windows,
+with the detail member of each 
+.PN XFocusOutEvent
+structure set to either
+.PN NotifyPointerRoot
+or
+.PN NotifyDetailNone . 
+.IP \- 5
+It generates a
+.PN FocusIn
+event on all root windows,
+with the detail member of each
+.PN XFocusInEvent
+structure set to
+.PN NotifyDetailNone 
+or
+.PN NotifyPointerRoot .
+.IP \- 5
+If the new focus is
+.PN PointerRoot ,
+it generates a
+.PN FocusIn
+event on each window from window P's root down to and including window P, 
+with the detail member of each
+.PN XFocusInEvent
+structure set to
+.PN NotifyPointer .
+.RE
+.\".SH 3
+.NH 3 
+Focus Events Generated by Grabs
+.XS
+\*(SN Focus Events Generated by Grabs 
+.XE
+.LP
+Focus events in which the keyboard grab activates
+are identified by
+.PN XFocusInEvent
+or
+.PN XFocusOutEvent
+structures whose mode member is set to 
+.PN NotifyGrab .
+Focus events in which the keyboard grab deactivates
+are identified by
+.PN XFocusInEvent
+or
+.PN XFocusOutEvent
+structures whose mode member is set to 
+.PN NotifyUngrab 
+(see 
+.PN XGrabKeyboard ).
+.IP \(bu 5
+When a keyboard grab activates before generating any actual 
+.PN KeyPress
+event that activates the grab,
+G is the grab_window, and F is the current focus, 
+the X server does the following:
+.RS
+.IP \- 5
+It generates 
+.PN FocusIn
+and
+.PN FocusOut
+events, with the mode members of the 
+.PN XFocusInEvent
+and
+.PN XFocusOutEvent
+structures set to 
+.PN NotifyGrab .
+These events are generated
+as if the focus were to change from
+F to G.
+.RE
+.IP \(bu 5
+When a keyboard grab deactivates after generating any actual
+.PN KeyRelease
+event that deactivates the grab,
+G is the grab_window, and F is the current focus,
+the X server does the following:
+.RS
+.IP \- 5
+It generates 
+.PN FocusIn
+and
+.PN FocusOut
+events, with the mode members of the 
+.PN XFocusInEvent
+and
+.PN XFocusOutEvent
+structures set to
+.PN NotifyUngrab .
+These events are generated
+as if the focus were to change from
+G to F.
+.RE
+.NH 2
+Key Map State Notification Events
+.XS
+\*(SN Key Map State Notification Events
+.XE
+.LP
+.IN "Events" "KeymapNotify"
+.IN "KeymapNotify" "" "@DEF@"
+The X server can report
+.PN KeymapNotify
+events to clients that want information about changes in their keyboard state.
+.LP
+To receive
+.PN KeymapNotify
+events, set the
+.PN KeymapStateMask
+bit in the event-mask attribute of the window. 
+The X server generates this event immediately after every
+.PN EnterNotify
+and
+.PN FocusIn
+event.
+.LP
+The structure for this event type contains:
+.LP
+.IN "XKeymapEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+/* generated on EnterWindow and FocusIn when KeymapState selected */
+typedef struct {
+	int type;	/* KeymapNotify */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window window;
+	char key_vector[32];
+} XKeymapEvent;	
+.De
+.LP
+.eM
+The window member is not used but is present to aid some toolkits.
+The key_vector member is set to the bit vector of the keyboard.
+Each bit set to 1 indicates that the corresponding key 
+is currently pressed.
+The vector is represented as 32 bytes.
+Byte N (from 0) contains the bits for keys 8N to 8N + 7 
+with the least significant bit in the byte representing key 8N.
+.NH 2
+Exposure Events
+.XS
+\*(SN Exposure Events
+.XE
+.LP
+The X protocol does not guarantee to preserve the contents of window 
+regions when
+the windows are obscured or reconfigured.
+Some implementations may preserve the contents of windows.
+Other implementations are free to destroy the contents of windows
+when exposed.
+X expects client applications to assume the responsibility for
+restoring the contents of an exposed window region. 
+(An exposed window region describes a formerly obscured window whose 
+region becomes visible.) 
+Therefore, the X server sends 
+.PN Expose 
+events describing the window and the region of the window that has been exposed.
+A naive client application usually redraws the entire window. 
+A more sophisticated client application redraws only the exposed region.
+.NH 3
+Expose Events
+.XS
+\*(SN Expose Events
+.XE
+.LP
+.IN "Events" "Expose"
+.IN "Expose" "" "@DEF@"
+The X server can report
+.PN Expose
+events to clients wanting information about when the contents of window regions
+have been lost.
+The circumstances in which the X server generates
+.PN Expose
+events are not as definite as those for other events.
+However, the X server never generates
+.PN Expose
+events on windows whose class you specified as
+.PN InputOnly .
+The X server can generate
+.PN Expose
+events when no valid contents are available for regions of a window
+and either the regions are visible, 
+the regions are viewable and the server is (perhaps newly) maintaining 
+backing store on the window,
+or the window is not viewable but the server is (perhaps newly) honoring the
+window's backing-store attribute of
+.PN Always
+or
+.PN WhenMapped .
+The regions decompose into an (arbitrary) set of rectangles,
+and an
+.PN Expose
+event is generated for each rectangle.
+For any given window,
+the X server guarantees to report contiguously 
+all of the regions exposed by some action that causes 
+.PN Expose 
+events, such as raising a window.
+.LP
+To receive
+.PN Expose
+events, set the
+.PN ExposureMask
+bit in the event-mask attribute of the window. 
+.LP
+The structure for this event type contains:
+.LP
+.IN "XExposeEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* Expose */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window window;
+	int x, y;
+	int width, height;
+	int count;	/* if nonzero, at least this many more */
+} XExposeEvent;
+.De
+.LP
+.eM
+The window member is set to the exposed (damaged) window.
+The x and y members are set to the coordinates relative to the window's origin
+and indicate the upper-left corner of the rectangle.
+The width and height members are set to the size (extent) of the rectangle.
+The count member is set to the number of
+.PN Expose
+events that are to follow.
+If count is zero, no more
+.PN Expose
+events follow for this window.
+However, if count is nonzero, at least that number of 
+.PN Expose 
+events (and possibly more) follow for this window.
+Simple applications that do not want to optimize redisplay by distinguishing
+between subareas of its window can just ignore all
+.PN Expose
+events with nonzero counts and perform full redisplays
+on events with zero counts.
+.NH 3
+GraphicsExpose and NoExpose Events
+.XS
+\*(SN GraphicsExpose and NoExpose Events
+.XE
+.LP
+.IN "Events" "GraphicsExpose"
+.IN "Events" "NoExpose"
+.IN "GraphicsExpose" "" "@DEF@"
+The X server can report
+.PN GraphicsExpose
+events to clients wanting information about when a destination region could not
+be computed during certain graphics requests:
+.PN XCopyArea
+or
+.PN XCopyPlane .
+The X server generates this event whenever a destination region could not be
+computed because of an obscured or out-of-bounds source region.
+In addition, the X server guarantees to report contiguously all of the regions exposed by
+some graphics request 
+(for example, copying an area of a drawable to a destination
+drawable).
+.LP
+.IN "NoExpose" "" "@DEF@"
+The X server generates a
+.PN NoExpose
+event whenever a graphics request that might
+produce a
+.PN GraphicsExpose
+event does not produce any.
+In other words, the client is really asking for a
+.PN GraphicsExpose
+event but instead receives a
+.PN NoExpose
+event.
+.LP
+To receive
+.PN GraphicsExpose
+or
+.PN NoExpose
+events, you must first set the graphics-exposure 
+attribute of the graphics context to
+.PN True .
+You also can set the graphics-expose attribute when creating a graphics
+context using
+.PN XCreateGC 
+or by calling
+.PN XSetGraphicsExposures .
+.LP
+The structures for these event types contain:
+.LP
+.IN "XGraphicsExposeEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* GraphicsExpose */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Drawable drawable;
+	int x, y;
+	int width, height;
+	int count;	/* if nonzero, at least this many more */
+	int major_code;	/* core is CopyArea or CopyPlane */
+	int minor_code;	/* not defined in the core */
+} XGraphicsExposeEvent;
+.De
+.LP
+.IN "XNoExposeEvent" "" "@DEF@"
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* NoExpose */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Drawable drawable;
+	int major_code;	/* core is CopyArea or CopyPlane */
+	int minor_code;	/* not defined in the core */
+} XNoExposeEvent;
+.De
+.LP
+.eM
+Both structures have these common members: drawable, major_code, and minor_code.
+The drawable member is set to the drawable of the destination region on 
+which the graphics request was to be performed.
+The major_code member is set to the graphics request initiated by the client
+and can be either
+.PN X_CopyArea
+or
+.PN X_CopyPlane .
+If it is
+.PN X_CopyArea ,
+a call to
+.PN XCopyArea
+initiated the request.
+If it is
+.PN X_CopyPlane ,
+a call to
+.PN XCopyPlane
+initiated the request.
+These constants are defined in 
+.hN X11/Xproto.h .
+The minor_code member,
+like the major_code member, 
+indicates which graphics request was initiated by
+the client. 
+However, the minor_code member is not defined by the core
+X protocol and will be zero in these cases, 
+although it may be used by an extension.
+.LP
+The 
+.PN XGraphicsExposeEvent
+structure has these additional members: x, y, width, height, and count. 
+The x and y members are set to the coordinates relative to the drawable's origin
+and indicate the upper-left corner of the rectangle.
+The width and height members are set to the size (extent) of the rectangle.
+The count member is set to the number of
+.PN GraphicsExpose
+events to follow.
+If count is zero, no more
+.PN GraphicsExpose
+events follow for this window.
+However, if count is nonzero, at least that number of
+.PN GraphicsExpose
+events (and possibly more) are to follow for this window.
+.NH 2
+Window State Change Events 
+.XS
+\*(SN Window State Change Events
+.XE
+.LP
+The following sections discuss:
+.IP \(bu 5
+.PN CirculateNotify
+events
+.IP \(bu 5
+.PN ConfigureNotify
+events
+.IP \(bu 5
+.PN CreateNotify 
+events
+.IP \(bu 5
+.PN DestroyNotify
+events
+.IP \(bu 5
+.PN GravityNotify
+events
+.IP \(bu 5
+.PN MapNotify
+events
+.IP \(bu 5
+.PN MappingNotify
+events
+.IP \(bu 5
+.PN ReparentNotify 
+events
+.IP \(bu 5
+.PN UnmapNotify
+events
+.IP \(bu 5
+.PN VisibilityNotify
+events
+.\" .SH 3
+.NH 3
+CirculateNotify Events
+.XS
+\*(SN CirculateNotify Events
+.XE
+.LP
+.IN "Events" "CirculateNotify"
+.IN "CirculateNotify" "" "@DEF@"
+The X server can report
+.PN CirculateNotify
+events to clients wanting information about when a window changes 
+its position in the stack.
+The X server generates this event type whenever a window is actually restacked 
+as a result of a client application calling
+.PN XCirculateSubwindows ,
+.PN XCirculateSubwindowsUp ,
+or
+.PN XCirculateSubwindowsDown .
+.LP
+To receive 
+.PN CirculateNotify
+events, set the
+.PN StructureNotifyMask
+bit in the event-mask attribute of the window
+or the
+.PN SubstructureNotifyMask
+bit in the event-mask attribute of the parent window
+(in which case, circulating any child generates an event).
+.LP
+The structure for this event type contains:
+.LP
+.IN "XCirculateEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* CirculateNotify */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window event;
+	Window window;
+	int place;	/* PlaceOnTop, PlaceOnBottom */
+} XCirculateEvent;
+.De
+.LP
+.eM
+The event member is set either to the restacked window or to its parent,
+depending on whether
+.PN StructureNotify
+or
+.PN SubstructureNotify
+was selected.
+The window member is set to the window that was restacked.
+The place member is set to the window's position after the restack occurs and
+is either
+.PN PlaceOnTop
+or
+.PN PlaceOnBottom .
+If it is
+.PN PlaceOnTop ,
+the window is now on top of all siblings.
+If it is
+.PN PlaceOnBottom ,
+the window is now below all siblings.
+.NH 3
+ConfigureNotify Events
+.XS
+\*(SN ConfigureNotify Events
+.XE
+.LP
+.IN "Events" "ConfigureNotify"
+.IN "ConfigureNotify" "" "@DEF@"
+The X server can report
+.PN ConfigureNotify
+events to clients wanting information about actual changes to a window's
+state, such as size, position, border, and stacking order.
+The X server generates this event type whenever one of the following configure 
+window requests made by a client application actually completes:
+.IP \(bu 5
+A window's size, position, border, and/or stacking order is reconfigured 
+by calling
+.PN XConfigureWindow .
+.IP \(bu 5
+The window's position in the stacking order is changed by calling
+.PN XLowerWindow ,
+.PN XRaiseWindow ,
+or
+.PN XRestackWindows .
+.IP \(bu 5
+A window is moved by calling
+.PN XMoveWindow .
+.IP \(bu 5
+A window's size is changed by calling
+.PN XResizeWindow .
+.IP \(bu 5
+A window's size and location is changed by calling
+.PN XMoveResizeWindow .
+.IP \(bu 5
+A window is mapped and its position in the stacking order is changed
+by calling
+.PN XMapRaised .
+.IP \(bu 5
+A window's border width is changed by calling
+.PN XSetWindowBorderWidth .
+.LP
+To receive 
+.PN ConfigureNotify
+events, set the
+.PN StructureNotifyMask
+bit in the event-mask attribute of the window or the
+.PN SubstructureNotifyMask
+bit in the event-mask attribute of the parent window
+(in which case, configuring any child generates an event).
+.LP
+The structure for this event type contains:
+.LP
+.IN "XConfigureEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* ConfigureNotify */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window event;
+	Window window;
+	int x, y;
+	int width, height;
+	int border_width;
+	Window above;
+	Bool override_redirect;
+} XConfigureEvent;
+.De
+.LP
+.eM
+The event member is set either to the reconfigured window or to its parent,
+depending on whether
+.PN StructureNotify
+or
+.PN SubstructureNotify
+was selected.
+The window member is set to the window whose size, position, 
+border, and/or stacking
+order was changed.
+.LP
+The x and y members are set to the coordinates relative to the parent window's 
+origin and indicate the position of the upper-left outside corner of the window.
+The width and height members are set to the inside size of the window, 
+not including
+the border.
+The border_width member is set to the width of the window's border, in pixels.
+.LP
+The above member is set to the sibling window and is used 
+for stacking operations.
+If the X server sets this member to
+.PN None ,
+the window whose state was changed is on the bottom of the stack
+with respect to sibling windows.
+However, if this member is set to a sibling window, 
+the window whose state was changed is placed on top of this sibling window.
+.LP
+The override_redirect member is set to the override-redirect attribute of the
+window.
+Window manager clients normally should ignore this window if the 
+override_redirect member
+is
+.PN True .
+.NH 3
+CreateNotify Events
+.XS
+\*(SN CreateNotify Events
+.XE
+.LP
+.IN "Events" "CreateNotify"
+.IN "CreateNotify" "" "@DEF@"
+The X server can report
+.PN CreateNotify
+events to clients wanting information about creation of windows.
+The X server generates this event whenever a client
+application creates a window by calling
+.PN XCreateWindow
+or
+.PN XCreateSimpleWindow .
+.LP
+To receive 
+.PN CreateNotify
+events, set the
+.PN SubstructureNotifyMask
+bit in the event-mask attribute of the window.
+Creating any children then generates an event.
+.LP
+The structure for the event type contains:
+.LP
+.IN "XCreateWindowEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* CreateNotify */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window parent;	/* parent of the window */
+	Window window;	/* window id of window created */
+	int x, y;	/* window location */
+	int width, height;	/* size of window */
+	int border_width;	/* border width */
+	Bool override_redirect;	/* creation should be overridden */
+} XCreateWindowEvent;
+.De
+.LP
+.eM
+The parent member is set to the created window's parent.
+The window member specifies the created window.
+The x and y members are set to the created window's coordinates relative 
+to the parent window's origin and indicate the position of the upper-left 
+outside corner of the created window.
+The width and height members are set to the inside size of the created window 
+(not including the border) and are always nonzero.
+The border_width member is set to the width of the created window's border, in pixels.
+The override_redirect member is set to the override-redirect attribute of the
+window.
+Window manager clients normally should ignore this window 
+if the override_redirect member is
+.PN True .
+.NH 3
+DestroyNotify Events
+.XS
+\*(SN DestroyNotify Events
+.XE
+.LP
+.IN "Events" "DestroyNotify"
+.IN "DestroyNotify" "" "@DEF@"
+The X server can report
+.PN DestroyNotify
+events to clients wanting information about which windows are destroyed.
+The X server generates this event whenever a client application destroys a 
+window by calling
+.PN XDestroyWindow
+or
+.PN XDestroySubwindows .
+.LP
+The ordering of the 
+.PN DestroyNotify 
+events is such that for any given window, 
+.PN DestroyNotify
+is generated on all inferiors of the window
+before being generated on the window itself.  
+The X protocol does not constrain the ordering among
+siblings and across subhierarchies.
+.LP
+To receive 
+.PN DestroyNotify
+events, set the
+.PN StructureNotifyMask
+bit in the event-mask attribute of the window or the
+.PN SubstructureNotifyMask
+bit in the event-mask attribute of the parent window
+(in which case, destroying any child generates an event).
+.LP
+The structure for this event type contains:
+.LP
+.IN "XDestroyWindowEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* DestroyNotify */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window event;
+	Window window;
+} XDestroyWindowEvent;
+.De
+.LP
+.eM
+The event member is set either to the destroyed window or to its parent,
+depending on whether
+.PN StructureNotify
+or 
+.PN SubstructureNotify
+was selected.
+The window member is set to the window that is destroyed.
+.NH 3
+GravityNotify Events
+.XS
+\*(SN GravityNotify Events
+.XE
+.LP
+.IN "Events" "GravityNotify"
+.IN "GravityNotify" "" "@DEF@"
+The X server can report
+.PN GravityNotify
+events to clients wanting information about when a window is moved because of a
+change in the size of its parent.
+The X server generates this event whenever a client
+application actually moves a child window as a result of resizing its parent by calling
+.PN XConfigureWindow ,
+.PN XMoveResizeWindow ,
+or
+.PN XResizeWindow . 
+.LP
+To receive 
+.PN GravityNotify
+events, set the
+.PN StructureNotifyMask
+bit in the event-mask attribute of the window or the
+.PN SubstructureNotifyMask
+bit in the event-mask attribute of the parent window
+(in which case, any child that is moved because its parent has been resized
+generates an event).
+.LP
+The structure for this event type contains:
+.LP
+.IN "XGravityEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* GravityNotify */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window event;
+	Window window;
+	int x, y;
+} XGravityEvent;
+.De
+.LP
+.eM
+The event member is set either to the window that was moved or to its parent,
+depending on whether
+.PN StructureNotify
+or
+.PN SubstructureNotify
+was selected.
+The window member is set to the child window that was moved.
+The x and y members are set to the coordinates relative to the 
+new parent window's origin
+and indicate the position of the upper-left outside corner of the 
+window.
+.NH 3
+MapNotify Events
+.XS
+\*(SN MapNotify Events
+.XE
+.LP
+.IN "Events" "MapNotify"
+.IN "MapNotify" "" "@DEF@"
+The X server can report
+.PN MapNotify
+events to clients wanting information about which windows are mapped.
+The X server generates this event type whenever a client application changes the
+window's state from unmapped to mapped by calling
+.PN XMapWindow ,
+.PN XMapRaised ,
+.PN XMapSubwindows ,
+.PN XReparentWindow ,
+or as a result of save-set processing.
+.LP
+To receive 
+.PN MapNotify
+events, set the
+.PN StructureNotifyMask
+bit in the event-mask attribute of the window or the
+.PN SubstructureNotifyMask
+bit in the event-mask attribute of the parent window
+(in which case, mapping any child generates an event).
+.LP
+The structure for this event type contains:
+.LP
+.IN "XMapEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* MapNotify */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window event;
+	Window window;
+	Bool override_redirect;	/* boolean, is override set... */
+} XMapEvent;
+.De
+.LP
+.eM
+The event member is set either to the window that was mapped or to its parent,
+depending on whether
+.PN StructureNotify
+or
+.PN SubstructureNotify
+was selected.
+The window member is set to the window that was mapped.
+The override_redirect member is set to the override-redirect attribute
+of the window.
+Window manager clients normally should ignore this window 
+if the override-redirect attribute is
+.PN True ,
+because these events usually are generated from pop-ups,
+which override structure control.
+.NH 3
+MappingNotify Events
+.XS
+\*(SN MappingNotify Events
+.XE
+.LP
+.IN "Events" "MappingNotify"
+.IN "MappingNotify" "" "@DEF@"
+The X server reports
+.PN MappingNotify
+events to all clients.
+There is no mechanism to express disinterest in this event.
+The X server generates this event type whenever a client application 
+successfully calls:
+.IP \(bu 5
+.PN XSetModifierMapping
+to indicate which KeyCodes are to be used as modifiers
+.IP \(bu 5
+.PN XChangeKeyboardMapping
+to change the keyboard mapping
+.IP \(bu 5
+.PN XSetPointerMapping
+to set the pointer mapping
+.LP
+The structure for this event type contains:
+.LP
+.IN "XMappingEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* MappingNotify */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window window;	/* unused */
+	int request;	/* one of MappingModifier, MappingKeyboard,
+		   MappingPointer */
+	int first_keycode;	/* first keycode */
+	int count;	/* defines range of change w. first_keycode*/
+} XMappingEvent;
+.De
+.LP
+.eM
+The request member is set to indicate the kind of mapping change that occurred
+and can be
+.PN MappingModifier ,
+.PN MappingKeyboard ,
+or
+.PN MappingPointer .
+If it is
+.PN MappingModifier ,
+the modifier mapping was changed.
+If it is
+.PN MappingKeyboard ,
+the keyboard mapping was changed.
+If it is
+.PN MappingPointer ,
+the pointer button mapping was changed. 
+The first_keycode and count members are set only 
+if the request member was set to
+.PN MappingKeyboard .
+The number in first_keycode represents the first number in the range 
+of the altered mapping, 
+and count represents the number of keycodes altered.
+.LP
+To update the client application's knowledge of the keyboard,
+you should call
+.PN XRefreshKeyboardMapping . 
+.NH 3
+ReparentNotify Events
+.XS
+\*(SN ReparentNotify Events
+.XE
+.LP
+.IN "Events" "ReparentNotify"
+.IN "ReparentNotify" "" "@DEF@"
+The X server can report
+.PN ReparentNotify
+events to clients wanting information about changing a window's parent.
+The X server generates this event whenever a client
+application calls
+.PN XReparentWindow 
+and the window is actually reparented.
+.LP
+To receive 
+.PN ReparentNotify
+events, set the
+.PN StructureNotifyMask
+bit in the event-mask attribute of the window or the
+.PN SubstructureNotifyMask
+bit in the event-mask attribute of either the old or the new parent window
+(in which case, reparenting any child generates an event).
+.LP
+The structure for this event type contains:
+.LP
+.IN "XReparentEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* ReparentNotify */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window event;
+	Window window;
+	Window parent;
+	int x, y;
+	Bool override_redirect;
+} XReparentEvent;
+.De
+.LP
+.eM
+The event member is set either to the reparented window
+or to the old or the new parent, depending on whether
+.PN StructureNotify
+or
+.PN SubstructureNotify
+was selected. 
+The window member is set to the window that was reparented.
+The parent member is set to the new parent window.
+The x and y members are set to the reparented window's coordinates relative 
+to the new parent window's
+origin and define the upper-left outer corner of the reparented window.
+The override_redirect member is set to the override-redirect attribute of the
+window specified by the window member.
+Window manager clients normally should ignore this window 
+if the override_redirect member is
+.PN True .
+.NH 3
+UnmapNotify Events
+.XS
+\*(SN UnmapNotify Events
+.XE
+.LP
+.IN "Events" "UnmapNotify"
+.IN "UnmapNotify" "" "@DEF@"
+The X server can report
+.PN UnmapNotify
+events to clients wanting information about which windows are unmapped.
+The X server generates this event type whenever a client application changes the
+window's state from mapped to unmapped.
+.LP
+To receive 
+.PN UnmapNotify
+events, set the
+.PN StructureNotifyMask
+bit in the event-mask attribute of the window or the
+.PN SubstructureNotifyMask
+bit in the event-mask attribute of the parent window
+(in which case, unmapping any child window generates an event).
+.LP
+The structure for this event type contains:
+.LP
+.IN "XUnmapEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* UnmapNotify */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window event;
+	Window window;
+	Bool from_configure;
+} XUnmapEvent;
+.De
+.LP
+.eM
+The event member is set either to the unmapped window or to its parent,
+depending on whether
+.PN StructureNotify
+or
+.PN SubstructureNotify
+was selected.
+This is the window used by the X server to report the event.
+The window member is set to the window that was unmapped.
+The from_configure member is set to
+.PN True 
+if the event was generated as a result of a resizing of the window's parent when
+the window itself had a win_gravity of
+.PN UnmapGravity .
+.NH 3
+VisibilityNotify Events
+.XS
+\*(SN VisibilityNotify Events
+.XE
+.LP
+.IN "Events" "VisibilityNotify"
+.IN "VisibilityNotify" "" "@DEF@"
+The X server can report
+.PN VisibilityNotify
+events to clients wanting any change in the visibility of the specified window.
+A region of a window is visible if someone looking at the screen can
+actually see it.
+The X server generates this event whenever the visibility changes state. 
+However, this event is never generated for windows whose class is
+.PN InputOnly .
+.LP
+All 
+.PN VisibilityNotify
+events caused by a hierarchy change are generated
+after any hierarchy event
+.Pn ( UnmapNotify , 
+.PN MapNotify , 
+.PN ConfigureNotify ,
+.PN GravityNotify ,
+.PN CirculateNotify )
+caused by that change.  Any
+.PN VisibilityNotify
+event on a given window is generated before any
+.PN Expose 
+events on that window, but it is not required that all
+.PN VisibilityNotify
+events on all windows be generated before all 
+.PN Expose
+events on all windows.  
+The X protocol does not constrain the ordering of 
+.PN VisibilityNotify
+events with
+respect to 
+.PN FocusOut , 
+.PN EnterNotify ,
+and 
+.PN LeaveNotify
+events.
+.LP
+To receive 
+.PN VisibilityNotify
+events, set the
+.PN VisibilityChangeMask
+bit in the event-mask attribute of the window. 
+.LP
+The structure for this event type contains:
+.LP
+.IN "XVisibilityEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* VisibilityNotify */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window window;
+	int state;
+} XVisibilityEvent;
+.De
+.LP
+.eM
+The window member is set to the window whose visibility state changes.
+The state member is set to the state of the window's visibility and can be
+.PN VisibilityUnobscured ,
+.PN VisibilityPartiallyObscured ,
+or
+.PN VisibilityFullyObscured .
+The X server ignores all of a window's subwindows
+when determining the visibility state of the window and processes 
+.PN VisibilityNotify
+events according to the following:
+.IP \(bu 5
+When the window changes state from partially obscured, fully obscured,
+or not viewable to viewable and completely unobscured,
+the X server generates the event with the state member of the
+.PN XVisibilityEvent
+structure set to
+.PN VisibilityUnobscured .
+.IP \(bu 5
+When the window changes state from viewable and completely unobscured or 
+not viewable to viewable and partially obscured,
+the X server generates the event with the state member of the
+.PN XVisibilityEvent
+structure set to
+.PN VisibilityPartiallyObscured .
+.IP \(bu 5
+When the window changes state from viewable and completely unobscured, 
+viewable and partially obscured, or not viewable to viewable and 
+fully obscured,
+the X server generates the event with the state member of the
+.PN XVisibilityEvent
+structure set to
+.PN VisibilityFullyObscured .
+.NH 2
+Structure Control Events
+.XS
+\*(SN Structure Control Events
+.XE
+.LP
+This section discusses:
+.IP \(bu 5
+.PN CirculateRequest
+events
+.IP \(bu 5
+.PN ConfigureRequest
+events
+.IP \(bu 5
+.PN MapRequest 
+events
+.IP \(bu 5
+.PN ResizeRequest 
+events
+.NH 3 
+CirculateRequest Events
+.XS
+\*(SN CirculateRequest Events
+.XE
+.LP
+.IN "Events" "CirculateRequest"
+.IN "CirculateRequest" "" "@DEF@"
+The X server can report
+.PN CirculateRequest
+events to clients wanting information about 
+when another client initiates a circulate window request 
+on a specified window.
+The X server generates this event type whenever a client initiates a circulate
+window request on a window and a subwindow actually needs to be restacked. 
+The client initiates a circulate window request on the window by calling
+.PN XCirculateSubwindows ,
+.PN XCirculateSubwindowsUp ,
+or
+.PN XCirculateSubwindowsDown .
+.LP
+To receive
+.PN CirculateRequest
+events, set the
+.PN SubstructureRedirectMask
+in the event-mask attribute of the window. 
+Then, in the future,
+the circulate window request for the specified window is not executed,
+and thus, any subwindow's position in the stack is not changed.
+For example, suppose a client application calls
+.PN XCirculateSubwindowsUp
+to raise a subwindow to the top of the stack.
+If you had selected
+.PN SubstructureRedirectMask
+on the window, the X server reports to you a
+.PN CirculateRequest
+event and does not raise the subwindow to the top of the stack.
+.LP
+The structure for this event type contains:
+.LP
+.IN "XCirculateRequestEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* CirculateRequest */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window parent;
+	Window window;
+	int place;	/* PlaceOnTop, PlaceOnBottom */
+} XCirculateRequestEvent;
+.De
+.LP
+.eM
+The parent member is set to the parent window.
+The window member is set to the subwindow to be restacked.
+The place member is set to what the new position in the stacking order should be
+and is either
+.PN PlaceOnTop
+or
+.PN PlaceOnBottom .
+If it is
+.PN PlaceOnTop ,
+the subwindow should be on top of all siblings.
+If it is
+.PN PlaceOnBottom ,
+the subwindow should be below all siblings.
+.NH 3
+ConfigureRequest Events
+.XS
+\*(SN ConfigureRequest Events
+.XE
+.LP
+.IN "Events" "ConfigureRequest"
+.IN "ConfigureRequest" "" "@DEF@"
+The X server can report
+.PN ConfigureRequest
+events to clients wanting information about when a different client initiates 
+a configure window request on any child of a specified window. 
+The configure window request attempts to 
+reconfigure a window's size, position, border, and stacking order.
+The X server generates this event whenever a different client initiates
+a configure window request on a window by calling
+.PN XConfigureWindow ,
+.PN XLowerWindow ,
+.PN XRaiseWindow ,
+.PN XMapRaised ,
+.PN XMoveResizeWindow ,
+.PN XMoveWindow ,
+.PN XResizeWindow ,
+.PN XRestackWindows ,
+or
+.PN XSetWindowBorderWidth .
+.LP
+To receive
+.PN ConfigureRequest
+events, set the
+.PN SubstructureRedirectMask
+bit in the event-mask attribute of the window. 
+.PN ConfigureRequest
+events are generated when a
+.PN ConfigureWindow
+protocol request is issued on a child window by another client.
+For example, suppose a client application calls
+.PN XLowerWindow
+to lower a window.
+If you had selected
+.PN SubstructureRedirectMask 
+on the parent window and if the override-redirect attribute 
+of the window is set to
+.PN False ,
+the X server reports a
+.PN ConfigureRequest
+event to you and does not lower the specified window.
+.LP
+The structure for this event type contains:
+.LP
+.IN "XConfigureRequestEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* ConfigureRequest */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window parent;
+	Window window;
+	int x, y;
+	int width, height;
+	int border_width;
+	Window above;
+	int detail;	/* Above, Below, TopIf, BottomIf, Opposite */
+	unsigned long value_mask;
+} XConfigureRequestEvent;
+.De
+.LP
+.eM
+The parent member is set to the parent window.
+The window member is set to the window whose size, position, border width, 
+and/or stacking order is to be reconfigured.
+The value_mask member indicates which components were specified in the
+.PN ConfigureWindow 
+protocol request.
+The corresponding values are reported as given in the request.
+The remaining values are filled in from the current geometry of the window,
+except in the case of above (sibling) and detail (stack-mode),
+which are reported as
+.PN None
+and
+.PN Above ,
+respectively, if they are not given in the request.
+.NH 3
+MapRequest Events
+.XS
+\*(SN MapRequest Events
+.XE
+.LP
+.IN "Events" "MapRequest"
+.IN "MapRequest" "" "@DEF@"
+The X server can report
+.PN MapRequest
+events to clients wanting information about a different client's desire 
+to map windows.
+A window is considered mapped when a map window request completes.
+The X server generates this event whenever a different client initiates 
+a map window request on an unmapped window whose override_redirect member 
+is set to
+.PN False .
+Clients initiate map window requests by calling
+.PN XMapWindow ,
+.PN XMapRaised ,
+or
+.PN XMapSubwindows .
+.LP
+To receive
+.PN MapRequest
+events, set the
+.PN SubstructureRedirectMask
+bit in the event-mask attribute of the window. 
+This means another client's attempts to map a child window by calling one of
+the map window request functions is intercepted, and you are sent a 
+.PN MapRequest
+instead.
+For example, suppose a client application calls
+.PN XMapWindow
+to map a window.
+If you (usually a window manager) had selected
+.PN SubstructureRedirectMask 
+on the parent window and if the override-redirect attribute 
+of the window is set to
+.PN False ,
+the X server reports a
+.PN MapRequest
+event to you 
+and does not map the specified window.
+Thus, this event gives your window manager client the ability 
+to control the placement of subwindows.
+.LP
+The structure for this event type contains:
+.LP
+.IN "XMapRequestEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* MapRequest */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window parent;
+	Window window;
+} XMapRequestEvent;
+.De
+.LP
+.eM
+The parent member is set to the parent window.
+The window member is set to the window to be mapped.
+.NH 3
+ResizeRequest Events
+.XS
+\*(SN ResizeRequest Events
+.XE
+.LP
+.IN "Events" "ResizeRequest"
+.IN "ResizeRequest" "" "@DEF@"
+The X server can report
+.PN ResizeRequest
+events to clients wanting information about another client's attempts to change the
+size of a window.
+The X server generates this event whenever some other client attempts to change
+the size of the specified window by calling
+.PN XConfigureWindow ,
+.PN XResizeWindow ,
+or
+.PN XMoveResizeWindow .
+.LP
+To receive
+.PN ResizeRequest
+events, set the
+.PN ResizeRedirect
+bit in the event-mask attribute of the window. 
+Any attempts to change the size by other clients are then redirected.
+.LP
+The structure for this event type contains:
+.LP
+.IN "XResizeRequestEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* ResizeRequest */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window window;
+	int width, height;
+} XResizeRequestEvent;
+.De
+.LP
+.eM
+The window member is set to the window whose size another 
+client attempted to change.
+The width and height members are set to the inside size of the window, 
+excluding the border.
+.NH 2
+Colormap State Change Events
+.XS
+\*(SN Colormap State Change Events
+.XE
+.LP
+.IN "Events" "ColormapNotify"
+.IN "ColormapNotify" "" "@DEF@"
+The X server can report
+.PN ColormapNotify
+events to clients wanting information about when the colormap changes 
+and when a colormap is installed or uninstalled. 
+The X server generates this event type whenever a client application:
+.IP \(bu 5
+Changes the colormap member of the
+.PN XSetWindowAttributes
+structure by 
+calling
+.PN XChangeWindowAttributes ,
+.PN XFreeColormap ,
+or
+.PN XSetWindowColormap 
+.IP \(bu 5
+Installs or uninstalls the colormap by calling
+.PN XInstallColormap
+or
+.PN XUninstallColormap 
+.LP
+To receive 
+.PN ColormapNotify 
+events, set the
+.PN ColormapChangeMask
+bit in the event-mask attribute of the window. 
+.LP
+The structure for this event type contains:
+.LP
+.IN "XColormapEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* ColormapNotify */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window window;
+	Colormap colormap;	/* colormap or None */
+	Bool new;
+	int state;	/* ColormapInstalled, ColormapUninstalled */
+} XColormapEvent;
+.De
+.LP
+.eM
+The window member is set to the window whose associated 
+colormap is changed, installed, or uninstalled.
+For a colormap that is changed, installed, or uninstalled,
+the colormap member is set to the colormap associated with the window. 
+For a colormap that is changed by a call to
+.PN XFreeColormap ,
+the colormap member is set to
+.PN None .
+The new member is set to indicate whether the colormap 
+for the specified window was changed or installed or uninstalled
+and can be 
+.PN True
+or
+.PN False .
+If it is
+.PN True ,
+the colormap was changed.
+If it is
+.PN False ,
+the colormap was installed or uninstalled.
+The state member is always set to indicate whether the colormap is installed or
+uninstalled and can be 
+.PN ColormapInstalled
+or
+.PN ColormapUninstalled .
+.NH 2
+Client Communication Events
+.XS
+\*(SN Client Communication Events
+.XE
+.LP
+This section discusses:
+.IP \(bu 5
+.PN ClientMessage 
+events
+.IP \(bu 5
+.PN PropertyNotify
+events
+.IP \(bu 5
+.PN SelectionClear
+events
+.IP \(bu 5
+.PN SelectionNotify
+events
+.IP \(bu 5
+.PN SelectionRequest
+events
+.NH 3
+ClientMessage Events
+.XS
+\*(SN ClientMessage Events
+.XE
+.LP
+.IN "Events" "ClientMessage"
+.IN "ClientMessage" "" "@DEF@"
+The X server generates
+.PN ClientMessage
+events only when a client calls the function
+.PN XSendEvent .
+.LP
+The structure for this event type contains:
+.LP
+.IN "XClientMessageEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 1i 3i
+.ta .5i 1i 3i
+typedef struct {
+	int type;	/* ClientMessage */
+	unsigned long serial;		/* # of last request processed by server */
+	Bool send_event;		/* true if this came from a SendEvent request */
+	Display *display;		/* Display the event was read from */
+	Window window;
+	Atom message_type;
+	int format;
+	union {
+		char b[20];
+		short s[10];
+		long l[5];
+	        } data;
+} XClientMessageEvent;
+.De
+.LP
+.eM
+The message_type member is set to an atom that indicates how the data 
+should be interpreted by the receiving client.
+The format member is set to 8, 16, or 32 and specifies whether the data
+should be viewed as a list of bytes, shorts, or longs.
+The data member is a union that contains the members b, s, and l.
+The b, s, and l members represent data of twenty 8-bit values, 
+ten 16-bit values, and five 32-bit values.
+Particular message types might not make use of all these values.
+The X server places no interpretation on the values in the window,
+message_type, or data members.
+.NH 3
+PropertyNotify Events
+.XS
+\*(SN PropertyNotify Events
+.XE
+.LP
+.IN "Events" "PropertyNotify"
+.IN "PropertyNotify" "" "@DEF@"
+The X server can report
+.PN PropertyNotify
+events to clients wanting information about property changes 
+for a specified window.
+.LP
+To receive
+.PN PropertyNotify
+events, set the
+.PN PropertyChangeMask
+bit in the event-mask attribute of the window. 
+.LP
+The structure for this event type contains:
+.LP
+.IN "XPropertyEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* PropertyNotify */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window window;
+	Atom atom;
+	Time time;
+	int state;	/* PropertyNewValue or PropertyDelete */
+} XPropertyEvent;
+.De
+.LP
+.eM
+The window member is set to the window whose associated 
+property was changed.
+The atom member is set to the property's atom and indicates which
+property was changed or desired.
+The time member is set to the server time when the property was changed.
+The state member is set to indicate whether the property was changed 
+to a new value or deleted and can be
+.PN PropertyNewValue
+or
+.PN PropertyDelete .
+The state member is set to
+.PN PropertyNewValue
+when a property of the window is changed using
+.PN XChangeProperty
+or
+.PN XRotateWindowProperties
+(even when adding zero-length data using
+.PN XChangeProperty )
+and when replacing all or part of a property with identical data using
+.PN XChangeProperty
+or 
+.PN XRotateWindowProperties .
+The state member is set to
+.PN PropertyDelete
+when a property of the window is deleted using
+.PN XDeleteProperty
+or, if the delete argument is 
+.PN True ,
+.PN XGetWindowProperty .
+.NH 3
+SelectionClear Events
+.XS
+\*(SN SelectionClear Events
+.XE
+.LP
+.IN "Events" "SelectionClear" 
+.IN "SelectionClear" "" "@DEF@"
+The X server reports
+.PN SelectionClear
+events to the client losing ownership of a selection.
+The X server generates this event type when another client
+asserts ownership of the selection by calling
+.PN XSetSelectionOwner .
+.LP
+The structure for this event type contains:
+.LP
+.IN "XSelectionClearEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* SelectionClear */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window window;
+	Atom selection;
+	Time time;
+} XSelectionClearEvent;
+.De
+.LP
+.eM
+The selection member is set to the selection atom.
+The time member is set to the last change time recorded for the 
+selection.
+The window member is the window that was specified by the current owner
+(the owner losing the selection) in its
+.PN XSetSelectionOwner
+call.
+.NH 3
+SelectionRequest Events
+.XS
+\*(SN SelectionRequest Events
+.XE
+.LP
+.IN "Events" "SelectionRequest"
+.IN "SelectionRequest" "" "@DEF@"
+The X server reports
+.PN SelectionRequest
+events to the owner of a selection.
+The X server generates this event whenever a client 
+requests a selection conversion by calling 
+.PN XConvertSelection 
+for the owned selection.
+.LP
+The structure for this event type contains:
+.LP
+.IN "XSelectionRequestEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* SelectionRequest */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window owner;
+	Window requestor;
+	Atom selection;
+	Atom target;
+	Atom property;
+	Time time;
+} XSelectionRequestEvent;
+.De
+.LP
+.eM
+The owner member is set to the window
+that was specified by the current owner in its
+.PN XSetSelectionOwner
+call.
+The requestor member is set to the window requesting the selection.
+The selection member is set to the atom that names the selection.
+For example, PRIMARY is used to indicate the primary selection.
+The target member is set to the atom that indicates the type
+the selection is desired in.
+The property member can be a property name or 
+.PN None .
+The time member is set to the timestamp or 
+.PN CurrentTime 
+value from the
+.PN ConvertSelection
+request.
+.LP
+The owner should convert the selection based on the specified target type
+and send a
+.PN SelectionNotify
+event back to the requestor.
+A complete specification for using selections is given in the X Consortium
+standard \fIInter-Client Communication Conventions Manual\fP.
+.NH 3
+SelectionNotify Events
+.XS
+\*(SN SelectionNotify Events
+.XE
+.LP
+.IN "Events" "SelectionNotify"
+.IN "SelectionNotify" "" "@DEF@"
+This event is generated by the X server in response to a
+.PN ConvertSelection 
+protocol request when there is no owner for the selection.
+When there is an owner, it should be generated by the owner
+of the selection by using
+.PN XSendEvent .
+The owner of a selection should send this event to a requestor when a selection
+has been converted and stored as a property
+or when a selection conversion could
+not be performed (which is indicated by setting the property member to
+.PN None ).
+.LP
+If
+.PN None
+is specified as the property in the 
+.PN ConvertSelection
+protocol request, the owner should choose a property name,
+store the result as that property on the requestor window,
+and then send a 
+.PN SelectionNotify
+giving that actual property name.
+.LP
+The structure for this event type contains:
+.LP
+.IN "XSelectionEvent" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	int type;	/* SelectionNotify */
+	unsigned long serial;	/* # of last request processed by server */
+	Bool send_event;	/* true if this came from a SendEvent request */
+	Display *display;	/* Display the event was read from */
+	Window requestor;
+	Atom selection;
+	Atom target;
+	Atom property;	/* atom or None */
+	Time time;
+} XSelectionEvent;
+.De
+.LP
+.eM
+The requestor member is set to the window associated with
+the requestor of the selection.
+The selection member is set to the atom that indicates the selection.
+For example, PRIMARY is used for the primary selection.
+The target member is set to the atom that indicates the converted type.
+For example, PIXMAP is used for a pixmap.
+The property member is set to the atom that indicates which
+property the result was stored on.
+If the conversion failed, 
+the property member is set to
+.PN None .
+The time member is set to the time the conversion took place and
+can be a timestamp or
+.PN CurrentTime .
+.bp
diff --git a/specs/libX11/CH11 b/specs/libX11/CH11
new file mode 100644
index 00000000..09d845d3
--- /dev/null
+++ b/specs/libX11/CH11
@@ -0,0 +1,1664 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 11\fP\s-1
+
+\s+1\fBEvent Handling Functions\fP\s-1
+.sp 2
+.nr H1 11
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.na
+.LP
+.XS
+Chapter 11: Event Handling Functions 
+.XE
+This chapter discusses the Xlib functions you can use to:
+.IP \(bu 5
+Select events
+.IP \(bu 5
+Handle the output buffer and the event queue
+.IP \(bu 5
+Select events from the event queue 
+.IP \(bu 5
+Send and get events
+.IP \(bu 5
+Handle protocol errors
+.NT Note
+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.
+.NE
+.LP
+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.
+.NH 2
+Selecting Events
+.XS
+\*(SN Selecting Events 
+.XE
+.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
+.PN XSetWindowAttributes
+structure when you call
+.PN XCreateWindow
+and
+.PN XChangeWindowAttributes .
+Another way is to use
+.PN XSelectInput . 
+.IN "XSelectInput" "" "@DEF@"
+.sM
+.FD 0
+XSelectInput\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_mask\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      long \fIevent_mask\fP\^;
+.FN	
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Wi whose events you are interested in
+.IP \fIw\fP 1i
+Specifies the window \*(Wi.
+.IP \fIevent_mask\fP 1i
+Specifies the event mask.
+.LP
+.eM 
+The
+.PN XSelectInput
+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.
+.IN "Event" "propagation"
+.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:
+.IP \(bu 5
+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.
+.IP \(bu 5
+Only one client at a time can select
+.PN CirculateRequest ,
+.PN ConfigureRequest ,
+or
+.PN MapRequest
+events, which are associated with
+the event mask
+.PN SubstructureRedirectMask . 
+.IP \(bu 5
+Only one client at a time can select
+a
+.PN ResizeRequest
+event, which is associated with
+the event mask
+.PN ResizeRedirectMask . 
+.IP \(bu 5
+Only one client at a time can select a 
+.PN ButtonPress 
+event, which is associated with
+the event mask
+.PN ButtonPressMask .
+.LP
+The server reports the event to all interested clients.
+.LP
+.PN XSelectInput
+can generate a
+.PN BadWindow 
+error.
+.NH 2
+Handling the Output Buffer
+.XS
+\*(SN Handling the Output Buffer
+.XE
+.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.
+.LP
+.sp
+To flush the output buffer, use 
+.PN XFlush .
+.IN "XFlush" "" "@DEF@"
+.sM
+.FD 0
+XFlush\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+The
+.PN XFlush
+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
+.PN XPending ,
+.PN XNextEvent ,
+and
+.PN XWindowEvent .
+.IN "XPending"
+.IN "XNextEvent"
+.IN "XWindowEvent"
+Events generated by the server may be enqueued into the library's event queue.
+.LP
+.sp
+To flush the output buffer and then wait until all requests have been processed,
+use 
+.PN XSync .
+.IN "XSync" "" "@DEF@"
+.sM
+.FD 0
+XSync\^(\^\fIdisplay\fP, \fIdiscard\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Bool \fIdiscard\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIdiscard\fP 1i
+Specifies a Boolean value that indicates whether 
+.PN XSync
+discards all events on the event queue.
+.LP
+.eM
+The
+.PN XSync
+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,
+.PN XSync
+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.
+.LP
+Finally, if you passed 
+.PN False ,
+.PN XSync
+does not discard the events in the queue.
+If you passed 
+.PN True ,
+.PN XSync 
+discards all events in the queue,
+including those events that were on the queue before
+.PN XSync
+was called.
+Client applications seldom need to call
+.PN XSync .
+.NH 2
+Event Queue Management
+.XS
+\*(SN Event Queue Management
+.XE
+.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.
+.LP
+.sp
+To check the number of events in the event queue, use
+.PN XEventsQueued .
+.IN "XEventsQueued" "" "@DEF@"
+.sM
+.FD 0
+int XEventsQueued\^(\^\fIdisplay\fP, \fImode\fP\^)
+.br
+     Display *\fIdisplay\fP\^;
+.br
+     int \fImode\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fImode\fP 1i
+Specifies the mode.
+You can pass
+.PN QueuedAlready ,
+.PN QueuedAfterFlush ,
+or
+.PN QueuedAfterReading .
+.LP
+.eM
+If mode is 
+.PN QueuedAlready ,
+.PN XEventsQueued 
+returns the number of events
+already in the event queue (and never performs a system call).
+If mode is 
+.PN QueuedAfterFlush , 
+.PN XEventsQueued
+returns the number of events already in the queue if the number is nonzero.
+If there are no events in the queue, 
+.PN XEventsQueued
+flushes the output buffer, 
+attempts to read more events out of the application's connection,
+and returns the number read.
+If mode is 
+.PN QueuedAfterReading , 
+.PN XEventsQueued
+returns the number of events already in the queue if the number is nonzero. 
+If there are no events in the queue, 
+.PN XEventsQueued
+attempts to read more events out of the application's connection 
+without flushing the output buffer and returns the number read.
+.LP
+.PN XEventsQueued
+always returns immediately without I/O if there are events already in the
+queue.
+.PN XEventsQueued
+with mode 
+.PN QueuedAfterFlush
+is identical in behavior to
+.PN XPending .
+.PN XEventsQueued
+with mode
+.PN QueuedAlready
+is identical to the
+.PN XQLength
+function.
+.LP
+.sp
+To return the number of events that are pending, use 
+.PN XPending .
+.IN "XPending" "" "@DEF@"
+.sM
+.FD 0
+int XPending\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN	
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+The
+.PN XPending
+function returns the number of events that have been received from the
+X server but have not been removed from the event queue.
+.PN XPending
+is identical to
+.PN XEventsQueued
+with the mode
+.PN QueuedAfterFlush
+specified.
+.NH 2
+Manipulating the Event Queue
+.XS
+\*(SN Manipulating the Event Queue 
+.XE
+.LP
+Xlib provides functions that let you manipulate the event queue.
+This section discusses how to:
+.IP \(bu 5
+Obtain events, in order, and remove them from the queue
+.IP \(bu 5
+Peek at events in the queue without removing them
+.IP \(bu 5
+Obtain events that match the event mask or the arbitrary
+predicate procedures that you provide
+.NH 3
+Returning the Next Event
+.XS
+\*(SN Returning the Next Event
+.XE
+.LP
+To get the next event and remove it from the queue, use
+.PN XNextEvent .
+.IN "XNextEvent" "" "@DEF@"
+.sM
+.FD 0
+XNextEvent\^(\^\fIdisplay\fP, \fIevent_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XEvent *\fIevent_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIevent_return\fP 1i
+Returns the next event in the queue.
+.LP
+.eM
+The
+.PN XNextEvent
+function copies the first event from the event queue into the specified
+.PN XEvent
+structure and then removes it from the queue.
+If the event queue is empty,
+.PN XNextEvent
+flushes the output buffer and blocks until an event is received.
+.LP
+.sp
+To peek at the event queue, use
+.PN XPeekEvent .
+.IN "XPeekEvent" "" "@DEF@"
+.sM
+.FD 0
+XPeekEvent\^(\^\fIdisplay\fP, \fIevent_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XEvent *\fIevent_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIevent_return\fP 1i
+Returns a copy of the matched event's associated structure.
+.LP
+.eM
+The
+.PN XPeekEvent
+function returns the first event from the event queue,
+but it does not remove the event from the queue.
+If the queue is empty,
+.PN XPeekEvent
+flushes the output buffer and blocks until an event is received.
+It then copies the event into the client-supplied
+.PN XEvent
+structure without removing it from the event queue.
+.NH 3
+Selecting Events Using a Predicate Procedure
+.XS
+\*(SN Selecting Events Using a Predicate Procedure
+.XE
+.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
+.PN XLockDisplay .
+.LP
+The predicate procedure and its associated arguments are:
+.sM
+.FD 0
+Bool (\^*\fIpredicate\fP\^)\^(\^\fIdisplay\fP, \fIevent\fP, \fIarg\fP\^)
+.br
+     Display *\fIdisplay\fP\^;
+.br
+     XEvent *\fIevent\fP\^;
+.br
+     XPointer \fIarg\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIevent\fP 1i
+Specifies the
+.PN XEvent
+structure.
+.IP \fIarg\fP 1i
+Specifies the argument passed in from the 
+.PN XIfEvent ,
+.PN XCheckIfEvent ,
+or
+.PN XPeekIfEvent 
+function.
+.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 
+.PN True .
+If it did not find a match, it must return
+.PN False .
+.LP
+.sp
+To check the event queue for a matching event
+and, if found, remove the event from the queue, use
+.PN XIfEvent .
+.IN "XIfEvent" "" "@DEF@"
+.sM
+.FD 0
+XIfEvent\^(\^\fIdisplay\fP, \fIevent_return\fP, \fIpredicate\fP, \fIarg\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XEvent *\fIevent_return\fP\^;
+.br
+      Bool (\^*\fIpredicate\fP\^)\^(\^)\^;
+.br
+      XPointer \fIarg\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIevent_return\fP 1i
+Returns the matched event's associated structure.
+.IP \fIpredicate\fP 1i
+Specifies the procedure that is to be called to determine
+if the next event in the queue matches what you want.
+.IP \fIarg\fP 1i
+Specifies the user-supplied argument that will be passed to the predicate procedure.
+.LP
+.eM
+The
+.PN XIfEvent
+function completes only when the specified predicate
+procedure returns 
+.PN True 
+for an event, 
+which indicates an event in the queue matches.
+.PN XIfEvent
+flushes the output buffer if it blocks waiting for additional events.
+.PN XIfEvent
+removes the matching event from the queue 
+and copies the structure into the client-supplied
+.PN XEvent
+structure.
+.LP
+.sp
+To check the event queue for a matching event without blocking, use
+.PN XCheckIfEvent .
+.IN "XCheckIfEvent" "" "@DEF@"
+.sM
+.FD 0
+Bool XCheckIfEvent\^(\^\fIdisplay\fP, \fIevent_return\fP, \fIpredicate\fP, \fIarg\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XEvent *\fIevent_return\fP\^;
+.br
+      Bool (\^*\fIpredicate\fP\^)\^(\^)\^;
+.br
+      XPointer \fIarg\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIevent_return\fP 1i
+Returns a copy of the matched event's associated structure.
+.IP \fIpredicate\fP 1i
+Specifies the procedure that is to be called to determine
+if the next event in the queue matches what you want.
+.IP \fIarg\fP 1i
+Specifies the user-supplied argument that will be passed to the predicate procedure.
+.LP
+.eM
+When the predicate procedure finds a match,
+.PN XCheckIfEvent
+copies the matched event into the client-supplied
+.PN XEvent
+structure and returns 
+.PN True .
+(This event is removed from the queue.)
+If the predicate procedure finds no match,
+.PN XCheckIfEvent
+returns
+.PN False ,
+and the output buffer will have been flushed.
+All earlier events stored in the queue are not discarded.
+.LP
+.sp
+To check the event queue for a matching event
+without removing the event from the queue, use
+.PN XPeekIfEvent .
+.IN "XPeekIfEvent" "" "@DEF@"
+.sM
+.FD 0
+XPeekIfEvent\^(\^\fIdisplay\fP, \fIevent_return\fP, \fIpredicate\fP, \fIarg\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XEvent *\fIevent_return\fP\^;
+.br
+      Bool (\^*\fIpredicate\fP\^)\^(\^)\^;
+.br
+      XPointer \fIarg\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIevent_return\fP 1i
+Returns a copy of the matched event's associated structure.
+.IP \fIpredicate\fP 1i
+Specifies the procedure that is to be called to determine
+if the next event in the queue matches what you want.
+.IP \fIarg\fP 1i
+Specifies the user-supplied argument that will be passed to the predicate procedure.
+.LP
+.eM
+The
+.PN XPeekIfEvent
+function returns only when the specified predicate
+procedure returns 
+.PN True
+for an event.
+After the predicate procedure finds a match,
+.PN XPeekIfEvent
+copies the matched event into the client-supplied
+.PN XEvent
+structure without removing the event from the queue.
+.PN XPeekIfEvent
+flushes the output buffer if it blocks waiting for additional events.
+.NH 3
+Selecting Events Using a Window or Event Mask
+.XS
+\*(SN Selecting Events Using a Window or Event Mask
+.XE
+.LP
+The functions discussed in this section let you select events by window 
+or event types, allowing you to process events out of order.
+.LP
+.sp
+To remove the next event that matches both a window and an event mask, use
+.PN XWindowEvent .
+.IN "XWindowEvent" "" "@DEF@"
+.sM
+.FD 0
+XWindowEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_mask\fP\^, \fIevent_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      long \fIevent_mask\fP\^;
+.br
+      XEvent *\fIevent_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Wi whose events you are interested in
+.IP \fIw\fP 1i
+Specifies the window \*(Wi.
+.IP \fIevent_mask\fP 1i
+Specifies the event mask.
+.IP \fIevent_return\fP 1i
+Returns the matched event's associated structure.
+.LP
+.eM
+The
+.PN XWindowEvent
+function searches the event queue for an event that matches both the specified
+window and event mask.
+When it finds a match,
+.PN XWindowEvent
+removes that event from the queue and copies it into the specified
+.PN XEvent
+structure.
+The other events stored in the queue are not discarded.
+If a matching event is not in the queue,
+.PN XWindowEvent
+flushes the output buffer and blocks until one is received.
+.LP
+.sp
+To remove the next event that matches both a window and an event mask (if any),
+use
+.PN XCheckWindowEvent .
+.IN "XCheckWindowEvent"
+This function is similar to
+.PN XWindowEvent 
+except that it never blocks and it returns a 
+.PN Bool 
+indicating if the event was returned.
+.IN "XCheckWindowEvent" "" "@DEF@"
+.sM
+.FD 0
+Bool XCheckWindowEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_mask\fP\^, \fIevent_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      long \fIevent_mask\fP\^;
+.br
+      XEvent *\fIevent_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Wi whose events you are interested in
+.IP \fIw\fP 1i
+Specifies the window \*(Wi.
+.IP \fIevent_mask\fP 1i
+Specifies the event mask.
+.IP \fIevent_return\fP 1i
+Returns the matched event's associated structure.
+.LP
+.eM
+The
+.PN XCheckWindowEvent
+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,
+.PN XCheckWindowEvent
+removes that event, copies it into the specified
+.PN XEvent
+structure, and returns
+.PN True .
+The other events stored in the queue are not discarded.
+If the event you requested is not available,
+.PN XCheckWindowEvent
+returns
+.PN False ,
+and the output buffer will have been flushed.
+.LP
+.sp
+To remove the next event that matches an event mask, use
+.PN XMaskEvent .
+.IN "XMaskEvent" "" "@DEF@"
+.sM
+.FD 0
+XMaskEvent\^(\^\fIdisplay\fP, \fIevent_mask\fP\^, \fIevent_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      long \fIevent_mask\fP\^;
+.br
+      XEvent *\fIevent_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIevent_mask\fP 1i
+Specifies the event mask.
+.IP \fIevent_return\fP 1i
+Returns the matched event's associated structure.
+.LP
+.eM
+The
+.PN XMaskEvent
+function searches the event queue for the events associated with the 
+specified mask.
+When it finds a match,
+.PN XMaskEvent
+removes that event and copies it into the specified
+.PN XEvent
+structure.
+The other events stored in the queue are not discarded.
+If the event you requested is not in the queue,
+.PN XMaskEvent
+flushes the output buffer and blocks until one is received.
+.LP
+.sp
+To return and remove the next event that matches an event mask (if any), use
+.PN XCheckMaskEvent .
+This function is similar to 
+.PN XMaskEvent 
+except that it never blocks and it returns a 
+.PN Bool 
+indicating if the event was returned.
+.IN "XCheckMaskEvent" "" "@DEF@"
+.sM
+.FD 0
+Bool XCheckMaskEvent\^(\^\fIdisplay\fP, \fIevent_mask\fP\^, \fIevent_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      long \fIevent_mask\fP\^;
+.br
+      XEvent *\fIevent_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIevent_mask\fP 1i
+Specifies the event mask.
+.IP \fIevent_return\fP 1i
+Returns the matched event's associated structure.
+.LP
+.eM
+The
+.PN XCheckMaskEvent
+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,
+.PN XCheckMaskEvent
+removes that event, copies it into the specified
+.PN XEvent
+structure, and returns
+.PN True .
+The other events stored in the queue are not discarded.
+If the event you requested is not available,
+.PN XCheckMaskEvent
+returns
+.PN False ,
+and the output buffer will have been flushed.
+.LP
+.sp 
+To return and remove the next event in the queue that matches an event type, use
+.PN XCheckTypedEvent .
+.IN "XCheckTypedEvent" "" "@DEF@"
+.sM
+.FD 0
+Bool XCheckTypedEvent\^(\^\fIdisplay\fP, \fIevent_type\fP\^, \fIevent_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIevent_type\fP\^;
+.br
+      XEvent *\fIevent_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIevent_type\fP 1i
+Specifies the event type to be compared.
+
+.IP \fIevent_return\fP 1i
+Returns the matched event's associated structure.
+.LP
+.eM
+The
+.PN XCheckTypedEvent
+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,
+.PN XCheckTypedEvent
+removes that event, copies it into the specified
+.PN XEvent
+structure, and returns
+.PN True .
+The other events in the queue are not discarded.
+If the event is not available,
+.PN XCheckTypedEvent
+returns
+.PN False ,
+and the output buffer will have been flushed.
+.LP
+.sp
+To return and remove the next event in the queue that matches an event type 
+and a window, use
+.PN XCheckTypedWindowEvent .
+.IN "XCheckTypedWindowEvent" "" "@DEF@"
+.sM
+.FD 0
+Bool XCheckTypedWindowEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_type\fP\^, \fIevent_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      int \fIevent_type\fP\^;
+.br
+      XEvent *\fIevent_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIevent_type\fP 1i
+Specifies the event type to be compared.
+
+.IP \fIevent_return\fP 1i
+Returns the matched event's associated structure.
+.LP
+.eM
+The
+.PN XCheckTypedWindowEvent
+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,
+.PN XCheckTypedWindowEvent
+removes the event from the queue, copies it into the specified
+.PN XEvent
+structure, and returns
+.PN True .
+The other events in the queue are not discarded.
+If the event is not available,
+.PN XCheckTypedWindowEvent
+returns
+.PN False ,
+and the output buffer will have been flushed.
+.NH 2
+Putting an Event Back into the Queue
+.XS
+\*(SN Putting an Event Back into the Queue 
+.XE
+.LP
+To push an event back into the event queue, use
+.PN XPutBackEvent .
+.IN "XPutBackEvent" "" "@DEF@"
+.sM
+.FD 0
+XPutBackEvent\^(\^\fIdisplay\fP, \fIevent\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XEvent *\fIevent\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIevent\fP 1i
+Specifies the event.
+.LP
+.eM 
+The
+.PN XPutBackEvent
+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
+.PN XPutBackEvent .
+.NH 2
+Sending Events to Other Applications
+.XS
+\*(SN Sending Events to Other Applications
+.XE
+.LP
+To send an event to a specified window, use
+.PN XSendEvent .
+.IN "XSendEvent"
+This function is often used in selection processing.
+For example, the owner of a selection should use
+.PN XSendEvent
+to send a
+.PN SelectionNotify
+event to a requestor when a selection has been converted 
+and stored as a property.
+.IN "XSendEvent" "" "@DEF@"
+.sM
+.FD 0
+Status XSendEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIpropagate\fP\^, \fIevent_mask\fP\^, \fIevent_send\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Bool \fIpropagate\fP\^;
+.br
+      long \fIevent_mask\fP\^;
+.br
+      XEvent *\fIevent_send\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window the event is to be sent to, or
+.PN PointerWindow ,
+or
+.PN InputFocus .
+.IP \fIpropagate\fP 1i
+Specifies a Boolean value.
+.IP \fIevent_mask\fP 1i
+Specifies the event mask.
+.IP \fIevent_send\fP 1i
+Specifies the event that is to be sent.
+.LP
+.eM
+The
+.PN XSendEvent
+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:
+.IP \(bu 5
+If w is
+.PN PointerWindow ,
+the destination window is the window that contains the pointer.
+.IP \(bu 5
+If w is
+.PN InputFocus 
+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.
+.LP
+To determine which clients should receive the specified events,
+.PN XSendEvent
+uses the propagate argument as follows:
+.IP \(bu 5
+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.
+.IP \(bu 5
+If propagate is 
+.PN False ,
+the event is sent to every client selecting on destination any of the event
+types in the event_mask argument.
+.IP \(bu 5
+If propagate is 
+.PN True 
+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 
+.PN InputFocus 
+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.
+.LP
+The event in the
+.PN XEvent
+structure must be one of the core events or one of the events
+defined by an extension (or a 
+.PN BadValue
+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
+.PN True
+in the forwarded event and to set the serial number in the event correctly;
+therefore these fields
+and the display field are ignored by
+.PN XSendEvent .
+.LP
+.PN XSendEvent
+returns zero if the conversion to wire protocol format failed
+and returns nonzero otherwise.
+.LP
+.PN XSendEvent
+can generate
+.PN BadValue
+and 
+.PN BadWindow 
+errors.
+.NH 2
+Getting Pointer Motion History
+.XS
+\*(SN Getting Pointer Motion History
+.XE
+.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.
+.LP
+.sp
+To determine the approximate maximum number of elements in the motion buffer, 
+use
+.PN XDisplayMotionBufferSize .
+.IN "XDisplayMotionBufferSize" "" "@DEF@"
+.sM
+.FD 0
+unsigned long XDisplayMotionBufferSize\^(\^\fIdisplay\fP\^)
+.br
+        Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+The server may retain the recent history of the pointer motion
+and do so to a finer granularity than is reported by
+.PN MotionNotify
+events.
+The
+.PN XGetMotionEvents
+function makes this history available.
+.LP
+.sp
+To get the motion history for a specified window and time, use
+.PN XGetMotionEvents .
+.IN "XGetMotionEvents" "" "@DEF@"
+.sM
+.FD 0
+XTimeCoord *XGetMotionEvents\^(\^\fIdisplay\fP, \fIw\fP\^, \fIstart\fP\^, \fIstop\fP\^, \fInevents_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Time \fIstart\fP\^, \fIstop\fP\^;	
+.br
+      int *\fInevents_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIstart\fP 1i
+.br
+.ns
+.IP \fIstop\fP 1i
+Specify the time interval in which the events are returned from the motion
+history buffer.
+You can pass a timestamp or
+.PN CurrentTime .
+.IP \fInevents_return\fP 1i
+Returns the number of events from the motion history buffer.
+.LP
+.eM
+The
+.PN XGetMotionEvents
+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;
+.PN XGetMotionEvents
+returns NULL.
+If the stop time is in the future, it is equivalent to specifying
+.PN CurrentTime .
+The return type for this function is a structure defined as follows:
+.LP
+.IN "XTimeCoord" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i
+.ta .5i
+typedef struct {
+	Time time;
+	short x, y;
+} XTimeCoord;
+.De
+.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
+.PN XFree .
+.LP
+.PN XGetMotionEvents
+can generate a
+.PN BadWindow 
+error.
+.NH 2
+Handling Protocol Errors
+.XS
+\*(SN Handling Protocol Errors
+.XE
+.LP
+Xlib provides functions that you can use to enable or disable synchronization
+and to use the default error handlers.
+.NH 3
+Enabling or Disabling Synchronization
+.XS
+\*(SN Enabling or Disabling Synchronization 
+.XE
+.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.
+.IN "_Xdebug"
+On POSIX-conformant systems,
+there is also a global variable 
+.PN _Xdebug 
+that, if set to nonzero before starting a program under a debugger, will force
+synchronous library behavior.
+.LP
+After completing their work,
+all Xlib functions that generate protocol requests call what is known as
+an after function.
+.PN XSetAfterFunction
+sets which function is to be called.
+.IN "XSetAfterFunction" "" "@DEF@"
+.sM
+.FD 0
+int (*XSetAfterFunction\^(\^\fIdisplay\fP, \fIprocedure\fP\^))()
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int (\^*\^\fIprocedure\fP\^)\^();
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIprocedure\fP 1i
+Specifies the procedure to be called.
+.LP
+.eM
+The specified procedure is called with only a display pointer.
+.PN XSetAfterFunction
+returns the previous after function.
+.LP
+To enable or disable synchronization, use 
+.PN XSynchronize .
+.IN "Debugging" "synchronous mode"
+.IN "XSynchronize" "" "@DEF@"
+.sM
+.FD 0
+int (*XSynchronize\^(\^\fIdisplay\fP, \fIonoff\fP\^)\^)()
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Bool \fIonoff\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIonoff\fP 1i
+Specifies a Boolean value that indicates whether to enable 
+or disable synchronization.
+.LP
+.eM
+The
+.PN XSynchronize
+function returns 
+the previous after function.
+If onoff is 
+.PN True , 
+.PN XSynchronize
+turns on synchronous behavior.
+If onoff is
+.PN False ,
+.PN XSynchronize 
+turns off synchronous behavior.
+.NH 3
+Using the Default Error Handlers
+.XS
+\*(SN Using the Default Error Handlers 
+.XE
+.LP
+.IN "Debugging" "error handlers"
+.IN "Error" "handlers"
+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.
+.LP
+.sp
+To set the error handler, use
+.PN XSetErrorHandler .
+.IN "XSetErrorHandler" "" "@DEF@"
+.sM
+.FD 0
+int (*XSetErrorHandler\^(\^\fIhandler\fP\^)\^)\^(\^)
+.br
+      int (\^*\^\fIhandler\fP\^)\^(Display *, XErrorEvent *)
+.FN
+.IP \fIhandler\fP 1i
+Specifies the program's supplied error handler.
+.LP
+.eM 
+Xlib generally calls the program's
+supplied error handler whenever an error is received.
+It is not called on
+.PN BadName
+errors from
+.PN OpenFont ,
+.PN LookupColor ,
+or
+.PN AllocNamedColor
+protocol requests or on
+.PN BadFont
+errors from a
+.PN QueryFont
+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.
+.LP
+The 
+.PN XErrorEvent
+structure contains:
+.IN "Debugging" "error event"
+.LP
+.IN "XErrorEvent" "" "@DEF"
+.Ds 0
+.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;
+.De
+.LP
+.IN "Serial Number"
+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 
+.PN NextRequest 
+immediately before the failing call was made.  
+The request_code member is a protocol request
+of the procedure that failed, as defined in 
+.hN X11/Xproto.h .
+The following error codes can be returned by the functions described in this
+chapter:
+.br
+.ne 13
+.IN "Debugging" "error numbers"
+.IN "Error" "codes"
+.\".CP T 3
+.\"Error Codes
+.IN "BadAccess" "" "@DEF@"
+.IN "BadAlloc" "" "@DEF@"
+.IN "BadAtom" "" "@DEF@"
+.IN "BadColor" "" "@DEF@"
+.IN "BadCursor" "" "@DEF@"
+.IN "BadDrawable" "" "@DEF@"
+.IN "BadFont" "" "@DEF@"
+.IN "BadGC" "" "@DEF@"
+.IN "BadIDChoice" "" "@DEF@"
+.TS H
+l c
+lw(1.75i) lw(4i).
+_
+.sp 6p
+.B
+Error Code	Description
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+T{
+.PN BadAccess
+T}	T{
+A client attempts to grab a key/button combination already grabbed 
+by another client.
+.sp 3p
+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.
+.sp 3p
+A client attempts to store into a read-only or unallocated colormap entry.
+.sp 3p
+A client attempts to modify the access control list from other than the local 
+(or otherwise authorized) host.
+.sp 3p
+A client attempts to select an event type that another client 
+has already selected.
+T}
+.sp 3p
+T{
+.PN BadAlloc
+T}	T{
+The server fails to allocate the requested resource.
+Note that the explicit listing of
+.PN BadAlloc
+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
+.PN BadAlloc
+error on any request for this reason,
+and clients should be prepared to receive such errors and handle or discard
+them.
+T}
+.sp 3p
+T{
+.PN BadAtom
+T}	T{
+A value for an atom argument does not name a defined atom.
+T}
+.sp 3p
+T{
+.PN BadColor
+T}	T{
+A value for a colormap argument does not name a defined colormap.
+T}
+.sp 3p
+T{
+.PN BadCursor
+T}	T{
+A value for a cursor argument does not name a defined cursor.
+T}
+.sp 3p
+T{
+.PN BadDrawable
+T}	T{
+A value for a drawable argument does not name a defined window or pixmap.
+T}
+.sp 3p
+T{
+.PN BadFont
+T}	T{
+A value for a font argument does not name a defined font (or, in some cases, 
+.PN GContext ).
+T}
+.sp 3p
+T{
+.PN BadGC
+T}	T{
+A value for a 
+.PN GContext 
+argument does not name a defined 
+.PN GContext .
+T}
+.sp 3p
+T{
+.PN BadIDChoice
+T}	T{
+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.
+T}
+.sp 3p
+T{
+.PN BadImplementation
+T}	T{
+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.
+T}
+.sp 3p
+T{
+.PN BadLength
+T}	T{
+The length of a request is shorter or longer than that required to 
+contain the arguments.
+This is an internal Xlib or server error.
+.sp 3p
+The length of a request exceeds the maximum length accepted by the server.
+T}
+.sp 3p
+T{
+.PN BadMatch
+T}	T{
+In a graphics request,
+the root and depth of the graphics context do not match those of the drawable.
+.sp 3p
+An 
+.PN InputOnly 
+window is used as a drawable.
+.sp 3p
+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.
+.sp 3p
+An 
+.PN InputOnly 
+window lacks this attribute.
+T}
+.sp 3p
+T{
+.PN BadName
+T}	T{
+A font or color of the specified name does not exist.
+T}
+.sp 3p
+T{
+.PN BadPixmap
+T}	T{
+A value for a pixmap argument does not name a defined pixmap.
+T}
+.sp 3p
+T{
+.PN BadRequest
+T}	T{
+The major or minor opcode does not specify a valid request.
+This usually is an Xlib or server error.
+T}
+.sp 3p
+T{
+.PN BadValue
+T}	T{
+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).
+T}
+.sp 3p
+T{
+.PN BadWindow
+T}	T{
+A value for a window argument does not name a defined window.
+T}
+.sp 6p
+_
+.TE
+.IN "BadImplementation" "" "@DEF@"
+.IN "BadLength" "" "@DEF@"
+.IN "BadMatch" "" "@DEF@"
+.IN "BadName" "" "@DEF@"
+.IN "BadPixmap" "" "@DEF@"
+.IN "BadRequest" "" "@DEF@"
+.IN "BadValue" "" "@DEF@"
+.IN "BadWindow" "" "@DEF@"
+.NT Note
+The 
+.PN BadAtom , 
+.PN BadColor , 
+.PN BadCursor , 
+.PN BadDrawable , 
+.PN BadFont , 
+.PN BadGC , 
+.PN BadPixmap , 
+and 
+.PN BadWindow
+errors are also used when the argument type is extended by a set of
+fixed alternatives.
+.NE
+.sp
+.LP
+To obtain textual descriptions of the specified error code, use 
+.PN XGetErrorText .
+.IN "XGetErrorText" "" "@DEF@"
+.IN "Debugging" "error message strings"
+.sM
+.FD 0
+XGetErrorText\^(\^\fIdisplay\fP, \fIcode\fP, \fIbuffer_return\fP, \fIlength\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIcode\fP\^;
+.br
+      char *\fIbuffer_return\fP\^;
+.br
+      int \fIlength\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIcode\fP 1i
+Specifies the error code for which you want to obtain a description.
+.IP \fIbuffer_return\fP 1i
+Returns the error description.
+.IP \fIlength\fP 1i
+Specifies the size of the buffer.
+.LP
+.eM 
+The
+.PN XGetErrorText
+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.
+.LP
+.sp
+To obtain error messages from the error database, use
+.PN XGetErrorDatabaseText .
+.IN "XGetErrorDatabaseText" "" "@DEF@"
+.sM
+.FD 0
+XGetErrorDatabaseText\^(\^\fIdisplay\fP, \fIname\fP, \fImessage\fP, \fIdefault_string\fP, \fIbuffer_return\fP, \fIlength\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      char *\fIname\fP, *\fImessage\fP\^;
+.br
+      char *\fIdefault_string\fP\^;
+.br
+      char *\fIbuffer_return\fP\^;
+.br
+      int \fIlength\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIname\fP 1i
+Specifies the name of the application.
+.IP \fImessage\fP 1i
+Specifies the type of the error message.
+.IP \fIdefault_string\fP 1i
+Specifies the default error message if none is found in the database.
+.IP \fIbuffer_return\fP 1i
+Returns the error description.
+.IP \fIlength\fP 1i
+Specifies the size of the buffer.
+.LP
+.eM
+The
+.PN XGetErrorDatabaseText
+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.
+.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.
+.IP XProtoError 1i
+The protocol error number is used as a string for the message argument.
+.IP XlibMessage 1i
+These are the message strings that are used internally by the library.
+.IP XRequest 1i
+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
+.PN InitExtension )
+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.
+.LP
+.sp
+To report an error to the user when the requested display does not exist, use
+.PN XDisplayName .
+.IN "XDisplayName" "" "@DEF@"
+.sM
+.FD 0
+char *XDisplayName\^(\^\fIstring\fP\^)
+.br
+      char *\fIstring\fP\^;
+.FN
+.IP \fIstring\fP 1i
+Specifies the character string.
+.LP
+.eM
+The
+.PN XDisplayName
+function returns the name of the display that 
+.PN XOpenDisplay
+would attempt to use.
+If a NULL string is specified,
+.PN XDisplayName
+looks in the environment for the display and returns the display name that
+.PN XOpenDisplay
+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.
+.LP
+.sp
+To handle fatal I/O errors, use
+.PN XSetIOErrorHandler .
+.IN "XSetIOErrorHandler" "" "@DEF@"
+.sM
+.FD 0
+int (*XSetIOErrorHandler\^(\^\fIhandler\fP\^)\^)\^(\^)
+.br
+      int (\^*\^\fIhandler\fP\^)(Display *);
+.FN
+.IP \fIhandler\fP 1i
+Specifies the program's supplied error handler.
+.LP
+.eM
+The
+.PN XSetIOErrorHandler
+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.
+.LP
+Note that the previous error handler is returned.
+.bp
diff --git a/specs/libX11/CH12 b/specs/libX11/CH12
new file mode 100644
index 00000000..08b9ba93
--- /dev/null
+++ b/specs/libX11/CH12
@@ -0,0 +1,2680 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 12\fP\s-1
+
+\s+1\fBInput Device Functions\fP\s-1
+.sp 2
+.nr H1 12
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.na
+.LP
+.XS
+Chapter 12: Input Device Functions
+.XE
+You can use the Xlib input device functions to:
+.IP \(bu 5
+Grab the pointer and individual buttons on the pointer
+.IP \(bu 5
+Grab the keyboard and individual keys on the keyboard
+.IP \(bu 5
+Resume event processing
+.IP \(bu 5
+Move the pointer
+.IP \(bu 5
+Set the input focus
+.IP \(bu 5
+Manipulate the keyboard and pointer settings
+.IP \(bu 5
+Manipulate the keyboard encoding
+.NH 2
+Pointer Grabbing 
+.XS
+\*(SN Pointer Grabbing  
+.XE
+.LP
+Xlib provides functions that you can use to control input from the pointer,
+which usually is a mouse.
+Usually, as soon as keyboard and mouse events occur,
+the X server delivers them to the appropriate client,
+which is determined by the window and input focus.
+The X server provides sufficient control over event delivery to
+allow window managers to support mouse ahead and various other
+styles of user interface.
+Many of these user interfaces depend on synchronous delivery of events.
+The delivery of  pointer and keyboard events can be controlled
+independently.
+.LP
+When mouse buttons or keyboard keys are grabbed, events
+will be sent to the grabbing client rather than the normal
+client who would have received the event.
+If the keyboard or pointer is in asynchronous mode,
+further mouse and keyboard events will continue to be processed.
+If the keyboard or pointer is in synchronous mode, no
+further events are processed until the grabbing client
+allows them (see
+.PN XAllowEvents ).
+The keyboard or pointer is considered frozen during this
+interval.
+The event that triggered the grab can also be replayed.
+.LP
+Note that the logical state of a device (as seen by client applications)
+may lag the physical state if device event processing is frozen.
+.LP
+.IN "Active grab" "" "@DEF@"
+There are two kinds of grabs:
+active and passive.
+An active grab occurs when a single client grabs the keyboard and/or pointer
+explicitly (see
+.PN XGrabPointer
+and
+.PN XGrabKeyboard ).
+.IN "Passive grab"
+A passive grab occurs when clients grab a particular keyboard key 
+or pointer button in a window,
+and the grab will activate when the key or button is actually pressed.
+Passive grabs are convenient for implementing reliable pop-up menus.
+For example, you can guarantee that the pop-up is mapped 
+before the up pointer button event occurs by
+grabbing a button requesting synchronous behavior.
+The down event will trigger the grab and freeze further
+processing of pointer events until you have the chance to
+map the pop-up window.
+You can then allow further event processing.
+The up event will then be correctly processed relative to the
+pop-up window.
+.LP
+For many operations,
+there are functions that take a time argument.
+The X server includes a timestamp in various events.
+One special time, called
+.IN "CurrentTime" "" "@DEF@"
+.IN "Time" "" "@DEF@"
+.PN CurrentTime ,
+represents the current server time.
+The X server maintains the time when the input focus was last changed,
+when the keyboard was last grabbed,
+when the pointer was last grabbed,
+or when a selection was last changed.
+Your
+application may be slow reacting to an event.
+You often need some way to specify that your
+request should not occur if another application has in the meanwhile
+taken control of the keyboard, pointer, or selection.
+By providing the timestamp from the event in the request, 
+you can arrange that the operation not take effect
+if someone else has performed an operation in the meanwhile.
+.LP
+A timestamp is a time value, expressed in milliseconds. 
+It typically is the time since the last server reset.
+Timestamp values wrap around (after about 49.7 days).
+The server, given its current time is represented by timestamp T, 
+always interprets timestamps from clients by treating half of the timestamp 
+space as being later in time than T.
+One timestamp value, named
+.PN CurrentTime ,
+is never generated by the server.
+This value is reserved for use in requests to represent the current server time.
+.LP
+For many functions in this section,
+you pass pointer event mask bits.
+The valid pointer event mask bits are:
+.PN ButtonPressMask ,
+.PN ButtonReleaseMask ,
+.PN EnterWindowMask ,
+.PN LeaveWindowMask ,
+.PN PointerMotionMask ,
+.PN PointerMotionHintMask ,
+.PN Button1MotionMask ,
+.PN Button2MotionMask ,
+.PN Button3MotionMask ,
+.PN Button4MotionMask ,
+.PN Button5MotionMask ,
+.PN ButtonMotionMask ,
+and
+.PN KeyMapStateMask .
+For other functions in this section,
+you pass keymask bits.
+The valid keymask bits are:
+.PN ShiftMask ,
+.PN LockMask ,
+.PN ControlMask ,
+.PN Mod1Mask ,
+.PN Mod2Mask ,
+.PN Mod3Mask ,
+.PN Mod4Mask ,
+and
+.PN Mod5Mask .
+.LP
+.sp
+To grab the pointer, use
+.PN XGrabPointer .
+.IN "Grabbing" "pointer"
+.IN "Pointer" "grabbing"
+.IN "XGrabPointer" "" "@DEF@"
+.sM
+.FD 0
+int XGrabPointer\^(\^\fIdisplay\fP, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIevent_mask\fP\^, \fIpointer_mode\fP\^,
+               \fIkeyboard_mode\fP\^, \fIconfine_to\fP\^, \fIcursor\fP\^, \fItime\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIgrab_window\fP\^;
+.br
+      Bool \fIowner_events\fP\^;
+.br
+      unsigned int \fIevent_mask\fP\^;	
+.br
+      int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^; 
+.br
+      Window \fIconfine_to\fP\^; 
+.br
+      Cursor \fIcursor\fP\^; 
+.br
+      Time \fItime\fP\^; 
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgrab_window\fP 1i
+Specifies the grab window.
+.IP \fIowner_events\fP 1i
+Specifies a Boolean value that indicates whether the pointer 
+events are to be reported as usual or reported with respect to the grab window 
+if selected by the event mask.
+.IP \fIevent_mask\fP 1i
+Specifies which pointer events are reported to the client.
+The mask is the bitwise inclusive OR of the valid pointer event mask bits.
+.IP \fIpointer_mode\fP 1i
+Specifies further processing of pointer events.
+You can pass 
+.PN GrabModeSync 
+or
+.PN GrabModeAsync .
+.IP \fIkeyboard_mode\fP 1i
+Specifies further processing of keyboard events.
+You can pass 
+.PN GrabModeSync 
+or
+.PN GrabModeAsync .
+.IP \fIconfine_to\fP 1i
+Specifies the window to confine the pointer in or
+.PN None .
+.IP \fIcursor\fP 1i
+Specifies the cursor that is to be displayed during the grab or
+.PN None . 
+.IP \fItime\fP 1i
+Specifies the time.
+You can pass either a timestamp or
+.PN CurrentTime .
+.LP
+.eM
+The
+.PN XGrabPointer
+function actively grabs control of the pointer and returns
+.PN GrabSuccess
+if the grab was successful.
+Further pointer events are reported only to the grabbing client.
+.PN XGrabPointer
+overrides any active pointer grab by this client.
+If owner_events is 
+.PN False , 
+all generated pointer events
+are reported with respect to grab_window and are reported only if
+selected by event_mask.
+If owner_events is 
+.PN True
+and if a generated
+pointer event would normally be reported to this client, 
+it is reported as usual. 
+Otherwise, the event is reported with respect to the
+grab_window and is reported only if selected by event_mask.
+For either value of owner_events, unreported events are discarded.
+.LP
+If the pointer_mode is 
+.PN GrabModeAsync , 
+pointer event processing continues as usual.
+If the pointer is currently frozen by this client, 
+the processing of events for the pointer is resumed.
+If the pointer_mode is 
+.PN GrabModeSync , 
+the state of the pointer, as seen by
+client applications,
+appears to freeze, and the X server generates no further pointer events
+until the grabbing client calls 
+.PN XAllowEvents
+or until the pointer grab is released.
+Actual pointer changes are not lost while the pointer is frozen;
+they are simply queued in the server for later processing.
+.LP
+If the keyboard_mode is 
+.PN GrabModeAsync , 
+keyboard event processing is unaffected by activation of the grab.
+If the keyboard_mode is 
+.PN GrabModeSync , 
+the state of the keyboard, as seen by
+client applications,
+appears to freeze, and the X server generates no further keyboard events
+until the grabbing client calls 
+.PN XAllowEvents
+or until the pointer grab is released.
+Actual keyboard changes are not lost while the pointer is frozen;
+they are simply queued in the server for later processing.
+.LP
+If a cursor is specified, it is displayed regardless of what
+window the pointer is in.  
+If 
+.PN None
+is specified,
+the normal cursor for that window is displayed
+when the pointer is in grab_window or one of its subwindows;
+otherwise, the cursor for grab_window is displayed.
+.LP
+If a confine_to window is specified,
+the pointer is restricted to stay contained in that window.
+The confine_to window need have no relationship to the grab_window.
+If the pointer is not initially in the confine_to window, 
+it is warped automatically to the closest edge 
+just before the grab activates and enter/leave events are generated as usual. 
+If the confine_to window is subsequently reconfigured, 
+the pointer is warped automatically, as necessary, 
+to keep it contained in the window.
+.LP
+The time argument allows you to avoid certain circumstances that come up
+if applications take a long time to respond or if there are long network
+delays.
+Consider a situation where you have two applications, both
+of which normally grab the pointer when clicked on.
+If both applications specify the timestamp from the event, 
+the second application may wake up faster and successfully grab the pointer
+before the first application. 
+The first application then will get an indication that the other application 
+grabbed the pointer before its request was processed.
+.LP
+.PN XGrabPointer 
+generates
+.PN EnterNotify 
+and
+.PN LeaveNotify 
+events.
+.LP
+Either if grab_window or confine_to window is not viewable
+or if the confine_to window lies completely outside the boundaries of the root
+window,
+.PN XGrabPointer
+fails and returns
+.PN GrabNotViewable .
+If the pointer is actively grabbed by some other client,
+it fails and returns
+.PN AlreadyGrabbed .
+If the pointer is frozen by an active grab of another client,
+it fails and returns
+.PN GrabFrozen .
+If the specified time is earlier than the last-pointer-grab time or later 
+than the current X server time, it fails and returns
+.PN GrabInvalidTime .
+Otherwise, the last-pointer-grab time is set to the specified time
+.Pn ( CurrentTime 
+is replaced by the current X server time).
+.LP
+.PN XGrabPointer
+can generate
+.PN BadCursor ,
+.PN BadValue ,
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To ungrab the pointer, use
+.PN XUngrabPointer .
+.IN "Ungrabbing" "pointer"
+.IN "Pointer" "ungrabbing"
+.IN "XUngrabPointer" "" "@DEF@"
+.sM
+.FD 0
+XUngrabPointer\^(\^\fIdisplay\fP, \fItime\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Time \fItime\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fItime\fP 1i
+Specifies the time.
+You can pass either a timestamp or
+.PN CurrentTime .
+.LP
+.eM
+The
+.PN XUngrabPointer
+function releases the pointer and any queued events
+if this client has actively grabbed the pointer from
+.PN XGrabPointer ,
+.PN XGrabButton ,
+or from a normal button press.
+.PN XUngrabPointer
+does not release the pointer if the specified
+time is earlier than the last-pointer-grab time or is later than the
+current X server time.
+It also generates 
+.PN EnterNotify 
+and 
+.PN LeaveNotify 
+events.
+The X server performs an 
+.PN UngrabPointer 
+request automatically if the event window or confine_to window 
+for an active pointer grab becomes not viewable
+or if window reconfiguration causes the confine_to window to lie completely
+outside the boundaries of the root window.
+.LP
+.sp
+To change an active pointer grab, use
+.PN XChangeActivePointerGrab .
+.IN "Pointer" "grabbing"
+.IN "Changing" "pointer grab" 
+.IN "XChangeActivePointerGrab" "" "@DEF@"
+.sM
+.FD 0
+XChangeActivePointerGrab\^(\^\fIdisplay\fP, \fIevent_mask\fP\^, \fIcursor\fP\^, \fItime\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      unsigned int \fIevent_mask\fP\^;
+.br
+      Cursor \fIcursor\fP\^;
+.br
+      Time \fItime\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIevent_mask\fP 1i
+Specifies which pointer events are reported to the client.
+The mask is the bitwise inclusive OR of the valid pointer event mask bits.
+.IP \fIcursor\fP 1i
+Specifies the cursor that is to be displayed or
+.PN None .
+.IP \fItime\fP 1i
+Specifies the time.
+You can pass either a timestamp or
+.PN CurrentTime .
+.LP
+.eM
+The
+.PN XChangeActivePointerGrab
+function changes the specified dynamic parameters if the pointer is actively
+grabbed by the client and if the specified time is no earlier than the
+last-pointer-grab time and no later than the current X server time.
+This function has no effect on the passive parameters of an
+.PN XGrabButton .
+The interpretation of event_mask and cursor is the same as described in
+.PN XGrabPointer .
+.LP
+.PN XChangeActivePointerGrab
+can generate
+.PN BadCursor 
+and
+.PN BadValue
+errors.
+.LP
+.sp
+To grab a pointer button, use
+.PN XGrabButton .
+.IN "Grabbing" "buttons"
+.IN "Button" "grabbing"
+.IN "XGrabButton" "" "@DEF@"
+.sM
+.FD 0
+XGrabButton\^(\^\fIdisplay\fP, \fIbutton\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIevent_mask\fP\^, 
+.br
+                \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^, \fIconfine_to\fP\^, \fIcursor\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      unsigned int \fIbutton\fP\^;
+.br
+      unsigned int \fImodifiers\fP\^;
+.br
+      Window \fIgrab_window\fP\^;
+.br
+      Bool \fIowner_events\fP\^;
+.br
+      unsigned int \fIevent_mask\fP\^;	
+.br
+      int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^;
+.br
+      Window \fIconfine_to\fP\^; 
+.br
+      Cursor \fIcursor\fP\^; 
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Bu grabbed
+.IP \fIbutton\fP 1i
+Specifies the pointer button that is to be \*(Bu or
+.PN AnyButton .
+.IP \fImodifiers\fP 1i
+Specifies the set of keymasks or
+.PN AnyModifier .
+The mask is the bitwise inclusive OR of the valid keymask bits.
+.IP \fIgrab_window\fP 1i
+Specifies the grab window.
+.IP \fIowner_events\fP 1i
+Specifies a Boolean value that indicates whether the pointer 
+events are to be reported as usual or reported with respect to the grab window 
+if selected by the event mask.
+.IP \fIevent_mask\fP 1i
+Specifies which pointer events are reported to the client.
+The mask is the bitwise inclusive OR of the valid pointer event mask bits.
+.IP \fIpointer_mode\fP 1i
+Specifies further processing of pointer events.
+You can pass 
+.PN GrabModeSync 
+or
+.PN GrabModeAsync .
+.IP \fIkeyboard_mode\fP 1i
+Specifies further processing of keyboard events.
+You can pass 
+.PN GrabModeSync 
+or
+.PN GrabModeAsync .
+.IP \fIconfine_to\fP 1i
+Specifies the window to confine the pointer in or
+.PN None .
+.IP \fIcursor\fP 1i
+Specifies the cursor that is to be displayed or
+.PN None .
+.LP
+.eM
+The
+.PN XGrabButton
+function establishes a passive grab.
+In the future,
+the pointer is actively grabbed (as for
+.PN XGrabPointer ),
+the last-pointer-grab time is set to the time at which the button was pressed
+(as transmitted in the
+.PN ButtonPress
+event), and the
+.PN ButtonPress
+event is reported if all of the following conditions are true:
+.IP \(bu 5
+The pointer is not grabbed, and the specified button is logically pressed
+when the specified modifier keys are logically down,
+and no other buttons or modifier keys are logically down.
+.IP \(bu 5
+The grab_window contains the pointer.
+.IP \(bu 5
+The confine_to window (if any) is viewable.
+.IP \(bu 5
+A passive grab on the same button/key combination does not exist
+on any ancestor of grab_window.
+.LP
+The interpretation of the remaining arguments is as for
+.PN XGrabPointer .
+The active grab is terminated automatically when the logical state of the
+pointer has all buttons released
+(independent of the state of the logical modifier keys).
+.LP
+Note that the logical state of a device (as seen by client applications)
+may lag the physical state if device event processing is frozen.
+.LP
+This request overrides all previous grabs by the same client on the same
+button/key combinations on the same window.
+A modifiers of 
+.PN AnyModifier 
+is equivalent to issuing the grab request for all
+possible modifier combinations (including the combination of no modifiers).  
+It is not required that all modifiers specified have currently assigned 
+KeyCodes.
+A button of 
+.PN AnyButton 
+is equivalent to
+issuing the request for all possible buttons.
+Otherwise, it is not required that the specified button currently be assigned
+to a physical button.
+.LP
+If some other client has already issued an
+.PN XGrabButton
+with the same button/key combination on the same window, a
+.PN BadAccess 
+error results.
+When using 
+.PN AnyModifier 
+or 
+.PN AnyButton , 
+the request fails completely,
+and a
+.PN BadAccess
+error results (no grabs are
+established) if there is a conflicting grab for any combination.
+.PN XGrabButton
+has no effect on an active grab.
+.LP
+.PN XGrabButton
+can generate
+.PN BadCursor ,
+.PN BadValue ,
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To ungrab a pointer button, use
+.PN XUngrabButton .
+.IN "Ungrabbing" "buttons"
+.IN "Button" "ungrabbing"
+.IN "XUngrabButton" "" "@DEF@"
+.sM
+.FD 0
+XUngrabButton\^(\^\fIdisplay\fP, \fIbutton\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      unsigned int \fIbutton\fP\^;
+.br
+      unsigned int \fImodifiers\fP\^;
+.br
+      Window \fIgrab_window\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Bu released
+.IP \fIbutton\fP 1i
+Specifies the pointer button that is to be \*(Bu or
+.PN AnyButton .
+.IP \fImodifiers\fP 1i
+Specifies the set of keymasks or
+.PN AnyModifier .
+The mask is the bitwise inclusive OR of the valid keymask bits.
+.IP \fIgrab_window\fP 1i
+Specifies the grab window.
+.LP
+.eM
+The
+.PN XUngrabButton
+function releases the passive button/key combination on the specified window if
+it was grabbed by this client.
+A modifiers of 
+.PN AnyModifier 
+is
+equivalent to issuing 
+the ungrab request for all possible modifier combinations, including 
+the combination of no modifiers.
+A button of 
+.PN AnyButton 
+is equivalent to issuing the
+request for all possible buttons.
+.PN XUngrabButton
+has no effect on an active grab.
+.LP
+.PN XUngrabButton
+can generate
+.PN BadValue
+and
+.PN BadWindow 
+errors.
+.NH 2
+Keyboard Grabbing 
+.XS
+\*(SN Keyboard Grabbing 
+.XE
+.LP
+Xlib provides functions that you can use to grab or ungrab the keyboard
+as well as allow events.
+.LP
+For many functions in this section,
+you pass keymask bits.
+The valid keymask bits are:
+.PN ShiftMask ,
+.PN LockMask ,
+.PN ControlMask ,
+.PN Mod1Mask ,
+.PN Mod2Mask ,
+.PN Mod3Mask ,
+.PN Mod4Mask ,
+and
+.PN Mod5Mask .
+.LP
+.sp
+To grab the keyboard, use
+.PN XGrabKeyboard .
+.IN "Keyboard" "grabbing"
+.IN "Grabbing" "keyboard"
+.IN "XGrabKeyboard" "" "@DEF@"
+.sM
+.FD 0
+int XGrabKeyboard\^(\^\fIdisplay\fP, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^, \fItime\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIgrab_window\fP\^;
+.br
+      Bool \fIowner_events\fP\^;
+.br
+      int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^;
+.br
+      Time \fItime\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgrab_window\fP 1i
+Specifies the grab window.
+.IP \fIowner_events\fP 1i
+Specifies a Boolean value that indicates whether the keyboard events 
+are to be reported as usual.
+.IP \fIpointer_mode\fP 1i
+Specifies further processing of pointer events.
+You can pass 
+.PN GrabModeSync 
+or
+.PN GrabModeAsync .
+.IP \fIkeyboard_mode\fP 1i
+Specifies further processing of keyboard events.
+You can pass 
+.PN GrabModeSync 
+or
+.PN GrabModeAsync .
+.IP \fItime\fP 1i
+Specifies the time.
+You can pass either a timestamp or
+.PN CurrentTime .
+.LP
+.eM
+The
+.PN XGrabKeyboard
+function actively grabs control of the keyboard and generates
+.PN FocusIn
+and
+.PN FocusOut
+events.
+Further key events are reported only to the
+grabbing client.
+.PN XGrabKeyboard
+overrides any active keyboard grab by this client.
+If owner_events is 
+.PN False , 
+all generated key events are reported with
+respect to grab_window.  
+If owner_events is 
+.PN True  
+and if a generated
+key event would normally be reported to this client, it is reported
+normally; otherwise, the event is reported with respect to the
+grab_window.  
+Both 
+.PN KeyPress 
+and 
+.PN KeyRelease 
+events are always reported,
+independent of any event selection made by the client.
+.LP
+If the keyboard_mode argument is 
+.PN GrabModeAsync ,
+keyboard event processing continues
+as usual. 
+If the keyboard is currently frozen by this client, 
+then processing of keyboard events is resumed.
+If the keyboard_mode  argument is
+.PN GrabModeSync ,
+the state of the keyboard (as seen by client applications) appears to freeze,
+and the X server generates no further keyboard events until the
+grabbing client issues a releasing 
+.PN XAllowEvents 
+call or until the keyboard grab is released.
+Actual keyboard changes are not lost while the keyboard is frozen; 
+they are simply queued in the server for later processing.
+.LP
+If pointer_mode is 
+.PN GrabModeAsync ,
+pointer event processing is unaffected
+by activation of the grab.  
+If pointer_mode is 
+.PN GrabModeSync ,
+the state of the pointer (as seen by client applications) appears to freeze, 
+and the X server generates no further pointer events 
+until the grabbing client issues a releasing 
+.PN XAllowEvents 
+call or until the keyboard grab is released.
+Actual pointer changes are not lost while the pointer is frozen; 
+they are simply queued in the server for later processing.
+.LP
+If the keyboard is actively grabbed by some other client,
+.PN XGrabKeyboard
+fails and returns
+.PN AlreadyGrabbed .
+If grab_window is not viewable,
+it fails and returns
+.PN GrabNotViewable .
+If the keyboard is frozen by an active grab of another client,
+it fails and returns
+.PN GrabFrozen .
+If the specified time is earlier than the last-keyboard-grab time 
+or later than the current X server time,
+it fails and returns
+.PN GrabInvalidTime .
+Otherwise, the last-keyboard-grab time is set to the specified time
+.Pn ( CurrentTime 
+is replaced by the current X server time).
+.LP
+.PN XGrabKeyboard
+can generate
+.PN BadValue
+and 
+.PN BadWindow 
+errors.
+.LP
+.sp
+To ungrab the keyboard, use
+.PN XUngrabKeyboard .
+.IN "Keyboard" "ungrabbing"
+.IN "Ungrabbing" "keyboard"
+.IN "XUngrabKeyboard" "" "@DEF@"
+.sM
+.FD 0
+XUngrabKeyboard\^(\^\fIdisplay\fP, \fItime\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Time \fItime\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fItime\fP 1i
+Specifies the time.
+You can pass either a timestamp or
+.PN CurrentTime .
+.LP
+.eM
+The
+.PN XUngrabKeyboard
+function
+releases the keyboard and any queued events if this client has it actively grabbed from
+either
+.PN XGrabKeyboard
+or
+.PN XGrabKey .
+.PN XUngrabKeyboard
+does not release the keyboard and any queued events
+if the specified time is earlier than
+the last-keyboard-grab time or is later than the current X server time.
+It also generates
+.PN FocusIn 
+and 
+.PN FocusOut 
+events.
+The X server automatically performs an 
+.PN UngrabKeyboard 
+request if the event window for an
+active keyboard grab becomes not viewable.
+.LP
+.sp
+To passively grab a single key of the keyboard, use
+.PN XGrabKey .
+.IN "Key" "grabbing"
+.IN "Grabbing" "keys"
+.IN "XGrabKey" "" "@DEF@"
+.sM
+.FD 0
+XGrabKey\^(\^\fIdisplay\fP, \fIkeycode\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIpointer_mode\fP\^, 
+.br
+             \fIkeyboard_mode\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIkeycode\fP\^;
+.br
+      unsigned int \fImodifiers\fP\^;
+.br
+      Window \fIgrab_window\fP\^;
+.br
+      Bool \fIowner_events\fP\^;
+.br
+      int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIkeycode\fP 1i
+Specifies the KeyCode or
+.PN AnyKey .
+.IP \fImodifiers\fP 1i
+Specifies the set of keymasks or
+.PN AnyModifier .
+The mask is the bitwise inclusive OR of the valid keymask bits.
+.IP \fIgrab_window\fP 1i
+Specifies the grab window.
+.IP \fIowner_events\fP 1i
+Specifies a Boolean value that indicates whether the keyboard events 
+are to be reported as usual.
+.IP \fIpointer_mode\fP 1i
+Specifies further processing of pointer events.
+You can pass 
+.PN GrabModeSync 
+or
+.PN GrabModeAsync .
+.IP \fIkeyboard_mode\fP 1i
+Specifies further processing of keyboard events.
+You can pass 
+.PN GrabModeSync 
+or
+.PN GrabModeAsync .
+.LP
+.eM
+The
+.PN XGrabKey
+function establishes a passive grab on the keyboard.
+In the future,
+the keyboard is actively grabbed (as for
+.PN XGrabKeyboard ),
+the last-keyboard-grab time is set to the time at which the key was pressed
+(as transmitted in the
+.PN KeyPress
+event), and the
+.PN KeyPress
+event is reported if all of the following conditions are true:
+.IP \(bu 5
+The keyboard is not grabbed and the specified key
+(which can itself be a modifier key) is logically pressed
+when the specified modifier keys are logically down,
+and no other modifier keys are logically down.
+.IP \(bu 5
+Either the grab_window is an ancestor of (or is) the focus window,
+or the grab_window is a descendant of the focus window and contains the pointer.
+.IP \(bu 5
+A passive grab on the same key combination does not exist
+on any ancestor of grab_window.
+.LP
+The interpretation of the remaining arguments is as for 
+.PN XGrabKeyboard .
+The active grab is terminated automatically when the logical state of the
+keyboard has the specified key released
+(independent of the logical state of the modifier keys).
+.LP
+Note that the logical state of a device (as seen by client applications)
+may lag the physical state if device event processing is frozen.
+.LP
+A modifiers argument of 
+.PN AnyModifier
+is equivalent to issuing the request for all
+possible modifier combinations (including the combination of no
+modifiers).  
+It is not required that all modifiers specified have
+currently assigned KeyCodes.
+A keycode argument of 
+.PN AnyKey
+is equivalent to issuing
+the request for all possible KeyCodes.
+Otherwise, the specified keycode must be in
+the range specified by min_keycode and max_keycode in the connection
+setup, 
+or a
+.PN BadValue
+error results.
+.LP
+If some other client has issued a 
+.PN XGrabKey
+with the same key combination on the same window, a 
+.PN BadAccess 
+error results.
+When using
+.PN AnyModifier
+or 
+.PN AnyKey ,
+the request fails completely,
+and a
+.PN BadAccess 
+error results (no grabs are established) 
+if there is a conflicting grab for any combination.
+.LP
+.PN XGrabKey
+can generate
+.PN BadAccess ,
+.PN BadValue , 
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To ungrab a key, use
+.PN XUngrabKey .
+.IN "Key" "ungrabbing"
+.IN "Ungrabbing" "keys"
+.IN "XUngrabKey" "" "@DEF@"
+.sM
+.FD 0
+XUngrabKey\^(\^\fIdisplay\fP, \fIkeycode\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIkeycode\fP\^;
+.br
+      unsigned int \fImodifiers\fP\^;
+.br
+      Window \fIgrab_window\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIkeycode\fP 1i
+Specifies the KeyCode or
+.PN AnyKey .
+.IP \fImodifiers\fP 1i
+Specifies the set of keymasks or
+.PN AnyModifier .
+The mask is the bitwise inclusive OR of the valid keymask bits.
+.IP \fIgrab_window\fP 1i
+Specifies the grab window.
+.LP
+.eM
+The
+.PN XUngrabKey
+function releases the key combination on the specified window if it was grabbed
+by this client.
+It has no effect on an active grab.
+A modifiers of
+.PN AnyModifier
+is equivalent to issuing
+the request for all possible modifier combinations
+(including the combination of no modifiers).
+A keycode argument of
+.PN AnyKey
+is equivalent to issuing the request for all possible key codes.
+.LP
+.PN XUngrabKey
+can generate
+.PN BadValue
+and
+.PN BadWindow 
+errors.
+.NH 2
+Resuming Event Processing
+.XS
+\*(SN Resuming Event Processing
+.XE
+.LP
+The previous sections discussed grab mechanisms with which processing
+of events by the server can be temporarily suspended.  This section
+describes the mechanism for resuming event processing.
+.LP
+.sp
+To allow further events to be processed when the device has been frozen, use
+.PN XAllowEvents .
+.IN "XAllowEvents" "" "@DEF@"
+.sM
+.FD 0
+XAllowEvents\^(\^\fIdisplay\fP, \fIevent_mode\fP\^, \fItime\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIevent_mode\fP\^; 
+.br
+      Time \fItime\fP\^; 
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIevent_mode\fP 1i
+Specifies the event mode.
+You can pass 
+.PN AsyncPointer , 
+.PN SyncPointer , 
+.PN AsyncKeyboard , 
+.PN SyncKeyboard ,
+.PN ReplayPointer , 
+.PN ReplayKeyboard ,
+.PN AsyncBoth ,
+or
+.PN SyncBoth .
+.IP \fItime\fP 1i
+Specifies the time.
+You can pass either a timestamp or
+.PN CurrentTime .
+.LP
+.eM
+The
+.PN XAllowEvents
+function releases some queued events if the client has caused a device 
+to freeze.
+It has no effect if the specified time is earlier than the last-grab
+time of the most recent active grab for the client or if the specified time
+is later than the current X server time.
+Depending on the event_mode argument, the following occurs:
+.TS
+lw(1.25i) lw(4.5i).
+T{
+.PN AsyncPointer
+T}	T{
+If the pointer is frozen by the client,
+pointer event processing continues as usual.
+If the pointer is frozen twice by the client on behalf of two separate grabs,
+.PN AsyncPointer 
+thaws for both.
+.PN AsyncPointer
+has no effect if the pointer is not frozen by the client,
+but the pointer need not be grabbed by the client.
+T}
+.sp 6p
+T{
+.PN SyncPointer 
+T}	T{
+If the pointer is frozen and actively grabbed by the client,
+pointer event processing continues as usual until the next 
+.PN ButtonPress 
+or 
+.PN ButtonRelease 
+event is reported to the client.
+At this time, 
+the pointer again appears to freeze.
+However, if the reported event causes the pointer grab to be released,
+the pointer does not freeze.
+.PN SyncPointer 
+has no effect if the pointer is not frozen by the client
+or if the pointer is not grabbed by the client.
+T}
+.sp 6p
+T{
+.PN ReplayPointer
+T}	T{
+If the pointer is actively grabbed by the client and is frozen as the result of
+an event having been sent to the client (either from the activation of an 
+.PN XGrabButton 
+or from a previous 
+.PN XAllowEvents 
+with mode 
+.PN SyncPointer
+but not from an 
+.PN XGrabPointer ),
+the pointer grab is released and that event is completely reprocessed.
+This time, however, the function ignores any passive grabs at or above 
+(toward the root of) the grab_window of the grab just released.
+The request has no effect if the pointer is not grabbed by the client
+or if the pointer is not frozen as the result of an event.
+T}
+.sp 6p
+T{
+.PN AsyncKeyboard 
+T}	T{
+If the keyboard is frozen by the client,
+keyboard event processing continues as usual.
+If the keyboard is frozen twice by the client on behalf of two separate grabs,
+.PN AsyncKeyboard 
+thaws for both.
+.PN AsyncKeyboard 
+has no effect if the keyboard is not frozen by the client,
+but the keyboard need not be grabbed by the client.
+T}
+.sp 6p
+T{
+.PN SyncKeyboard
+T}	T{
+If the keyboard is frozen and actively grabbed by the client,
+keyboard event processing continues as usual until the next 
+.PN KeyPress 
+or 
+.PN KeyRelease 
+event is reported to the client.
+At this time,
+the keyboard again appears to freeze.
+However, if the reported event causes the keyboard grab to be released,
+the keyboard does not freeze.
+.PN SyncKeyboard 
+has no effect if the keyboard is not frozen by the client
+or if the keyboard is not grabbed by the client.
+T}
+.sp 6p
+T{
+.PN ReplayKeyboard
+T}	T{
+If the keyboard is actively grabbed by the client and is frozen 
+as the result of an event having been sent to the client (either from the
+activation of an 
+.PN XGrabKey 
+or from a previous 
+.PN XAllowEvents 
+with mode 
+.PN SyncKeyboard 
+but not from an 
+.PN XGrabKeyboard ),
+the keyboard grab is released and that event is completely reprocessed.
+This time, however, the function ignores any passive grabs at or above 
+(toward the root of)
+the grab_window of the grab just released.
+The request has no effect if the keyboard is not grabbed by the client
+or if the keyboard is not frozen as the result of an event.
+T}
+.sp 6p
+T{
+.PN SyncBoth
+T}	T{
+If both pointer and keyboard are frozen by the client,
+event processing for both devices continues as usual until the next
+.PN ButtonPress , 
+.PN ButtonRelease , 
+.PN KeyPress , 
+or 
+.PN KeyRelease 
+event is reported to the client for a grabbed device 
+(button event for the pointer, key event for the keyboard), 
+at which time the devices again appear to freeze.  
+However, if the reported event causes the grab to be released,
+then the devices do not freeze (but if the other device is still
+grabbed, then a subsequent event for it will still cause both devices
+to freeze).  
+.PN SyncBoth
+has no effect unless both pointer and keyboard
+are frozen by the client.
+If the pointer or keyboard is frozen twice
+by the client on behalf of two separate grabs, 
+.PN SyncBoth 
+thaws for both (but a subsequent freeze for 
+.PN SyncBoth 
+will only freeze each device once).
+T}
+.sp 6p
+T{
+.PN AsyncBoth
+T}	T{
+If the pointer and the keyboard are frozen by the
+client, event processing for both devices continues as usual.
+If a device is frozen twice by the client on behalf of two separate grabs,
+.PN AsyncBoth 
+thaws for both.
+.PN AsyncBoth 
+has no effect unless both
+pointer and keyboard are frozen by the client.
+T}
+.TE
+.LP
+.PN AsyncPointer , 
+.PN SyncPointer , 
+and 
+.PN ReplayPointer 
+have no effect on the
+processing of keyboard events.
+.PN AsyncKeyboard , 
+.PN SyncKeyboard , 
+and 
+.PN ReplayKeyboard 
+have no effect on the
+processing of pointer events.
+It is possible for both a pointer grab and a keyboard grab (by the same 
+or different clients) to be active simultaneously.
+If a device is frozen on behalf of either grab,
+no event processing is performed for the device.
+It is possible for a single device to be frozen because of both grabs.
+In this case,
+the freeze must be released on behalf of both grabs before events can 
+again be processed.
+If a device is frozen twice by a single client,
+then a single
+.PN AllowEvents
+releases both.
+.LP
+.PN XAllowEvents
+can generate a
+.PN BadValue 
+error.
+.NH 2
+Moving the Pointer
+.XS
+\*(SN Moving the Pointer
+.XE
+.LP
+Although movement of the pointer normally should be left to the
+control of the end user, sometimes it is necessary to move the
+pointer to a new position under program control.
+.LP
+.sp
+To move the pointer to an arbitrary point in a window, use
+.PN XWarpPointer .
+.IN "XWarpPointer" "" "@DEF@"
+.sM
+.FD 0
+XWarpPointer\^(\^\fIdisplay\fP, \fIsrc_w\fP\^, \fIdest_w\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIsrc_width\fP\^, \fIsrc_height\fP\^, \fIdest_x\fP\^, 
+.br
+                \fIdest_y\fP\^)
+.br
+        Display *\fIdisplay\fP\^;
+.br
+        Window \fIsrc_w\fP\^, \fIdest_w\fP\^;
+.br
+        int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
+.br
+        unsigned int \fIsrc_width\fP\^, \fIsrc_height\fP\^;
+.br
+        int \fIdest_x\fP\^, \fIdest_y\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIsrc_w\fP 1i
+Specifies the source window or
+.PN None .
+.IP \fIdest_w\fP 1i
+Specifies the destination window or
+.PN None .
+.IP \fIsrc_x\fP 1i
+.br
+.ns
+.IP \fIsrc_y\fP 1i
+.br
+.ns
+.IP \fIsrc_width\fP 1i
+.br
+.ns
+.IP \fIsrc_height\fP 1i
+Specify a rectangle in the source window.
+.IP \fIdest_x\fP 1i
+.br
+.ns
+.IP \fIdest_y\fP 1i
+Specify the x and y coordinates within the destination window.
+.LP
+.eM
+If dest_w is
+.PN None ,
+.PN XWarpPointer
+moves the pointer by the offsets (dest_x, dest_y) relative to the current
+position of the pointer.
+If dest_w is a window,
+.PN XWarpPointer
+moves the pointer to the offsets (dest_x, dest_y) relative to the origin of
+dest_w.
+However, if src_w is a window,
+the move only takes place if the window src_w contains the pointer 
+and if the specified rectangle of src_w contains the pointer.
+.LP
+The src_x and src_y coordinates are relative to the origin of src_w.
+If src_height is zero,
+it is replaced with the current height of src_w minus src_y.
+If src_width is zero,
+it is replaced with the current width of src_w minus src_x.
+.LP
+There is seldom any reason for calling this function. 
+The pointer should normally be left to the user.
+If you do use this function, however, it generates events just as if the user
+had instantaneously moved the pointer from one position to another.
+Note that you cannot use
+.PN XWarpPointer
+to move the pointer outside the confine_to window of an active pointer grab.
+An attempt to do so will only move the pointer as far as the closest edge of the
+confine_to window. 
+.LP
+.PN XWarpPointer
+can generate a
+.PN BadWindow 
+error.
+.NH 2
+Controlling Input Focus
+.XS
+\*(SN Controlling Input Focus 
+.XE
+.LP
+Xlib provides functions that you can use to set and get the input focus.
+The input focus is a shared resource, and cooperation among clients is
+required for correct interaction.  See the
+\fIInter-Client Communication Conventions Manual\fP 
+for input focus policy.
+.LP
+.sp
+To set the input focus, use
+.PN XSetInputFocus .
+.IN "XSetInputFocus" "" "@DEF@"
+.sM
+.FD 0
+XSetInputFocus\^(\^\fIdisplay\fP, \fIfocus\fP\^, \fIrevert_to\fP\^, \fItime\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIfocus\fP\^;
+.br
+      int \fIrevert_to\fP\^; 
+.br
+      Time \fItime\fP\^; 
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIfocus\fP 1i
+Specifies the window,
+.PN PointerRoot ,
+or
+.PN None .
+.IP \fIrevert_to\fP 1i
+Specifies where the input focus reverts to if the window becomes not
+viewable.
+You can pass 
+.PN RevertToParent , 
+.PN RevertToPointerRoot , 
+or 
+.PN RevertToNone .
+.IP \fItime\fP 1i
+Specifies the time.
+You can pass either a timestamp or
+.PN CurrentTime .
+.LP
+.eM
+The
+.PN XSetInputFocus
+function changes the input focus and the last-focus-change time.
+It has no effect if the specified time is earlier than the current
+last-focus-change time or is later than the current X server time.
+Otherwise, the last-focus-change time is set to the specified time
+.Pn ( CurrentTime 
+is replaced by the current X server time).
+.PN XSetInputFocus
+causes the X server to generate
+.PN FocusIn 
+and 
+.PN FocusOut 
+events.
+.LP
+Depending on the focus argument,
+the following occurs: 
+.IP \(bu 5
+If focus is
+.PN None ,
+all keyboard events are discarded until a new focus window is set,
+and the revert_to argument is ignored.
+.IP \(bu 5
+If focus is a window, 
+it becomes the keyboard's focus window.
+If a generated keyboard event would normally be reported to this window
+or one of its inferiors, the event is reported as usual. 
+Otherwise, the event is reported relative to the focus window.
+.IP \(bu 5
+If focus is
+.PN PointerRoot ,
+the focus window is dynamically taken to be the root window of whatever screen 
+the pointer is on at each keyboard event.  
+In this case, the revert_to argument is ignored.
+.LP
+The specified focus window must be viewable at the time 
+.PN XSetInputFocus
+is called,
+or a
+.PN BadMatch
+error results.
+If the focus window later becomes not viewable, 
+the X server
+evaluates the revert_to argument to determine the new focus window as follows: 
+.IP \(bu 5
+If revert_to is
+.PN RevertToParent ,
+the focus reverts to the parent (or the closest viewable ancestor), 
+and the new revert_to value is taken to be
+.PN RevertToNone .  
+.IP \(bu 5
+If revert_to is
+.PN RevertToPointerRoot 
+or 
+.PN RevertToNone ,
+the focus reverts to
+.PN PointerRoot
+or
+.PN None ,
+respectively.
+When the focus reverts,
+the X server generates
+.PN FocusIn
+and
+.PN FocusOut
+events, but the last-focus-change time is not affected.
+.LP
+.PN XSetInputFocus
+can generate
+.PN BadMatch ,
+.PN BadValue ,
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To obtain the current input focus, use
+.PN XGetInputFocus .
+.IN "XGetInputFocus" "" "@DEF@"
+.sM
+.FD 0
+XGetInputFocus\^(\^\fIdisplay\fP, \fIfocus_return\fP\^, \fIrevert_to_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window *\fIfocus_return\fP\^;
+.br
+      int *\fIrevert_to_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIfocus_return\fP 1i
+Returns the focus window,
+.PN PointerRoot ,
+or 
+.PN None .
+.IP \fIrevert_to_return\fP 1i
+Returns the current focus state
+.Pn ( RevertToParent , 
+.PN RevertToPointerRoot , 
+or 
+.PN RevertToNone ).
+.LP
+.eM
+The
+.PN XGetInputFocus
+function returns the focus window and the current focus state.
+.NH 2
+Manipulating the Keyboard and Pointer Settings
+.XS
+\*(SN Manipulating the Keyboard and Pointer Settings 
+.XE
+.LP
+Xlib provides functions that you can use to
+change the keyboard control, obtain a list of the auto-repeat keys,
+turn keyboard auto-repeat on or off, ring the bell, 
+set or obtain the pointer button or keyboard mapping, 
+and obtain a bit vector for the keyboard.
+.LP
+.IN "Keyboard" "bell volume"
+.IN "Keyboard" "keyclick volume"
+.IN "Keyboard" "bit vector"
+.IN "Mouse" "programming"
+This section discusses 
+the user-preference options of bell, key click,
+pointer behavior, and so on.
+The default values for many of these options are server dependent.
+Not all implementations will actually be able to control all of these
+parameters.
+.LP
+The
+.PN XChangeKeyboardControl
+function changes control of a keyboard and operates on a
+.PN XKeyboardControl
+structure:
+.sM
+.LP
+/* Mask bits for ChangeKeyboardControl */
+.TS
+lw(.5i) lw(2.5i) lw(.8i).
+T{
+#define
+T}	T{
+.PN KBKeyClickPercent
+T}	T{
+(1L<<0)
+T}
+T{
+#define
+T}	T{
+.PN KBBellPercent
+T}	T{
+(1L<<1)
+T}
+T{
+#define
+T}	T{
+.PN KBBellPitch
+T}	T{
+(1L<<2)
+T}
+T{
+#define
+T}	T{
+.PN KBBellDuration
+T}	T{
+(1L<<3)
+T}
+T{
+#define
+T}	T{
+.PN KBLed
+T}	T{
+(1L<<4)
+T}
+T{
+#define
+T}	T{
+.PN KBLedMode
+T}	T{
+(1L<<5)
+T}
+T{
+#define
+T}	T{
+.PN KBKey
+T}	T{
+(1L<<6)
+T}
+T{
+#define
+T}	T{
+.PN KBAutoRepeatMode
+T}	T{
+(1L<<7)
+T}
+.TE
+.IN "XKeyboardControl" "" "@DEF@"
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+/* Values */
+
+typedef struct {
+	int key_click_percent;
+	int bell_percent;
+	int bell_pitch;
+	int bell_duration;
+	int led;
+	int led_mode;	/* LedModeOn, LedModeOff */
+	int key;
+	int auto_repeat_mode;	/* AutoRepeatModeOff, AutoRepeatModeOn, 
+                            	AutoRepeatModeDefault */
+} XKeyboardControl;
+.De
+.LP
+.eM
+The key_click_percent member sets the volume for key clicks between 0 (off) 
+and 100 (loud) inclusive, if possible.  
+A setting of \-1 restores the default.
+Other negative values generate a
+.PN BadValue
+error.
+.LP
+The bell_percent sets the base volume for the bell between 0 (off) and 100
+(loud) inclusive, if possible.  
+A setting of \-1 restores the default.
+Other negative values generate a
+.PN BadValue
+error.
+The bell_pitch member sets the pitch (specified in Hz) of the bell, if possible.
+A setting of \-1 restores the default.
+Other negative values generate a
+.PN BadValue
+error.
+The bell_duration member sets the duration of the
+bell specified in milliseconds, if possible.  
+A setting of \-1 restores the default.
+Other negative values generate a
+.PN BadValue
+error.
+.LP
+If both the led_mode and led members are specified,
+the state of that LED is changed, if possible.  
+The led_mode member can be set to
+.PN LedModeOn
+or
+.PN LedModeOff .
+If only led_mode is specified, the state of
+all LEDs are changed, if possible.  
+At most 32 LEDs numbered from one are supported. 
+No standard interpretation of LEDs is defined.
+If led is specified without led_mode, a
+.PN BadMatch
+error results. 
+.LP
+If both the auto_repeat_mode and key members are specified, 
+the auto_repeat_mode of that key is changed (according to
+.PN AutoRepeatModeOn ,
+.PN AutoRepeatModeOff ,
+or
+.PN AutoRepeatModeDefault ),
+if possible.
+If only auto_repeat_mode is
+specified, the global auto_repeat_mode for the entire keyboard is
+changed, if possible, and does not affect the per-key settings.
+If a key is specified without an auto_repeat_mode, a
+.PN BadMatch
+error results.
+Each key has an individual mode of whether or not it should auto-repeat
+and a default setting for the mode.
+In addition,
+there is a global mode of whether auto-repeat should be enabled or not
+and a default setting for that mode.
+When global mode is
+.PN AutoRepeatModeOn ,
+keys should obey their individual auto-repeat modes.
+When global mode is
+.PN AutoRepeatModeOff ,
+no keys should auto-repeat.
+An auto-repeating key generates alternating
+.PN KeyPress
+and
+.PN KeyRelease
+events.
+When a key is used as a modifier,
+it is desirable for the key not to auto-repeat,
+regardless of its auto-repeat setting.
+.LP
+A bell generator connected with the console but not directly on a
+keyboard is treated as if it were part of the keyboard.
+The order in which controls are verified and altered is server-dependent.
+If an error is generated, a subset of the controls may have been altered.
+.LP
+.sp
+.IN "XChangeKeyboardControl" "" "@DEF@"
+.sM
+.FD 0
+XChangeKeyboardControl\^(\^\fIdisplay\fP, \fIvalue_mask\fP\^, \fIvalues\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      unsigned long \fIvalue_mask\fP\^;
+.br
+      XKeyboardControl *\fIvalues\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIvalue_mask\fP 1i
+Specifies which controls to change.
+This mask is the bitwise inclusive OR of the valid control mask bits.
+.IP \fIvalues\fP 1i
+Specifies one value for each bit set to 1 in the mask.
+.LP
+.eM
+The
+.PN XChangeKeyboardControl
+function controls the keyboard characteristics defined by the
+.PN XKeyboardControl
+structure.
+The value_mask argument specifies which values are to be changed.
+.LP
+.PN XChangeKeyboardControl
+can generate
+.PN BadMatch
+and
+.PN BadValue 
+errors.
+.LP
+.sp
+To obtain the current control values for the keyboard, use
+.PN XGetKeyboardControl .
+.IN "XGetKeyboardControl" "" "@DEF@"
+.sM
+.FD 0
+XGetKeyboardControl\^(\^\fIdisplay\fP, \fIvalues_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XKeyboardState *\fIvalues_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIvalues_return\fP 1i
+Returns the current keyboard controls in the specified
+.PN XKeyboardState 
+structure.
+.LP
+.eM
+The
+.PN XGetKeyboardControl
+function returns the current control values for the keyboard to the
+.PN XKeyboardState
+structure.
+.LP
+.IN "XGetKeyboardControl"
+.IN "XKeyboardState" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 
+.ta .5i
+typedef struct {
+	int key_click_percent;
+	int bell_percent;
+	unsigned int bell_pitch, bell_duration;
+	unsigned long led_mask;
+	int global_auto_repeat;
+	char auto_repeats[32];
+} XKeyboardState;
+.De
+.LP
+.eM
+For the LEDs, 
+the least significant bit of led_mask corresponds to LED one,
+and each bit set to 1 in led_mask indicates an LED that is lit.
+The global_auto_repeat member can be set to
+.PN AutoRepeatModeOn
+or
+.PN AutoRepeatModeOff .
+The auto_repeats member is a bit vector.
+Each bit set to 1 indicates that auto-repeat is enabled 
+for the corresponding key.
+The vector is represented as 32 bytes.  
+Byte N (from 0) contains the bits for keys 8N to 8N + 7
+with the least significant bit in the byte representing key 8N.
+.LP
+.sp
+To turn on keyboard auto-repeat, use
+.PN XAutoRepeatOn .
+.IN "XAutoRepeatOn" "" "@DEF@"
+.sM
+.FD 0
+XAutoRepeatOn\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+The
+.PN XAutoRepeatOn
+function turns on auto-repeat for the keyboard on the specified display.
+.LP
+.sp
+To turn off keyboard auto-repeat, use
+.PN XAutoRepeatOff .
+.IN "XAutoRepeatOff" "" "@DEF@"
+.sM
+.FD 0
+XAutoRepeatOff\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+The
+.PN XAutoRepeatOff
+function turns off auto-repeat for the keyboard on the specified display.
+.LP
+.sp
+To ring the bell, use
+.PN XBell .
+.IN "XBell" "" "@DEF@"
+.sM
+.FD 0
+XBell\^(\^\fIdisplay\fP, \fIpercent\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIpercent\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIpercent\fP 1i
+Specifies the volume for the bell,
+which can range from \-100 to 100 inclusive. 
+.LP
+.eM
+The
+.PN XBell
+function rings the bell on the keyboard on the specified display, if possible.
+The specified volume is relative to the base volume for the keyboard.
+If the value for the percent argument is not in the range \-100 to 100
+inclusive, a
+.PN BadValue
+error results.
+The volume at which the bell rings
+when the percent argument is nonnegative is:
+.IP
+base \- [(base * percent) / 100] + percent
+.LP
+The volume at which the bell rings
+when the percent argument is negative is:
+.IP
+base + [(base * percent) / 100]
+.LP
+To change the base volume of the bell, use
+.PN XChangeKeyboardControl .
+.LP
+.PN XBell
+can generate a
+.PN BadValue 
+error.
+.LP
+.sp
+To obtain a bit vector that describes the state of the keyboard, use
+.PN XQueryKeymap .
+.IN "XQueryKeymap" "" "@DEF@"
+.sM
+.FD 0
+XQueryKeymap\^(\^\fIdisplay\fP, \fIkeys_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      char \fIkeys_return\fP[32]\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIkeys_return\fP 1i
+Returns an array of bytes that identifies which keys are pressed down.
+Each bit represents one key of the keyboard.
+.LP
+.eM
+The
+.PN XQueryKeymap
+function returns a bit vector for the logical state of the keyboard, 
+where each bit set to 1 indicates that the corresponding key is currently 
+pressed down.
+The vector is represented as 32 bytes.
+Byte N (from 0) contains the bits for keys 8N to 8N + 7 
+with the least significant bit in the byte representing key 8N.
+.LP
+Note that the logical state of a device (as seen by client applications)
+may lag the physical state if device event processing is frozen.
+.LP
+.sp
+To set the mapping of the pointer buttons, use
+.PN XSetPointerMapping .
+.IN "XSetPointerMapping" "" "@DEF@"
+.sM
+.FD 0
+int XSetPointerMapping\^(\^\fIdisplay\fP, \fImap\fP, \fInmap\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      unsigned char \fImap\fP\^[]\^;
+.br
+      int \fInmap\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fImap\fP 1i
+Specifies the mapping list.
+.IP \fInmap\fP 1i
+Specifies the number of items in the mapping list.
+.LP
+.eM
+The
+.PN XSetPointerMapping
+function sets the mapping of the pointer.
+If it succeeds, the X server generates a
+.PN MappingNotify
+event, and
+.PN XSetPointerMapping
+returns
+.PN MappingSuccess .
+Element map[i] defines the logical button number for the physical button
+i+1.
+The length of the list must be the same as
+.PN XGetPointerMapping
+would return,
+or a
+.PN BadValue
+error results.
+A zero element disables a button, and elements are not restricted in
+value by the number of physical buttons.
+However, no two elements can have the same nonzero value,
+or a
+.PN BadValue
+error results.
+If any of the buttons to be altered are logically in the down state,
+.PN XSetPointerMapping
+returns
+.PN MappingBusy ,
+and the mapping is not changed.
+.LP
+.PN XSetPointerMapping
+can generate a
+.PN BadValue 
+error.
+.LP
+.sp
+To get the pointer mapping, use
+.PN XGetPointerMapping .
+.IN "XGetPointerMapping" "" "@DEF@"
+.sM
+.FD 0
+int XGetPointerMapping\^(\^\fIdisplay\fP, \fImap_return\fP, \fInmap\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      unsigned char \fImap_return\fP\^[]\^;
+.br
+      int \fInmap\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fImap_return\fP 1i
+Returns the mapping list.
+.IP \fInmap\fP 1i
+Specifies the number of items in the mapping list.
+.LP
+.eM
+The
+.PN XGetPointerMapping
+function returns the current mapping of the pointer.
+Pointer buttons are numbered starting from one.
+.PN XGetPointerMapping
+returns the number of physical buttons actually on the pointer.
+The nominal mapping for a pointer is map[i]=i+1.
+The nmap argument specifies the length of the array where the pointer
+mapping is returned, and only the first nmap elements are returned 
+in map_return.
+.LP
+.sp
+To control the pointer's interactive feel, use
+.PN XChangePointerControl .
+.IN "XChangePointerControl" "" "@DEF@"
+.sM
+.FD 0
+XChangePointerControl\^(\^\fIdisplay\fP, \fIdo_accel\fP\^, \fIdo_threshold\fP\^, \fIaccel_numerator\fP\^, 
+.br
+                        \fIaccel_denominator\fP\^, \fIthreshold\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Bool \fIdo_accel\fP\^, \fIdo_threshold\fP\^;
+.br
+      int \fIaccel_numerator\fP\^, \fIaccel_denominator\fP\^;
+.br
+      int \fIthreshold\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIdo_accel\fP 1i
+Specifies a Boolean value that controls whether the values for 
+the accel_numerator or accel_denominator are used.
+.IP \fIdo_threshold\fP 1i
+Specifies a Boolean value that controls whether the value for the 
+threshold is used.
+.IP \fIaccel_numerator\fP 1i
+Specifies the numerator for the acceleration multiplier.
+.IP \fIaccel_denominator\fP 1i
+Specifies the denominator for the acceleration multiplier.
+.IP \fIthreshold\fP 1i
+Specifies the acceleration threshold.
+.LP
+.eM
+The
+.PN XChangePointerControl
+function defines how the pointing device moves.
+The acceleration, expressed as a fraction, is a
+multiplier for movement. 
+For example,
+specifying 3/1 means the pointer moves three times as fast as normal.
+The fraction may be rounded arbitrarily by the X server.  
+Acceleration
+only takes effect if the pointer moves more than threshold pixels at
+once and only applies to the amount beyond the value in the threshold argument.
+Setting a value to \-1 restores the default.
+The values of the do_accel and do_threshold arguments must be 
+.PN True 
+for the pointer values to be set,
+or the parameters are unchanged.
+Negative values (other than \-1) generate a
+.PN BadValue
+error, as does a zero value
+for the accel_denominator argument.
+.LP
+.PN XChangePointerControl
+can generate a
+.PN BadValue 
+error.
+.LP
+.sp
+To get the current pointer parameters, use
+.PN XGetPointerControl .
+.IN "XGetPointerControl" "" "@DEF@"
+.sM
+.FD 0
+XGetPointerControl\^(\^\fIdisplay\fP, \fIaccel_numerator_return\fP\^, \fIaccel_denominator_return\fP\^, 
+.br
+                       \fIthreshold_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int *\fIaccel_numerator_return\fP\^, *\fIaccel_denominator_return\fP\^;
+.br
+      int *\fIthreshold_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIaccel_numerator_return\fP 1i
+Returns the numerator for the acceleration multiplier.
+.IP \fIaccel_denominator_return\fP 1i
+Returns the denominator for the acceleration multiplier.
+.IP \fIthreshold_return\fP 1i
+Returns the acceleration threshold.
+.LP
+.eM
+The
+.PN XGetPointerControl
+function returns the pointer's current acceleration multiplier
+and acceleration threshold.
+.NH 2
+Manipulating the Keyboard Encoding
+.XS
+\*(SN Manipulating the Keyboard Encoding 
+.XE
+.LP
+A KeyCode represents a physical (or logical) key.  
+KeyCodes lie in the inclusive range [8,255].  
+A KeyCode value carries no intrinsic information,
+although server implementors may attempt to encode geometry 
+(for example, matrix) information in some fashion so that it can
+be interpreted in a server-dependent fashion.
+The mapping between keys and KeyCodes cannot be changed.
+.LP
+A KeySym is an encoding of a symbol on the cap of a key.  
+The set of defined KeySyms includes the ISO Latin character sets (1\-4), 
+Katakana, Arabic, Cyrillic, Greek, Technical,
+Special, Publishing, APL, Hebrew, Thai, Korean
+and a miscellany of keys found
+on keyboards (Return, Help, Tab, and so on).  
+To the extent possible, these sets are derived from international
+standards. 
+In areas where no standards exist,
+some of these sets are derived from Digital Equipment Corporation standards.
+The list of defined symbols can be found in
+.hN X11/keysymdef.h .
+Unfortunately, some C preprocessors have
+limits on the number of defined symbols.
+If you must use KeySyms not
+in the Latin 1\-4, Greek, and miscellaneous classes,
+you may have to define a symbol for those sets.
+Most applications usually only include 
+.hN X11/keysym.h ,
+which defines symbols for ISO Latin 1\-4, Greek, and miscellaneous.
+.LP
+A list of KeySyms is associated with each KeyCode.
+The list is intended to convey the set of symbols on the corresponding key.
+If the list (ignoring trailing
+.PN NoSymbol
+entries) is 
+a single KeySym ``\fIK\fP'',
+then the list is treated as if it were the list 
+``\fIK\fP NoSymbol \fIK\fP NoSymbol''.
+If the list (ignoring trailing
+.PN NoSymbol
+entries) is a pair of KeySyms ``\fIK1 K2\fP'',
+then the list is treated as if it were the list ``\fIK1 K2 K1 K2\fP''.
+If the list (ignoring trailing
+.PN NoSymbol
+entries) is a triple of KeySyms ``\fIK1 K2 K3\fP'',
+then the list is treated as if it were the list ``\fIK1 K2 K3\fP NoSymbol''.
+When an explicit ``void'' element is desired in the list,
+the value
+.PN VoidSymbol
+can be used.
+.LP
+The first four elements of the list are split into two groups of KeySyms.
+Group 1 contains the first and second KeySyms;
+Group 2 contains the third and fourth KeySyms.
+Within each group,
+if the second element of the group is
+.PN NoSymbol ,
+then the group should be treated as if the second element were 
+the same as the first element,
+except when the first element is an alphabetic KeySym ``\fIK\fP'' 
+for which both lowercase and uppercase forms are defined.
+In that case,
+the group should be treated as if the first element were 
+the lowercase form of ``\fIK\fP'' and the second element were 
+the uppercase form of ``\fIK\fP''.
+.LP
+The standard rules for obtaining a KeySym from a
+.PN KeyPress
+event make use of only the Group 1 and Group 2 KeySyms;
+no interpretation of other KeySyms in the list is given.
+Which group to use is determined by the modifier state.
+Switching between groups is controlled by the KeySym named MODE SWITCH,
+by attaching that KeySym to some KeyCode and attaching 
+that KeyCode to any one of the modifiers
+.PN Mod1
+through
+.PN Mod5 .
+This modifier is called the \fIgroup modifier\fP\^.
+For any KeyCode,
+Group 1 is used when the group modifier is off,
+and Group 2 is used when the group modifier is on.
+.LP
+The
+.PN Lock
+modifier is interpreted as CapsLock when the KeySym named XK_Caps_Lock
+is attached to some KeyCode and that KeyCode is attached to the
+.PN Lock
+modifier.  The
+.PN Lock
+modifier is interpreted as ShiftLock when the KeySym named XK_Shift_Lock
+is attached to some KeyCode and that KeyCode is attached to the
+.PN Lock 
+modifier.  If the
+.PN Lock 
+modifier could be interpreted as both
+CapsLock and ShiftLock, the CapsLock interpretation is used.
+.LP
+The operation of keypad keys is controlled by the KeySym named XK_Num_Lock,
+by attaching that KeySym to some KeyCode and attaching that KeyCode to any
+one of the modifiers
+.PN Mod1 
+through
+.PN Mod5 . 
+This modifier is called the
+\fInumlock modifier\fP\^.  The standard KeySyms with the prefix ``XK_KP_''
+in their
+name are called keypad KeySyms; these are KeySyms with numeric value in
+the hexadecimal range 0xFF80 to 0xFFBD inclusive.  In addition,
+vendor-specific KeySyms in the hexadecimal range 0x11000000 to 0x1100FFFF
+are also keypad KeySyms.
+.LP
+Within a group, the choice of KeySym is determined by applying the first
+rule that is satisfied from the following list:
+.IP \(bu 5
+The numlock modifier is on and the second KeySym is a keypad KeySym.  In
+this case, if the
+.PN Shift 
+modifier is on, or if the
+.PN Lock 
+modifier is on and
+is interpreted as ShiftLock, then the first KeySym is used, otherwise the
+second KeySym is used.
+.IP \(bu 5
+The
+.PN Shift 
+and
+.PN Lock 
+modifiers are both off.  In this case, the first
+KeySym is used.
+.IP \(bu 5
+The
+.PN Shift 
+modifier is off, and the
+.PN Lock 
+modifier is on and is
+interpreted as CapsLock.  In this case, the first KeySym is used, but if
+that KeySym is lowercase alphabetic, then the corresponding uppercase
+KeySym is used instead.
+.IP \(bu 5
+The
+.PN Shift 
+modifier is on, and the
+.PN Lock 
+modifier is on and is interpreted
+as CapsLock.  In this case, the second KeySym is used, but if that KeySym
+is lowercase alphabetic, then the corresponding uppercase KeySym is used
+instead.
+.IP \(bu 5
+The
+.PN Shift 
+modifier is on, or the
+.PN Lock 
+modifier is on and is interpreted
+as ShiftLock, or both.  In this case, the second KeySym is used.
+.LP
+No spatial geometry of the symbols on the key is defined by
+their order in the KeySym list, 
+although a geometry might be defined on a
+server-specific basis.
+The X server does not use the mapping between KeyCodes and KeySyms.
+Rather, it merely stores it for reading and writing by clients.
+.sp
+.LP
+To obtain the legal KeyCodes for a display, use
+.PN XDisplayKeycodes .
+.IN "XDisplayKeycodes" "" "@DEF@"
+.sM
+.FD 0
+XDisplayKeycodes\^(\^\fIdisplay\fP\^, \fImin_keycodes_return\fP\^, \
+\fImax_keycodes_return\fP\^)
+.br
+        Display *\^\fIdisplay\fP\^;
+.br
+        int *\^\fImin_keycodes_return\fP\^, *\^\fImax_keycodes_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fImin_keycodes_return\fP 1i
+Returns the minimum number of KeyCodes.
+.IP \fImax_keycodes_return\fP 1i
+Returns the maximum number of KeyCodes.
+.LP
+.eM
+The
+.PN XDisplayKeycodes
+function returns the min-keycodes and max-keycodes supported by the
+specified display.
+The minimum number of KeyCodes returned is never less than 8,
+and the maximum number of KeyCodes returned is never greater than 255.
+Not all KeyCodes in this range are required to have corresponding keys.
+.sp
+.LP
+To obtain the symbols for the specified KeyCodes, use
+.PN XGetKeyboardMapping .
+.IN "XGetKeyboardMapping" "" "@DEF@"
+.sM
+.FD 0
+KeySym *XGetKeyboardMapping(\^\fIdisplay\fP, \fIfirst_keycode\fP, \fIkeycode_count\fP, 
+.br
+                            \fIkeysyms_per_keycode_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      KeyCode \fIfirst_keycode\fP\^;
+.br
+      int \fIkeycode_count\fP\^;
+.br
+      int *\fIkeysyms_per_keycode_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Kc returned
+.IP \fIfirst_keycode\fP 1i
+Specifies the first KeyCode that is to be \*(Kc.
+.IP \fIkeycode_count\fP 1i
+Specifies the number of KeyCodes that are to be returned.
+.IP \fIkeysyms_per_keycode_return\fP 1i
+Returns the number of KeySyms per KeyCode.
+.LP
+.eM
+The
+.PN XGetKeyboardMapping
+function returns the symbols for the specified number of KeyCodes
+starting with first_keycode.
+The value specified in first_keycode must be greater than 
+or equal to min_keycode as returned by
+.PN XDisplayKeycodes ,
+or a
+.PN BadValue 
+error results.
+In addition, the following expression must be less than or equal 
+to max_keycode as returned by
+.PN XDisplayKeycodes :
+.LP
+.Ds 
+first_keycode + keycode_count \- 1
+.De
+.LP
+If this is not the case, a 
+.PN BadValue 
+error results. 
+The number of elements in the KeySyms list is:
+.LP
+.Ds 
+keycode_count * keysyms_per_keycode_return
+.De
+.LP
+KeySym number N, counting from zero, for KeyCode K has the following index
+in the list, counting from zero: 
+.Ds
+(K \- first_code) * keysyms_per_code_return + N
+.De
+.LP
+The X server arbitrarily chooses the keysyms_per_keycode_return value 
+to be large enough to report all requested symbols. 
+A special KeySym value of 
+.PN NoSymbol 
+is used to fill in unused elements for
+individual KeyCodes.
+To free the storage returned by 
+.PN XGetKeyboardMapping ,
+use
+.PN XFree .
+.LP
+.PN XGetKeyboardMapping
+can generate a
+.PN BadValue 
+error.
+.LP
+.sp
+To change the keyboard mapping, use
+.PN XChangeKeyboardMapping .
+.IN "XChangeKeyboardMapping" "" "@DEF@"
+.sM
+.FD 0
+XChangeKeyboardMapping(\^\fIdisplay\fP, \fIfirst_keycode\fP, \fIkeysyms_per_keycode\fP, \fIkeysyms\fP, \fInum_codes\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIfirst_keycode\fP\^;
+.br
+      int \fIkeysyms_per_keycode\fP\^;
+.br
+      KeySym *\fIkeysyms\fP\^;
+.br
+      int \fInum_codes\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Kc changed
+.IP \fIfirst_keycode\fP 1i
+Specifies the first KeyCode that is to be \*(Kc.
+.IP \fIkeysyms_per_keycode\fP 1i
+Specifies the number of KeySyms per KeyCode.
+.IP \fIkeysyms\fP 1i
+Specifies an array of KeySyms.
+.IP \fInum_codes\fP 1i
+Specifies the number of KeyCodes that are to be changed.
+.LP
+.eM
+The
+.PN XChangeKeyboardMapping
+function defines the symbols for the specified number of KeyCodes
+starting with first_keycode.
+The symbols for KeyCodes outside this range remain unchanged.  
+The number of elements in keysyms must be:
+.LP
+.Ds
+num_codes * keysyms_per_keycode
+.De
+.LP
+The specified first_keycode must be greater than or equal to min_keycode 
+returned by
+.PN XDisplayKeycodes ,
+or a 
+.PN BadValue 
+error results.
+In addition, the following expression must be less than or equal to 
+max_keycode as returned by
+.PN XDisplayKeycodes ,
+or a
+.PN BadValue 
+error results:
+.LP
+.Ds
+first_keycode + num_codes \- 1
+.De
+.LP
+KeySym number N, counting from zero, for KeyCode K has the following index
+in keysyms, counting from zero: 
+.LP
+.Ds 
+(K \- first_keycode) * keysyms_per_keycode + N
+.De
+.LP
+The specified keysyms_per_keycode can be chosen arbitrarily by the client
+to be large enough to hold all desired symbols. 
+A special KeySym value of 
+.PN NoSymbol 
+should be used to fill in unused elements 
+for individual KeyCodes.  
+It is legal for 
+.PN NoSymbol 
+to appear in nontrailing positions
+of the effective list for a KeyCode.
+.PN XChangeKeyboardMapping
+generates a 
+.PN MappingNotify 
+event.
+.LP
+There is no requirement that the X server interpret this mapping. 
+It is merely stored for reading and writing by clients.
+.LP
+.PN XChangeKeyboardMapping
+can generate
+.PN BadAlloc 
+and
+.PN BadValue 
+errors.
+.LP
+The next six functions make use of the 
+.PN XModifierKeymap
+data structure, which contains:
+.LP
+.IN "XModifierKeymap" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	int max_keypermod;	/* This server's max number of keys per modifier */
+	KeyCode *modifiermap;	/* An 8 by max_keypermod array of the modifiers */
+} XModifierKeymap;
+.De
+.LP
+.eM
+To create an
+.PN XModifierKeymap
+structure, use
+.PN XNewModifiermap .
+.IN "XNewModifiermap" "" "@DEF@"
+.sM
+.FD 0
+XModifierKeymap *XNewModifiermap(\^\fImax_keys_per_mod\fP\^)
+.br
+        int \fImax_keys_per_mod\fP\^;
+.FN
+.IP \fImax_keys_per_mod\fP 1i
+Specifies the number of KeyCode entries preallocated to the modifiers
+in the map.
+.LP
+.eM
+The
+.PN XNewModifiermap
+function returns a pointer to
+.PN XModifierKeymap
+structure for later use.
+.LP
+.sp
+To add a new entry to an 
+.PN XModifierKeymap
+structure, use
+.PN XInsertModifiermapEntry .
+.IN "XInsertModifiermapEntry" "" "@DEF@"
+.sM
+.FD 0
+XModifierKeymap *XInsertModifiermapEntry\^(\^\fImodmap\fP, \
+\fIkeycode_entry\fP, \fImodifier\fP\^)
+.br
+     XModifierKeymap *\fImodmap\fP\^;
+.br
+     KeyCode \fIkeycode_entry\fP\^;
+.br
+     int \fImodifier\fP\^;
+.FN
+.IP \fImodmap\fP 1i
+Specifies the 
+.PN XModifierKeymap
+structure.
+.IP \fIkeycode_entry\fP 1i
+Specifies the KeyCode. 
+.IP \fImodifier\fP 1i
+Specifies the modifier.
+.LP
+.eM
+The
+.PN XInsertModifiermapEntry
+function adds the specified KeyCode to the set that controls the specified
+modifier and returns the resulting
+.PN XModifierKeymap
+structure (expanded as needed).
+.LP
+.sp
+To delete an entry from an 
+.PN XModifierKeymap
+structure, use
+.PN XDeleteModifiermapEntry .
+.IN "XDeleteModifiermapEntry" "" "@DEF@"
+.sM
+.FD 0
+XModifierKeymap *XDeleteModifiermapEntry\^(\^\fImodmap\fP, \
+\fIkeycode_entry\fP, \fImodifier\fP\^)
+.br
+     XModifierKeymap *\fImodmap\fP\^;
+.br
+     KeyCode \fIkeycode_entry\fP\^;
+.br
+     int \fImodifier\fP\^;
+.FN
+.IP \fImodmap\fP 1i
+Specifies the 
+.PN XModifierKeymap
+structure.
+.IP \fIkeycode_entry\fP 1i
+Specifies the KeyCode. 
+.IP \fImodifier\fP 1i
+Specifies the modifier.
+.LP
+.eM
+The
+.PN XDeleteModifiermapEntry
+function deletes the specified KeyCode from the set that controls the
+specified modifier and returns a pointer to the resulting
+.PN XModifierKeymap
+structure.
+.LP
+.sp
+To destroy an
+.PN XModifierKeymap
+structure, use
+.PN XFreeModifiermap .
+.IN "XFreeModifiermap" "" "@DEF@"
+.sM
+.FD 0
+XFreeModifiermap(\^\fImodmap\fP\^)
+.br
+        XModifierKeymap *\fImodmap\fP;
+.FN
+.IP \fImodmap\fP 1i
+Specifies the 
+.PN XModifierKeymap
+structure.
+.LP
+.eM
+The
+.PN XFreeModifiermap
+function frees the specified
+.PN XModifierKeymap
+structure.
+.LP
+.sp
+To set the KeyCodes to be used as modifiers, use
+.PN XSetModifierMapping .
+.IN "XSetModifierMapping" "" "@DEF@"
+.sM
+.FD 0
+int XSetModifierMapping(\^\fIdisplay\fP, \fImodmap\fP\^)
+.br
+        Display *\fIdisplay\fP\^;
+.br
+        XModifierKeymap *\fImodmap\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fImodmap\fP 1i
+Specifies the 
+.PN XModifierKeymap
+structure.
+.LP
+.eM
+The
+.PN XSetModifierMapping
+function specifies the KeyCodes of the keys (if any) that are to be used 
+as modifiers.
+If it succeeds,
+the X server generates a
+.PN MappingNotify
+event, and
+.PN XSetModifierMapping
+returns
+.PN MappingSuccess .
+X permits at most 8 modifier keys.
+If more than 8 are specified in the
+.PN XModifierKeymap
+structure, a
+.PN BadLength
+error results.
+.LP
+The modifiermap member of the 
+.PN XModifierKeymap
+structure contains 8 sets of max_keypermod KeyCodes, 
+one for each modifier in the order 
+.PN Shift , 
+.PN Lock , 
+.PN Control , 
+.PN Mod1 , 
+.PN Mod2 , 
+.PN Mod3 , 
+.PN Mod4 , 
+and 
+.PN Mod5 .
+Only nonzero KeyCodes have meaning in each set, 
+and zero KeyCodes are ignored.
+In addition, all of the nonzero KeyCodes must be in the range specified by 
+min_keycode and max_keycode in the 
+.PN Display 
+structure,
+or a 
+.PN BadValue 
+error results.
+.LP
+An X server can impose restrictions on how modifiers can be changed, 
+for example,
+if certain keys do not generate up transitions in hardware,
+if auto-repeat cannot be disabled on certain keys,
+or if multiple modifier keys are not supported.  
+If some such restriction is violated, 
+the status reply is
+.PN MappingFailed ,
+and none of the modifiers are changed.
+If the new KeyCodes specified for a modifier differ from those
+currently defined and any (current or new) keys for that modifier are
+in the logically down state, 
+.PN XSetModifierMapping
+returns
+.PN MappingBusy , 
+and none of the modifiers is changed.
+.LP
+.PN XSetModifierMapping
+can generate
+.PN BadAlloc
+and 
+.PN BadValue 
+errors.
+.LP
+.sp
+To obtain the KeyCodes used as modifiers, use
+.PN XGetModifierMapping .
+.IN "XGetModifierMapping" "" "@DEF@"
+.sM
+.FD 0
+XModifierKeymap *XGetModifierMapping(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+The
+.PN XGetModifierMapping
+function returns a pointer to a newly created
+.PN XModifierKeymap
+structure that contains the keys being used as modifiers.
+The structure should be freed after use by calling
+.PN XFreeModifiermap .
+If only zero values appear in the set for any modifier, 
+that modifier is disabled.
+.bp
diff --git a/specs/libX11/CH13 b/specs/libX11/CH13
new file mode 100644
index 00000000..ed143c69
--- /dev/null
+++ b/specs/libX11/CH13
@@ -0,0 +1,7673 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 13\fP\s-1
+
+\s+1\fBLocales and Internationalized Text Functions\fP\s-1
+.sp 2
+.nr H1 13
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.na
+.LP
+.XS
+Chapter 13: Locales and Internationalized Text Functions
+.XE
+An internationalized application is one that is adaptable to the requirements
+of different native languages, local customs, and character string encodings.
+The process of adapting the operation to a particular native language,
+local custom, or string encoding is called \fIlocalization\fP\^.
+A goal of internationalization is to permit localization
+without program source modifications or recompilation.
+.LP
+As one of the localization mechanisms,
+Xlib provides an X Input Method
+.Pn ( XIM )
+functional interface for internationalized text input
+and an X Output Method
+.Pn ( XOM )
+functional interface for internationalized text output.
+.LP
+Internationalization in X is based on the concept of a \fIlocale\fP.
+A locale defines the localized behavior of a program at run time.
+Locales affect Xlib in its:
+.IP \(bu 5
+Encoding and processing of input method text
+.IP \(bu 5
+Encoding of resource files and values
+.IP \(bu 5
+Encoding and imaging of text strings
+.IP \(bu 5
+Encoding and decoding for inter-client text communication
+.LP
+Characters from various languages are represented in a computer
+using an encoding.
+Different languages have different encodings,
+and there are even different encodings for the same characters
+in the same language.
+.LP
+This chapter defines support for localized text imaging and text input
+and describes the locale mechanism that controls all locale-dependent
+Xlib functions.
+Sets of functions are provided for multibyte (char *) text as well as
+wide character (wchar_t) text in the form supported 
+by the host C language environment.
+The multibyte and wide character functions
+are equivalent except for the form of the text argument.
+.LP
+The Xlib internationalization functions are not meant to provide
+support for multilingual applications (mixing multiple languages
+within a single piece of text), but they make it possible to
+implement applications that work in limited fashion with more than
+one language in independent contexts.
+.LP
+The remainder of this chapter discusses:
+.IP \(bu 5
+X locale management
+.IP \(bu 5
+Locale and modifier dependencies
+.IP \(bu 5
+Variable argument lists
+.IP \(bu 5
+Output methods
+.IP \(bu 5
+Input methods
+.IP \(bu 5
+String constants
+.NH 2
+X Locale Management
+.XS
+\*(SN X Locale Management
+.XE
+.LP
+X supports one or more of the locales defined by the host environment.
+On implementations that conform to the ANSI C library,
+the locale announcement method is
+.PN setlocale .
+This function configures the locale operation of both
+the host C library and Xlib.
+The operation of Xlib is governed by the LC_CTYPE category;
+this is called the \fIcurrent locale\fP.
+An implementation is permitted to provide implementation-dependent
+mechanisms for announcing the locale in addition to
+.PN setlocale .
+.LP
+On implementations that do not conform to the ANSI C library, 
+the locale announcement method is Xlib implementation-dependent.
+.LP
+The mechanism by which the semantic operation of Xlib is defined
+for a specific locale is implementation-dependent.
+.LP
+.sp
+X is not required to support all the locales supported by the host.
+To determine if the current locale is supported by X, use
+.PN XSupportsLocale .
+.IN "XSupportsLocale" "" "@DEF@"
+.sM
+.FD 0
+Bool XSupportsLocale\^(\|)
+.FN
+.LP
+.eM
+The 
+.PN XSupportsLocale
+function returns 
+.PN True
+if Xlib functions are capable of operating under the current locale.
+If it returns 
+.PN False ,
+Xlib locale-dependent functions for which the 
+.PN XLocaleNotSupported 
+return status is defined will return 
+.PN XLocaleNotSupported .
+Other Xlib locale-dependent routines will operate in the ``C'' locale.
+.LP
+The client is responsible for selecting its locale and X modifiers.
+Clients should provide a means for the user to override the clients'
+locale selection at client invocation.
+Most single-display X clients operate in a single locale 
+for both X and the host processing environment.
+They will configure the locale by calling three functions: 
+the host locale configuration function,
+.PN XSupportsLocale ,
+and 
+.PN XSetLocaleModifiers .
+.LP
+The semantics of certain categories of X internationalization capabilities
+can be configured by setting modifiers.
+Modifiers are named by implementation-dependent and locale-specific strings.
+The only standard use for this capability at present
+is selecting one of several styles of keyboard input method.
+.LP
+.sp
+To configure Xlib locale modifiers for the current locale, use
+.PN XSetLocaleModifiers .
+.IN "XSetLocaleModifiers" "" "@DEF@"
+.sM
+.FD 0
+char *XSetLocaleModifiers\^(\^\fImodifier_list\fP\^)
+.br
+      char *\fImodifier_list\fP\^;
+.FN
+.IP \fImodifier_list\fP 1i
+Specifies the modifiers.
+.LP
+.eM
+The
+.PN XSetLocaleModifiers
+function sets the X modifiers for the current locale setting.
+The modifier_list argument is a null-terminated string of the form
+``{@\^\fIcategory\fP\^=\^\fIvalue\fP\^}'', that is,
+having zero or more concatenated ``@\^\fIcategory\fP\^=\^\fIvalue\fP\^''
+entries, where \fIcategory\fP is a category name 
+and \fIvalue\fP is the (possibly empty) setting for that category.
+The values are encoded in the current locale.
+Category names are restricted to the POSIX Portable Filename Character Set.
+.LP
+The local host X locale modifiers announcer (on POSIX-compliant systems,
+the XMODIFIERS environment variable) is appended to the modifier_list to
+provide default values on the local host.
+If a given category appears more than once in the list,
+the first setting in the list is used.
+If a given category is not included in the full modifier list,
+the category is set to an implementation-dependent default
+for the current locale.
+An empty value for a category explicitly specifies the
+implementation-dependent default.
+.LP
+If the function is successful, it returns a pointer to a string.
+The contents of the string are such that a subsequent call with that string
+(in the same locale) will restore the modifiers to the same settings.
+If modifier_list is a NULL pointer,
+.PN XSetLocaleModifiers
+also returns a pointer to such a string,
+and the current locale modifiers are not changed.
+.LP
+If invalid values are given for one or more modifier categories supported by
+the locale, a NULL pointer is returned, and none of the
+current modifiers are changed.
+.LP
+At program startup,
+the modifiers that are in effect are unspecified until
+the first successful call to set them.  Whenever the locale is changed, the
+modifiers that are in effect become unspecified until the next successful call
+to set them.
+Clients should always call
+.PN XSetLocaleModifiers
+with a non-NULL modifier_list after setting the locale
+before they call any locale-dependent Xlib routine.
+.LP
+The only standard modifier category currently defined is ``im'',
+which identifies the desired input method.
+The values for input method are not standardized.
+A single locale may use multiple input methods,
+switching input method under user control.
+The modifier may specify the initial input method in effect
+or an ordered list of input methods.
+Multiple input methods may be specified in a single im value string
+in an implementation-dependent manner.
+.LP
+The returned modifiers string is owned by Xlib and should not be modified or
+freed by the client.
+It may be freed by Xlib after the current locale or modifiers are changed.
+Until freed, it will not be modified by Xlib.
+.LP
+The recommended procedure for clients initializing their locale and modifiers
+is to obtain locale and modifier announcers separately from
+one of the following prioritized sources:
+.IP \(bu 5
+A command line option
+.IP \(bu 5
+A resource
+.IP \(bu 5
+The empty string ("\^")
+.LP
+The first of these that is defined should be used.
+Note that when a locale command line option or locale resource is defined,
+the effect should be to set all categories to the specified locale,
+overriding any category-specific settings in the local host environment.
+.NH 2
+Locale and Modifier Dependencies
+.XS
+\*(SN Locale and Modifier Dependencies
+.XE
+.LP
+The internationalized Xlib functions operate in the current locale
+configured by the host environment and X locale modifiers set by
+.PN XSetLocaleModifiers
+or in the locale and modifiers configured at the time
+some object supplied to the function was created.
+For each locale-dependent function,
+the following table describes the locale (and modifiers) dependency:
+.TS H
+lw(1.25i) lw(2.5i) lw(2i).
+_
+.sp 6p
+.B
+Locale from	Affects the Function	In
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+	Locale Query/Configuration:
+.sp 6p
+T{
+.PN setlocale
+T}	T{
+.PN XSupportsLocale
+T}	T{
+Locale queried
+T}
+	T{
+.PN XSetLocaleModifiers
+T}	T{
+Locale modified
+T}
+.sp
+	Resources:
+.sp 6p
+T{
+.PN setlocale
+T}	T{
+.PN XrmGetFileDatabase
+T}	T{
+Locale of 
+.PN XrmDatabase
+T}
+	T{
+.PN XrmGetStringDatabase
+T}
+T{
+.PN XrmDatabase
+T}	T{
+.PN XrmPutFileDatabase
+T}	T{
+Locale of 
+.PN XrmDatabase
+T}
+	T{
+.PN XrmLocaleOfDatabase
+T}
+.sp
+	Setting Standard Properties:
+.sp 6p
+T{
+.PN setlocale
+T}	T{
+.PN XmbSetWMProperties
+T}	T{
+Encoding of supplied/returned
+T}
+		text (some WM_ property
+		text in environment locale)
+.sp 6p
+T{
+.PN setlocale
+T}	T{
+.PN XmbTextPropertyToTextList
+T}	T{
+Encoding of supplied/returned text
+T}
+	T{
+.PN XwcTextPropertyToTextList
+T}
+	T{
+.PN XmbTextListToTextProperty
+T}
+	T{
+.PN XwcTextListToTextProperty
+T}
+.sp
+	Text Input:
+.sp 6p
+T{
+.PN setlocale
+T}	T{
+.PN XOpenIM
+T}	T{
+XIM input method selection
+T}
+	T{
+.PN XRegisterIMInstantiateCallback
+T}	T{
+XIM selection
+T}
+	T{
+.PN XUnregisterIMInstantiateCallback
+T}	T{
+XIM selection
+T}
+T{
+.PN XIM
+T}	T{
+.PN XCreateIC
+T}	T{
+XIC input method configuration
+T}
+	T{
+.PN XLocaleOfIM , 
+and so on
+T}	T{
+Queried locale
+T}
+T{
+.PN XIC
+T}	T{
+.PN XmbLookupString
+T}	T{
+Keyboard layout
+T}
+	T{
+.PN XwcLookupString
+T}	T{
+Encoding of returned text
+T}
+.sp
+	Text Drawing:
+.sp 6p
+T{
+.PN setlocale
+T}	T{
+.PN XOpenOM
+T}	T{
+XOM output method selection
+T}
+	T{
+.PN XCreateFontSet
+T}	T{
+Charsets of fonts in 
+.PN XFontSet
+T}
+T{
+.PN XOM
+T}	T{
+.PN XCreateOC
+T}	T{
+XOC output method configuration
+T}
+	T{
+.PN XLocaleOfOM , 
+and so on
+T}	T{
+Queried locale
+T}
+T{
+.PN XFontSet
+T}	T{
+.PN XmbDrawText ,
+T}	T{
+Locale of supplied text
+T}
+	T{
+.PN XwcDrawText ,
+and so on
+T}	T{
+Locale of supplied text
+T}
+	T{
+.PN XExtentsOfFontSet ,
+and so on
+T}	T{
+Locale-dependent metrics
+T}
+	T{
+.PN XmbTextExtents ,
+T}
+	T{
+.PN XwcTextExtents , 
+and so on
+T}
+.sp
+	Xlib Errors:
+.sp 6p
+T{
+.PN setlocale
+T}	T{
+.PN XGetErrorDatabaseText
+T}	T{
+Locale of error message
+T}
+	T{
+.PN XGetErrorText
+T}
+.sp 6p
+_
+.TE
+.LP
+Clients may assume that a locale-encoded text string returned 
+by an X function can be passed to a C library routine, or vice versa,
+if the locale is the same at the two calls.
+.LP
+All text strings processed by internationalized Xlib functions are assumed
+to begin in the initial state of the encoding of the locale, if the encoding
+is state-dependent.
+.LP
+All Xlib functions behave as if they do not change the current locale
+or X modifier setting.
+(This means that if they do change locale or call 
+.PN XSetLocaleModifiers
+with a non-NULL argument, they must save and restore the current state on
+entry and exit.)
+Also, Xlib functions on implementations that conform to the ANSI C library do
+not alter the global state associated with the ANSI C functions 
+.PN mblen , 
+.PN mbtowc , 
+.PN wctomb ,
+and 
+.PN strtok .
+.NH 2
+Variable Argument Lists
+.XS
+\*(SN Variable Argument Lists
+.XE
+.LP
+Various functions in this chapter have arguments that conform
+to the ANSI C variable argument list calling convention.
+Each function denoted with an argument of the form ``...'' takes 
+a variable-length list of name and value pairs,
+where each name is a string and each value is of type 
+.PN XPointer .
+A name argument that is NULL identifies the end of the list. 
+.LP
+A variable-length argument list may contain a nested list.
+If the name 
+.PN XNVaNestedList
+is specified in place of an argument name,
+then the following value is interpreted as an 
+.PN XVaNestedList
+value that specifies a list of values logically inserted into the
+original list at the point of declaration.
+A NULL identifies the end of a nested list.
+.LP
+.sp
+To allocate a nested variable argument list dynamically, use
+.PN XVaCreateNestedList .
+.IN "XVaCreateNestedList" "" @DEF@"
+.sM
+.FD 0
+typedef void * XVaNestedList;
+
+XVaNestedList XVaCreateNestedList\^(\^\fIdummy\fP\^, ...)
+.br
+      int \fIdummy\fP\^; 
+.FN
+.IP \fIdummy\fP 1i
+Specifies an unused argument (required by ANSI C).
+.ds Al
+.IP ... 1i
+Specifies the variable length argument list\*(Al.
+.LP
+.eM
+The
+.PN XVaCreateNestedList
+function allocates memory and copies its arguments into
+a single list pointer,
+which may be used as a value for arguments requiring a list value.
+Any entries are copied as specified.
+Data passed by reference is not copied;
+the caller must ensure data remains valid for the lifetime
+of the nested list.
+The list should be freed using
+.PN XFree
+when it is no longer needed.
+.NH 2
+Output Methods
+.XS
+\*(SN Output Methods
+.XE
+.LP
+This section provides discussions of the following X Output Method
+(XOM) topics:
+.IP \(bu 5
+Output method overview
+.IP \(bu 5
+Output method functions
+.IP \(bu 5
+Output method values
+.IP \(bu 5
+Output context functions
+.IP \(bu 5
+Output context values
+.IP \(bu 5
+Creating and freeing a font set
+.IP \(bu 5
+Obtaining font set metrics
+.IP \(bu 5
+Drawing text using font sets
+.NH 3
+Output Method Overview
+.XS
+\*(SN Output Method Overview
+.XE
+.LP
+Locale-dependent text may include one or more text components, each of
+which may require different fonts and character set encodings.
+In some languages, each component might have a different
+drawing direction, and some components might contain
+context-dependent characters that change shape based on
+relationships with neighboring characters.
+.LP
+When drawing such locale-dependent text, some locale-specific
+knowledge is required;
+for example, what fonts are required to draw the text,
+how the text can be separated into components, and which
+fonts are selected to draw each component.
+Further, when bidirectional text must be drawn,
+the internal representation order of the text must be changed
+into the visual representation order to be drawn.
+.LP
+An X Output Method provides a functional interface so that clients
+do not have to deal directly with such locale-dependent details.
+Output methods provide the following capabilities:
+.IP \(bu 5
+Creating a set of fonts required to draw locale-dependent text.
+.IP \(bu 5
+Drawing locale-dependent text with a font set without the caller
+needing to be aware of locale dependencies.
+.IP \(bu 5
+Obtaining the escapement and extents in pixels of locale-dependent text.
+.IP \(bu 5
+Determining if bidirectional or context-dependent drawing is required
+in a specific locale with a specific font set.
+.LP
+Two different abstractions are used in the representation of
+the output method for clients.
+.LP
+The abstraction used to communicate with an output method
+is an opaque data structure represented by the 
+.PN XOM
+data type.
+The abstraction for representing the state of a particular output thread
+is called an \fIoutput context\fP.
+The Xlib representation of an output context is an 
+.PN XOC ,
+which is compatible with 
+.PN XFontSet
+in terms of its functional interface, but is 
+a broader, more generalized abstraction.
+.NH 3 
+Output Method Functions
+.XS
+\*(SN Output Method Functions
+.XE
+.LP
+To open an output method, use
+.PN XOpenOM .
+.IN "XOpenOM" "" "@DEF@"
+.sM
+.FD 0
+XOM XOpenOM\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XrmDatabase \fIdb\fP\^;
+.br
+      char *\fIres_name\fP\^;
+.br
+      char *\fIres_class\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIdb\fP 1i
+Specifies a pointer to the resource database.
+.IP \fIres_name\fP 1i
+Specifies the full resource name of the application.
+.IP \fIres_class\fP 1i
+Specifies the full class name of the application.
+.LP
+.eM
+The
+.PN XOpenOM
+function opens an output method
+matching the current locale and modifiers specification.
+The current locale and modifiers are bound to the output method
+when
+.PN XOpenOM
+is called.
+The locale associated with an output method cannot be changed.
+.LP
+The specific output method to which this call will be routed
+is identified on the basis of the current locale and modifiers.
+.PN XOpenOM
+will identify a default output method corresponding to the
+current locale.
+That default can be modified using 
+.PN XSetLocaleModifiers
+to set the output method modifier.
+.LP
+The db argument is the resource database to be used by the output method
+for looking up resources that are private to the output method.
+It is not intended that this database be used to look
+up values that can be set as OC values in an output context.
+If db is NULL,
+no database is passed to the output method.
+.LP
+The res_name and res_class arguments specify the resource name 
+and class of the application. 
+They are intended to be used as prefixes by the output method
+when looking up resources that are common to all output contexts
+that may be created for this output method.
+The characters used for resource names and classes must be in the
+X Portable Character Set.
+The resources looked up are not fully specified
+if res_name or res_class is NULL.
+.LP
+The res_name and res_class arguments are not assumed to exist beyond
+the call to
+.PN XOpenOM .
+The specified resource database is assumed to exist for the lifetime
+of the output method.
+.LP
+.PN XOpenOM
+returns NULL if no output method could be opened.
+.LP
+.sp
+To close an output method, use
+.PN XCloseOM .
+.IN "XCloseOM" "" "@DEF@"
+.sM
+.FD 0
+Status XCloseOM\^(\^\fIom\fP\^)
+.br
+      XOM \fIom\fP\^;
+.FN
+.IP \fIom\fP 1i
+Specifies the output method.
+.LP
+.eM
+The
+.PN XCloseOM
+function closes the specified output method.
+.LP
+.sp
+To set output method attributes, use 
+.PN XSetOMValues .
+.IN "XSetOMValues" "" "@DEF@"
+.sM
+.FD 0
+char * XSetOMValues\^(\^\fIom\fP\^, ...)
+.br
+      XOM \fIom\fP\^; 
+.FN
+.IP \fIom\fP 1i
+Specifies the output method.
+.ds Al \ to set XOM values
+.IP ... 1i
+Specifies the variable-length argument list\*(Al.
+.LP
+.eM
+The
+.PN XSetOMValues
+function presents a variable argument list programming interface
+for setting properties or features of the specified output method.
+This function returns NULL if it succeeds;
+otherwise,
+it returns the name of the first argument that could not be obtained.
+.LP
+No standard arguments are currently defined by Xlib.
+.LP
+.sp
+To query an output method, use 
+.PN XGetOMValues .
+.IN "XGetOMValues" "" "@DEF@"
+.sM
+.FD 0
+char * XGetOMValues\^(\^\fIom\fP\^, ...)
+.br
+      XOM \fIom\fP\^; 
+.FN
+.IP \fIom\fP 1i
+Specifies the output method.
+.ds Al \ to get XOM values
+.IP ... 1i
+Specifies the variable-length argument list\*(Al.
+.LP
+.eM
+The
+.PN XGetOMValues
+function presents a variable argument list programming interface
+for querying properties or features of the specified output method.
+This function returns NULL if it succeeds;
+otherwise,
+it returns the name of the first argument that could not be obtained.
+.LP
+To obtain the display associated with an output method, use
+.PN XDisplayOfOM .
+.IN "XDisplayOfOM" "" "@DEF@"
+.sM
+.FD 0
+Display * XDisplayOfOM\^(\^\fIom\fP\^)
+.br
+	XOM \fIom\fP\^;
+.FN
+.IP \fIom\fP 1i
+Specifies the output method.
+.LP
+.eM
+The
+.PN XDisplayOfOM
+function returns the display associated with the specified output method.
+.LP
+.sp
+To get the locale associated with an output method, use
+.PN XLocaleOfOM .
+.IN "XLocaleOfOM" "" "@DEF@"
+.sM
+.FD 0
+char * XLocaleOfOM\^(\^\fIom\fP\^)
+.br
+      XOM \fIom\fP\^; 
+.FN
+.IP \fIom\fP 1i
+Specifies the output method.
+.LP
+.eM
+The
+.PN XLocaleOfOM
+returns the locale associated with the specified output method.
+.NH 3
+X Output Method Values
+.XS
+\*(SN X Output Method Values
+.XE
+.LP
+The following table describes how XOM values are interpreted by an
+output method.
+The first column lists the XOM values.  The second column indicates
+how each of the XOM values are treated by a particular output style.
+.LP
+.LP
+The following key applies to this table.
+.TS H
+lw(1i) lw(4.75i).
+_
+.sp 6p
+.B
+Key	Explanation
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+G	T{
+This value may be read using 
+.PN XGetOMValues .
+T}
+.sp 6p
+_
+.TE
+.LP
+.TS H
+lw(2.25i) c
+lw(2.25i) c.
+_
+.sp 6p
+.B
+XOM Value	Key
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+T{
+.PN XNRequiredCharSet
+T}	T{
+G
+T}
+T{
+.PN XNQueryOrientation
+T}	T{
+G
+T}
+T{
+.PN XNDirectionalDependentDrawing
+T}	T{
+G
+T}
+T{
+.PN XNContextualDrawing
+T}	T{
+G
+T}
+.sp 6p
+_
+.TE
+.LP
+.NH 4
+Required Char Set
+.XS
+\*(SN Required Char Set
+.XE
+.LP
+The
+.PN XNRequiredCharSet
+argument returns the list of charsets that are required for loading the fonts
+needed for the locale.
+The value of the argument is a pointer to a structure of type
+.PN XOMCharSetList .
+.LP
+The
+.PN XOMCharSetList
+structure is defined as follows:
+.IN "XOMCharSetList" "" "@DEF@"
+.sM
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	int charset_count;
+	char **charset_list;
+} XOMCharSetList;
+.De
+.LP
+.eM
+The charset_list member is a list of one or more null-terminated
+charset names, and the charset_count member is the number of
+charset names.
+.LP
+The required charset list is owned by Xlib and should not be modified or
+freed by the client.
+It will be freed by a call to 
+.PN XCloseOM
+with the associated 
+.PN XOM .
+Until freed, its contents will not be modified by Xlib.
+.LP
+.NH 4
+Query Orientation
+.XS
+\*(SN Query Orientation
+.XE
+.LP
+The
+.PN XNQueryOrientation
+argument returns the global orientation of text when drawn.
+Other than
+.PN XOMOrientation_LTR_TTB ,
+the set of orientations supported is locale-dependent.
+The value of the argument is a pointer to a structure of type
+.PN XOMOrientation .
+Clients are responsible for freeing the
+.PN XOMOrientation
+structure by using
+.PN XFree ;
+this also frees the contents of the structure.
+.LP
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	int num_orientation;
+	XOrientation *orientation;	/* Input Text description */
+} XOMOrientation;
+
+typedef enum {
+	XOMOrientation_LTR_TTB,
+	XOMOrientation_RTL_TTB,	
+	XOMOrientation_TTB_LTR,
+	XOMOrientation_TTB_RTL,
+	XOMOrientation_Context
+} XOrientation;
+.De
+.LP
+.eM
+The possible value for XOrientation may be:
+.IP \(bu 5
+.PN XOMOrientation_LTR_TTB  
+left-to-right, top-to-bottom global orientation
+.IP \(bu 5
+.PN XOMOrientation_RTL_TTB  
+right-to-left, top-to-bottom global orientation
+.IP \(bu 5
+.PN XOMOrientation_TTB_LTR  
+top-to-bottom, left-to-right global orientation
+.IP \(bu 5
+.PN XOMOrientation_TTB_RTL  
+top-to-bottom, right-to-left global orientation
+.IP \(bu 5
+.PN XOMOrientation_Context  
+contextual global orientation
+.LP
+.NH 4
+Directional Dependent Drawing
+.XS
+\*(SN Directional Dependent Drawing
+.XE
+.LP
+The
+.PN XNDirectionalDependentDrawing
+argument indicates whether the text rendering functions
+implement implicit handling of directional text.  If this value
+is
+.PN True ,
+the output method has knowledge of directional
+dependencies and reorders text as necessary when
+rendering text.  If this value is
+.PN False ,
+the output method does not implement any directional text
+handling, and all character directions are assumed to be left-to-right.
+.LP
+Regardless of the rendering order of characters,
+the origins of all characters are on the primary draw direction side
+of the drawing origin.
+.LP
+This OM value presents functionality identical to the
+.PN XDirectionalDependentDrawing
+function.
+.NH 4
+Context Dependent Drawing
+.XS
+\*(SN Context Dependent Drawing
+.XE
+.LP
+The
+.PN XNContextualDrawing
+argument indicates whether the text rendering functions
+implement implicit context-dependent drawing.  If this value is
+.PN True ,
+the output method has knowledge of context dependencies and
+performs character shape editing, combining glyphs to present
+a single character as necessary.  The actual shape editing is
+dependent on the locale implementation and the font set used.
+.LP
+This OM value presents functionality identical to the
+.PN XContextualDrawing
+function.
+.NH 3
+Output Context Functions
+.XS
+\*(SN Output Context Functions
+.XE
+.LP
+An output context is an abstraction that contains both the data
+required by an output method and the information required
+to display that data.
+There can be multiple output contexts for one output method.
+The programming interfaces for creating, reading, or modifying
+an output context use a variable argument list.
+The name elements of the argument lists are referred to as XOC values.
+It is intended that output methods be controlled by these XOC values.
+As new XOC values are created,
+they should be registered with the X Consortium.
+An
+.PN XOC
+can be used anywhere an
+.PN XFontSet
+can be used, and vice versa;
+.PN XFontSet
+is retained for compatibility with previous releases.
+The concepts of output methods and output contexts include broader,
+more generalized abstraction than font set,
+supporting complex and more intelligent text display, and dealing not only
+with multiple fonts but also with context dependencies.
+However,
+.PN XFontSet
+is widely used in several interfaces, so
+.PN XOC
+is defined as an upward compatible type of
+.PN XFontSet .
+.LP
+.sp
+To create an output context, use
+.PN XCreateOC .
+.IN "XCreateOC" "" "@DEF@"
+.sM
+.FD 0
+XOC XCreateOC\^(\^\fIom\fP\^, ...)
+.br
+      XOM \fIom\fP\^;
+.FN
+.IP \fIom\fP 1i
+Specifies the output method.
+.ds Al \ to set XOC values
+.IP ... 1i
+Specifies the variable-length argument list\*(Al.
+.LP
+.eM
+The
+.PN XCreateOC 
+function creates an output context within the specified output method.
+.LP
+The base font names argument is mandatory at creation time, and
+the output context will not be created unless it is provided.
+All other output context values can be set later.
+.LP
+.PN XCreateOC
+returns NULL if no output context could be created.
+NULL can be returned for any of the following reasons:
+.IP \(bu 5
+A required argument was not set.
+.IP \(bu 5
+A read-only argument was set.
+.IP \(bu 5
+An argument name is not recognized.
+.IP \(bu 5
+The output method encountered an output method implementation-dependent error.
+.LP
+.PN XCreateOC
+can generate a
+.PN BadAtom
+error.
+.LP
+.sp
+To destroy an output context, use
+.PN XDestroyOC .
+.IN "XDestroyOC" "" "@DEF@"
+.sM
+.FD 0
+void XDestroyOC\^(\^\fIoc\fP\^)
+.br
+      XOC \fIoc\fP\^;
+.FN
+.IP \fIoc\fP 1i
+Specifies the output context.
+.LP
+.eM
+The
+.PN XDestroyOC
+function destroys the specified output context.
+.LP
+.sp
+To get the output method associated with an output context, use
+.PN XOMOfOC .
+.IN "XOMOfOC" "" "@DEF@"
+.sM
+.FD 0
+XOM XOMOfOC\^(\^\fIoc\fP\^)
+.br
+      XOC \fIoc\fP\^; 
+.FN
+.IP \fIoc\fP 1i
+Specifies the output context.
+.LP
+.eM
+The
+.PN XOMOfOC
+function returns the output method associated with the
+specified output context.
+.LP
+.sp
+Xlib provides two functions for setting and reading output context values,
+respectively,
+.PN XSetOCValues
+and
+.PN XGetOCValues .
+Both functions have a variable-length argument list.
+In that argument list, any XOC value's name must be denoted
+with a character string using the X Portable Character Set.
+.LP
+.sp
+To set XOC values, use
+.PN XSetOCValues .
+.IN "XSetOCValues" "" "@DEF@"
+.sM
+.FD 0
+char * XSetOCValues\^(\^\fIoc\fP\^, ...)
+.br
+      XOC \fIoc\fP\^;
+.FN
+.IP \fIoc\fP 1i
+Specifies the output context.
+.ds Al \ to set XOC values
+.IP ... 1i
+Specifies the variable-length argument list\*(Al.
+.LP
+.eM
+The
+.PN XSetOCValues
+function returns NULL if no error occurred; 
+otherwise,
+it returns the name of the first argument that could not be set.
+An argument might not be set for any of the following reasons:
+.IP \(bu 5
+The argument is read-only.
+.IP \(bu 5
+The argument name is not recognized.
+.IP \(bu 5
+An implementation-dependent error occurs.
+.LP
+Each value to be set must be an appropriate datum,
+matching the data type imposed by the semantics of the argument.
+.LP
+.PN XSetOCValues
+can generate a
+.PN BadAtom 
+error.
+.LP
+.sp
+To obtain XOC values, use
+.PN XGetOCValues .
+.IN "XGetOCValues" "" "@DEF@"
+.sM
+.FD 0
+char * XGetOCValues\^(\^\fIoc\fP\^, ...)
+.br
+      XOC \fIoc\fP\^;
+.FN
+.IP \fIoc\fP 1i
+Specifies the output context.
+.ds Al \ to get XOC values
+.IP ... 1i
+Specifies the variable-length argument list\*(Al.
+.LP
+.eM
+The
+.PN XGetOCValues
+function returns NULL if no error occurred; otherwise,
+it returns the name of the first argument that could not be obtained.
+An argument might not be obtained for any of the following reasons:
+.IP \(bu 5
+The argument name is not recognized.
+.IP \(bu 5
+An implementation-dependent error occurs.
+.LP
+Each argument value
+following a name must point to a location where the value is to be stored.
+.NH 3 
+Output Context Values
+.XS
+\*(SN Output Context Values
+.XE
+.LP
+The following table describes how XOC values are interpreted
+by an output method.
+The first column lists the XOC values.
+The second column indicates the alternative interfaces that function
+identically and are provided for compatibility with previous releases.
+The third column indicates how each of the XOC values is treated.
+.LP
+The following keys apply to this table.
+.TS H
+lw(1i) lw(4.75i).
+_
+.sp 6p
+.B
+Key	Explanation
+.sp 6p
+_
+.TH
+.R
+C	T{
+This value must be set with
+.PN XCreateOC .
+T}
+D	T{
+This value may be set using 
+.PN XCreateOC .
+If it is not set,
+.br
+a default is provided.
+T}
+G	T{
+This value may be read using 
+.PN XGetOCValues .
+T}
+S	T{
+This value must be set using
+.PN XSetOCValues .
+T}
+.sp 6p
+_
+.TE
+.LP
+.TS H
+l c c
+l c c.
+_
+.sp 6p
+.B
+XOC Value	Alternative Interface	Key
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+T{
+BaseFontName
+T}	T{
+.PN XCreateFontSet
+T}	T{
+C-G
+T}
+T{
+MissingCharSet
+T}	T{
+.PN XCreateFontSet
+T}	T{
+G
+T}
+T{
+DefaultString
+T}	T{
+.PN XCreateFontSet
+T}	T{
+G
+T}
+T{
+Orientation
+T}	T{
+\-
+T}	T{
+D-S-G
+T}
+T{
+ResourceName
+T}	T{
+\-
+T}	T{
+S-G
+T}
+T{
+ResourceClass
+T}	T{
+\-
+T}	T{
+S-G
+T}
+T{
+FontInfo
+T}	T{
+.PN XFontsOfFontSet
+T}	T{
+G
+T}
+T{
+OMAutomatic
+T}	T{
+\-
+T}	T{
+G
+T}
+.sp 6p
+_
+.TE
+.LP
+.NH 4
+Base Font Name
+.XS
+\*(SN Base Font Name
+.XE
+.LP
+The
+.PN XNBaseFontName
+argument is a list of base font names that Xlib uses
+to load the fonts needed for the locale.
+The base font names are a comma-separated list.  The string is null-terminated
+and is assumed to be in the Host Portable Character Encoding;
+otherwise, the result is implementation-dependent.
+White space immediately on either side of a separating comma is ignored.
+.LP
+Use of XLFD font names permits Xlib to obtain the fonts needed for a
+variety of locales from a single locale-independent base font name.
+The single base font name should name a family of fonts whose members
+are encoded in the various charsets needed by the locales of interest.
+.LP
+An XLFD base font name can explicitly name a charset needed for the locale.
+This allows the user to specify an exact font for use with a charset required
+by a locale, fully controlling the font selection.
+.LP
+If a base font name is not an XLFD name,
+Xlib will attempt to obtain an XLFD name from the font properties
+for the font.
+If Xlib is successful, the
+.PN XGetOCValues
+function will return this XLFD name instead of the client-supplied name.
+.LP
+This argument must be set at creation time
+and cannot be changed.
+If no fonts exist for any of the required charsets,
+or if the locale definition in Xlib requires that a font exist
+for a particular charset and a font is not found for that charset,
+.PN XCreateOC
+returns NULL.
+.LP
+When querying for the
+.PN XNBaseFontName
+XOC value,
+.PN XGetOCValues
+returns a null-terminated string identifying the base font names that
+Xlib used to load the fonts needed for the locale.
+This string is owned by Xlib and should not be modified or freed by
+the client.
+The string will be freed by a call to
+.PN XDestroyOC
+with the associated
+.PN XOC .
+Until freed, the string contents will not be modified by Xlib.
+.NH 4
+Missing CharSet
+.XS
+\*(SN Missing CharSet
+.XE
+.LP
+The
+.PN XNMissingCharSet
+argument returns the list of required charsets that are missing from the
+font set.
+The value of the argument is a pointer to a structure of type
+.PN XOMCharSetList .
+.LP
+If fonts exist for all of the charsets required by the current locale,
+charset_list is set to NULL and charset_count is set to zero.
+If no fonts exist for one or more of the required charsets,
+charset_list is set to a list of one or more null-terminated charset names
+for which no fonts exist, and charset_count is set to the number of
+missing charsets.
+The charsets are from the list of the required charsets for
+the encoding of the locale and do not include any charsets to which Xlib
+may be able to remap a required charset.
+.LP
+The missing charset list is owned by Xlib and should not be modified or
+freed by the client.
+It will be freed by a call to 
+.PN XDestroyOC
+with the associated
+.PN XOC .
+Until freed, its contents will not be modified by Xlib.
+.NH 4
+Default String
+.XS
+\*(SN Default String
+.XE
+.LP
+When a drawing or measuring function is called with an
+.PN XOC
+that has missing charsets, some characters in the locale will not be
+drawable.
+The
+.PN XNDefaultString
+argument returns a pointer to a string that represents the glyphs
+that are drawn with this
+.PN XOC
+when the charsets of the available fonts do not include all glyphs
+required to draw a character.
+The string does not necessarily consist of valid characters
+in the current locale and is not necessarily drawn with
+the fonts loaded for the font set,
+but the client can draw or measure the default glyphs
+by including this string in a string being drawn or measured with the
+.PN XOC .
+.LP
+If the
+.PN XNDefaultString
+argument returned the empty string ("\^"),
+no glyphs are drawn and the escapement is zero.
+The returned string is null-terminated.
+It is owned by Xlib and should not be modified or freed by the client.
+It will be freed by a call to
+.PN XDestroyOC
+with the associated
+.PN XOC .
+Until freed, its contents will not be modified by Xlib.
+.NH 4
+Orientation
+.XS
+\*(SN Orientation
+.XE
+.LP
+The
+.PN XNOrientation
+argument specifies the current orientation of text when drawn.  The value of
+this argument is one of the values returned by the
+.PN XGetOMValues
+function with the
+.PN XNQueryOrientation
+argument specified in the
+.PN XOrientation
+list.
+The value of the argument is of type
+.PN XOrientation .
+When
+.PN XNOrientation
+is queried, the value specifies the current orientation.  
+When
+.PN XNOrientation
+is set, a value is used to set the current orientation.
+.LP
+When 
+.PN XOMOrientation_Context
+is set, the text orientation of the 
+text is determined according to an implementation-defined method
+(for example, ISO 6429 control sequences), and the initial text orientation for
+locale-dependent Xlib functions is assumed to 
+be
+.PN XOMOrientation_LTR_TTB .
+.LP
+The
+.PN XNOrientation
+value does not change the prime drawing direction 
+for Xlib drawing functions.  
+.NH 4
+Resource Name and Class
+.XS
+\*(SN Resource Name and Class
+.XE
+.LP
+The
+.PN XNResourceName
+and
+.PN XNResourceClass
+arguments are strings that specify the full name and class
+used by the client to obtain resources for the display of the output context.
+These values should be used as prefixes for name and class
+when looking up resources that may vary according to the output context.
+If these values are not set,
+the resources will not be fully specified.
+.LP
+It is not intended that values that can be set as XOM values be
+set as resources.
+.LP
+When querying for the
+.PN XNResourceName
+or
+.PN XNResourceClass
+XOC value,
+.PN XGetOCValues
+returns a null-terminated string.
+This string is owned by Xlib and should not be modified or freed by
+the client.
+The string will be freed by a call to
+.PN XDestroyOC
+with the associated
+.PN XOC
+or when the associated value is changed via
+.PN XSetOCValues .
+Until freed, the string contents will not be modified by Xlib.
+.NH 4
+Font Info
+.XS
+\*(SN Font Info
+.XE
+.LP
+The
+.PN XNFontInfo
+argument specifies a list of one or more 
+.PN XFontStruct
+structures
+and font names for the fonts used for drawing by the given output context.
+The value of the argument is a pointer to a structure of type
+.PN XOMFontInfo .
+.LP
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	int num_font;
+	XFontStruct **font_struct_list;
+	char **font_name_list;
+} XOMFontInfo;
+.De
+.LP
+.eM
+A list of pointers to the
+.PN XFontStruct
+structures is returned to font_struct_list.
+A list of pointers to null-terminated, fully-specified font name strings
+in the locale of the output context is returned to font_name_list.
+The font_name_list order corresponds to the font_struct_list order.
+The number of
+.PN XFontStruct
+structures and font names is returned to num_font.
+.LP
+Because it is not guaranteed that a given character will be imaged using a
+single font glyph,
+there is no provision for mapping a character or default string 
+to the font properties, font ID, or direction hint for the font 
+for the character.
+The client may access the 
+.PN XFontStruct
+list to obtain these values for all the fonts currently in use.
+.LP
+Xlib does not guarantee that fonts are loaded from the server
+at the creation of an 
+.PN XOC .
+Xlib may choose to cache font data, loading it only as needed to draw text 
+or compute text dimensions.
+Therefore, existence of the per_char metrics in the 
+.PN XFontStruct
+structures in the
+.PN XFontStructSet
+is undefined.
+Also, note that all properties in the 
+.PN XFontStruct
+structures are in the STRING encoding.
+.LP
+The client must not free the 
+.PN XOMFontInfo
+struct itself; it will be freed when the
+.PN XOC
+is closed.
+.NH 4
+OM Automatic
+.XS
+\*(SN OM Automatic
+.XE
+.LP
+The
+.PN XNOMAutomatic
+argument returns whether the associated output context was created by
+.PN XCreateFontSet
+or not.  Because the
+.PN XFreeFontSet
+function not only destroys the output context but also closes the implicit
+output method associated with it,
+.PN XFreeFontSet
+should be used with any output context created by 
+.PN XCreateFontSet .
+However, it is possible that a client does not know how the output context
+was created.
+Before a client destroys the output context,
+it can query whether
+.PN XNOMAutomatic
+is set to determine whether 
+.PN XFreeFontSet 
+or 
+.PN XDestroyOC
+should be used to destroy the output context.
+.NH 3
+Creating and Freeing a Font Set
+.XS
+\*(SN Creating and Freeing a Font Set
+.XE
+.LP
+Xlib international text drawing is done using a set of one or more fonts,
+as needed for the locale of the text.
+Fonts are loaded according to a list of base font names 
+supplied by the client and the charsets required by the locale.
+The
+.PN XFontSet
+is an opaque type representing the state of a particular output thread
+and is equivalent to the type
+.PN XOC .
+.LP
+.sp
+The 
+.PN XCreateFontSet
+function is a convenience function for creating an output context using
+only default values.  The returned
+.PN XFontSet
+has an implicitly created
+.PN XOM .
+This
+.PN XOM
+has an OM value
+.PN XNOMAutomatic
+automatically set to
+.PN True
+so that the output context self indicates whether it was created by
+.PN XCreateOC
+or
+.PN XCreateFontSet .
+.IN "XCreateFontSet" "" "@DEF@"
+.sM
+.FD 0
+XFontSet XCreateFontSet\^(\^\fIdisplay\fP\^, \fIbase_font_name_list\fP\^, \fImissing_charset_list_return\fP\^,
+.br
+               \fImissing_charset_count_return\fP\^, \fIdef_string_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      char *\fIbase_font_name_list\fP\^;
+.br
+      char ***\fImissing_charset_list_return\fP\^;
+.br
+      int *\fImissing_charset_count_return\fP\^;
+.br
+      char **\fIdef_string_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIbase_font_name_list\fP 1i
+Specifies the base font names.
+.IP \fImissing_charset_list_return\fP 1i
+Returns the missing charsets.
+.IP \fImissing_charset_count_return\fP 1i
+Returns the number of missing charsets.
+.IP \fIdef_string_return\fP 1i
+Returns the string drawn for missing charsets.
+.LP
+.eM
+The 
+.PN XCreateFontSet
+function creates a font set for the specified display.
+The font set is bound to the current locale when 
+.PN XCreateFontSet
+is called.
+The font set may be used in subsequent calls to obtain font
+and character information and to image text in the locale of the font set.
+.LP
+The base_font_name_list argument is a list of base font names
+that Xlib uses to load the fonts needed for the locale.
+The base font names are a comma-separated list.
+The string is null-terminated
+and is assumed to be in the Host Portable Character Encoding; 
+otherwise, the result is implementation-dependent.
+White space immediately on either side of a separating comma is ignored.
+.LP
+Use of XLFD font names permits Xlib to obtain the fonts needed for a
+variety of locales from a single locale-independent base font name.
+The single base font name should name a family of fonts whose members
+are encoded in the various charsets needed by the locales of interest.
+.LP
+An XLFD base font name can explicitly name a charset needed for the locale.
+This allows the user to specify an exact font for use with a charset required
+by a locale, fully controlling the font selection.
+.LP
+If a base font name is not an XLFD name,
+Xlib will attempt to obtain an XLFD name from the font properties
+for the font.
+If this action is successful in obtaining an XLFD name, the
+.PN XBaseFontNameListOfFontSet
+function will return this XLFD name instead of the client-supplied name.
+.LP
+Xlib uses the following algorithm to select the fonts
+that will be used to display text with the 
+.PN XFontSet .
+.LP
+For each font charset required by the locale,
+the base font name list is searched for the first appearance of one 
+of the following cases that names a set of fonts that exist at the server:
+.IP \(bu 5
+The first XLFD-conforming base font name that specifies the required
+charset or a superset of the required charset in its 
+.PN CharSetRegistry
+and 
+.PN CharSetEncoding
+fields.
+The implementation may use a base font name whose specified charset
+is a superset of the required charset, for example,
+an ISO8859-1 font for an ASCII charset.
+.IP \(bu 5
+The first set of one or more XLFD-conforming base font names
+that specify one or more charsets that can be remapped to support the
+required charset.
+The Xlib implementation may recognize various mappings 
+from a required charset to one or more other charsets
+and use the fonts for those charsets.
+For example, JIS Roman is ASCII with tilde and backslash replaced 
+by yen and overbar;
+Xlib may load an ISO8859-1 font to support this character set
+if a JIS Roman font is not available.
+.IP \(bu 5
+The first XLFD-conforming font name or the first non-XLFD font name
+for which an XLFD font name can be obtained, combined with the
+required charset (replacing the 
+.PN CharSetRegistry
+and
+.PN CharSetEncoding
+fields in the XLFD font name).
+As in case 1,
+the implementation may use a charset that is a superset
+of the required charset.
+.IP \(bu 5
+The first font name that can be mapped in some implementation-dependent
+manner to one or more fonts that support imaging text in the charset.
+.LP
+For example, assume that a locale required the charsets:
+.LP
+.Ds 0
+ISO8859-1
+JISX0208.1983
+JISX0201.1976
+GB2312-1980.0
+.De
+.LP
+The user could supply a base_font_name_list that explicitly specifies the
+charsets, ensuring that specific fonts are used if they exist.
+For example:
+.LP
+.Ds 0
+"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\\
+-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\\
+-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\\
+-Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1"
+.De
+.LP
+Alternatively, the user could supply a base_font_name_list
+that omits the charsets,
+letting Xlib select font charsets required for the locale.
+For example:
+.LP
+.Ds 0
+"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
+-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\\
+-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\
+-Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"
+.De
+.LP
+Alternatively, the user could simply supply a single base font name
+that allows Xlib to select from all available fonts
+that meet certain minimum XLFD property requirements.
+For example:
+.LP
+.Ds 0
+"-*-*-*-R-Normal--*-180-100-100-*-*"
+.De
+.LP
+If 
+.PN XCreateFontSet
+is unable to create the font set, 
+either because there is insufficient memory or because the current locale
+is not supported,
+.PN XCreateFontSet
+returns NULL, missing_charset_list_return is set to NULL,
+and missing_charset_count_return
+is set to zero.
+If fonts exist for all of the charsets required by the current locale,
+.PN XCreateFontSet
+returns a valid
+.PN XFontSet ,
+missing_charset_list_return is set to NULL,
+and missing_charset_count_return is set to zero.
+.LP
+If no font exists for one or more of the required charsets,
+.PN XCreateFontSet
+sets missing_charset_list_return to a
+list of one or more null-terminated charset names for which no font exists
+and sets missing_charset_count_return to the number of missing fonts.
+The charsets are from the list of the required charsets for
+the encoding of the locale and do not include any charsets to which Xlib
+may be able to remap a required charset.
+.LP
+If no font exists for any of the required charsets
+or if the locale definition in Xlib requires that a font exist
+for a particular charset and a font is not found for that charset, 
+.PN XCreateFontSet
+returns NULL.
+Otherwise, 
+.PN XCreateFontSet
+returns a valid 
+.PN XFontSet
+to font_set.
+.LP
+When an Xmb/wc drawing or measuring function is called with an
+.PN XFontSet
+that has missing charsets, some characters in the locale will not be
+drawable.
+If def_string_return is non-NULL,
+.PN XCreateFontSet
+returns a pointer to a string that represents the glyphs
+that are drawn with this 
+.PN XFontSet
+when the charsets of the available fonts do not include all font glyphs
+required to draw a codepoint.
+The string does not necessarily consist of valid characters 
+in the current locale and is not necessarily drawn with
+the fonts loaded for the font set,
+but the client can draw and measure the default glyphs
+by including this string in a string being drawn or measured with the 
+.PN XFontSet .
+.LP
+If the string returned to def_string_return is the empty string ("\^"),
+no glyphs are drawn, and the escapement is zero.
+The returned string is null-terminated.
+It is owned by Xlib and should not be modified or freed by the client.
+It will be freed by a call to 
+.PN XFreeFontSet
+with the associated 
+.PN XFontSet .
+Until freed, its contents will not be modified by Xlib.
+.LP
+The client is responsible for constructing an error message from the
+missing charset and default string information and may choose to continue
+operation in the case that some fonts did not exist.
+.LP
+The returned 
+.PN XFontSet
+and missing charset list should be freed with 
+.PN XFreeFontSet
+and
+.PN XFreeStringList ,
+respectively.
+The client-supplied base_font_name_list may be freed 
+by the client after calling 
+.PN XCreateFontSet .
+.LP
+.sp
+To obtain a list of 
+.PN XFontStruct
+structures and full font names given an 
+.PN XFontSet ,
+use
+.PN XFontsOfFontSet .
+.IN "XFontsOfFontSet" "" "@DEF@"
+.sM
+.FD 0
+int XFontsOfFontSet\^(\^\fIfont_set\fP\^, \fIfont_struct_list_return\fP\^, \fIfont_name_list_return\fP\^)
+.br
+       XFontSet \fIfont_set\fP\^;
+.br
+       XFontStruct ***\fIfont_struct_list_return\fP\^;
+.br
+       char ***\fIfont_name_list_return\fP\^;
+.FN
+.IP \fIfont_set\fP 1i
+Specifies the font set.
+.IP \fIfont_struct_list_return\fP 1i
+Returns the list of font structs.
+.IP \fIfont_name_list_return\fP 1i
+Returns the list of font names.
+.LP
+.eM
+The
+.PN XFontsOfFontSet
+function returns a list of one or more 
+.PN XFontStructs
+and font names for the fonts used by the Xmb and Xwc layers
+for the given font set.
+A list of pointers to the
+.PN XFontStruct
+structures is returned to font_struct_list_return.
+A list of pointers to null-terminated, fully specified font name strings
+in the locale of the font set is returned to font_name_list_return.
+The font_name_list order corresponds to the font_struct_list order.
+The number of
+.PN XFontStruct
+structures and font names is returned as the value of the function.
+.LP
+Because it is not guaranteed that a given character will be imaged using a
+single font glyph,
+there is no provision for mapping a character or default string 
+to the font properties, font ID, or direction hint for the font 
+for the character.
+The client may access the 
+.PN XFontStruct
+list to obtain these values for all the fonts currently in use.
+.LP
+Xlib does not guarantee that fonts are loaded from the server
+at the creation of an 
+.PN XFontSet .
+Xlib may choose to cache font data, loading it only as needed to draw text 
+or compute text dimensions.
+Therefore, existence of the per_char metrics in the 
+.PN XFontStruct
+structures in the
+.PN XFontStructSet
+is undefined.
+Also, note that all properties in the 
+.PN XFontStruct
+structures are in the STRING encoding.
+.LP
+The 
+.PN XFontStruct
+and font name lists are owned by Xlib 
+and should not be modified or freed by the client.
+They will be freed by a call to
+.PN XFreeFontSet
+with the associated
+.PN XFontSet .
+Until freed, their contents will not be modified by Xlib.
+.LP
+.sp
+To obtain the base font name list and the selected font name list given an
+.PN XFontSet ,
+use
+.PN XBaseFontNameListOfFontSet .
+.IN "XBaseFontNameListOfFontSet" "" "@DEF@"
+.sM
+.FD 0
+char *XBaseFontNameListOfFontSet\^(\^\fIfont_set\fP\^)
+.br
+      XFontSet \fIfont_set\fP\^;
+.FN
+.IP \fIfont_set\fP 1i
+Specifies the font set.
+.LP
+.eM
+The
+.PN XBaseFontNameListOfFontSet
+function returns the original base font name list supplied
+by the client when the 
+.PN XFontSet
+was created.
+A null-terminated string containing a list of
+comma-separated font names is returned
+as the value of the function.
+White space may appear immediately on either side of separating commas.
+.LP
+If 
+.PN XCreateFontSet
+obtained an XLFD name from the font properties for the font specified
+by a non-XLFD base name, the
+.PN XBaseFontNameListOfFontSet
+function will return the XLFD name instead of the non-XLFD base name.
+.LP
+The base font name list is owned by Xlib and should not be modified or
+freed by the client.
+It will be freed by a call to 
+.PN XFreeFontSet
+with the associated 
+.PN XFontSet .
+Until freed, its contents will not be modified by Xlib.
+.LP
+.sp
+To obtain the locale name given an 
+.PN XFontSet ,
+use
+.PN XLocaleOfFontSet .
+.IN "XLocaleOfFontSet" "" "@DEF@"
+.sM
+.FD 0
+char *XLocaleOfFontSet\^(\^\fIfont_set\fP\^)
+.br
+      XFontSet \fIfont_set\fP\^;
+.FN
+.IP \fIfont_set\fP 1i
+Specifies the font set.
+.LP
+.eM
+The
+.PN XLocaleOfFontSet
+function
+returns the name of the locale bound to the specified
+.PN XFontSet ,
+as a null-terminated string.
+.LP
+The returned locale name string is owned by Xlib
+and should not be modified or freed by the client.
+It may be freed by a call to
+.PN XFreeFontSet
+with the associated 
+.PN XFontSet .
+Until freed, it will not be modified by Xlib.
+.LP
+.sp
+The 
+.PN XFreeFontSet
+function is a convenience function for freeing an output context.
+.PN XFreeFontSet 
+also frees its associated 
+.PN XOM
+if the output context was created by
+.PN XCreateFontSet .
+.IN "XFreeFontSet" "" "@DEF@"
+.sM
+.FD 0
+void XFreeFontSet\^(\^\fIdisplay\fP\^, \fIfont_set\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XFontSet \fIfont_set\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIfont_set\fP 1i
+Specifies the font set.
+.LP
+.eM
+The
+.PN XFreeFontSet
+function frees the specified font set.
+The associated base font name list, font name list, 
+.PN XFontStruct
+list, and 
+.PN XFontSetExtents , 
+if any, are freed.
+.NH 3
+Obtaining Font Set Metrics
+.XS
+\*(SN Obtaining Font Set Metrics
+.XE
+.LP
+Metrics for the internationalized text drawing functions 
+are defined in terms of a primary draw direction, 
+which is the default direction in which the character origin advances
+for each succeeding character in the string.
+The Xlib interface is currently defined to support only a left-to-right
+primary draw direction.
+The drawing origin is the position passed to the drawing function 
+when the text is drawn.
+The baseline is a line drawn through the drawing origin parallel
+to the primary draw direction.
+Character ink is the pixels painted in the foreground color 
+and does not include interline or intercharacter spacing 
+or image text background pixels.
+.LP
+The drawing functions are allowed to implement implicit text
+directionality control, reversing the order in which characters are
+rendered along the primary draw direction in response to locale-specific
+lexical analysis of the string.
+.LP
+Regardless of the character rendering order,
+the origins of all characters are on the primary draw direction side
+of the drawing origin.
+The screen location of a particular character image may be determined with
+.PN XmbTextPerCharExtents
+or
+.PN XwcTextPerCharExtents .
+.LP
+The drawing functions are allowed to implement context-dependent
+rendering, where the glyphs drawn for a string are not simply a
+concatenation of the glyphs that represent each individual character.
+A string of two characters drawn with 
+.PN XmbDrawString
+may render differently than if the two characters 
+were drawn with separate calls to
+.PN XmbDrawString .
+If the client appends or inserts a character 
+in a previously drawn string,
+the client may need to redraw some adjacent characters 
+to obtain proper rendering.
+.LP
+.sp
+To find out about direction-dependent rendering, use
+.PN XDirectionalDependentDrawing .
+.IN "XDirectionalDependentDrawing" "" "@DEF@"
+.sM
+.FD 0
+Bool XDirectionalDependentDrawing\^(\^\fIfont_set\fP\^)
+.br
+      XFontSet \fIfont_set\fP\^;
+.FN
+.IP \fIfont_set\fP 1i
+Specifies the font set.
+.LP
+.eM
+The
+.PN XDirectionalDependentDrawing
+function returns
+.PN True
+if the drawing functions implement implicit text directionality;
+otherwise, it returns
+.PN False .
+.LP
+.sp
+To find out about context-dependent rendering, use
+.PN XContextualDrawing .
+.IN "XContextualDrawing" "" "@DEF@"
+.sM
+.FD 0
+Bool XContextualDrawing\^(\^\fIfont_set\fP\^)
+.br
+      XFontSet \fIfont_set\fP\^;
+.FN
+.IP \fIfont_set\fP 1i
+Specifies the font set.
+.LP
+.eM
+The
+.PN XContextualDrawing
+function returns
+.PN True
+if text drawn with the font set might include context-dependent drawing;
+otherwise, it returns
+.PN False .
+.LP
+.sp
+To find out about context-dependent or direction-dependent rendering, use
+.PN XContextDependentDrawing .
+.IN "XContextDependentDrawing" "" "@DEF@"
+.sM
+.FD 0
+Bool XContextDependentDrawing\^(\^\fIfont_set\fP\^)
+.br
+      XFontSet \fIfont_set\fP\^;
+.FN
+.IP \fIfont_set\fP 1i
+Specifies the font set.
+.LP
+.eM
+The
+.PN XContextDependentDrawing
+function returns
+.PN True
+if the drawing functions implement implicit text directionality or
+if text drawn with the font_set might include context-dependent drawing;
+otherwise, it returns
+.PN False .
+.LP
+The drawing functions do not interpret newline, tab, or other control
+characters.
+The behavior when nonprinting characters other than space are drawn
+is implementation-dependent.
+It is the client's responsibility to interpret control characters
+in a text stream.
+.LP
+The maximum character extents for the fonts that are used by the text
+drawing layers can be accessed by the 
+.PN XFontSetExtents
+structure:
+.IN "XFontSetExtents" "" "@DEF@"
+.LP
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	XRectangle max_ink_extent;	/* over all drawable characters */
+	XRectangle max_logical_extent;	/* over all drawable characters */
+} XFontSetExtents;
+.De
+.LP
+The 
+.PN XRectangle
+structures used to return font set metrics are the usual Xlib screen-oriented 
+rectangles
+with x, y giving the upper left corner, and width and height always positive.
+.LP
+The max_ink_extent member gives the maximum extent, over all drawable characters, of
+the rectangles that bound the character glyph image drawn in the
+foreground color, relative to a constant origin.
+See 
+.PN XmbTextExtents
+and
+.PN XwcTextExtents
+for detailed semantics.
+.LP
+The max_logical_extent member gives the maximum extent,
+over all drawable characters, of the rectangles 
+that specify minimum spacing to other graphical features,
+relative to a constant origin.
+Other graphical features drawn by the client, for example,
+a border surrounding the text, should not intersect this rectangle.
+The max_logical_extent member should be used to compute minimum 
+interline spacing and the minimum area that must be allowed
+in a text field to draw a given number of arbitrary characters.
+.LP
+Due to context-dependent rendering,
+appending a given character to a string may change 
+the string's extent by an amount other than that character's
+individual extent.
+.LP
+The rectangles for a given character in a string can be obtained from
+.PN XmbPerCharExtents
+or
+.PN XwcPerCharExtents .
+.LP
+.sp
+To obtain the maximum extents structure given an
+.PN XFontSet ,
+use
+.PN XExtentsOfFontSet .
+.IN "XExtentsOfFontSet" "" "@DEF@"
+.sM
+.FD 0
+XFontSetExtents *XExtentsOfFontSet\^(\^\fIfont_set\fP\^)
+.br
+       XFontSet \fIfont_set\fP\^;
+.FN
+.IP \fIfont_set\fP 1i
+Specifies the font set.
+.LP
+.eM
+The
+.PN XExtentsOfFontSet
+function returns an
+.PN XFontSetExtents
+structure for the fonts used by the Xmb and Xwc layers
+for the given font set.
+.LP
+The 
+.PN XFontSetExtents
+structure is owned by Xlib and should not be modified
+or freed by the client.
+It will be freed by a call to 
+.PN XFreeFontSet
+with the associated 
+.PN XFontSet .
+Until freed, its contents will not be modified by Xlib.
+.LP
+.sp
+To obtain the escapement in pixels of the specified text as a value,
+use
+.PN XmbTextEscapement
+or 
+.PN XwcTextEscapement .
+.IN "XmbTextEscapement" "" "@DEF@"
+.IN "XwcTextEscapement" "" "@DEF@"
+.sM
+.FD 0
+int XmbTextEscapement\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^)
+.br
+      XFontSet \fIfont_set\fP\^;
+.br
+      char *\fIstring\fP\^;
+.br
+      int \fInum_bytes\fP\^;
+.FN
+.FD 0
+int XwcTextEscapement\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^)
+.br
+      XFontSet \fIfont_set\fP\^;
+.br
+      wchar_t *\fIstring\fP\^;
+.br
+      int \fInum_wchars\fP\^;
+.FN
+.IP \fIfont_set\fP 1i
+Specifies the font set.
+.IP \fIstring\fP 1i
+Specifies the character string.
+.IP \fInum_bytes\fP 1i
+Specifies the number of bytes in the string argument.
+.IP \fInum_wchars\fP 1i
+Specifies the number of characters in the string argument.
+.LP
+.eM
+The
+.PN XmbTextEscapement
+and
+.PN XwcTextEscapement
+functions return the escapement in pixels of the specified string as a value,
+using the fonts loaded for the specified font set.
+The escapement is the distance in pixels in the primary draw
+direction from the drawing origin to the origin of the next character to
+be drawn, assuming that the rendering of the next character is not
+dependent on the supplied string.
+.LP
+Regardless of the character rendering order,
+the escapement is always positive.
+.LP
+.sp
+To obtain the overall_ink_return and overall_logical_return arguments,
+the overall bounding box of the string's image, and a logical bounding box,
+use
+.PN XmbTextExtents
+ or
+.PN XwcTextExtents .
+.IN "XmbTextExtents" "" "@DEF@"
+.IN "XwcTextExtents" "" "@DEF@"
+.sM
+.FD 0
+int XmbTextExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^)
+.br
+      XFontSet \fIfont_set\fP\^;
+.br
+      char *\fIstring\fP\^;
+.br
+      int \fInum_bytes\fP\^;
+.br
+      XRectangle *\fIoverall_ink_return\fP\^;
+.br
+      XRectangle *\fIoverall_logical_return\fP\^;
+.FN
+.FD 0
+int XwcTextExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^, 
+\fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^)
+.br
+      XFontSet \fIfont_set\fP\^;
+.br
+      wchar_t *\fIstring\fP\^;
+.br
+      int \fInum_wchars\fP\^;
+.br
+      XRectangle *\fIoverall_ink_return\fP\^;
+.br
+      XRectangle *\fIoverall_logical_return\fP\^;
+.FN
+.IP \fIfont_set\fP 1i
+Specifies the font set.
+.IP \fIstring\fP 1i
+Specifies the character string.
+.IP \fInum_bytes\fP 1i
+Specifies the number of bytes in the string argument.
+.IP \fInum_wchars\fP 1i
+Specifies the number of characters in the string argument.
+.ds Ov dimensions
+.IP \fIoverall_ink_return\fP 1i
+Returns the overall ink \*(Ov.
+.IP \fIoverall_logical_return\fP 1i
+Returns the overall logical \*(Ov.
+.LP
+.eM
+The
+.PN XmbTextExtents
+and
+.PN XwcTextExtents
+functions set the components of the specified overall_ink_return and
+overall_logical_return
+arguments to the overall bounding box of the string's image
+and a logical bounding box for spacing purposes, respectively.
+They return the value returned by 
+.PN XmbTextEscapement
+or
+.PN XwcTextEscapement .
+These metrics are relative to the drawing origin of the string,
+using the fonts loaded for the specified font set.
+.LP
+If the overall_ink_return argument is non-NULL,
+it is set to the bounding box of the string's character ink.
+The overall_ink_return for a nondescending, horizontally drawn
+Latin character is conventionally entirely above the baseline;
+that is, overall_ink_return.height <= \-overall_ink_return.y.
+The overall_ink_return for a nonkerned character
+is entirely at, and to the right of, the origin;
+that is, overall_ink_return.x >= 0.
+A character consisting of a single pixel at the origin would set
+overall_ink_return fields y = 0, x = 0, width = 1, and height = 1.
+.LP
+If the overall_logical_return argument is non-NULL,
+it is set to the bounding box that provides minimum spacing
+to other graphical features for the string.
+Other graphical features, for example, a border surrounding the text,
+should not intersect this rectangle.
+.LP
+When the 
+.PN XFontSet
+has missing charsets,
+metrics for each unavailable character are taken 
+from the default string returned by 
+.PN XCreateFontSet 
+so that the metrics represent the text as it will actually be drawn.
+The behavior for an invalid codepoint is undefined.
+.LP
+To determine the effective drawing origin for a character in a drawn string,
+the client should call 
+.PN XmbTextPerCharExtents
+on the entire string, then on the character,
+and subtract the x values of the returned 
+rectangles for the character.
+This is useful to redraw portions of a line of text
+or to justify words, but for context-dependent rendering,
+the client should not assume that it can redraw the character by itself
+and get the same rendering.
+.LP
+.sp
+To obtain per-character information for a text string,
+use
+.PN XmbTextPerCharExtents
+or
+.PN XwcTextPerCharExtents .
+.IN "XmbTextPerCharExtents" "" "@DEF@"
+.IN "XwcTextPerCharExtents" "" "@DEF@"
+.sM
+.FD 0
+Status XmbTextPerCharExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^, \fIink_array_return\fP\^,
+.br
+           \fIlogical_array_return\fP\^, \fIarray_size\fP\^, \fInum_chars_return\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_logical_return\fP\^)
+.br
+      XFontSet \fIfont_set\fP\^;
+.br
+      char *\fIstring\fP\^;
+.br
+      int \fInum_bytes\fP\^;
+.br
+      XRectangle *\fIink_array_return\fP\^;
+.br
+      XRectangle *\fIlogical_array_return\fP\^;
+.br
+      int \fIarray_size\fP\^;
+.br
+      int *\fInum_chars_return\fP\^;
+.br
+      XRectangle *\fIoverall_ink_return\fP\^;
+.br
+      XRectangle *\fIoverall_logical_return\fP\^;
+.FN
+.FD 0
+Status XwcTextPerCharExtents\^(\^\fIfont_set\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^, \fIink_array_return\fP\^,
+.br
+          \fIlogical_array_return\fP\^, \fIarray_size\fP\^, \fInum_chars_return\fP\^, \fIoverall_ink_return\fP\^, \fIoverall_ink_return\fP\^)
+.br
+      XFontSet \fIfont_set\fP\^;
+.br
+      wchar_t *\fIstring\fP\^;
+.br
+      int \fInum_wchars\fP\^;
+.br
+      XRectangle *\fIink_array_return\fP\^;
+.br
+      XRectangle *\fIlogical_array_return\fP;
+.br
+      int \fIarray_size\fP\^;
+.br
+      int *\fInum_chars_return\fP\^;
+.br
+      XRectangle *\fIoverall_ink_return\fP\^;
+.br
+      XRectangle *\fIoverall_logical_return\fP\^;
+.FN
+.IP \fIfont_set\fP 1i
+Specifies the font set.
+.IP \fIstring\fP 1i
+Specifies the character string.
+.IP \fInum_bytes\fP 1i
+Specifies the number of bytes in the string argument.
+.IP \fInum_wchars\fP 1i
+Specifies the number of characters in the string argument.
+.IP \fIink_array_return\fP 1i
+Returns the ink dimensions for each character.
+.IP \fIlogical_array_return\fP 1i
+Returns the logical dimensions for each character.
+.IP \fIarray_size\fP 1i
+Specifies the size of ink_array_return and logical_array_return.
+The caller must pass in arrays of this size.
+.IP \fInum_chars_return\fP 1i
+Returns the number of characters in the string argument.
+.ds Ov extents of the entire string
+.IP \fIoverall_ink_return\fP 1i
+Returns the overall ink \*(Ov.
+.IP \fIoverall_logical_return\fP 1i
+Returns the overall logical \*(Ov.
+.LP
+.eM
+The
+.PN XmbTextPerCharExtents
+and
+.PN XwcTextPerCharExtents
+functions return the text dimensions of each character of the specified text,
+using the fonts loaded for the specified font set.
+Each successive element of ink_array_return and logical_array_return
+is set to the successive character's drawn metrics,
+relative to the drawing origin of the string and one 
+rectangle
+for each character in the supplied text string.
+The number of elements of ink_array_return and logical_array_return
+that have been set is returned to num_chars_return.
+.LP
+Each element of ink_array_return is set to the bounding box 
+of the corresponding character's drawn foreground color.
+Each element of logical_array_return is set to the bounding box 
+that provides minimum spacing to other graphical features
+for the corresponding character.
+Other graphical features should not intersect any of the
+logical_array_return rectangles.
+.LP
+Note that an 
+.PN XRectangle
+represents the effective drawing dimensions of the character,
+regardless of the number of font glyphs that are used to draw
+the character or the direction in which the character is drawn.
+If multiple characters map to a single character glyph,
+the dimensions of all the 
+.PN XRectangles
+of those characters are the same.
+.LP
+When the 
+.PN XFontSet
+has missing charsets, metrics for each unavailable
+character are taken from the default string returned by 
+.PN XCreateFontSet
+so that the metrics represent the text as it will actually be drawn.
+The behavior for an invalid codepoint is undefined.
+.LP
+If the array_size is too small for the number of characters in the
+supplied text, the functions return zero
+and num_chars_return is set to the number of rectangles required.
+Otherwise, the functions return a nonzero value.
+.LP
+If the overall_ink_return or overall_logical_return argument is non-NULL,
+.PN XmbTextPerCharExtents
+and 
+.PN XwcTextPerCharExtents
+return the maximum extent of the string's metrics to overall_ink_return
+or overall_logical_return, as returned by 
+.PN XmbTextExtents
+or 
+.PN XwcTextExtents .
+.NH 3
+Drawing Text Using Font Sets
+.XS
+\*(SN Drawing Text Using Font Sets
+.XE
+.LP
+The functions defined in this section
+draw text at a specified location in a drawable.
+They are similar to the functions
+.PN XDrawText ,
+.PN XDrawString ,
+and
+.PN XDrawImageString
+except that they work with font sets instead of single fonts
+and interpret the text based on the locale of the font set
+instead of treating the bytes of the string as direct font indexes.
+See section 8.6 for details of the use of Graphics Contexts (GCs)
+and possible protocol errors.
+If a 
+.PN BadFont
+error is generated,
+characters prior to the offending character may have been drawn.
+.LP
+The text is drawn using the fonts loaded for the specified font set;
+the font in the GC is ignored and may be modified by the functions.
+No validation that all fonts conform to some width rule is performed.
+.LP
+The text functions
+.PN XmbDrawText
+and
+.PN XwcDrawText
+use the following structures:
+.LP
+.IN "XmbTextItem" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	char *chars;	/* pointer to string */
+	int nchars;	/* number of bytes */
+	int delta;	/* pixel delta between strings */
+	XFontSet font_set; 	/* fonts, None means don't change */
+} XmbTextItem;
+.De
+.LP
+.IN "XwcTextItem" "" "@DEF@"
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	wchar_t *chars;	/* pointer to wide char string */
+	int nchars;	/* number of wide characters */
+	int delta;	/* pixel delta between strings */
+	XFontSet font_set;	/* fonts, None means don't change */
+} XwcTextItem;
+.De
+.LP
+.eM
+.sp
+To draw text using multiple font sets in a given drawable, use
+.PN XmbDrawText
+or
+.PN XwcDrawText .
+.IN "XmbDrawText" "" "@DEF@"
+.IN "XwcDrawText" "" "@DEF@"
+.sM
+.FD 0
+void XmbDrawText\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      XmbTextItem *\fIitems\fP\^;
+.br
+      int \fInitems\fP\^;
+.FN
+.FD 0
+void XwcDrawText\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIitems\fP\^, \fInitems\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      XwcTextItem *\fIitems\fP\^;
+.br
+      int \fInitems\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIgc\fP 1i
+Specifies the GC.
+.ds Xy
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.IP \fIitems\fP 1i
+Specifies an array of text items.
+.IP \fInitems\fP 1i
+Specifies the number of text items in the array.
+.LP
+.eM
+The
+.PN XmbDrawText
+and 
+.PN XwcDrawText 
+functions allow complex spacing and font set shifts between text strings.
+Each text item is processed in turn, with the origin of a text
+element advanced in the primary draw direction by the escapement of the
+previous text item.
+A text item delta specifies an additional escapement of the text item
+drawing origin in the primary draw direction.
+A font_set member other than 
+.PN None
+in an item causes the font set to be used for this and subsequent text items
+in the text_items list.
+Leading text items with a font_set member set to
+.PN None
+will not be drawn.
+.LP
+.PN XmbDrawText
+and
+.PN XwcDrawText
+do not perform any context-dependent rendering between text segments.
+Clients may compute the drawing metrics by passing each text segment to
+.PN XmbTextExtents
+and
+.PN XwcTextExtents
+or 
+.PN XmbTextPerCharExtents
+and
+.PN XwcTextPerCharExtents .
+When the 
+.PN XFontSet
+has missing charsets, each unavailable character is drawn 
+with the default string returned by 
+.PN XCreateFontSet .
+The behavior for an invalid codepoint is undefined.
+.LP
+.sp
+To draw text using a single font set in a given drawable, use
+.PN XmbDrawString
+or
+.PN XwcDrawString .
+.IN "XmbDrawString" "" "@DEF@"
+.IN "XwcDrawString" "" "@DEF@"
+.sM
+.FD 0
+void XmbDrawString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      XFontSet \fIfont_set\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      char *\fIstring\fP\^;
+.br
+      int \fInum_bytes\fP\^;
+.FN
+.FD 0
+void XwcDrawString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      XFontSet \fIfont_set\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      wchar_t *\fIstring\fP\^;
+.br
+      int \fInum_wchars\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIfont_set\fP 1i
+Specifies the font set.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.ds Xy
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.IP \fIstring\fP 1i
+Specifies the character string.
+.IP \fInum_bytes\fP 1i
+Specifies the number of bytes in the string argument.
+.IP \fInum_wchars\fP 1i
+Specifies the number of characters in the string argument.
+.LP
+.eM
+The
+.PN XmbDrawString
+and
+.PN XwcDrawString
+functions draw the specified text with the foreground pixel.
+When the 
+.PN XFontSet
+has missing charsets, each unavailable character is drawn 
+with the default string returned by 
+.PN XCreateFontSet .
+The behavior for an invalid codepoint is undefined.
+.LP
+.sp
+To draw image text using a single font set in a given drawable, use
+.PN XmbDrawImageString
+or
+.PN XwcDrawImageString .
+.IN "XmbDrawImageString" "" "@DEF@"
+.IN "XwcDrawImageString" "" "@DEF@"
+.sM
+.FD 0
+void XmbDrawImageString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_bytes\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      XFontSet \fIfont_set\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      char *\fIstring\fP\^;
+.br
+      int \fInum_bytes\fP\^;
+.FN
+.FD 0
+void XwcDrawImageString\^(\^\fIdisplay\fP\^, \fId\fP\^, \fIfont_set\fP\^, \fIgc\fP\^, \fIx\fP\^, \fIy\fP\^, \fIstring\fP\^, \fInum_wchars\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      XFontSet \fIfont_set\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.br
+      wchar_t *\fIstring\fP\^;
+.br
+      int \fInum_wchars\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fId\fP 1i
+Specifies the drawable. 
+.IP \fIfont_set\fP 1i
+Specifies the font set.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.ds Xy
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.IP \fIstring\fP 1i
+Specifies the character string.
+.IP \fInum_bytes\fP 1i
+Specifies the number of bytes in the string argument.
+.IP \fInum_wchars\fP 1i
+Specifies the number of characters in the string argument.
+.LP
+.eM
+The
+.PN XmbDrawImageString
+and
+.PN XwcDrawImageString
+functions fill a destination rectangle with the background pixel defined
+in the GC and then paint the text with the foreground pixel.
+The filled rectangle is the rectangle returned to overall_logical_return by
+.PN XmbTextExtents
+or 
+.PN XwcTextExtents
+for the same text and 
+.PN XFontSet .
+.LP
+When the 
+.PN XFontSet
+has missing charsets, each unavailable character is drawn 
+with the default string returned by 
+.PN XCreateFontSet .
+The behavior for an invalid codepoint is undefined.
+.NH 2
+Input Methods
+.XS
+\*(SN Input Methods
+.XE
+.LP
+This section provides discussions of the following X Input Method
+(XIM) topics:
+.IP \(bu 5
+Input method overview
+.IP \(bu 5
+Input method management
+.IP \(bu 5
+Input method functions
+.IP \(bu 5
+Input method values
+.IP \(bu 5
+Input context functions
+.IP \(bu 5
+Input context values
+.IP \(bu 5
+Input method callback semantics
+.IP \(bu 5
+Event filtering
+.IP \(bu 5
+Getting keyboard input
+.IP \(bu 5
+Input method conventions
+.NH 3
+Input Method Overview
+.XS
+\*(SN Input Method Overview
+.XE
+.LP
+This section provides definitions for terms and concepts used
+for internationalized text input and a brief overview of the
+intended use of the mechanisms provided by Xlib.
+.LP
+A large number of languages in the world use alphabets
+consisting of a small set of symbols (letters) to form words.
+To enter text into a computer in an alphabetic language,
+a user usually has a keyboard on which there exist key symbols corresponding
+to the alphabet.
+Sometimes, a few characters of an alphabetic language are missing
+on the keyboard.
+Many computer users who speak a Latin-alphabet-based language 
+only have an English-based keyboard.
+They need to hit a combination of keystrokes
+to enter a character that does not exist directly on the keyboard.
+A number of algorithms have been developed for entering such characters.
+These are known as European input methods, compose input methods, 
+or dead-key input methods.
+.LP
+Japanese is an example of a language with a phonetic symbol set,
+where each symbol represents a specific sound.
+There are two phonetic symbol sets in Japanese:  Katakana and Hiragana.
+In general,
+Katakana is used for words that are of foreign origin,
+and Hiragana is used for writing native Japanese words.
+Collectively, the two systems are called Kana.
+Each set consists of 48 characters.
+.LP
+Korean also has a phonetic symbol set, called Hangul.
+Each of the 24 basic phonetic symbols (14 consonants and 10 vowels)
+represents a specific sound.
+A syllable is composed of two or three parts: 
+the initial consonants, the vowels, and the optional last consonants.
+With Hangul,
+syllables can be treated as the basic units on which text processing is done.
+For example,
+a delete operation may work on a phonetic symbol or a syllable.
+Korean code sets include several thousands of these syllables.
+A user types the phonetic symbols that make up the syllables of the words
+to be entered.
+The display may change as each phonetic symbol is entered.
+For example,
+when the second phonetic symbol of a syllable is entered,
+the first phonetic symbol may change its shape and size.
+Likewise, when the third phonetic symbol is entered,
+the first two phonetic symbols may change their shape and size.
+.LP
+Not all languages rely solely on alphabetic or phonetic systems.
+Some languages, including Japanese and Korean, employ an
+ideographic writing system.
+In an ideographic system, rather than taking a small set of
+symbols and combining them in different ways to create words,
+each word consists of one unique symbol (or, occasionally, several symbols).
+The number of symbols can be very large: 
+approximately 50,000 have been identified in Hanzi,
+the Chinese ideographic system.
+.LP
+Two major aspects of ideographic systems impact their use with computers.
+First, the standard computer character sets in Japan, China, and Korea
+include roughly 8,000 characters,
+while sets in Taiwan have between 15,000 and 30,000 characters.
+This makes it necessary to use more than one byte to represent a character.
+Second, it obviously is impractical to have a keyboard that includes
+all of a given language's ideographic symbols.
+Therefore, a mechanism is required for entering characters
+so that a keyboard with a reasonable number of keys can be used.
+Those input methods are usually based on phonetics,
+but there also exist methods based on the graphical properties of
+characters.
+.LP
+In Japan, both Kana and the ideographic system Kanji are used.
+In Korea, Hangul and sometimes the ideographic system Hanja are used.
+Now consider entering ideographs in Japan, Korea, China, and Taiwan.
+.LP
+In Japan, either Kana or English characters are typed and then a region
+is selected (sometimes automatically) for conversion to Kanji.
+Several Kanji characters may have the same phonetic representation.
+If that is the case with the string entered,
+a menu of characters is presented and
+the user must choose the appropriate one.
+If no choice is necessary or a preference has been established,
+the input method does the substitution directly.
+When Latin characters are converted to Kana or Kanji,
+it is called a romaji conversion.
+.LP
+In Korea, it is usually acceptable to keep Korean text in Hangul form,
+but some people may choose to write Hanja-originated words in Hanja
+rather than in Hangul.
+To change Hangul to Hanja,
+the user selects a region for conversion
+and then follows the same basic method as that described for Japanese.
+.LP
+Probably because there are well-accepted phonetic writing systems
+for Japanese and Korean,
+computer input methods in these countries for entering ideographs 
+are fairly standard.
+Keyboard keys have both English characters and phonetic symbols
+engraved on them, and the user can switch between the two sets.
+.LP
+The situation is different for Chinese.
+While there is a phonetic system called Pinyin promoted by authorities,
+there is no consensus for entering Chinese text.
+Some vendors use a phonetic decomposition (Pinyin or another),
+others use ideographic decomposition of Chinese words,
+with various implementations and keyboard layouts. 
+There are about 16 known methods, none of which is a clear standard. 
+.LP
+Also, there are actually two ideographic sets used:
+Traditional Chinese (the original written Chinese)
+and Simplified Chinese.
+Several years ago,
+the People's Republic of China launched a campaign to simplify
+some ideographic characters and eliminate redundancies altogether.
+Under the plan, 
+characters would be streamlined every five years.
+Characters have been revised several times now, 
+resulting in the smaller, simpler set that makes up Simplified Chinese.
+.NH 4
+Input Method Architecture
+.XS
+\*(SN Input Method Architecture
+.XE
+.LP
+As shown in the previous section,
+there are many different input methods in use today,
+each varying with language, culture, and history. 
+A common feature of many input methods is that the user may type
+multiple keystrokes to compose a single character (or set
+of characters).
+The process of composing characters from keystrokes is called
+\fIpreediting\fP.
+It may require complex algorithms and large dictionaries 
+involving substantial computer resources.
+.LP
+Input methods may require one or more areas in which to show the
+feedback of the actual keystrokes, to propose disambiguation to the
+user, to list dictionaries, and so on.
+The input method areas of concern are as follows:
+.IP \(bu 5
+The \fIstatus\fP area is a logical extension of the
+LEDs that exist on the physical keyboard.
+It is a window that is intended to present the internal state
+of the input method that is critical to the user.
+The status area may consist of text data and bitmaps or some combination.
+.IP \(bu 5
+The \fIpreedit\fP area displays the
+intermediate text for those languages that are composing prior to 
+the client handling the data.   
+.IP \(bu 5
+The \fIauxiliary\fP area is used for pop-up menus and customizing
+dialogs that may be required for an input method.
+There may be multiple auxiliary areas for an input method.
+Auxiliary areas are managed by the input method independent of the client.
+Auxiliary areas are assumed to be separate dialogs,
+which are maintained by the input method.
+.LP
+There are various user interaction styles used for preediting.
+The ones supported by Xlib are as follows:
+.IP \(bu 5
+For \fIon-the-spot\fP input methods,
+preediting data will be displayed directly in the application window.
+Application data is moved to allow preedit data to appear
+at the point of insertion.
+.IP \(bu 5
+\fIOver-the-spot\fP preediting means that the data is displayed in
+a preedit window that is placed over the point of insertion.
+.IP \(bu 5
+\fIOff-the-spot\fP preediting means that the preedit window is
+inside the application window but not at the point of insertion.
+Often, this type of window is placed at the bottom of the application window.
+.IP \(bu 5
+\fIRoot-window\fP preediting refers to input methods that use a preedit
+window that is the child of 
+.PN RootWindow .
+.LP
+It would require a lot of computing resources if portable applications
+had to include input methods for all the languages in the world.
+To avoid this,
+a goal of the Xlib design is to allow an application 
+to communicate with an input method placed in a separate process.
+Such a process is called an \fIinput server\fP.
+The server to which the application should connect is dependent on
+the environment when the application is started up,
+that is, the user language and the actual encoding to be used for it.
+The input method connection is said to be \fIlocale-dependent\fP.
+It is also user-dependent.
+For a given language, the user can choose, to some extent,
+the user interface style of input method (if choice is possible among
+several).
+.LP
+Using an input server implies communication overhead,
+but applications can be migrated without relinking.
+Input methods can be implemented either as a
+stub communicating to an input server or as a local library.
+.LP
+An input method may be based on a \fIfront-end\fP or a \fIback-end\fP
+architecture.
+In a front-end architecture,
+there are two separate connections to the X server:
+keystrokes go directly from the X server to the input method on
+one connection and other events to the regular client connection.
+The input method is then acting as a filter and sends composed strings
+to the client.
+A front-end architecture requires synchronization between the
+two connections to avoid lost key events or locking issues.
+.LP
+In a back-end architecture,
+a single X server connection is used.
+A dispatching mechanism must decide on this channel to delegate appropriate
+keystrokes to the input method.
+For instance,
+it may retain a Help keystroke for its own purpose.
+In the case where the input method is a separate process (that is, a server),
+there must be a special communication protocol between the back-end client
+and the input server.
+.LP
+A front-end architecture introduces synchronization issues
+and a filtering mechanism for noncharacter keystrokes
+(Function keys, Help, and so on).
+A back-end architecture sometimes implies more communication overhead
+and more process switching.
+If all three processes (X server, input server, client)
+are running on a single workstation, 
+there are two process switches for each keystroke in a back-end
+architecture,
+but there is only one in a front-end architecture.
+.LP
+The abstraction used by a client to communicate with an input method
+is an opaque data structure represented by the 
+.PN XIM
+data type.
+This data structure is returned by the 
+.PN XOpenIM
+function, which opens an input method on a given display.
+Subsequent operations on this data structure encapsulate all communication
+between client and input method.
+There is no need for an X client to use any networking library 
+or natural language package to use an input method.
+.LP
+A single input server may be used for one or more languages,
+supporting one or more encoding schemes.
+But the strings returned from an input method will always be encoded
+in the (single) locale associated with the
+.PN XIM
+object.
+.NH 4
+Input Contexts
+.XS
+\*(SN Input Contexts
+.XE
+.LP
+Xlib provides the ability to manage a multi-threaded state for text input.
+A client may be using multiple windows,
+each window with multiple text entry areas,
+and the user possibly switching among them at any time.
+The abstraction for representing the state of a particular input thread
+is called an \fIinput context\fP.
+The Xlib representation of an input context is an 
+.PN XIC .
+.LP
+An input context is the abstraction retaining the state, properties,
+and semantics of communication between a client and an input method.
+An input context is a combination of an input method, a locale
+specifying the encoding of the character strings to be returned,
+a client window, internal state information,
+and various layout or appearance characteristics.
+The input context concept somewhat matches for input the graphics context
+abstraction defined for graphics output.
+.LP
+One input context belongs to exactly one input method.
+Different input contexts may be associated with the same input method,
+possibly with the same client window.
+An 
+.PN XIC
+is created with the
+.PN XCreateIC
+function, providing an 
+.PN XIM
+argument and affiliating the input context to the input method
+for its lifetime. 
+When an input method is closed with 
+.PN XCloseIM ,
+all of its affiliated input contexts should not be used any more
+(and should preferably be destroyed before closing the input method).
+.LP
+Considering the example of a client window with multiple text entry areas,
+the application programmer could, for example, choose to implement as follows:
+.IP \(bu 5
+As many input contexts are created as text entry areas, and the client
+will get the input accumulated on each context each time it looks up
+in that context.
+.IP \(bu 5
+A single context is created for a top-level window in the application.
+If such a window contains several text entry areas, 
+each time the user moves to another text entry area,
+the client has to indicate changes in the context.
+.LP
+A range of choices can be made by application designers to use
+either a single or multiple input contexts,
+according to the needs of their application.
+.NH 4
+Getting Keyboard Input
+.XS
+\*(SN Getting Keyboard Input
+.XE
+.LP
+To obtain characters from an input method,
+a client must call the function
+.PN XmbLookupString
+or 
+.PN XwcLookupString
+with an input context created from that input method.
+Both a locale and display are bound to an input method when it is opened,
+and an input context inherits this locale and display.
+Any strings returned by 
+.PN XmbLookupString
+or
+.PN XwcLookupString
+will be encoded in that locale. 
+.NH 4 
+Focus Management
+.XS
+\*(SN Focus Management
+.XE
+.LP
+For each text entry area in which the
+.PN XmbLookupString
+or
+.PN XwcLookupString
+functions are used,
+there will be an associated input context.
+.LP
+When the application focus moves to a text entry area,
+the application must set the input context focus to the
+input context associated with that area.
+The input context focus is set by calling 
+.PN XSetICFocus
+with the appropriate input context.
+.LP
+Also, when the application focus moves out of a text entry area, the
+application should unset the focus for the associated input context
+by calling
+.PN XUnsetICFocus .
+As an optimization, if
+.PN XSetICFocus
+is called successively on two different input contexts,
+setting the focus on the second 
+will automatically unset the focus on the first.
+.LP
+To set and unset the input context focus correctly,
+it is necessary to track application-level focus changes.
+Such focus changes do not necessarily correspond to X server focus changes.
+.LP
+If a single input context
+is being used to do input for
+multiple text entry areas, it will also be necessary
+to set the focus window of the
+input context whenever the focus window changes
+(see section 13.5.6.3).
+.NH 4 
+Geometry Management
+.XS
+\*(SN Geometry Management
+.XE
+.LP
+In most input method architectures 
+(on-the-spot being the notable exception),
+the input method will perform the display of its own data.
+To provide better visual locality,
+it is often desirable to have the input method areas embedded within a client.
+To do this,
+the client may need to allocate space for an input method.
+Xlib provides support that allows the size and position of input method
+areas to be provided by a client.
+The input method areas that are supported for geometry management
+are the status area and the preedit area.
+.LP
+The fundamental concept on which geometry management for input method windows
+is based is the proper division of responsibilities between the
+client (or toolkit) and the input method.
+The division of responsibilities is as follows:
+.IP \(bu 5
+The client is responsible for the geometry of the input method window.
+.IP \(bu 5
+The input method is responsible for the contents of the input method window.
+.LP
+An input method is able to suggest a size to the client,
+but it cannot suggest a placement.
+Also the input method can only suggest a size.
+It does not determine the size,
+and it must accept the size it is given.
+.LP
+Before a client provides geometry management for an input method,
+it must determine if geometry management is needed.
+The input method indicates the need for geometry management 
+by setting 
+.PN XIMPreeditArea
+or 
+.PN XIMStatusArea
+in its 
+.PN XIMStyles
+value returned by 
+.PN XGetIMValues .
+When a client has decided that it will provide geometry management
+for an input method, 
+it indicates that decision by setting the
+.PN XNInputStyle
+value in the 
+.PN XIC .
+.LP
+After a client has established with the input method
+that it will do geometry management,
+the client must negotiate the geometry with the input method.
+The geometry is negotiated by the following steps:
+.IP \(bu 5
+The client suggests an area to the input method by setting the
+.PN XNAreaNeeded
+value for that area.
+If the client has no constraints for the input method,
+it either will not suggest an area or will set the width and height to zero.
+Otherwise, it will set one of the values.
+.IP \(bu 5
+The client will get the XIC value 
+.PN XNAreaNeeded .
+The input method will return its suggested size in this value.
+The input method should pay attention to any constraints suggested
+by the client.
+.IP \(bu 5
+The client sets the XIC value
+.PN XNArea
+to inform the input method of the geometry of its window.  
+The client should try to honor the geometry requested by the input method.
+The input method must accept this geometry.
+.LP
+Clients doing geometry management must be aware that setting other
+XIC values may affect the geometry desired by an input method.
+For example, 
+.PN XNFontSet
+and
+.PN XNLineSpacing
+may change the geometry desired by the input method.  
+.LP
+The table of XIC values (see section 13.5.6)
+indicates the values that can cause the desired geometry to change
+when they are set.
+It is the responsibility of the client to renegotiate the geometry
+of the input method window when it is needed.
+.LP
+In addition,
+a geometry management callback is provided
+by which an input method can initiate a geometry change.
+.NH 4
+Event Filtering
+.XS
+\*(SN Event Filtering
+.XE
+.LP
+A filtering mechanism is provided to allow input methods
+to capture X events transparently to clients.
+It is expected that toolkits (or clients) using
+.PN XmbLookupString
+or
+.PN XwcLookupString 
+will call this filter at some point in the event processing mechanism
+to make sure that events needed by an input method can be filtered
+by that input method.
+.LP
+If there were no filter,
+a client could receive and discard events that are necessary
+for the proper functioning of an input method.
+The following provides a few examples of such events:
+.IP \(bu 5
+Expose events on preedit window in local mode.
+.IP \(bu 5
+Events may be used by an input method to communicate with an input server.
+Such input server protocol-related events have to be intercepted
+if one does not want to disturb client code.
+.IP \(bu 5
+Key events can be sent to a filter before they are bound
+to translations such as those the X Toolkit Intrinsics library provides.
+.LP
+Clients are expected to get the XIC value 
+.PN XNFilterEvents
+and augment the event mask for the client window with that event mask.
+This mask may be zero.
+.NH 4
+Callbacks
+.XS
+\*(SN Callbacks
+.XE
+.LP
+When an on-the-spot input method is implemented,
+only the client can insert or delete preedit data in place
+and possibly scroll existing text.
+This means that the echo of the keystrokes has to be achieved 
+by the client itself, tightly coupled with the input method logic.
+.LP
+When the user enters a keystroke,
+the client calls
+.PN XmbLookupString
+or
+.PN XwcLookupString .
+At this point, in the on-the-spot case,
+the echo of the keystroke in the preedit has not yet been done.
+Before returning to the client logic that handles the input characters,
+the look-up function
+must call the echoing logic to insert the new keystroke.
+If the keystrokes entered so far make up a character,
+the keystrokes entered need to be deleted,
+and the composed character will be returned.
+Hence, what happens is that, while being called by client code,
+the input method logic has to call back to the client before it returns.
+The client code, that is, a callback procedure,
+is called from the input method logic.
+.LP
+There are a number of cases where the input method logic has to
+call back the client.
+Each of those cases is associated with a well-defined callback action.
+It is possible for the client to specify, for each input context,
+what callback is to be called for each action.
+.LP
+There are also callbacks provided for feedback of status information
+and a callback to initiate a geometry request for an input method.
+.NH 4
+Visible Position Feedback Masks
+.XS
+\*(SN Visible Position Feedback Masks
+.XE
+.LP
+In the on-the-spot input style, there is a problem when
+attempting to draw preedit strings that are longer than the
+available space.  Once the display area is exceeded, it is not
+clear how best to display the preedit string.
+The visible position feedback masks of
+.PN XIMText
+help resolve this problem by allowing the input method to specify hints that
+indicate the essential portions of the preedit string.
+For example, such hints can help developers implement
+scrolling of a long preedit string within a short preedit display area.
+.NH 4
+Preedit String Management
+.XS
+\*(SN Preedit String Management
+.XE
+.LP
+As highlighted before, the input method architecture provides
+preediting, which supports a type of preprocessor input composition.
+In this case, composition consists of interpreting a sequence
+of key events and returning a committed string via 
+.PN XmbLookupString
+or
+.PN XwcLookupString .
+This provides the basics for input methods.
+.LP
+In addition to preediting based on key events, a general framework
+is provided to give a client that desires it more advanced preediting based
+on the text within the client.  This framework is called 
+\fIstring conversion\fP and is provided using XIC values. 
+The fundamental concept of string conversion
+is to allow the input method to manipulate the client's
+text independent of any user preediting operation.
+.LP
+The need for string conversion is based on 
+language needs and input method capabilities.
+The following are some examples of string conversion:
+.IP \(bu 5
+Transliteration conversion provides language-specific conversions
+within the input method.
+In the case of Korean input, users wish to convert a Hangul string 
+into a Hanja string while in preediting, after preediting,
+or in other situations (for example, on a selected string).
+The conversion is triggered when the user
+presses a Hangul-to-Hanja key sequence (which may be input method specific).
+Sometimes the user may want to invoke the conversion after finishing
+preediting or on a user-selected string.  
+Thus, the string to be converted is in an application buffer, not in 
+the preedit area of the input method.  The string conversion services
+allow the client to request this transliteration conversion from the 
+input method.
+There are many other transliteration conversions defined for 
+various languages, for example, Kana-to-Kanji conversion in Japanese.
+.sp
+The key to remember is that transliteration conversions are triggered
+at the request of the user and returned to the client 
+immediately without affecting the preedit area of the input method.
+.IP \(bu 5
+Reconversion of a previously committed string or 
+a selected string is supported by many input methods as a 
+convenience to the user.
+For example, a user tends to mistype the commit key while
+preediting.  In that case, some input methods provide a special
+key sequence to request a ``reconvert'' operation on the 
+committed string, similiar to the undo facility provided by most
+text editors.
+Another example is where the user is proofreading a document 
+that has some misconversions from preediting and wants to correct
+the misconverted text.  Such reconversion is again triggered
+by the user invoking some special action, but reconversions should
+not affect the state of the preedit area.  
+.IP \(bu 5
+Context-sensitive conversion is required for some languages
+and input methods that need to retrieve text that surrounds the
+current spot location (cursor position) of the client's buffer.
+Such text is needed when the preediting operation depends on 
+some surrounding characters (usually preceding the spot location).
+For example, 
+in Thai language input, certain character sequences may be invalid and
+the input method may want to check whether characters constitute a
+valid word.  Input methods that do such context-dependent
+checking need to retrieve the characters surrounding the current
+cursor position to obtain complete words.
+.sp
+Unlike other conversions, this conversion is not explicitly 
+requested by the user.
+Input methods that provide such context-sensitive conversion 
+continuously need to request context from the client, and any change
+in the context of the spot location may affect such conversions.
+The client's context would be needed if the user moves the cursor
+and starts editing again.
+.sp
+For this reason, an input method supporting this type of conversion
+should take notice of when the client calls
+.PN XmbResetIC
+or
+.PN XwcResetIC ,
+which is usually an indication of a context change.  
+.LP
+Context-sensitive conversions just need a copy of the client's text,
+while other conversions replace the client's text with new text
+to achieve the reconversion or transliteration.   Yet in all
+cases the result of a conversion, either immediately or via preediting,
+is returned by the
+.PN XmbLookupString
+and
+.PN XwcLookupString
+functions.
+.LP
+String conversion support is dependent on the availability of the 
+.PN XNStringConversion
+or 
+.PN XNStringConversionCallback 
+XIC values.
+Because the input method may not support string conversions,
+clients have to query the availability of string conversion
+operations by checking the supported XIC values list by calling
+.PN XGetIMValues
+with the
+.PN XNQueryICValuesList
+IM value.
+.LP
+The difference between these two values is whether the
+conversion is invoked by the client or the input method.  
+The 
+.PN XNStringConversion
+XIC value is used by clients to request 
+a string conversion from the input method.  The client
+is responsible for determining which events are used 
+to trigger the string conversion and whether the string to be
+converted should be copied or deleted.  The type of conversion
+is determined by the input method; the client can only 
+pass the string to be converted.  The client is guaranteed that
+no
+.PN XNStringConversionCallback
+will be issued when this value is set; thus, the client need
+only set one of these values.
+.LP
+The
+.PN XNStringConversionCallback
+XIC value is used by the client to notify the input method that
+it will accept requests from the input method for string conversion.
+If this value is set,
+it is the input method's responsibility to determine which
+events are used to trigger the string conversion.
+When such events occur, the input method issues a call to the
+client-supplied procedure to retrieve the string to be converted.  The client's
+callback procedure is notified whether to copy or delete the string and 
+is provided with hints as to the amount of text needed.
+The
+.PN XIMStringConversionCallbackStruct
+specifies which text should be passed back to the input method.
+.LP
+Finally, the input method may call the client's 
+.PN XNStringConversionCallback
+procedure multiple times if the string returned from the callback is
+not sufficient to perform a successful conversion.   The arguments
+to the client's procedure allow the input method to define a
+position (in character units) relative to the client's cursor position 
+and the size of the text needed.  By varying the position and size of
+the desired text in subsequent callbacks, the input method can retrieve 
+additional text.
+.LP
+.NH 3
+Input Method Management
+.XS
+\*(SN Input Method Management
+.XE
+.LP
+The interface to input methods might appear to be simply creating
+an input method
+.Pn ( XOpenIM )
+and freeing an input method
+.Pn ( XCloseIM ).
+However, input methods may 
+require complex communication with input method servers (IM servers),
+for example:
+.IP \(bu 5
+If the X server, IM server, and X clients are started asynchronously,
+some clients may attempt to connect to the IM server before it is
+fully operational, and fail.
+Therefore, some mechanism is needed to allow clients to detect when an IM 
+server has started.
+.LP
+It is up to clients to decide what should be done when an IM server is 
+not available (for example, wait, or use some other IM server).
+.LP
+.IP \(bu 5
+Some input methods may allow the underlying IM server to be switched. 
+Such customization may be desired without restarting the entire client.
+.LP
+To support management of input methods in these cases, the following 
+functions are provided:
+.TS
+lw(2.4i) lw(3.3i).
+T{
+.PN XRegisterIMInstantiateCallback
+T}	T{
+This function allows clients to register a callback procedure
+to be called when Xlib detects that an IM server is up and available.
+T}
+T{
+.PN XOpenIM
+T}	T{
+A client calls this function as a result of the callback procedure
+being called.
+T}
+T{
+.PN XSetIMValue ,
+.PN XSetICValue
+T}	T{
+These functions use the XIM and XIC values,
+.PN XNDestroyCallback ,
+to allow a client 
+to register a callback procedure to be called when Xlib detects that
+an IM server that was associated with an opened 
+input method is no longer available.
+.sp 4p
+In addition, this function can be used to switch IM servers for those input 
+methods that support such functionality.  The IM value for switching IM 
+servers is implementation-dependent; see the description below about
+switching IM servers.
+T}
+T{
+.PN XUnregisterIMInstantiateCallback
+T}	T{
+This function removes a callback procedure registered by the client.
+T}
+.TE
+.LP
+Input methods that support switching of IM servers may exhibit some
+side-effects:
+.IP \(bu 5
+The input method will ensure that any new IM server supports any of the 
+input styles being used by input contexts already associated with the
+input method.
+However, the list of supported input styles may be different.
+.LP
+.IP \(bu 5
+Geometry management requests on previously created input contexts
+may be initiated by the new IM server.
+.LP
+.NH 4
+Hot Keys
+.XS
+\*(SN Hot Keys
+.XE
+.LP
+Some clients need to guarantee which keys can be used to escape from the
+input method, regardless of the input method state;
+for example, the client-specific Help key or the keys to move the
+input focus.
+The HotKey mechanism allows clients 
+to specify a set of keys for this purpose.  However, the input 
+method might not allow clients to specify hot keys.
+Therefore, clients have to query support of hot keys by checking the
+supported XIC values list by calling
+.PN XGetIMValues
+with the
+.PN XNQueryICValuesList
+IM value.
+When the hot keys specified conflict with the key bindings of the 
+input method, hot keys take precedence over the key bindings of the input 
+method.
+.LP
+.NH 4
+Preedit State Operation
+.XS
+\*(SN Preedit State Operation
+.XE
+.LP
+An input method may have several internal states, depending on its
+implementation and the locale.  However, one state that is
+independent of locale and implementation is whether the input method
+is currently performing a preediting operation.
+Xlib provides the ability for an application to manage the preedit state
+programmatically.  Two methods are provided for
+retrieving the preedit state of an input context.
+One method is to query the state by calling
+.PN XGetICValues
+with the
+.PN XNPreeditState
+XIC value.
+Another method is to receive notification whenever
+the preedit state is changed.  To receive such notification,
+an application needs to register a callback by calling
+.PN XSetICValues
+with the
+.PN XNPreeditStateNotifyCallback
+XIC value. 
+In order to change the preedit state programmatically, an application 
+needs to call 
+.PN XSetICValues
+with
+.PN XNPreeditState.
+.LP
+Availability of the preedit state is input method dependent.  The input 
+method may not provide the ability to set the state or to
+retrieve the state programmatically.  Therefore, clients have to 
+query availability of preedit state operations by checking the 
+supported XIC values list by calling
+.PN XGetIMValues
+with the
+.PN XNQueryICValuesList
+IM value.
+.NH 3 
+Input Method Functions
+.XS
+\*(SN Input Method Functions
+.XE
+.LP
+To open a connection, use
+.PN XOpenIM .
+.IN "XOpenIM" "" "@DEF@"
+.sM
+.FD 0
+XIM XOpenIM\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XrmDatabase \fIdb\fP\^;
+.br
+      char *\fIres_name\fP\^;
+.br
+      char *\fIres_class\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIdb\fP 1i
+Specifies a pointer to the resource database.
+.IP \fIres_name\fP 1i
+Specifies the full resource name of the application.
+.IP \fIres_class\fP 1i
+Specifies the full class name of the application.
+.LP
+.eM
+The
+.PN XOpenIM
+function opens an input method, 
+matching the current locale and modifiers specification.
+Current locale and modifiers are bound to the input method at opening time.
+The locale associated with an input method cannot be changed dynamically.
+This implies that the strings returned by
+.PN XmbLookupString
+or
+.PN XwcLookupString ,
+for any input context affiliated with a given input method,
+will be encoded in the locale current at the time the input method is opened.
+.LP
+The specific input method to which this call will be routed
+is identified on the basis of the current locale. 
+.PN XOpenIM
+will identify a default input method corresponding to the
+current locale.
+That default can be modified using 
+.PN XSetLocaleModifiers
+for the input method modifier.
+.LP
+The db argument is the resource database to be used by the input method
+for looking up resources that are private to the input method.
+It is not intended that this database be used to look
+up values that can be set as IC values in an input context.
+If db is NULL,
+no database is passed to the input method.
+.LP
+The res_name and res_class arguments specify the resource name 
+and class of the application. 
+They are intended to be used as prefixes by the input method
+when looking up resources that are common to all input contexts
+that may be created for this input method.
+The characters used for resource names and classes must be in the
+X Portable Character Set.
+The resources looked up are not fully specified
+if res_name or res_class is NULL.
+.LP
+The res_name and res_class arguments are not assumed to exist beyond
+the call to
+.PN XOpenIM .
+The specified resource database is assumed to exist for the lifetime
+of the input method.
+.LP
+.PN XOpenIM
+returns NULL if no input method could be opened.
+.LP
+.sp
+To close a connection, use
+.PN XCloseIM .
+.IN "XCloseIM" "" "@DEF@"
+.sM
+.FD 0
+Status XCloseIM\^(\^\fIim\fP\^)
+.br
+      XIM \fIim\fP\^;
+.FN
+.IP \fIim\fP 1i
+Specifies the input method.
+.LP
+.eM
+The
+.PN XCloseIM
+function closes the specified input method.
+.LP
+.sp
+To set input method attributes, use
+.PN XSetIMValues .
+.IN "XSetIMValues" "" "@DEF@"
+.sM
+.FD 0
+char * XSetIMValues\^(\^\fIim\fP\^, ...)
+.br
+      XIM \fIim\fP\^; 
+.FN
+.IP \fIim\fP 1i
+Specifies the input method.
+.ds Al \ to set XIM values
+.IP ... 1i
+Specifies the variable-length argument list\*(Al.
+.LP
+.eM
+The
+.PN XSetIMValues
+function presents a variable argument list programming interface
+for setting attributes of the specified input method.
+It returns NULL if it succeeds;
+otherwise,
+it returns the name of the first argument that could not be set.
+Xlib does not attempt to set arguments from the supplied list that
+follow the failed argument;
+all arguments in the list preceding the failed argument have been set
+correctly.
+.LP
+.sp
+To query an input method, use 
+.PN XGetIMValues .
+.IN "XGetIMValues" "" "@DEF@"
+.sM
+.FD 0
+char * XGetIMValues\^(\^\fIim\fP\^, ...)
+.br
+      XIM \fIim\fP\^; 
+.FN
+.IP \fIim\fP 1i
+Specifies the input method.
+.ds Al \ to get XIM values
+.IP ... 1i
+Specifies the variable length argument list\*(Al.
+.LP
+.eM
+The
+.PN XGetIMValues
+function presents a variable argument list programming interface
+for querying properties or features of the specified input method.
+This function returns NULL if it succeeds;
+otherwise,
+it returns the name of the first argument that could not be obtained.
+.LP
+Each XIM value argument (following a name) must point to
+a location where the XIM value is to be stored.
+That is, if the XIM value is of type T,
+the argument must be of type T*.
+If T itself is a pointer type,
+then
+.PN XGetIMValues
+allocates memory to store the actual data,
+and the client is responsible for freeing this data by calling
+.PN XFree
+with the returned pointer.
+.LP
+.sp
+To obtain the display associated with an input method, use
+.PN XDisplayOfIM .
+.IN "XDisplayOfIM" "" "@DEF@"
+.sM
+.FD 0
+Display * XDisplayOfIM\^(\^\fIim\fP\^)
+.br
+	XIM \fIim\fP\^;
+.FN
+.IP \fIim\fP 1i
+Specifies the input method.
+.LP
+.eM
+The
+.PN XDisplayOfIM
+function returns the display associated with the specified input method.
+.LP
+.sp
+To get the locale associated with an input method, use
+.PN XLocaleOfIM .
+.IN "XLocaleOfIM" "" "@DEF@"
+.sM
+.FD 0
+char * XLocaleOfIM\^(\^\fIim\fP\^)
+.br
+      XIM \fIim\fP\^; 
+.FN
+.IP \fIim\fP 1i
+Specifies the input method.
+.LP
+.eM
+The
+.PN XLocaleOfIM
+function returns the locale associated with the specified input method.
+.LP
+.sp
+To register an input method instantiate callback, use
+.PN XRegisterIMInstantiateCallback .
+.IN "XRegisterIMInstantiateCallback" "" "@DEF@"
+.sM
+.FD 0
+Bool XRegisterIMInstantiateCallback\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^, \fIcallback\fP\^, \fIclient_data\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XrmDatabase \fIdb\fP\^;
+.br
+      char *\fIres_name\fP\^;
+.br
+      char *\fIres_class\fP\^;
+.br
+      XIMProc  \fIcallback\fP\^;
+.br
+      XPointer *\fIclient_data\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIdb\fP 1i
+Specifies a pointer to the resource database.
+.IP \fIres_name\fP 1i
+Specifies the full resource name of the application.
+.IP \fIres_class\fP 1i
+Specifies the full class name of the application.
+.IP \fIcallback\fP 1i
+Specifies a pointer to the input method instantiate callback.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data.
+.LP
+.eM
+The
+.PN XRegisterIMInstantiateCallback
+function registers a callback to be invoked whenever a new input method
+becomes available for the specified display that matches the current
+locale and modifiers.
+.LP
+The function returns 
+.PN True
+ if it succeeds; otherwise, it returns 
+.PN False .
+.LP
+The generic prototype is as follows:
+.IN "IMInstantiateCallback" "" "@DEF@"
+.sM
+.FD 0
+void IMInstantiateCallback\^(\^\fIdisplay\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XPointer \fIclient_data\fP\^;	
+.br
+      XPointer \fIcall_data\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data.
+.IP \fIcall_data\fP 1i
+Not used for this callback and always passed as NULL.
+.LP
+.eM
+To unregister an input method instantiation callback, use
+.PN XUnregisterIMInstantiateCallback .
+.IN "XUnregisterIMInstantiateCallback" "" "@DEF@"
+.sM
+.FD 0
+Bool XUnregisterIMInstantiateCallback\^(\^\fIdisplay\fP\^, \fIdb\fP\^, \fIres_name\fP\^, \fIres_class\fP\^, \fIcallback\fP\^, \fIclient_data\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XrmDatabase \fIdb\fP\^;
+.br
+      char *\fIres_name\fP\^;
+.br
+      char *\fIres_class\fP\^;
+.br
+      XIMProc  \fIcallback\fP\^;
+.br
+      XPointer *\fIclient_data\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIdb\fP 1i
+Specifies a pointer to the resource database.
+.IP \fIres_name\fP 1i
+Specifies the full resource name of the application.
+.IP \fIres_class\fP 1i
+Specifies the full class name of the application.
+.IP \fIcallback\fP 1i
+Specifies a pointer to the input method instantiate callback.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data.
+.LP
+.eM
+The
+.PN XUnregisterIMInstantiateCallback
+function removes an input method instantiation callback previously
+registered.
+The function returns
+.PN True
+if it succeeds; otherwise, it returns 
+.PN False .
+.NH 3 
+Input Method Values
+.XS
+\*(SN Input Method Values
+.XE
+.LP
+The following table describes how XIM values are interpreted
+by an input method.
+The first column lists the XIM values.
+The second column indicates how each of the XIM values 
+are treated by that input style.
+.LP
+.LP
+The following keys apply to this table.
+.TS H
+lw(1i) lw(4.75i).
+_
+.sp 6p
+.B
+Key	Explanation
+.sp 6p
+_
+.TH
+.R
+D	T{
+This value may be set using 
+.PN XSetIMValues .
+If it is not set,
+.br
+a default is provided.
+T}
+S	T{
+This value may be set using 
+.PN XSetIMValues .
+T}
+G	T{
+This value may be read using 
+.PN XGetIMValues .
+T}
+.sp 6p
+_
+.TE
+.LP
+.TS H
+lw(2.25i) c
+lw(2.25i) c.
+_
+.sp 6p
+.B
+XIM Value	Key
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+T{
+.PN XNQueryInputStyle
+T}	T{
+G
+T}
+T{
+.PN XNResourceName
+T}	T{
+D-S-G
+T}
+T{
+.PN XNResourceClass
+T}	T{
+D-S-G
+T}
+T{
+.PN XNDestroyCallback
+T}	T{
+D-S-G
+T}
+T{
+.PN XNQueryIMValuesList
+T}	T{
+G
+T}
+T{
+.PN XNQueryICValuesList
+T}	T{
+G
+T}
+T{
+.PN XNVisiblePosition
+T}	T{
+G
+T}
+T{
+.PN XNR6PreeditCallbackBehavior
+T}	T{
+D-S-G
+T}
+.sp 6p
+_
+.TE
+.LP
+.PN XNR6PreeditCallbackBehavior
+is obsolete and its use is not recommended (see section 13.5.4.6).
+.LP
+.NH 4
+Query Input Style
+.XS
+\*(SN Query Input Style
+.XE
+.LP
+A client should always query the input method to determine which input 
+styles are supported.
+The client should then find an input style it is capable of supporting.
+.LP
+If the client cannot find an input style that it can support,
+it should negotiate with the user the continuation of the program
+(exit, choose another input method, and so on).
+.LP
+The argument value must be a pointer to a location
+where the returned value will be stored.
+The returned value is a pointer to a structure of type
+.PN XIMStyles .
+Clients are responsible for freeing the 
+.PN XIMStyles
+structure.
+To do so, use
+.PN XFree .
+.LP
+The
+.PN XIMStyles
+structure is defined as follows:
+.LP
+.IN "XIMStyle" "" "@DEF@"
+.IN "XIMPreeditArea" "" "@DEF@"
+.IN "XIMPreeditCallbacks" "" "@DEF@"
+.IN "XIMPreeditPosition" "" "@DEF@"
+.IN "XIMPreeditNothing" "" "@DEF@"
+.IN "XIMPreeditNone" "" "@DEF@"
+.IN "XIMStatusArea" "" "@DEF@"
+.IN "XIMStatusCallbacks" "" "@DEF@"
+.IN "XIMStatusNothing" "" "@DEF@"
+.IN "XIMStatusNone" "" "@DEF@"
+.IN "XIMStyles" "" "@DEF@"
+.sM
+.Ds 0
+typedef unsigned long XIMStyle;
+.De
+.TS
+lw(.5i) lw(2i) lw(2.5i).
+T{
+#define
+T}	T{
+.PN XIMPreeditArea
+T}	T{
+0x0001L
+T}
+T{
+#define
+T}	T{
+.PN XIMPreeditCallbacks
+T}	T{
+0x0002L
+T}
+T{
+#define
+T}	T{
+.PN XIMPreeditPosition
+T}	T{
+0x0004L
+T}
+T{
+#define
+T}	T{
+.PN XIMPreeditNothing
+T}	T{
+0x0008L
+T}
+T{
+#define
+T}	T{
+.PN XIMPreeditNone
+T}	T{
+0x0010L
+T}
+.sp
+T{
+#define
+T}	T{
+.PN XIMStatusArea
+T}	T{
+0x0100L
+T}
+T{
+#define
+T}	T{
+.PN XIMStatusCallbacks
+T}	T{
+0x0200L
+T}
+T{
+#define
+T}	T{
+.PN XIMStatusNothing
+T}	T{
+0x0400L
+T}
+T{
+#define
+T}	T{
+.PN XIMStatusNone
+T}	T{
+0x0800L
+T}
+.TE
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	unsigned short count_styles;
+	XIMStyle * supported_styles;
+} XIMStyles;
+.De
+.LP
+.eM
+An 
+.PN XIMStyles
+structure contains the number of input styles supported
+in its count_styles field.
+This is also the size of the supported_styles array.
+.LP
+The supported styles is a list of bitmask combinations,
+which indicate the combination of styles for each of the areas supported.
+These areas are described later.
+Each element in the list should select one of the bitmask values for
+each area.
+The list describes the complete set of combinations supported.
+Only these combinations are supported by the input method.
+.LP
+The preedit category defines what type of support is provided
+by the input method for preedit information.
+.IN "XIMPreeditArea" "" "@DEF@"
+.IN "XIMPreeditPosition" "" "@DEF@"
+.IN "XIMPreeditCallbacks" "" "@DEF@"
+.IN "XIMPreeditNothing" "" "@DEF@"
+.IN "XIMPreeditNone" "" "@DEF@"
+.TS
+lw(1.5i) lw(4.25i).
+T{
+.PN XIMPreeditArea 
+T}	T{
+If chosen,
+the input method would require the client to provide some area values
+for it to do its preediting.
+Refer to XIC values 
+.PN XNArea
+and
+.PN XNAreaNeeded .
+T}
+T{
+.PN XIMPreeditPosition
+T}	T{
+If chosen,
+the input method would require the client to provide positional values. 
+Refer to XIC values 
+.PN XNSpotLocation
+and
+.PN XNFocusWindow .
+T}
+T{
+.PN XIMPreeditCallbacks
+T}	T{
+If chosen,
+the input method would require the client to define the set of preedit callbacks.
+Refer to XIC values 
+.PN XNPreeditStartCallback ,
+.PN XNPreeditDoneCallback , 
+.PN XNPreeditDrawCallback ,
+and
+.PN XNPreeditCaretCallback .
+T}
+T{
+.PN XIMPreeditNothing
+T}	T{
+If chosen, the input method can function without any preedit values.
+T}
+T{
+.PN XIMPreeditNone
+T}	T{
+The input method does not provide any preedit feedback.
+Any preedit value is ignored.
+This style is mutually exclusive with the other preedit styles.
+T}
+.TE
+.LP
+The status category defines what type of support is provided
+by the input method for status information.
+.IN "XIMStatusArea" "" "@DEF@"
+.IN "XIMStatusCallbacks" "" "@DEF@"
+.IN "XIMStatusNothing" "" "@DEF@"
+.IN "XIMStatusNone" "" "@DEF@"
+.TS
+lw(1.5i) lw(4.25i).
+T{
+.PN XIMStatusArea
+T}	T{
+The input method requires the client to provide
+some area values for it to do its status feedback.
+See
+.PN XNArea
+and
+.PN XNAreaNeeded .
+T}
+T{
+.PN XIMStatusCallbacks
+T}	T{
+The input method requires the client to define the set of status callbacks,
+.PN XNStatusStartCallback , 
+.PN XNStatusDoneCallback ,
+and
+.PN XNStatusDrawCallback .
+T}
+T{
+.PN XIMStatusNothing
+T}	T{
+The input method can function without any status values.
+T}
+T{
+.PN XIMStatusNone
+T}	T{
+The input method does not provide any status feedback.
+If chosen, any status value is ignored.
+This style is mutually exclusive with the other status styles.
+T}
+.TE
+.NH 4
+Resource Name and Class
+.XS
+\*(SN Resource Name and Class
+.XE
+.LP
+The
+.PN XNResourceName
+and
+.PN XNResourceClass
+arguments are strings that specify the full name and class
+used by the input method.
+These values should be used as prefixes for the name and class
+when looking up resources that may vary according to the input method.
+If these values are not set,
+the resources will not be fully specified.
+.LP
+It is not intended that values that can be set as XIM values be
+set as resources.
+.LP
+.NH 4
+Destroy Callback
+.XS
+\*(SN Destroy Callback
+.XE
+.LP
+The 
+.PN XNDestroyCallback 
+argument is a pointer to a structure of type
+.PN XIMCallback .
+.PN XNDestroyCallback
+is triggered when an input method stops its service for any reason. 
+After the callback is invoked, the input method is closed and the
+associated input context(s) are destroyed by Xlib.
+Therefore, the client should not call
+.PN XCloseIM
+or
+.PN XDestroyIC .
+.LP
+The generic prototype of this callback function is as follows:
+.IN "DestroyCallback" "" "@DEF@"
+.sM
+.FD 0
+void DestroyCallback\^(\^\fIim\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
+.br
+      XIM \fIim\fP\^;
+.br
+      XPointer \fIclient_data\fP\^;
+.br
+      XPointer \fIcall_data\fP\^;
+.FN
+.IP \fIim\fP 1i
+Specifies the input method.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data.
+.IP \fIcall_data\fP 1i
+Not used for this callback and always passed as NULL.
+.LP
+.eM
+A DestroyCallback is always called with a NULL call_data argument.
+.LP
+.NH 4
+Query IM/IC Values List
+.XS
+\*(SN Query IM/IC Values List
+.XE
+.LP
+.PN XNQueryIMValuesList
+and
+.PN XNQueryICValuesList
+are used to query about XIM and XIC values supported by the input method.
+.LP
+The argument value must be a pointer to a location where the returned
+value will be stored.  The returned value is a pointer to a structure
+of type
+.PN XIMValuesList .
+Clients are responsible for freeing the 
+.PN XIMValuesList
+structure.
+To do so, use
+.PN XFree .
+.LP
+The
+.PN XIMValuesList
+structure is defined as follows:
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	unsigned short count_values;
+	char **supported_values;
+} XIMValuesList;
+.De
+.LP
+.eM
+.NH 4
+Visible Position
+.XS
+\*(SN Visible Position
+.XE
+.LP
+The 
+.PN XNVisiblePosition
+argument indicates whether the visible position masks of 
+.PN XIMFeedback
+in
+.PN XIMText
+are available.
+.LP
+The argument value must be a pointer to a location where the returned
+value will be stored.  The returned value is of type
+.PN Bool .
+If the returned value is
+.PN True ,
+the input method uses the visible position masks of
+.PN XIMFeedback
+in
+.PN XIMText ;
+otherwise, the input method does not use the masks.
+.LP
+Because this XIM value is optional, a client should call
+.PN XGetIMValues
+with argument
+.PN XNQueryIMValues
+before using this argument.
+If the 
+.PN XNVisiblePosition
+does not exist in the IM values list returned from 
+.PN XNQueryIMValues ,
+the visible position masks of
+.PN XIMFeedback
+in
+.PN XIMText
+are not used to indicate the visible position.
+.LP
+.NH 4
+Preedit Callback Behavior
+.XS
+\*(SN Preedit Callback Behavior
+.XE
+.LP
+The
+.PN XNR6PreeditCallbackBehavior
+argument originally included in the X11R6 specification has been
+deprecated.\(dg
+.\" If XNR6PreeditCallbackBehavior is not deprecated, then its type
+.\" should be changed from *Bool to Bool.
+.FS \(dg
+During formulation of the X11R6 specification, the behavior of
+the R6 PreeditDrawCallbacks was going to differ significantly from
+that of the R5 callbacks.
+Late changes to the specification converged the R5 and R6 behaviors,
+eliminating the need for
+.PN XNR6PreeditCallbackBehavior .
+Unfortunately, this argument was not removed from the R6 specification
+before it was published.
+.FE
+.LP
+The 
+.PN XNR6PreeditCallbackBehavior
+argument indicates whether the behavior of preedit callbacks regarding
+.PN XIMPreeditDrawCallbackStruct
+values follows Release 5 or Release 6 semantics.
+.LP
+The value is of type
+.PN Bool .
+When querying for
+.PN XNR6PreeditCallbackBehavior ,
+if the returned value is
+.PN True ,
+the input method uses the Release 6 behavior;
+otherwise, it uses the Release 5 behavior.
+The default value is
+.PN False .
+In order to use Release 6 semantics, the value of
+.PN XNR6PreeditCallbackBehavior
+must be set to
+.PN True .
+.LP
+Because this XIM value is optional, a client should call
+.PN XGetIMValues
+with argument
+.PN XNQueryIMValues
+before using this argument.
+If the
+.PN XNR6PreeditCallbackBehavior
+does not exist in the IM values list returned from
+.PN XNQueryIMValues ,
+the PreeditCallback behavior is Release 5 semantics.
+.LP
+.NH 3
+Input Context Functions
+.XS
+\*(SN Input Context Functions
+.XE
+.LP
+An input context is an abstraction that is used to contain both the data
+required (if any) by an input method and the information required
+to display that data.
+There may be multiple input contexts for one input method.
+The programming interfaces for creating, reading, or modifying
+an input context use a variable argument list.
+The name elements of the argument lists are referred to as XIC values.
+It is intended that input methods be controlled by these XIC values.
+As new XIC values are created,
+they should be registered with the X Consortium.
+.LP
+.sp
+To create an input context, use
+.PN XCreateIC .
+.IN "XCreateIC" "" "@DEF@"
+.sM
+.FD 0
+XIC XCreateIC\^(\^\fIim\fP\^, ...)
+.br
+      XIM \fIim\fP\^;
+.FN
+.IP \fIim\fP 1i
+Specifies the input method.
+.ds Al \ to set XIC values
+.IP ... 1i
+Specifies the variable length argument list\*(Al.
+.LP
+.eM
+The
+.PN XCreateIC 
+function creates a context within the specified input method.
+.LP
+Some of the arguments are mandatory at creation time, and
+the input context will not be created if those arguments are not provided.
+The mandatory arguments are the input style and the set of text callbacks
+(if the input style selected requires callbacks).
+All other input context values can be set later.
+.LP
+.PN XCreateIC
+returns a NULL value if no input context could be created.
+A NULL value could be returned for any of the following reasons:
+.IP \(bu 5
+A required argument was not set.
+.IP \(bu 5
+A read-only argument was set (for example,
+.PN XNFilterEvents ).
+.IP \(bu 5
+The argument name is not recognized.
+.IP \(bu 5
+The input method encountered an input method implementation-dependent error.
+.LP
+.PN XCreateIC
+can generate
+.PN BadAtom ,
+.PN BadColor ,
+.PN BadPixmap ,
+and
+.PN BadWindow
+errors.
+.LP
+.sp
+To destroy an input context, use
+.PN XDestroyIC .
+.IN "XDestroyIC" "" "@DEF@"
+.sM
+.FD 0
+void XDestroyIC\^(\^\fIic\fP\^)
+.br
+      XIC \fIic\fP\^;
+.FN
+.IP \fIic\fP 1i
+Specifies the input context.
+.LP
+.eM
+.PN XDestroyIC
+destroys the specified input context.
+.LP
+.sp
+To communicate to and synchronize with input method
+for any changes in keyboard focus from the client side,
+use 
+.PN XSetICFocus
+and
+.PN XUnsetICFocus .
+.IN "XSetICFocus" "" "@DEF@"
+.sM
+.FD 0
+void XSetICFocus\^(\^\fIic\fP\^)
+.br
+      XIC \fIic\fP\^; 
+.FN
+.IP \fIic\fP 1i
+Specifies the input context.
+.LP
+.eM
+The
+.PN XSetICFocus
+function allows a client to notify an input method that the focus window
+attached to the specified input context has received keyboard focus.
+The input method should take action to provide appropriate feedback.
+Complete feedback specification is a matter of user interface policy.
+.LP
+Calling
+.PN XSetICFocus
+does not affect the focus window value.
+.LP
+.sp
+.IN "XUnsetICFocus" "" "@DEF@"
+.sM
+.FD 0
+void XUnsetICFocus\^(\^\fIic\fP\^)
+.br
+      XIC \fIic\fP\^;
+.FN
+.IP \fIic\fP 1i
+Specifies the input context.
+.LP
+.eM
+The
+.PN XUnsetICFocus
+function allows a client to notify an input method that the specified input context
+has lost the keyboard focus and that no more input is expected on the focus window
+attached to that input context.
+The input method should take action to provide appropriate feedback.
+Complete feedback specification is a matter of user interface policy.
+.LP
+Calling
+.PN XUnsetICFocus
+does not affect the focus window value;
+the client may still receive 
+events from the input method that are directed to the focus window.
+.LP
+.sp
+To reset the state of an input context to its initial state, use
+.PN XmbResetIC
+or
+.PN XwcResetIC .
+.IN "XmbResetIC" "" "@DEF@"
+.IN "XwcResetIC" "" "@DE@"
+.sM
+.FD 0
+char * XmbResetIC\^(\^\fIic\fP\^)
+.br
+      XIC \fIic\fP\^;
+.FN
+.FD 0
+wchar_t * XwcResetIC\^(\^\fIic\fP\^)
+.br
+      XIC \fIic\fP\^; 
+.FN
+.IP \fIic\fP 1i
+Specifies the input context.
+.LP
+.eM
+When
+.PN XNResetState
+is set to
+.PN XIMInitialState ,
+.PN XmbResetIC
+and
+.PN XwcResetIC
+reset an input context to its initial state;
+when
+.PN XNResetState
+is set to
+.PN XIMPreserveState ,
+the current input context state is preserved.
+In both cases, any input pending on that context is deleted.
+The input method is required to clear the preedit area, if any,
+and update the status accordingly.
+Calling 
+.PN XmbResetIC
+or
+.PN XwcResetIC
+does not change the focus.
+.LP
+The return value of
+.PN XmbResetIC
+is its current preedit string as a multibyte string.
+If there is any preedit text drawn or visible to the user,
+then these procedures must return a non-NULL string.
+If there is no visible preedit text, 
+then it is input method implementation-dependent 
+whether these procedures return a non-NULL string or NULL.
+.LP
+The client should free the returned string by calling
+.PN XFree .
+.LP
+.sp
+To get the input method associated with an input context, use
+.PN XIMOfIC .
+.IN "XIMOfIC" "" "@DEF@"
+.sM
+.FD 0
+XIM XIMOfIC\^(\^\fIic\fP\^)
+.br
+      XIC \fIic\fP\^; 
+.FN
+.IP \fIic\fP 1i
+Specifies the input context.
+.LP
+.eM
+The
+.PN XIMOfIC
+function returns the input method associated with the specified input context.
+.LP
+.sp
+Xlib provides two functions for setting and reading XIC values, respectively,
+.PN XSetICValues
+and
+.PN XGetICValues .
+Both functions have a variable-length argument list.
+In that argument list, any XIC value's name must be denoted
+with a character string using the X Portable Character Set.
+.LP
+.sp
+To set XIC values, use
+.PN XSetICValues .
+.IN "XSetICValues" "" "@DEF@"
+.sM
+.FD 0
+char * XSetICValues\^(\^\fIic\fP\^, ...)
+.br
+      XIC \fIic\fP\^;
+.FN
+.IP \fIic\fP 1i
+Specifies the input context.
+.ds Al \ to set XIC values
+.IP ... 1i
+Specifies the variable length argument list\*(Al.
+.LP
+.eM
+The
+.PN XSetICValues
+function returns NULL if no error occurred; 
+otherwise,
+it returns the name of the first argument that could not be set.
+An argument might not be set for any of the following reasons:
+.IP \(bu 5
+The argument is read-only (for example,
+.PN XNFilterEvents ).
+.IP \(bu 5
+The argument name is not recognized.
+.IP \(bu 5
+An implementation-dependent error occurs.
+.LP
+Each value to be set must be an appropriate datum,
+matching the data type imposed by the semantics of the argument.
+.LP
+.PN XSetICValues
+can generate
+.PN BadAtom ,
+.PN BadColor ,
+.PN BadCursor ,
+.PN BadPixmap ,
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To obtain XIC values, use
+.PN XGetICValues .
+.IN "XGetICValues" "" "@DEF@"
+.sM
+.FD 0
+char * XGetICValues\^(\^\fIic\fP\^, ...)
+.br
+      XIC \fIic\fP\^;
+.FN
+.IP \fIic\fP 1i
+Specifies the input context.
+.ds Al \ to get XIC values
+.IP ... 1i
+Specifies the variable length argument list\*(Al.
+.LP
+.eM
+The
+.PN XGetICValues
+function returns NULL if no error occurred; otherwise,
+it returns the name of the first argument that could not be obtained.
+An argument could not be obtained for any of the following reasons:
+.IP \(bu 5
+The argument name is not recognized.
+.IP \(bu 5
+The input method encountered an implementation-dependent error.
+.LP
+Each IC attribute value argument (following a name) must point to
+a location where the IC value is to be stored.
+That is, if the IC value is of type T,
+the argument must be of type T*.
+If T itself is a pointer type,
+then
+.PN XGetICValues
+allocates memory to store the actual data,
+and the client is responsible for freeing this data by calling
+.PN XFree
+with the returned pointer.
+The exception to this rule is for an IC value of type
+.PN XVaNestedList
+(for preedit and status attributes).
+In this case,  the argument must also be of type
+.PN XVaNestedList .
+Then, the rule of changing type T to T* and freeing the allocated data
+applies to each element of the nested list.
+.NH 3 
+Input Context Values
+.XS
+\*(SN Input Context Values
+.XE
+.LP
+The following tables describe how XIC values are interpreted
+by an input method depending on the input style chosen by the 
+user.
+.LP
+The first column lists the XIC values.
+The second column indicates which values are involved in affecting,
+negotiating, and setting the geometry of the input method windows.
+The subentries under the third column indicate the different
+input styles that are supported.
+Each of these columns indicates how each of the XIC values 
+are treated by that input style.
+.LP
+The following keys apply to these tables.
+.TS H
+lw(1i) lw(4.75i).
+_
+.sp 6p
+.B
+Key	Explanation
+.sp 6p
+_
+.TH
+.R
+C	T{
+This value must be set with 
+.PN XCreateIC .
+T}
+D	T{
+This value may be set using 
+.PN XCreateIC .
+If it is not set,
+a default is provided.
+T}
+G	T{
+This value may be read using 
+.PN XGetICValues .
+T}
+GN	T{
+This value may cause geometry negotiation when its value is set by means of
+.PN XCreateIC
+or
+.PN XSetICValues .
+T}
+GR	T{
+This value will be the response of the input method when any 
+GN value is changed.
+T}
+GS	T{
+This value will cause the geometry of the input method window to be set.
+T}
+O	T{
+This value must be set once and only once.
+It need not be set at create time.
+T}
+S	T{
+This value may be set with
+.PN XSetICValues .
+T}
+Ignored	T{
+This value is ignored by the input method for the given input style.
+T}
+.sp 6p
+_
+.TE
+.LP
+.TS H
+c c c s s s s
+l c c c c c c
+c c c c c c c
+l c c c c c c.
+_
+.sp 6p
+.B
+		Input Style			
+XIC Value	Geometry	Preedit	Preedit	Preedit	Preedit	Preedit
+	Management	Callback	Position	Area	Nothing	None
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+Input Style		C-G	C-G	C-G	C-G	C-G
+Client Window		O-G	O-G	O-G	O-G	Ignored
+Focus Window	GN	D-S-G	D-S-G	D-S-G	D-S-G	Ignored
+Resource Name		Ignored	D-S-G	D-S-G	D-S-G	Ignored
+Resource Class		Ignored	D-S-G	D-S-G	D-S-G	Ignored
+Geometry Callback		Ignored	Ignored	D-S-G	Ignored	Ignored
+Filter Events		G	G	G	G	Ignored
+Destroy Callback		D-S-G	D-S-G	D-S-G	D-S-G	D-S-G
+String Conversion Callback		S-G	S-G	S-G	S-G	S-G
+String Conversion		D-S-G	D-S-G	D-S-G	D-S-G	D-S-G
+Reset State		D-S-G	D-S-G	D-S-G	D-S-G	Ignored
+HotKey		S-G	S-G	S-G	S-G	Ignored
+HotKeyState		D-S-G	D-S-G	D-S-G	D-S-G	Ignored
+.sp 6p
+\fBPreedit\fP
+Area	GS	Ignored	D-S-G	D-S-G	Ignored	Ignored
+Area Needed	GN-GR	Ignored	Ignored	S-G	Ignored	Ignored
+Spot Location		Ignored	D-S-G	Ignored	Ignored	Ignored
+Colormap		Ignored	D-S-G	D-S-G	D-S-G	Ignored
+Foreground		Ignored	D-S-G	D-S-G	D-S-G	Ignored
+Background		Ignored	D-S-G	D-S-G	D-S-G	Ignored
+Background Pixmap		Ignored	D-S-G	D-S-G	D-S-G	Ignored
+Font Set	GN	Ignored	D-S-G	D-S-G	D-S-G	Ignored
+Line Spacing	GN	Ignored	D-S-G	D-S-G	D-S-G	Ignored
+Cursor		Ignored	D-S-G	D-S-G	D-S-G	Ignored
+Preedit State		D-S-G	D-S-G	D-S-G	D-S-G	Ignored
+Preedit State Notify Callback		S-G	S-G	S-G	S-G	Ignored
+Preedit Callbacks		C-S-G	Ignored	Ignored	Ignored	Ignored
+.sp 6p
+_
+.TE
+.LP
+.TS H
+c c c s s s
+l c c c c c
+c c c c c c 
+l c c c c c.
+_
+.sp 6p
+.B
+		Input Style			
+XIC Value	Geometry	Status	Status	Status	Status
+	Management	Callback	Area	Nothing	None
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+Input Style		C-G	C-G	C-G	C-G
+Client Window		O-G	O-G	O-G	Ignored
+Focus Window	GN	D-S-G	D-S-G	D-S-G	Ignored
+Resource Name		Ignored	D-S-G	D-S-G	Ignored
+Resource Class		Ignored	D-S-G	D-S-G	Ignored
+Geometry Callback		Ignored	D-S-G	Ignored	Ignored
+Filter Events		G	G	G	G
+.sp 6p
+\fBStatus\fP					
+Area	GS	Ignored	D-S-G	Ignored	Ignored
+Area Needed	GN-GR	Ignored	S-G	Ignored	Ignored
+Colormap		Ignored	D-S-G	D-S-G	Ignored
+Foreground		Ignored	D-S-G	D-S-G	Ignored
+Background		Ignored	D-S-G	D-S-G	Ignored
+Background Pixmap		Ignored	D-S-G	D-S-G	Ignored
+Font Set	GN	Ignored	D-S-G	D-S-G	Ignored
+Line Spacing	GN	Ignored	D-S-G	D-S-G	Ignored
+Cursor		Ignored	D-S-G	D-S-G	Ignored
+Status Callbacks		C-S-G	Ignored	Ignored	Ignored
+.sp 6p
+_
+.TE
+.NH 4 
+Input Style
+.XS
+\*(SN Input Style
+.XE
+.LP
+The
+.PN XNInputStyle
+argument specifies the input style to be used.
+The value of this argument must be one of the values returned by the
+.PN XGetIMValues
+function with the
+.PN XNQueryInputStyle
+argument specified in the supported_styles list.
+.LP
+Note that this argument must be set at creation time
+and cannot be changed.
+.NH 4 
+Client Window
+.XS
+\*(SN Client Window
+.XE
+.LP
+.IN "XNClientWindow" "" "@DEF@"
+The
+.PN XNClientWindow
+argument specifies to the input method the client window in
+which the input method
+can display data or create subwindows.
+Geometry values for input method areas are given with respect to the client
+window.
+Dynamic change of client window is not supported.
+This argument may be set only once and
+should be set before any input is done using this input context.
+If it is not set,
+the input method may not operate correctly.
+.LP
+If an attempt is made to set this value a second time with
+.PN XSetICValues ,
+the string
+.PN XNClientWindow
+will be returned by
+.PN XSetICValues ,
+and the client window will not be changed.
+.LP
+If the client window is not a valid window ID on the display
+attached to the input method,
+a 
+.PN BadWindow 
+error can be generated when this value is used by the input method.
+.NH 4 
+Focus Window
+.XS
+\*(SN Focus Window
+.XE
+.LP
+.IN "XNFocusWindow" "" "@DEF@"
+The
+.PN XNFocusWindow
+argument specifies the focus window.
+The primary purpose of the 
+.PN XNFocusWindow
+is to identify the window that will receive the key event when input
+is composed.
+In addition, the input method may possibly affect the focus window
+as follows:
+.IP \(bu 5
+Select events on it
+.IP \(bu 5
+Send events to it
+.IP \(bu 5
+Modify its properties
+.IP \(bu 5
+Grab the keyboard within that window  
+.LP
+The associated value must be of type 
+.PN Window .
+If the focus window is not a valid window ID on the display 
+attached to the input method,
+a 
+.PN BadWindow
+error can be generated when this value is used by the input method.
+.LP
+When this XIC value is left unspecified,
+the input method will use the client window as the default focus window.
+.NH 4
+Resource Name and Class
+.XS
+\*(SN Resource Name and Class
+.XE
+.LP
+.IN "XNResourceName" "" "@DEF@"
+.IN "XNResourceClass" "" "@DEF@"
+The
+.PN XNResourceName
+and
+.PN XNResourceClass
+arguments are strings that specify the full name and class
+used by the client to obtain resources for the client window. 
+These values should be used as prefixes for name and class
+when looking up resources that may vary according to the input context.
+If these values are not set,
+the resources will not be fully specified.
+.LP
+It is not intended that values that can be set as XIC values be
+set as resources.
+.NH 4
+Geometry Callback
+.XS
+\*(SN Geometry Callback
+.XE
+.LP
+.IN "XNGeometryCallback" "" "@DEF@"
+The 
+.PN XNGeometryCallback
+argument is a structure of type 
+.PN XIMCallback 
+(see section 13.5.6.13.12).
+.LP
+The 
+.PN XNGeometryCallback
+argument specifies the geometry callback that a client can set.
+This callback is not required for correct operation of either 
+an input method or a client.
+It can be set for a client whose user interface policy permits
+an input method to request the dynamic change of that input 
+method's window.
+An input method that does dynamic change will need to filter any
+events that it uses to initiate the change.
+.NH 4
+Filter Events
+.XS
+\*(SN Filter Events
+.XE
+.LP
+.IN "XNFilterEvents" "" "@DEF@"
+The 
+.PN XNFilterEvents
+argument returns the event mask that an input method needs
+to have selected for.
+The client is expected to augment its own event mask 
+for the client window with this one.
+.LP
+This argument is read-only, is set by the input method at create time,
+and is never changed.
+.LP
+The type of this argument is 
+.PN unsigned
+.PN long .
+Setting this value will cause an error.
+.NH 4
+Destroy Callback
+.XS
+\*(SN Destroy Callback 
+.XE
+.LP
+The 
+.PN XNDestroyCallback 
+argument is a pointer to a structure of type
+.PN XIMCallback 
+(see section 13.5.6.13.12).  This callback is triggered when the input method 
+stops its service for any reason; for example, when a connection to an IM
+server is broken.  After the destroy callback is called, 
+the input context is destroyed and the input method is closed.
+Therefore, the client should not call 
+.PN XDestroyIC
+and
+.PN XCloseIM .
+.LP
+.NH 4
+String Conversion Callback
+.XS
+\*(SN String Conversion Callback
+.XE
+.LP
+The
+.PN XNStringConversionCallback
+argument is a structure of type
+.PN XIMCallback 
+(see section 13.5.6.13.12).
+.LP
+The
+.PN XNStringConversionCallback
+argument specifies a string conversion callback.  This callback
+is not required for correct operation of
+either the input method or the client.  It can be set by a client
+to support string conversions that may be requested
+by the input method.  An input method that does string conversions
+will filter any events that it uses to initiate the conversion.
+.LP
+Because this XIC value is optional, a client should call
+.PN XGetIMValues
+with argument
+.PN XNQueryICValuesList
+before using this argument.
+.LP
+.NH 4
+String Conversion 
+.XS
+\*(SN String Conversion
+.XE
+.LP
+The
+.PN XNStringConversion
+argument is a structure of type
+.PN XIMStringConversionText .
+.LP
+The
+.PN XNStringConversion
+argument specifies the string to be converted by an input method.
+This argument is not required for correct operation of either
+the input method or the client.
+.LP
+String conversion facilitates the manipulation of text independent
+of preediting.
+It is essential for some input methods and clients to manipulate
+text by performing context-sensitive conversion,
+reconversion, or transliteration conversion on it.
+.LP
+Because this XIC value is optional, a client should call
+.PN XGetIMValues
+with argument
+.PN XNQueryICValuesList
+before using this argument.
+.LP
+The
+.PN XIMStringConversionText
+structure is defined as follows:
+.LP
+.sM
+.Ds 0
+
+typedef struct _XIMStringConversionText {
+	unsigned short length;
+	XIMStringConversionFeedback *feedback;
+	Bool encoding_is_wchar;
+	union {
+		char	*mbs;
+		wchar_t *wcs;
+	} string;
+} XIMStringConversionText;
+
+typedef unsigned long XIMStringConversionFeedback;
+.De
+.LP
+.eM
+The feedback member is reserved for future use.  The text to be
+converted is defined by the string and length members.  The length
+is indicated in characters.  To prevent the library from freeing memory
+pointed to by an uninitialized pointer, the client should set the feedback
+element to NULL.
+.LP
+.NH 4
+Reset State
+.XS
+\*(SN Reset State
+.XE
+.LP
+The
+.PN XNResetState
+argument specifies the state the input context will return to after calling
+.PN XmbResetIC
+or
+.PN XwcResetIC .
+.LP
+The XIC state may be set to its initial state, as specified by the
+.PN XNPreeditState
+value when
+.PN XCreateIC
+was called, or it may be set to preserve the current state.
+.LP
+The valid masks for
+.PN XIMResetState
+are as follows:
+.LP
+.IN "XIMInitialState" "" "@DEF@"
+.IN "XINPreserveState" "" "@DEF@"
+.sM
+.LP
+.Ds 0
+typedef unsigned long XIMResetState;
+.De
+.TS
+lw(.5i) lw(2i) lw(2i).
+T{
+#define
+T}	T{
+.PN XIMInitialState
+T}	T{
+(1L)
+T}
+T{
+#define
+T}	T{
+.PN XIMPreserveState
+T}	T{
+(1L<<1)
+T}
+.TE
+.LP
+.eM
+If
+.PN XIMInitialState
+is set, then
+.PN XmbResetIC
+and
+.PN XwcResetIC
+will return to the initial
+.PN XNPreeditState
+state of the XIC.
+.LP
+If
+.PN XIMPreserveState
+is set, then 
+.PN XmbResetIC
+and
+.PN XwcResetIC
+will preserve the current state of the XIC.
+.LP
+If
+.PN XNResetState
+is left unspecified, the default is
+.PN XIMInitialState .
+.LP
+.PN XIMResetState
+values other than those specified above will default to
+.PN XIMInitialState .
+.LP
+Because this XIC value is optional, a client should call
+.PN XGetIMValues
+with argument
+.PN XNQueryICValuesList
+before using this argument.
+.LP
+.NH 4
+Hot Keys
+.XS
+\*(SN Hot Keys
+.XE
+.LP
+The
+.PN XNHotKey
+argument specifies the hot key list to the XIC.
+The hot key list is a pointer to the structure of type
+.PN XIMHotKeyTriggers ,
+which specifies the key events that must be received
+without any interruption of the input method.
+For the hot key list set with this argument to be utilized, the client
+must also set
+.PN XNHotKeyState
+to
+.PN XIMHotKeyStateON .
+.LP
+Because this XIC value is optional, a client should call
+.PN XGetIMValues
+with argument
+.PN XNQueryICValuesList
+before using this functionality.
+.LP
+The value of the argument is a pointer to a structure of type
+.PN XIMHotKeyTriggers .
+.LP
+If an event for a key in the hot key list is found, then the process will
+receive the event and it will be processed inside the client.
+.LP
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	KeySym keysym;
+	unsigned int modifier;
+	unsigned int modifier_mask;
+} XIMHotKeyTrigger;
+
+typedef struct {
+	int num_hot_key;
+	XIMHotKeyTrigger *key;
+} XIMHotKeyTriggers;
+.De
+.LP
+.eM
+.LP
+The combination of modifier and modifier_mask are used to represent one of
+three states for each modifier:
+either the modifier must be on, or the modifier must be off, or the modifier
+is a ``don't care'' \- it may be on or off.
+When a modifier_mask bit is set to 0, the state of the associated modifier
+is ignored when evaluating whether the key is hot or not.
+.TS H
+lw(1i) lw(1i) lw(3i).
+_
+.sp 6p
+.B
+Modifier Bit	Mask Bit	Meaning
+.sp 6p
+_
+.sp 6p
+.TH
+.R
+T{
+0
+T}	T{
+1
+T}	T{
+The modifier must be off.
+T}
+T{
+1
+T}	T{
+1
+T}	T{
+The modifier must be on.
+T}
+T{
+n/a
+T}	T{
+0
+T}	T{
+Do not care if the modifier is on or off.
+T}
+.sp 6p
+_
+.TE
+.NH 4
+Hot Key State
+.XS
+\*(SN Hot Key State
+.XE
+.LP
+The
+.PN XNHotKeyState
+argument specifies the hot key state of the input method.
+This is usually used to switch the input method between hot key
+operation and normal input processing.
+.LP
+The value of the argument is a pointer to a structure of type
+XIMHotKeyState .
+.LP
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef unsigned long XIMHotKeyState;
+.De
+.TS
+lw(.5i) lw(3i) lw(2i).
+T{
+#define
+T}	T{
+.PN XIMHotKeyStateON
+T}	T{
+(0x0001L)
+T}
+T{
+#define
+T}	T{
+.PN XIMHotKeyStateOFF
+T}	T{
+(0x0002L)
+T}
+.TE
+.LP
+.eM
+.LP
+If not specified, the default is
+.PN XIMHotKeyStateOFF .
+.LP
+.NH 4
+Preedit and Status Attributes
+.XS
+\*(SN Preedit and Status Attributes
+.XE
+.LP
+.IN "XNPreeditAttributes" "" "@DEF@"
+.IN "XNStatusAttributes" "" "@DEF@"
+The
+.PN XNPreeditAttributes
+and
+.PN XNStatusAttributes
+arguments specify to an input method the attributes to be used for the 
+preedit and status areas,
+if any.
+Those attributes are passed to 
+.PN XSetICValues
+or
+.PN XGetICValues
+as a nested variable-length list.
+The names to be used in these lists are described in the following sections.
+.NH 5 
+Area
+.XS
+\*(SN Area
+.XE
+.LP
+.IN "XNArea" "" "@DEF@"
+The value of the
+.PN XNArea
+argument must be a pointer to a structure of type
+.PN XRectangle.
+The interpretation of the
+.PN XNArea
+argument is dependent on the input method style that has been set.
+.LP
+If the input method style is 
+.PN XIMPreeditPosition ,
+.PN XNArea
+specifies the clipping region within which preediting will take place.
+If the focus window has been set,
+the coordinates are assumed to be relative to the focus window.
+Otherwise, the coordinates are assumed to be relative to the client window.
+If neither has been set,
+the results are undefined.
+.LP
+If 
+.PN XNArea
+is not specified, is set to NULL, or is invalid,
+the input method will default the clipping region
+to the geometry of the
+.PN XNFocusWindow .
+If the area specified is NULL or invalid,
+the results are undefined.
+.LP
+If the input style is 
+.PN XIMPreeditArea
+or 
+.PN XIMStatusArea ,
+.PN XNArea
+specifies the geometry provided by the client to the input method.
+The input method may use this area to display its data,
+either preedit or status depending on the area designated.
+The input method may create a window as a child of the client window
+with dimensions that fit the
+.PN XNArea .
+The coordinates are relative to the client window.
+If the client window has not been set yet,
+the input method should save these values 
+and apply them when the client window is set.
+If 
+.PN XNArea
+is not specified, is set to NULL, or is invalid,
+the results are undefined.
+.NH 5
+Area Needed
+.XS
+\*(SN Area Needed
+.XE
+.LP
+.IN "XNAreaNeeded" "" "@DEF@"
+When set, the
+.PN XNAreaNeeded
+argument specifies the geometry suggested by the client for this area
+(preedit or status).
+The value associated with the argument must be a pointer to a 
+structure of type 
+.PN XRectangle .
+Note that the x, y values are not used
+and that nonzero values for width or height are the constraints 
+that the client wishes the input method to respect.
+.LP
+When read, the
+.PN XNAreaNeeded
+argument specifies the preferred geometry desired by the input method
+for the area.
+.LP
+This argument is only valid if the input style is 
+.PN XIMPreeditArea
+or 
+.PN XIMStatusArea .
+It is used for geometry negotiation between the client and the input method
+and has no other effect on the input method 
+(see section 13.5.1.5).
+.NH 5 
+Spot Location
+.XS
+\*(SN Spot Location
+.XE
+.LP
+.IN "XNSpotLocation" "" "@DEF@"
+The
+.PN XNSpotLocation
+argument specifies to the input method the coordinates of the spot
+to be used by an input method executing with 
+.PN XNInputStyle 
+set to 
+.PN XIMPreeditPosition .
+When specified to any input method other than 
+.PN XIMPreeditPosition ,
+this XIC value is ignored.
+.LP
+The x coordinate specifies the position where the next character
+would be inserted.
+The y coordinate is the position of the baseline used
+by the current text line in the focus window.
+The x and y coordinates are relative to the focus window, if it has been set;
+otherwise, they are relative to the client window.
+If neither the focus window nor the client window has been set,
+the results are undefined.
+.LP
+The value of the argument is a pointer to a structure of type
+.PN XPoint .
+.NH 5
+Colormap
+.XS
+\*(SN Colormap
+.XE
+.LP
+Two different arguments can be used to indicate what colormap the input method
+should use to allocate colors, a colormap ID, or a standard colormap name.
+.LP
+.IN "XNColormap" "" "@DEF@"
+The
+.PN XNColormap
+argument is used to specify a colormap ID.
+The argument value is of type
+.PN Colormap .
+An invalid argument may generate a 
+.PN BadColor
+error when it is used by the input method.
+.LP
+.IN "XNStdColormap" "" "@DEF@"
+The
+.PN XNStdColormap
+argument is used to indicate the name of the standard colormap
+in which the input method should allocate colors.
+The argument value is an 
+.PN Atom
+that should be a valid atom for calling
+.PN XGetRGBColormaps .
+An invalid argument may generate a
+.PN BadAtom
+error when it is used by the input method.
+.LP
+If the colormap is left unspecified,
+the client window colormap becomes the default.
+.NH 5
+Foreground and Background
+.XS
+\*(SN Foreground and Background
+.XE
+.LP
+.IN "XNForeground" "" "@DEF@"
+.IN "XNBackground" "" "@DEF@"
+The
+.PN XNForeground
+and
+.PN XNBackground
+arguments specify the foreground and background pixel, respectively.
+The argument value is of type
+.PN unsigned
+.PN long .
+It must be a valid pixel in the input method colormap.
+.LP
+If these values are left unspecified,
+the default is determined by the input method.
+.NH 5
+Background Pixmap
+.XS
+\*(SN Background Pixmap
+.XE
+.LP
+The
+.PN XNBackgroundPixmap
+argument specifies a background pixmap to be used as the background of the
+window.
+The value must be of type 
+.PN Pixmap .
+An invalid argument may generate a
+.PN BadPixmap
+error when it is used by the input method.
+.LP
+If this value is left unspecified,
+the default is determined by the input method.
+.NH 5
+Font Set
+.XS
+\*(SN Font Set
+.XE
+.LP
+.IN "XNFontSet" "" "@DEF@"
+The
+.PN XNFontSet
+argument specifies to the input method what font set is to be used.
+The argument value is of type
+.PN XFontSet .
+.LP
+If this value is left unspecified,
+the default is determined by the input method.
+.NH 5
+Line Spacing
+.XS
+\*(SN Line Spacing
+.XE
+.LP
+The
+.PN XNLineSpace
+argument specifies to the input method what line spacing is to be used
+in the preedit window if more than one line is to be used.
+This argument is of type
+.PN int .
+.LP
+If this value is left unspecified,
+the default is determined by the input method.
+.NH 5
+Cursor
+.XS
+\*(SN Cursor
+.XE
+.LP
+.IN "XNCursor" "" "DEF@"
+The
+.PN XNCursor
+argument specifies to the input method what cursor is to be used
+in the specified window.
+This argument is of type 
+.PN Cursor .
+.LP
+An invalid argument may generate a
+.PN BadCursor
+error when it is used by the input method.
+If this value is left unspecified,
+the default is determined by the input method.
+.NH 5 
+Preedit State
+.XS
+\*(SN Preedit State
+.XE
+.LP
+The
+.PN XNPreeditState
+argument specifies the state of input preediting for the input method.
+Input preediting can be on or off.
+.LP
+The valid mask names for
+.PN XNPreeditState
+are as follows:
+.LP
+.IN "XIMPreeditUnknown" "" "@DEV@"
+.IN "XIMPreeditEnable" "" "@DEF@"
+.IN "XIMPreeditDisable" "" "@DEV@"
+.sM
+.LP
+.Ds 0
+typedef unsigned long XIMPreeditState;
+.De
+.TS
+lw(.5i) lw(2i) lw(2i).
+T{
+#define
+T}	T{
+.PN XIMPreeditUnknown
+T}	T{
+0L
+T}
+T{
+#define
+T}	T{
+.PN XIMPreeditEnable
+T}	T{
+1L
+T}
+T{
+#define
+T}	T{
+.PN XIMPreeditDisable
+T}	T{
+(1L<<1)
+T}
+.TE
+.LP
+.eM
+If a value of
+.PN XIMPreeditEnable
+is set, then input preediting is turned on by the input method.
+.LP
+If a value of
+.PN XIMPreeditDisable
+is set, then input preediting is turned off by the input method.
+.LP
+If
+.PN XNPreeditState
+is left unspecified, then the state will be implementation-dependent.
+.LP
+When
+.PN XNResetState
+is set to
+.PN XIMInitialState ,
+the
+.PN XNPreeditState
+value specified at the creation time will be reflected as the initial state for
+.PN XmbResetIC
+and
+.PN XwcResetIC .
+.LP
+Because this XIC value is optional, a client should call
+.PN XGetIMValues
+with argument
+.PN XNQueryICValuesList
+before using this argument.
+.NH 5
+Preedit State Notify Callback
+.XS
+\*(SN Preedit State Notify Callback
+.XE
+.LP
+The preedit state notify callback is triggered by the input method
+when the preediting state has changed.
+The value of the
+.PN XNPreeditStateNotifyCallback
+argument is a pointer to a structure of type
+.PN XIMCallback .
+The generic prototype is as follows:
+.IN "PreeditStateNotifyCallback" "" "@DEF@"
+.sM
+.FD 0
+void PreeditStateNotifyCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
+.br
+      XIC \fIic\fP\^;
+.br
+      XPointer \fIclient_data\fP\^;
+.br
+      XIMPreeditStateNotifyCallbackStruct *\fIcall_data\fP\^;
+.FN
+.IP \fIic\fP 1i
+Specifies the input context.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data.
+.IP \fIcall_data\fP 1i
+Specifies the current preedit state.
+.LP
+.eM
+The
+.PN XIMPreeditStateNotifyCallbackStruct
+structure is defined as follows:
+.LP
+.IN "XIMPreeditStateNotifyCallbackStruct" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct _XIMPreeditStateNotifyCallbackStruct {
+	XIMPreeditState state;
+} XIMPreeditStateNotifyCallbackStruct;
+.De
+.LP
+.eM
+.LP
+Because this XIC value is optional, a client should call
+.PN XGetIMValues
+with argument
+.PN XNQueryICValuesList
+before using this argument.
+.NH 5
+Preedit and Status Callbacks
+.XS
+\*(SN Preedit and Status Callbacks
+.XE
+.LP
+A client that wants to support the input style
+.PN XIMPreeditCallbacks
+must provide a set of preedit callbacks to the input method.
+The set of preedit callbacks is as follows:
+.IN "XNPreeditStartCallback" "" "@DEF@"
+.IN "XNPreeditDoneCallback" "" "@DEF@"
+.IN "XNPreeditDrawCallback" "" "@DEF@"
+.IN "XNPreeditCaretCallback" "" "@DEF@"
+.TS
+lw(1.75i) lw(4i).
+T{
+.PN XNPreeditStartCallback
+T}	T{
+This is called when the input method starts preedit.
+T}
+T{
+.PN XNPreeditDoneCallback
+T}	T{
+This is called when the input method stops preedit.
+T}
+T{
+.PN XNPreeditDrawCallback
+T}	T{
+This is called when a number of preedit keystrokes should be echoed.
+T}
+T{
+.PN XNPreeditCaretCallback
+T}	T{
+This is called to move the text insertion point within the preedit string.
+T}
+.TE
+.LP
+A client that wants to support the input style
+.PN XIMStatusCallbacks
+must provide a set of status callbacks to the input method.
+The set of status callbacks is as follows:
+.IN "XNStatusStartCallback" "" "@DEF@"
+.IN "XNStatusDoneCallback" "" "@DEF@"
+.IN "XNStatusDrawCallback" "" "@DEF@"
+.TS
+lw(1.75i) lw(4i).
+T{
+.PN XNStatusStartCallback
+T}	T{
+This is called when the input method initializes the status area.
+T}
+T{
+.PN XNStatusDoneCallback
+T}	T{
+This is called when the input method no longer needs the status area.
+T}
+T{
+.PN XNStatusDrawCallback
+T}	T{
+This is called when updating of the status area is required.
+T}
+.TE
+.LP
+The value of any status or preedit argument is a pointer
+to a structure of type
+.PN XIMCallback .
+.IN "XIMProc" "" "@DEF@"
+.IN "XIMCallback" "" "@DEF@"
+.sM
+.LP
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef void (*XIMProc)();
+
+typedef struct {
+	XPointer client_data;
+	XIMProc callback;
+} XIMCallback;
+.De
+.LP
+.eM
+Each callback has some particular semantics and will carry the data
+that expresses the environment necessary to the client 
+into a specific data structure.
+This paragraph only describes the arguments to be used to set
+the callback.
+.LP
+Setting any of these values while doing preedit
+may cause unexpected results.
+.NH 3
+Input Method Callback Semantics
+.XS
+\*(SN Input Method Callback Semantics
+.XE
+.LP
+XIM callbacks are procedures defined by clients or text drawing packages
+that are to be called from the input method when selected events occur.
+Most clients will use a text editing package or a toolkit
+and, hence, will not need to define such callbacks.
+This section defines the callback semantics, when they are triggered,
+and what their arguments are.
+This information is mostly useful for X toolkit implementors.
+.LP
+Callbacks are mostly provided so that clients (or text editing
+packages) can implement on-the-spot preediting in their own window.
+In that case,
+the input method needs to communicate and synchronize with the client.
+The input method needs to communicate changes in the preedit window 
+when it is under control of the client.
+Those callbacks allow the client to initialize the preedit area,
+display a new preedit string,
+move the text insertion point during preedit,
+terminate preedit, or update the status area.
+.LP
+All callback procedures follow the generic prototype:
+.IN "CallbackPrototype" "" "@DEF@"
+.sM
+.FD 0
+void CallbackPrototype\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
+.br
+      XIC \fIic\fP\^;
+.br
+      XPointer \fIclient_data\fP\^;	
+.br
+      SomeType \fIcall_data\fP\^;
+.FN
+.IP \fIic\fP 1i
+Specifies the input context.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data.
+.IP \fIcall_data\fP 1i
+Specifies data specific to the callback.
+.LP
+.eM
+The call_data argument is a structure that expresses the arguments needed
+to achieve the semantics;
+that is,
+it is a specific data structure appropriate to the callback.
+In cases where no data is needed in the callback,
+this call_data argument is NULL.
+The client_data argument is a closure that has been initially specified
+by the client when specifying the callback and passed back.
+It may serve, for example, to inherit application context in the callback.
+.LP
+The following paragraphs describe the programming semantics
+and specific data structure associated with the different reasons.
+.NH 4
+Geometry Callback
+.XS
+\*(SN Geometry Callback
+.XE
+.LP
+The geometry callback is triggered by the input method 
+to indicate that it wants the client to negotiate geometry.
+The generic prototype is as follows:
+.IN "GeometryCallback" "" "@DEF@"
+.sM
+.FD 0
+void GeometryCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
+.br
+      XIC \fIic\fP\^;
+.br
+      XPointer \fIclient_data\fP\^;
+.br
+      XPointer \fIcall_data\fP\^;
+.FN
+.IP \fIic\fP 1i
+Specifies the input context.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data.
+.IP \fIcall_data\fP 1i
+Not used for this callback and always passed as NULL.
+.LP
+.eM
+The callback is called with a NULL call_data argument.
+.NH 4
+Destroy Callback
+.XS
+\*(SN Destroy Callback
+.XE
+.LP
+The destroy callback is triggered by the input method 
+when it stops service for any reason.
+After the callback is invoked, the input context will be freed by Xlib.
+The generic prototype is as follows:
+.IN "DestroyCallback" "" "@DEF@"
+.sM
+.FD 0
+void DestroyCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
+.br
+      XIC \fIic\fP\^;
+.br
+      XPointer \fIclient_data\fP\^;
+.br
+      XPointer \fIcall_data\fP\^;
+.FN
+.IP \fIic\fP 1i
+Specifies the input context.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data.
+.IP \fIcall_data\fP 1i
+Not used for this callback and always passed as NULL.
+.LP
+.eM
+The callback is called with a NULL call_data argument.
+.NH 4
+String Conversion Callback
+.XS
+\*(SN String Conversion Callback
+.XE
+.LP
+The string conversion callback is triggered by the input method 
+to request the client to return the string to be converted.  The
+returned string may be either a multibyte or wide character string,
+with an encoding matching the locale bound to the input context.
+The callback prototype is as follows:
+.IN "StringConversionCallback" "" "@DEF@"
+.sM
+.FD 0
+void StringConversionCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
+.br
+      XIC \fIic\fP\^;
+.br
+      XPointer \fIclient_data\fP\^;
+.br
+      XIMStringConversionCallbackStruct *\fIcall_data\fP\^;
+.FN
+.IP \fIic\fP 1i
+Specifies the input method.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data.
+.IP \fIcall_data\fP 1i
+Specifies the amount of the string to be converted.
+.LP
+.eM
+The callback is passed an
+.PN XIMStringConversionCallbackStruct
+structure in the call_data argument.
+The text member is an
+.PN XIMStringConversionText
+structure (see section 13.5.6.9) to be filled in by the client
+and describes the text to be sent to the input method.
+The data pointed to by the 
+string and feedback elements of the
+.PN XIMStringConversionText
+structure will be freed using
+.PN XFree
+by the input method
+after the callback returns.  So the client should not point to 
+internal buffers that are critical to the client.
+Similarly, because the feedback element is currently reserved for future
+use, the client should set feedback to NULL to prevent the library from
+freeing memory at some random location due to an uninitialized pointer.
+.LP
+The 
+.PN XIMStringConversionCallbackStruct
+structure is defined as follows:
+.LP
+.IN "XIMStringConversionCallbackStruct" "" "@DEF@"
+.sM
+.LP
+.Ds 0
+typedef struct _XIMStringConversionCallbackStruct {
+	XIMStringConversionPosition position;		
+	XIMCaretDirection direction;
+	short factor;
+	XIMStringConversionOperation operation;
+	XIMStringConversionText *text;
+} XIMStringConversionCallbackStruct;
+
+typedef short XIMStringConversionPosition;
+
+typedef unsigned short XIMStringConversionOperation;
+
+.De
+.LP
+.TS
+lw(.5i) lw(3i) lw(2i).
+T{
+#define
+T}	T{
+.PN XIMStringConversionSubstitution
+T}	T{
+(0x0001)
+T}
+T{
+#define
+T}	T{
+.PN XIMStringConversionRetrieval
+T}	T{
+(0x0002)
+T}
+.TE
+.LP
+.eM
+.PN XIMStringConversionPosition
+specifies the starting position of the string to be returned
+in the
+.PN XIMStringConversionText
+structure.  The value identifies a position, in units of characters,
+relative to the client's cursor position in the client's buffer.
+.LP
+The ending position of the text buffer is determined by
+the direction and factor members.  Specifically, it is the character position 
+relative to the starting point as defined by the
+.PN XIMCaretDirection .
+The factor member of 
+.PN XIMStringConversionCallbackStruct 
+specifies the number of
+.PN XIMCaretDirection 
+positions to be applied.  For example, if the direction specifies
+.PN XIMLineEnd
+and factor is 1, then all characters from the starting position to 
+the end of the current display line are returned.  If the direction
+specifies
+.PN XIMForwardChar
+or
+.PN XIMBackwardChar ,
+then the factor specifies a relative position, indicated in characters, 
+from the starting position.
+.LP
+.PN XIMStringConversionOperation
+specifies whether the string to be converted should be 
+deleted (substitution) or copied (retrieval) from the client's
+buffer.  When the
+.PN XIMStringConversionOperation
+is
+.PN XIMStringConversionSubstitution ,
+the client must delete the string to be converted from its own buffer.
+When the
+.PN XIMStringConversionOperation
+is
+.PN XIMStringConversionRetrieval ,
+the client must not delete the string to be converted from its buffer.
+The substitute operation is typically used for reconversion and
+transliteration conversion,
+while the retrieval operation is typically used for context-sensitive 
+conversion.
+.NH 4
+Preedit State Callbacks
+.XS
+\*(SN Preedit State Callbacks
+.XE
+.LP
+When the input method turns preediting on or off, a
+.PN PreeditStartCallback
+or
+.PN PreeditDoneCallback
+callback is triggered to let the toolkit do the setup
+or the cleanup for the preedit region.
+.IN "PreeditStartCallback" "" "@DEF@"
+.sM
+.FD 0
+int PreeditStartCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
+.br
+      XIC \fIic\fP\^;
+.br
+      XPointer \fIclient_data\fP\^;
+.br
+      XPointer \fIcall_data\fP\^;
+.FN
+.IP \fIic\fP 1i
+Specifies the input context.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data.
+.IP \fIcall_data\fP 1i
+Not used for this callback and always passed as NULL.
+.LP
+.eM
+When preedit starts on the specified input context,
+the callback is called with a NULL call_data argument.
+.PN PreeditStartCallback
+will return the maximum size of the preedit string.
+A positive number indicates the maximum number of bytes allowed
+in the preedit string, 
+and a value of \-1 indicates there is no limit.
+.IN "PreeditDoneCallback" "" "@DEF@"
+.sM
+.FD 0
+void PreeditDoneCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
+.br
+      XIC \fIic\fP\^;
+.br
+      XPointer \fIclient_data\fP\^;
+.br
+      XPointer \fIcall_data\fP\^;
+.FN
+.IP \fIic\fP 1i
+Specifies the input context.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data.
+.IP \fIcall_data\fP 1i
+Not used for this callback and always passed as NULL.
+.LP
+.eM
+When preedit stops on the specified input context,
+the callback is called with a NULL call_data argument.
+The client can release the data allocated by
+.PN PreeditStartCallback .
+.LP
+.PN PreeditStartCallback
+should initialize appropriate data needed for
+displaying preedit information and for handling further 
+.PN PreeditDrawCallback
+calls.
+Once
+.PN PreeditStartCallback
+is called, it will not be called again before
+.PN PreeditDoneCallback
+has been called.
+.NH 4
+Preedit Draw Callback
+.XS
+\*(SN Preedit Draw Callback
+.XE
+.LP
+This callback is triggered to draw and insert, delete or replace,
+preedit text in the preedit region.
+The preedit text may include unconverted input text such as Japanese Kana,
+converted text such as Japanese Kanji characters, or characters of both kinds.
+That string is either a multibyte or wide character string, 
+whose encoding matches the locale bound to the input context.
+The callback prototype
+is as follows:
+.IN "PreeditDrawCallback" "" "@DEF@"
+.sM
+.FD 0
+void PreeditDrawCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
+.br
+      XIC \fIic\fP\^;
+.br
+      XPointer \fIclient_data\fP\^;
+.br
+      XIMPreeditDrawCallbackStruct *\fIcall_data\fP\^;
+.FN
+.IP \fIic\fP 1i
+Specifies the input context.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data.
+.IP \fIcall_data\fP 1i
+Specifies the preedit drawing information.
+.LP
+.eM
+The callback is passed an 
+.PN XIMPreeditDrawCallbackStruct
+structure in the call_data argument.
+The text member of this structure contains the text to be drawn.
+After the string has been drawn,
+the caret should be moved to the specified location.
+.LP
+The 
+.PN XIMPreeditDrawCallbackStruct
+structure is defined as follows:
+.LP
+.IN "XIMPreeditDrawCallbackStruct" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct _XIMPreeditDrawCallbackStruct {
+	int caret;	/* Cursor offset within preedit string */
+	int chg_first;	/* Starting change position */
+	int chg_length;	/* Length of the change in character count */
+	XIMText *text;
+} XIMPreeditDrawCallbackStruct;
+.De
+.LP
+.eM
+The client must keep updating a buffer of the preedit text
+and the callback arguments referring to indexes in that buffer.
+The call_data fields have specific meanings according to the operation,
+as follows:
+.IP \(bu 5
+To indicate text deletion, 
+the call_data member specifies a NULL text field.
+The text to be deleted is then the current text in the buffer 
+from position chg_first (starting at zero) on a character length
+of chg_length.
+.IP \(bu 5
+When text is non-NULL,
+it indicates insertion or replacement of text in the buffer.
+.IP
+The chg_length member
+identifies the number of characters in the current preedit buffer
+that are affected by this call.
+A positive chg_length indicates that chg_length number of characters, starting
+at chg_first, must be deleted or must be replaced by text, whose length is
+specified in the
+.PN XIMText
+structure.
+.IP
+A chg_length value of zero indicates that text must be inserted
+right at the position specified by chg_first.
+A value of zero for chg_first specifies the first character in the buffer.
+.IP
+chg_length and chg_first combine to identify the modification required to
+the preedit buffer; beginning at chg_first, replace chg_length number of
+characters with the text in the supplied
+.PN XIMText
+structure. For example, suppose the preedit buffer contains the string "ABCDE".
+.IP
+.DS I
+.ft C
+Text:      A B C D E
+          ^ ^ ^ ^ ^ ^
+CharPos:  0 1 2 3 4 5
+.sp
+.ft P
+.DE
+The CharPos in the diagram shows the location of the character position
+relative to the character.
+.IP
+If the value of chg_first is 1 and the value of chg_length is 3, this
+says to replace 3 characters beginning at character position 1 with the
+string in the
+.PN XIMText
+structure.
+Hence, BCD would be replaced by the value in the structure.
+.IP
+Though chg_length and chg_first are both signed integers they will
+never have a negative value.
+.IP \(bu 5
+The caret member
+identifies the character position before which the cursor should
+be placed \- after modification to the preedit buffer has been completed.
+For example, if caret is zero, the cursor is at
+the beginning of the buffer.  If the caret is one, the cursor is between
+the first and second character.
+.LP
+.IN "XIMText" "" @DEF@"
+.sM
+.Ds
+.TA .5i 1.5i 3i
+typedef struct _XIMText {
+	unsigned short length;
+	XIMFeedback * feedback;
+	Bool encoding_is_wchar; 
+	union {
+		char * multi_byte;
+		wchar_t * wide_char;
+	} string; 
+} XIMText;
+.De
+.LP
+.eM
+The text string passed is actually a structure specifying as follows:
+.IP \(bu 5
+The length member is the text length in characters.
+.IP \(bu 5
+The encoding_is_wchar member is a value that indicates 
+if the text string is encoded in wide character or multibyte format.
+The text string may be passed either as multibyte or as wide character;
+the input method controls in which form data is passed.
+The client's
+callback routine must be able to handle data passed in either form.
+.IP \(bu 5
+The string member is the text string.
+.IP \(bu 5
+The feedback member indicates rendering type for each character in the
+string member.
+If string is NULL (indicating that only highlighting of the existing
+preedit buffer should be updated), feedback points to length highlight
+elements that should be applied to the existing preedit buffer, beginning
+at chg_first.
+.LP
+The feedback member expresses the types of rendering feedback
+the callback should apply when drawing text.
+Rendering of the text to be drawn is specified either in generic ways
+(for example, primary, secondary) or in specific ways (reverse, underline).
+When generic indications are given,
+the client is free to choose the rendering style.
+It is necessary, however, that primary and secondary be mapped 
+to two distinct rendering styles.
+.LP
+If an input method wants to control display of the preedit string, an 
+input method can indicate the visibility hints using feedbacks in
+a specific way.
+The 
+.PN XIMVisibleToForward ,
+.PN XIMVisibleToBackward ,
+and
+.PN XIMVisibleCenter
+masks are exclusively used for these visibility hints.
+The 
+.PN XIMVisibleToForward
+mask
+indicates that the preedit text is preferably displayed in the
+primary draw direction from the
+caret position in the preedit area forward.
+The 
+.PN XIMVisibleToBackward
+mask
+indicates that the preedit text is preferably displayed from
+the caret position in the preedit area backward, relative to the primary
+draw direction.
+The 
+.PN XIMVisibleCenter
+mask
+indicates that the preedit text is preferably displayed with
+the caret position in the preedit area centered.
+.LP
+The insertion point of the preedit string could exist outside of
+the visible area when visibility hints are used.
+Only one of the 
+masks
+is valid for the entire preedit string, and only one character
+can hold one of these feedbacks for a given input context at one time.
+This feedback may be OR'ed together with another highlight (such as
+.PN XIMReverse ).
+Only the most recently set feedback is valid, and any previous
+feedback is automatically canceled.  This is a hint to the client, and
+the client is free to choose how to display the preedit string.
+.LP
+The feedback member also specifies how rendering of the text argument
+should be performed.
+If the feedback is NULL,
+the callback should apply the same feedback as is used for the surrounding
+characters in the preedit buffer; if chg_first is at a highlight boundary,
+the client can choose which of the two highlights to use.
+If feedback is not NULL, feedback specifies an array defining the
+rendering for each
+character of the string, and the length of the array is thus length.
+.LP
+If an input method wants to indicate that it is only updating the feedback of
+the preedit text without changing the content of it, 
+the
+.PN XIMText
+structure will contain a NULL value for the string field,
+the number of characters affected (relative to chg_first)
+will be in the length field,
+and the feedback field will point to an array of 
+.PN XIMFeedback .
+.LP
+Each element in the feedback array is a bitmask represented by a value of type
+.PN XIMFeedback .
+The valid mask names are as follows:
+.LP
+.IN "XIMReverse" "" "@DEF@"
+.IN "XIMUnderline" "" "@DEF@"
+.IN "XIMHighlight" "" "@DEF@"
+.IN "XIMPrimary" "" "@DEF@"
+.IN "XIMSecondary" "" "@DEF@"
+.IN "XIMTertiary" "" "@DEF@"
+.IN "XIMVisibleToForward" "" "@DEF@"
+.IN "XIMVisibleToBackward" "" "@DEF@"
+.IN "XIMVisibleCenter" "" "@DEF@"
+.sM
+.LP
+.Ds 0
+typedef unsigned long XIMFeedback;
+.De
+.TS
+lw(.5i) lw(2i) lw(2i).
+T{
+#define
+T}	T{
+.PN XIMReverse
+T}	T{
+1L
+T}
+T{
+#define
+T}	T{
+.PN XIMUnderline
+T}	T{
+(1L<<1) 
+T}
+T{
+#define
+T}	T{
+.PN XIMHighlight
+T}	T{
+(1L<<2)
+T}
+T{
+#define
+T}	T{
+.PN XIMPrimary
+T}	T{
+(1L<<5)\(dg
+T}
+T{
+#define
+T}	T{
+.PN XIMSecondary
+T}	T{
+(1L<<6)\(dg
+T}
+T{
+#define
+T}	T{
+.PN XIMTertiary
+T}	T{
+(1L<<7)\(dg
+T}
+T{
+#define
+T}	T{
+.PN XIMVisibleToForward
+T}	T{
+(1L<<8)
+T}
+T{
+#define
+T}	T{
+.PN XIMVisibleToBackward
+T}	T{
+(1L<<9)
+T}
+T{
+#define
+T}	T{
+.PN XIMVisibleCenter
+T}	T{
+(1L<<10)
+T}
+.TE
+.LP
+.eM
+.LP
+Characters drawn with the
+.PN XIMReverse
+highlight should be drawn by swapping the foreground and background colors
+used to draw normal, unhighlighted characters.
+Characters drawn with the
+.PN XIMUnderline
+highlight should be underlined.
+Characters drawn with the
+.PN XIMHighlight ,
+.PN XIMPrimary ,
+.PN XIMSecondary ,
+and
+.PN XIMTertiary
+highlights should be drawn in some unique manner that must be different
+from
+.PN XIMReverse
+and
+.PN XIMUnderline .
+.FS \(dg
+The values for
+.PN XIMPrimary ,
+.PN XIMSecondary ,
+and
+.PN XIMTertiary
+were incorrectly defined in the R5 specification.
+The X Consortium's X11R5
+implementation correctly implemented the values for these highlights.
+The value of these highlights has been corrected in this specification
+to agree with the values in the Consortium's X11R5 and X11R6 implementations.
+.FE
+.NH 4
+Preedit Caret Callback
+.XS
+\*(SN Preedit Caret Callback
+.XE
+.LP
+An input method may have its own navigation keys to allow the user
+to move the text insertion point in the preedit area 
+(for example, to move backward or forward). 
+Consequently, input method needs to indicate to the client that it
+should move the text insertion point.
+It then calls the PreeditCaretCallback.
+.IN "PreeditCaretCallback" "" "@DEF@"
+.sM
+.FD 0
+void PreeditCaretCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
+.br
+      XIC \fIic\fP\^;
+.br
+      XPointer \fIclient_data\fP\^;
+.br
+      XIMPreeditCaretCallbackStruct *\fIcall_data\fP\^;
+.FN
+.IP \fIic\fP 1i
+Specifies the input context.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data.
+.IP \fIcall_data\fP 1i
+Specifies the preedit caret information.
+.LP
+.eM
+The input method will trigger PreeditCaretCallback
+to move the text insertion point during preedit.
+The call_data argument contains a pointer to an 
+.PN XIMPreeditCaretCallbackStruct
+structure,
+which indicates where the caret should be moved.
+The callback must move the insertion point to its new location
+and return, in field position, the new offset value from the initial position.  
+.LP
+The
+.PN XIMPreeditCaretCallbackStruct
+structure is defined as follows:
+.IN "XIMPreeditCaretCallbackStruct" "" "@DEF@"
+.LP
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct _XIMPreeditCaretCallbackStruct {
+	int position;	/* Caret offset within preedit string */
+	XIMCaretDirection direction;	/* Caret moves direction */
+	XIMCaretStyle style;	/* Feedback of the caret */
+} XIMPreeditCaretCallbackStruct;
+.De
+.LP
+.eM
+The
+.PN XIMCaretStyle
+structure is defined as follows:
+.LP
+.IN "XIMCaretStyle" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef enum {
+	XIMIsInvisible,	/* Disable caret feedback */ 
+	XIMIsPrimary,	/* UI defined caret feedback */
+	XIMIsSecondary,	/* UI defined caret feedback */
+} XIMCaretStyle;
+.De
+.LP
+.eM
+The
+.PN XIMCaretDirection
+structure is defined as follows:
+.IN "XIMCaretDirection" "" "@DEF@"
+.LP
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef enum {
+	XIMForwardChar, XIMBackwardChar,
+	XIMForwardWord, XIMBackwardWord,
+	XIMCaretUp, XIMCaretDown,
+	XIMNextLine, XIMPreviousLine,
+	XIMLineStart, XIMLineEnd, 
+	XIMAbsolutePosition,
+	XIMDontChange,
+ } XIMCaretDirection;
+.De
+.LP
+.eM
+These values are defined as follows:
+.IN "XIMForwardChar" "" "@DEF@"
+.IN "XIMBackwardChar" "" "@DEF@"
+.IN "XIMForwardWord" "" "@DEF@"
+.IN "XIMBackwardWord" "" "@DEF@"
+.IN "XIMCaretUp" "" "@DEF@"
+.IN "XIMCaretDown" "" "@DEF@"
+.TS
+lw(1.5i) lw(4.25i).
+T{
+.PN XIMForwardChar
+T}	T{
+Move the caret forward one character position.
+T}
+T{
+.PN XIMBackwardChar
+T}	T{
+Move the caret backward one character position.
+T}
+T{
+.PN XIMForwardWord
+T}	T{
+Move the caret forward one word.
+T}
+T{
+.PN XIMBackwardWord
+T}	T{
+Move the caret backward one word.
+T}
+T{
+.PN XIMCaretUp
+T}	T{
+Move the caret up one line keeping the current horizontal offset.
+T}
+T{
+.PN XIMCaretDown
+T}	T{
+Move the caret down one line keeping the current horizontal offset.
+T}
+T{
+.PN XIMPreviousLine
+T}	T{
+Move the caret to the beginning of the previous line.
+T}
+T{
+.PN XIMNextLine
+T}	T{
+Move the caret to the beginning of the next line.
+T}
+T{
+.PN XIMLineStart
+T}	T{
+Move the caret to the beginning of the current display line 
+that contains the caret.
+T}
+T{
+.PN XIMLineEnd
+T}	T{
+Move the caret to the end of the current display line 
+that contains the caret.
+T}
+T{
+.PN XIMAbsolutePosition
+T}	T{
+The callback must move to the location specified by the position field
+of the callback data, indicated in characters, starting from the beginning
+of the preedit text.
+Hence, a value of zero means move back to the beginning of the preedit text.
+T}
+T{
+.PN XIMDontChange
+T}	T{
+The caret position does not change.
+T}
+.TE
+.IN "XIMNextLine" "" "@DEF@"
+.IN "XIMPreviousLine" "" "@DEF@"
+.IN "XIMLineStart" "" "@DEF@"
+.IN "XIMLineEnd" "" "@DEF@"
+.IN "XIMAbsolutePosition" "" "@DEF@"
+.IN "XIMDontChange" "" "@DEF@"
+.NH 4
+Status Callbacks
+.XS
+\*(SN Status Callbacks
+.XE
+.LP
+An input method may communicate changes in the status of an input context
+(for example, created, destroyed, or focus changes) with three status
+callbacks:  StatusStartCallback, StatusDoneCallback, and StatusDrawCallback.
+.LP
+.sp
+When the input context is created or gains focus, 
+the input method calls the StatusStartCallback callback.
+.IN "StatusStartCallback" "" "@DEF@"
+.sM
+.FD 0
+void StatusStartCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
+.br
+      XIC \fIic\fP\^;
+.br
+      XPointer \fIclient_data\fP\^;
+.br
+      XPointer \fIcall_data\fP\^;
+.FN
+.IP \fIic\fP 1i
+Specifies the input context.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data.
+.IP \fIcall_data\fP 1i
+Not used for this callback and always passed as NULL.
+.LP
+.eM
+The callback should initialize appropriate data for displaying status
+and for responding to StatusDrawCallback calls.  
+Once StatusStartCallback is called,
+it will not be called again before StatusDoneCallback has been called.
+.LP
+.sp
+When an input context
+is destroyed or when it loses focus, the input method calls StatusDoneCallback.
+.IN "StatusDoneCallback" "" "@DEF@"
+.sM
+.FD 0
+void StatusDoneCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
+.br
+      XIC \fIic\fP\^;
+.br
+      XPointer \fIclient_data\fP\^;
+.br
+      XPointer \fIcall_data\fP\^;
+.FN
+.IP \fIic\fP 1i
+Specifies the input context.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data.
+.IP \fIcall_data\fP 1i
+Not used for this callback and always passed as NULL.
+.LP
+.eM
+The callback may release any data allocated on 
+.PN StatusStart .
+.LP
+.sp
+When an input context status has to be updated, the input method calls
+StatusDrawCallback.
+.IN "StatusDrawCallback" "" "@DEF@"
+.sM
+.FD 0
+void StatusDrawCallback\^(\^\fIic\fP\^, \fIclient_data\fP\^, \fIcall_data\fP\^)
+.br
+      XIC \fIic\fP\^;
+.br
+      XPointer \fIclient_data\fP\^;
+.br
+      XIMStatusDrawCallbackStruct *\fIcall_data\fP\^;
+.FN
+.IP \fIic\fP 1i
+Specifies the input context.
+.IP \fIclient_data\fP 1i
+Specifies the additional client data.
+.IP \fIcall_data\fP 1i
+Specifies the status drawing information.
+.LP
+.eM
+The callback should update the status area by either drawing a string
+or imaging a bitmap in the status area.
+.LP
+The
+.PN XIMStatusDataType
+and
+.PN XIMStatusDrawCallbackStruct
+structures are defined as follows:
+.IN "XIMStatusDataType" "" "@DEF@"
+.IN "XIMStatusDrawCallbackStruct" "" "@DEF@"
+.LP
+.sM
+.Ds 0
+.TA .5i 1i 3i
+.ta .5i 1i 3i
+typedef enum {
+	XIMTextType,
+	XIMBitmapType,
+} XIMStatusDataType;
+
+typedef struct _XIMStatusDrawCallbackStruct {
+	XIMStatusDataType type;
+	union {
+		XIMText *text;
+		Pixmap  bitmap;
+	} data;
+} XIMStatusDrawCallbackStruct;
+.De
+.LP
+.eM
+.LP
+The feedback styles
+.PN XIMVisibleToForward ,
+.PN XIMVisibleToBackward ,
+and
+.PN XIMVisibleToCenter
+are not relevant and will not appear in the
+.PN XIMFeedback
+element of the
+.PN XIMText
+structure.
+.LP
+.NH 3
+Event Filtering
+.XS
+\*(SN Event Filtering
+.XE
+.LP
+Xlib provides the ability for an input method
+to register a filter internal to Xlib.
+This filter is called by a client (or toolkit) by calling
+.PN XFilterEvent
+after calling 
+.PN XNextEvent .
+Any client that uses the 
+.PN XIM
+interface should call
+.PN XFilterEvent
+to allow input methods to process their events without knowledge
+of the client's dispatching mechanism.
+A client's user interface policy may determine the priority
+of event filters with respect to other event-handling mechanisms
+(for example, modal grabs).
+.LP
+Clients may not know how many filters there are, if any,
+and what they do.
+They may only know if an event has been filtered on return of 
+.PN XFilterEvent .
+Clients should discard filtered events.
+.sp
+.LP
+To filter an event, use
+.PN XFilterEvent .
+.IN "XFilterEvent" "" "@DEF@"
+.sM
+.FD 0
+Bool XFilterEvent\^(\^\fIevent\fP\^, \fIw\fP\^)
+.br
+      XEvent *\fIevent\fP\^;
+.br
+      Window \fIw\fP\^;
+.FN
+.ds Ev event to filter
+.IP \fIevent\fP 1i
+Specifies the \*(Ev.
+.ds Wi for which the filter is to be applied
+.IP \fIw\fP 1i
+Specifies the window \*(Wi.
+.LP
+.eM
+If the window argument is
+.PN None ,
+.PN XFilterEvent 
+applies the filter to the window specified in the
+.PN XEvent
+structure.
+The window argument is provided so that layers above Xlib
+that do event redirection can indicate to which window an event
+has been redirected.
+.LP
+If
+.PN XFilterEvent
+returns
+.PN True ,
+then some input method has filtered the event,
+and the client should discard the event.
+If
+.PN XFilterEvent
+returns
+.PN False ,
+then the client should continue processing the event.
+.LP
+If a grab has occurred in the client and
+.PN XFilterEvent
+returns
+.PN True ,
+the client should ungrab the keyboard.
+.NH 3
+Getting Keyboard Input
+.XS
+\*(SN Getting Keyboard Input
+.XE
+.LP
+To get composed input from an input method,
+use
+.PN XmbLookupString
+or
+.PN XwcLookupString .
+.IN "XmbLookupString" "" "@DEF@"
+.IN "XwcLookupString" "" "@DEF@"
+.sM
+.FD 0
+int XmbLookupString\^(\^\fIic\fP\^, \fIevent\fP\^, \fIbuffer_return\fP\^, \fIbytes_buffer\fP\^, \fIkeysym_return\fP\^, \fIstatus_return\fP\^)
+.br
+      XIC \fIic\fP\^;
+.br
+      XKeyPressedEvent *\fIevent\fP;
+.br
+      char *\fIbuffer_return\fP\^;
+.br
+      int \fIbytes_buffer\fP\^;
+.br
+      KeySym *\fIkeysym_return\fP\^;
+.br
+      Status *\fIstatus_return\fP\^;
+.FN
+.FD 0
+int XwcLookupString\^(\^\fIic\fP\^, \fIevent\fP\^, \fIbuffer_return\fP\^, \fIbytes_buffer\fP\^, \fIkeysym_return\fP\^, \fIstatus_return\fP\^)
+.br
+      XIC \fIic\fP\^;
+.br
+      XKeyPressedEvent *\fIevent\fP\^;
+.br
+      wchar_t *\fIbuffer_return\fP\^;
+.br
+      int \fIwchars_buffer\fP\^;
+.br
+      KeySym *\fIkeysym_return\fP\^;
+.br
+      Status *\fIstatus_return\fP\^;
+.FN
+.IP \fIic\fP 1i
+Specifies the input context.
+.ds Ev key event to be used
+.IP \fIevent\fP 1i
+Specifies the \*(Ev.
+.IP \fIbuffer_return\fP 1i
+Returns a multibyte string or wide character string (if any)
+from the input method.
+.IP \fIbytes_buffer\fP 1i
+.br
+.ns
+.IP \fIwchars_buffer\fP 1i
+Specifies space available in the return buffer.
+.IP \fIkeysym_return\fP 1i
+Returns the KeySym computed from the event if this argument is not NULL.
+.IP \fIstatus_return\fP 1i
+Returns a value indicating what kind of data is returned.
+.LP
+.eM
+The
+.PN XmbLookupString
+and
+.PN XwcLookupString
+functions return the string from the input method specified
+in the buffer_return argument.
+If no string is returned,
+the buffer_return argument is unchanged.
+.LP
+The KeySym into which the KeyCode from the event was mapped is returned
+in the keysym_return argument if it is non-NULL and the status_return
+argument indicates that a KeySym was returned.
+If both a string and a KeySym are returned,
+the KeySym value does not necessarily correspond to the string returned.
+.LP
+.PN XmbLookupString
+returns the length of the string in bytes, and
+.PN XwcLookupString
+returns the length of the string in characters.
+Both
+.PN XmbLookupString
+and
+.PN XwcLookupString
+return text in the encoding of the locale bound to the input method
+of the specified input context.
+.LP
+Each string returned by
+.PN XmbLookupString
+and
+.PN XwcLookupString
+begins in the initial state of the encoding of the locale
+(if the encoding of the locale is state-dependent).
+.NT
+To insure proper input processing,
+it is essential that the client pass only 
+.PN KeyPress
+events to
+.PN XmbLookupString
+and
+.PN XwcLookupString .
+Their behavior when a client passes a 
+.PN KeyRelease
+event is undefined.
+.NE
+.LP
+Clients should check the status_return argument before
+using the other returned values.
+These two functions both return a value to status_return 
+that indicates what has been returned in the other arguments.
+The possible values returned are:
+.TS
+lw(1.5i) lw(4.3i).
+T{
+.PN XBufferOverflow
+T}	T{
+The input string to be returned is too large for the supplied buffer_return.
+The required size
+.Pn ( XmbLookupString
+in bytes;
+.PN XwcLookupString
+in characters) is returned as the value of the function,
+and the contents of buffer_return and keysym_return are not modified.
+The client should recall the function with the same event
+and a buffer of adequate size to obtain the string.
+T}
+T{
+.PN XLookupNone
+T}	T{
+No consistent input has been composed so far.
+The contents of buffer_return and keysym_return are not modified, 
+and the function returns zero.
+T}
+T{
+.PN XLookupChars
+T}	T{
+Some input characters have been composed.
+They are placed in the buffer_return argument,
+and the string length is returned as the value of the function.
+The string is encoded in the locale bound to the input context.
+The content of the keysym_return argument is not modified.
+T}
+T{
+.PN XLookupKeySym
+T}	T{
+A KeySym has been returned instead of a string
+and is returned in keysym_return.
+The content of the buffer_return argument is not modified,
+and the function returns zero.
+T}
+T{
+.PN XLookupBoth
+T}	T{
+Both a KeySym and a string are returned;
+.PN XLookupChars
+and
+.PN XLookupKeySym
+occur simultaneously.
+T}
+.TE
+.LP
+It does not make any difference if the input context passed as an argument to
+.PN XmbLookupString
+and
+.PN XwcLookupString
+is the one currently in possession of the focus or not.
+Input may have been composed within an input context before it lost the focus,
+and that input may be returned on subsequent calls to
+.PN XmbLookupString
+or
+.PN XwcLookupString
+even though it does not have any more keyboard focus.
+.NH 3
+Input Method Conventions
+.XS
+\*(SN Input Method Conventions
+.XE
+.LP
+The input method architecture is transparent to the client.
+However, clients should respect a number of conventions in order
+to work properly.
+Clients must also be aware of possible effects of synchronization
+between input method and library in the case of a remote input server.
+.NH 4 
+Client Conventions
+.XS
+\*(SN Client Conventions
+.XE
+.LP
+A well-behaved client (or toolkit) should first query the input method style.
+If the client cannot satisfy the requirements of the supported styles
+(in terms of geometry management or callbacks),
+it should negotiate with the user continuation of the program
+or raise an exception or error of some sort.
+.NH 4 
+Synchronization Conventions
+.XS
+\*(SN Synchronization Conventions
+.XE
+.LP
+A 
+.PN KeyPress
+event with a KeyCode of zero is used exclusively as a
+signal that an input method has composed input that can be returned by
+.PN XmbLookupString
+or
+.PN XwcLookupString .
+No other use is made of a 
+.PN KeyPress
+event with KeyCode of zero.
+.LP
+Such an event may be generated by either a front-end
+or a back-end input method in an implementation-dependent manner.
+Some possible ways to generate this event include:
+.IP \(bu 5
+A synthetic event sent by an input method server
+.IP \(bu 5
+An artificial event created by a input method filter and pushed
+onto a client's event queue
+.IP \(bu 5
+A 
+.PN KeyPress
+event whose KeyCode value is modified by an input method filter
+.LP
+When callback support is specified by the client,
+input methods will not take action unless they explicitly
+called back the client and obtained no response
+(the callback is not specified or returned invalid data).
+.NH 2
+String Constants
+.XS
+\*(SN String Constants
+.XE
+.LP
+The following symbols for string constants are defined in
+.hN X11/Xlib.h .
+Although they are shown here with particular macro definitions,
+they may be implemented as macros, as global symbols, or as a
+mixture of the two.  The string pointer value itself
+is not significant; clients must not assume that inequality of two
+values implies inequality of the actual string data.
+.IN "XNVaNestedList" "" "@DEF@"
+.IN "XNSeparatorofNestedList "" "@DEF@"
+.IN "XNQueryInputStyle" "" "@DEF@"
+.IN "XNClientWindow" "" "@DEF@"
+.IN "XNInputStyle" "" "@DEF@"
+.IN "XNFocusWindow" "" "@DEF@"
+.IN "XNResourceName" "" "@DEF@"
+.IN "XNResourceClass" "" "@DEF@"
+.IN "XNGeometryCallback" "" "@DEF@"
+.IN "XNDestroyCallback" "" "@DEF@"
+.IN "XNFilterEvents" "" "@DEF@"
+.IN "XNPreeditStartCallback" "" "@DEF@"
+.IN "XNPreeditDoneCallback" "" "@DEF@"
+.IN "XNPreeditDrawCallback" "" "@DEF@"
+.IN "XNPreeditCaretCallback" "" "@DEF@"
+.IN "XNPreeditStateNotifyCallback" "" "@DEF@"
+.IN "XNPreeditAttributes" "" "@DEF@"
+.IN "XNStatusStartCallback" "" "@DEF@"
+.IN "XNStatusDoneCallback" "" "@DEF@"
+.IN "XNStatusDrawCallback" "" "@DEF@"
+.IN "XNStatusAttributes" "" "@DEF@"
+.IN "XNArea" "" "@DEF@"
+.IN "XNAreaNeeded" "" "@DEF@"
+.IN "XNSpotLocation" "" "@DEF@"
+.IN "XNColormap" "" "@DEF@"
+.IN "XNStdColormap" "" "@DEF@"
+.IN "XNForeground" "" "@DEF@"
+.IN "XNBackground" "" "@DEF@"
+.IN "XNBackgroundPixmap" "" "@DEF@"
+.IN "XNFontSet" "" "@DEF@"
+.IN "XNLineSpace" "" "@DEF@"
+.IN "XNCursor" "" "@DEF@"
+.TS
+lw(.5i) lw(2.75i) lw(2.5i).
+T{
+#define
+T}	T{
+.PN XNVaNestedList
+T}	T{
+"XNVaNestedList"
+T}
+T{
+#define
+T}	T{
+.PN XNSeparatorofNestedList
+T}	T{
+"separatorofNestedList"
+T}
+T{
+#define
+T}	T{
+.PN XNQueryInputStyle
+T}	T{
+"queryInputStyle"
+T}
+T{
+#define
+T}	T{
+.PN XNClientWindow
+T}	T{
+"clientWindow"
+T}
+T{
+#define
+T}	T{
+.PN XNInputStyle
+T}	T{
+"inputStyle"
+T}
+T{
+#define
+T}	T{
+.PN XNFocusWindow
+T}	T{
+"focusWindow"
+T}
+T{
+#define
+T}	T{
+.PN XNResourceName
+T}	T{
+"resourceName"
+T}
+T{
+#define
+T}	T{
+.PN XNResourceClass
+T}	T{
+"resourceClass"
+T}
+T{
+#define
+T}	T{
+.PN XNGeometryCallback
+T}	T{
+"geometryCallback"
+T}
+T{
+#define
+T}	T{
+.PN XNDestroyCallback
+T}	T{
+"destroyCallback"
+T}
+T{
+#define
+T}	T{
+.PN XNFilterEvents
+T}	T{
+"filterEvents"
+T}
+T{
+#define
+T}	T{
+.PN XNPreeditStartCallback
+T}	T{
+"preeditStartCallback"
+T}
+T{
+#define
+T}	T{
+.PN XNPreeditDoneCallback
+T}	T{
+"preeditDoneCallback"
+T}
+T{
+#define
+T}	T{
+.PN XNPreeditDrawCallback
+T}	T{
+"preeditDrawCallback"
+T}
+T{
+#define
+T}	T{
+.PN XNPreeditCaretCallback
+T}	T{
+"preeditCaretCallback"
+T}
+T{
+#define
+T}	T{
+.PN XNPreeditStateNotifyCallback
+T}	T{
+"preeditStateNotifyCallback"
+T}
+T{
+#define
+T}	T{
+.PN XNPreeditAttributes
+T}	T{
+"preeditAttributes"
+T}
+.TE
+.sp -1
+.TS
+lw(.5i) lw(2.75i) lw(2.5i).
+T{
+#define
+T}	T{
+.PN XNStatusStartCallback
+T}	T{
+"statusStartCallback"
+T}
+T{
+#define
+T}	T{
+.PN XNStatusDoneCallback
+T}	T{
+"statusDoneCallback"
+T}
+T{
+#define
+T}	T{
+.PN XNStatusDrawCallback
+T}	T{
+"statusDrawCallback"
+T}
+T{
+#define
+T}	T{
+.PN XNStatusAttributes
+T}	T{
+"statusAttributes"
+T}
+T{
+#define
+T}	T{
+.PN XNArea
+T}	T{
+"area"
+T}
+T{
+#define
+T}	T{
+.PN XNAreaNeeded
+T}	T{
+"areaNeeded"
+T}
+T{
+#define
+T}	T{
+.PN XNSpotLocation
+T}	T{
+"spotLocation"
+T}
+T{
+#define
+T}	T{
+.PN XNColormap
+T}	T{
+"colorMap"
+T}
+T{
+#define
+T}	T{
+.PN XNStdColormap
+T}	T{
+"stdColorMap"
+T}
+T{
+#define
+T}	T{
+.PN XNForeground
+T}	T{
+"foreground"
+T}
+T{
+#define
+T}	T{
+.PN XNBackground
+T}	T{
+"background"
+T}
+T{
+#define
+T}	T{
+.PN XNBackgroundPixmap
+T}	T{
+"backgroundPixmap"
+T}
+T{
+#define
+T}	T{
+.PN XNFontSet
+T}	T{
+"fontSet"
+T}
+T{
+#define
+T}	T{
+.PN XNLineSpace
+T}	T{
+"lineSpace"
+T}
+T{
+#define
+T}	T{
+.PN XNCursor
+T}	T{
+"cursor"
+T}
+.TE
+.sp -1
+.TS
+lw(.5i) lw(2.75i) lw(2.5i).
+T{
+#define
+T}	T{
+.PN XNQueryIMValuesList
+T}	T{
+"queryIMValuesList"
+T}	
+T{
+#define
+T}	T{
+.PN XNQueryICValuesList
+T}	T{
+"queryICValuesList"
+T}	
+T{
+#define
+T}	T{
+.PN XNStringConversionCallback
+T}	T{
+"stringConversionCallback"
+T}	
+T{
+#define
+T}	T{
+.PN XNStringConversion
+T}	T{
+"stringConversion"
+T}	
+T{
+#define
+T}	T{
+.PN XNResetState
+T}	T{
+"resetState"
+T}	
+T{
+#define
+T}	T{
+.PN XNHotKey
+T}	T{
+"hotkey"
+T}	
+T{
+#define
+T}	T{
+.PN XNHotKeyState
+T}	T{
+"hotkeyState"
+T}	
+T{
+#define
+T}	T{
+.PN XNPreeditState
+T}	T{
+"preeditState"
+T}
+T{
+#define
+T}	T{
+.PN XNVisiblePosition
+T}	T{
+"visiblePosition"
+T}
+T{
+#define
+T}	T{
+.PN XNR6PreeditCallbackBehavior
+T}	T{
+"r6PreeditCallback"
+T}
+.TE
+.sp -1
+.IN "XNQueryIMValuesList" "" "@DEF@"
+.IN "XNQueryICValuesList" "" "@DEF@"
+.IN "XNStringConversionCallback" "" "@DEF@"
+.IN "XNStringConversion" "" "@DEF@"
+.IN "XNResetState" "" "@DEF@"
+.IN "XNHotKey" "" "@DEF@"
+.IN "XNHotKeyState" "" "@DEF@"
+.IN "XNPreeditState" "" "@DEF@"
+.IN "XNVisiblePosition" "" "@DEF@"
+.IN "XNR6PreeditCallbackBehavior" "" "@DEF@"
+.TS
+lw(.5i) lw(2.75i) lw(2.5i).
+T{
+#define
+T}	T{
+.PN XNRequiredCharSet
+T}	T{
+"requiredCharSet"
+T}	
+T{
+#define
+T}	T{
+.PN XNQueryOrientation
+T}	T{
+"queryOrientation"
+T}
+T{
+#define
+T}	T{
+.PN XNDirectionalDependentDrawing
+T}	T{
+"directionalDependentDrawing"
+T}
+T{
+#define
+T}	T{
+.PN XNContextualDrawing
+T}	T{
+"contextualDrawing"
+T}
+T{
+#define
+T}	T{
+.PN XNBaseFontName
+T}	T{
+"baseFontName"
+T}	
+T{
+#define
+T}	T{
+.PN XNMissingCharSet
+T}	T{
+"missingCharSet"
+T}	
+T{
+#define
+T}	T{
+.PN XNDefaultString
+T}	T{
+"defaultString"
+T}	
+T{
+#define
+T}	T{
+.PN XNOrientation
+T}	T{
+"orientation"
+T}	
+T{
+#define
+T}	T{
+.PN XNFontInfo
+T}	T{
+"fontInfo"
+T}	
+T{
+#define
+T}	T{
+.PN XNOMAutomatic
+T}	T{
+"omAutomatic"
+T}
+.TE
+.IN "XNRequiredCharSet" "" "@DEF@"
+.IN "XNQueryOrientation" "" "@DEF@"
+.IN "XNDirectionalDependentDrawing" "" "@DEF@"
+.IN "XNContextualDrawing" "" "@DEF@"
+.IN "XNBaseFontName" "" "@DEF@"
+.IN "XNMissingCharSet" "" "@DEF@"
+.IN "XNDefaultString" "" "@DEF@"
+.IN "XNOrientation" "" "@DEF@"
+.IN "XNFontInfo" "" "@DEF@"
+.IN "XNOMAutomatic" "" "@DEF@"
+.bp
diff --git a/specs/libX11/CH14 b/specs/libX11/CH14
new file mode 100644
index 00000000..34c09da8
--- /dev/null
+++ b/specs/libX11/CH14
@@ -0,0 +1,3590 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 14\fP\s-1
+
+\s+1\fBInter-Client Communication Functions\fP\s-1
+.sp 2
+.nr H1 14
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.na
+.LP
+.XS
+Chapter 14: Inter-Client Communication Functions
+.XE
+The \fIInter-Client Communication Conventions Manual\fP,
+hereafter referred to as the ICCCM, details the
+X Consortium approved conventions that govern inter-client communications.
+These conventions ensure peer-to-peer client cooperation in the use 
+of selections, cut buffers, and shared resources as well as client cooperation
+with window and session managers.
+For further information,
+see the \fIInter-Client Communication Conventions Manual\fP.
+.LP
+Xlib provides a number of standard properties and programming interfaces
+that are ICCCM compliant.
+The predefined atoms for some of these properties are defined in the
+.hN X11/Xatom.h
+header file, where
+to avoid name conflicts with user symbols their
+.PN #define
+name has an XA_ prefix.
+For further information about atoms and properties,
+see section 4.3.
+.LP
+Xlib's selection and cut buffer mechanisms provide the primary programming 
+interfaces by which peer client applications communicate with each other 
+(see sections 4.5 and 16.6).
+The functions discussed in this chapter provide 
+the primary programming interfaces by which client applications communicate 
+with their window and session managers as well as share standard colormaps.
+.LP
+The standard properties that are of special interest for communicating 
+with window and session managers are:
+.IN "Atom" "predefined"
+.TS H
+lw(2i) lw(1.1i) lw(.4i) lw(2.25i)
+lw(2i) lw(1.1i) cw(.4i) lw(2.25i).
+_
+.sp 6p
+.B
+Name	Type	Format	Description
+.sp 6p
+_
+.TH
+.R
+T{
+\s-1WM_CLASS\s+1
+T}	T{
+\s-1STRING\s+1
+T}	T{
+8
+T}	T{
+Set by application programs to allow window and session
+managers to obtain the application's resources from the resource database.
+T}
+.sp 6p
+T{
+\s-1WM_CLIENT_MACHINE\s+1
+T}	T{
+\s-1TEXT\s+1
+T}	T{
+T}	T{
+The string name of the machine on which the client application is running.
+T}
+.sp 6p
+T{
+\s-1WM_COLORMAP_WINDOWS\s+1
+T}	T{
+\s-1WINDOW\s+1
+T}	T{
+32
+T}	T{
+The list of window IDs that may need a different colormap
+from that of their top-level window.
+T}
+.sp 6p
+T{
+\s-1WM_COMMAND\s+1
+T}	T{
+\s-1TEXT\s+1
+T}	T{
+T}	T{
+The command and arguments, null-separated, used to invoke the
+application.
+T}
+.sp 6p
+T{
+\s-1WM_HINTS\s+1
+T}	T{
+\s-1WM_HINTS\s+1
+T}	T{
+32
+T}	T{
+Additional hints set by the client for use by the window manager.
+The C type of this property is 
+.PN XWMHints .
+T}
+.sp 6p
+T{
+\s-1WM_ICON_NAME\s+1
+T}	T{
+\s-1TEXT\s+1
+T}	T{
+T}	T{
+The name to be used in an icon.
+T}
+.sp 6p
+T{
+\s-1WM_ICON_SIZE\s+1
+T}	T{
+\s-1WM_ICON_SIZE\s+1
+T}	T{
+32
+T}	T{
+The window manager may set this property on the root window to
+specify the icon sizes it supports.
+The C type of this property is 
+.PN XIconSize .
+T}
+.sp 6p
+T{
+\s-1WM_NAME\s+1
+T}	T{
+\s-1TEXT\s+1
+T}	T{
+T}	T{
+The name of the application.
+T}
+.sp 6p
+T{
+\s-1WM_NORMAL_HINTS\s+1
+T}	T{
+\s-1WM_SIZE_HINTS\s+1
+T}	T{
+32
+T}	T{
+Size hints for a window in its normal state.
+The C type of this property is
+.PN XSizeHints .
+T}
+.sp 6p
+T{
+\s-1WM_PROTOCOLS\s+1
+T}	T{
+\s-1ATOM\s+1
+T}	T{
+32
+T}	T{
+List of atoms that identify the communications protocols between the
+client and window manager in which the client is willing to participate.
+T}
+.sp 6p
+T{
+\s-1WM_STATE\s+1
+T}	T{
+\s-1WM_STATE\s+1
+T}	T{
+32
+T}	T{
+Intended for communication between window and session managers only.
+T}
+.sp 6p
+T{
+\s-1WM_TRANSIENT_FOR\s+1
+T}	T{
+\s-1WINDOW\s+1
+T}	T{
+32
+T}	T{
+Set by application programs to indicate to the window manager that a transient
+top-level window, such as a dialog box.
+T}
+.sp 6p
+_
+.TE
+.LP
+The remainder of this chapter discusses:
+.IP \(bu 5
+Client to window manager communication
+.IP \(bu 5
+Client to session manager communication
+.IP \(bu 5
+Standard colormaps
+.NH 2
+Client to Window Manager Communication
+.XS
+\*(SN Client to Window Manager Communication
+.XE
+.LP
+This section discusses how to:
+.IP \(bu 5
+Manipulate top-level windows
+.IP \(bu 5
+Convert string lists
+.IP \(bu 5
+Set and read text properties
+.IP \(bu 5
+Set and read the WM_NAME property
+.IP \(bu 5
+Set and read the WM_ICON_NAME property
+.IP \(bu 5
+Set and read the WM_HINTS property
+.IP \(bu 5
+Set and read the WM_NORMAL_HINTS property
+.IP \(bu 5
+Set and read the WM_CLASS property
+.IP \(bu 5
+Set and read the WM_TRANSIENT_FOR property
+.IP \(bu 5
+Set and read the WM_PROTOCOLS property
+.IP \(bu 5
+Set and read the WM_COLORMAP_WINDOWS property
+.IP \(bu 5
+Set and read the WM_ICON_SIZE property
+.IP \(bu 5
+Use window manager convenience functions
+.NH 3
+Manipulating Top-Level Windows
+.XS
+\*(SN Manipulating Top-Level Windows
+.XE
+.LP
+Xlib provides functions that you can use to change the visibility or size
+of top-level windows (that is, those that were created as children 
+of the root window).
+Note that the subwindows that you create are ignored by window managers.
+Therefore,
+you should use the basic window functions described in chapter 3
+to manipulate your application's subwindows.
+.LP
+To request that a top-level window be iconified, use
+.PN XIconifyWindow .
+.IN "XIconifyWindow" "" "@DEF@"
+.sM
+.FD 0
+Status XIconifyWindow\^(\^\fIdisplay\fP, \fIw\fP, \fIscreen_number\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP;
+.br
+      int \fIscreen_number\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.LP
+.eM
+The 
+.PN XIconifyWindow 
+function sends a WM_CHANGE_STATE 
+.PN ClientMessage 
+event with a format of 32 and a first data element of 
+.PN IconicState 
+(as described in section 4.1.4 of the 
+\fIInter-Client Communication Conventions Manual\fP)
+and a window of w
+to the root window of the specified screen
+with an event mask set to
+.PN SubstructureNotifyMask |
+.PN SubstructureRedirectMask .
+Window managers may elect to receive this message and
+if the window is in its normal state, 
+may treat it as a request to change the window's state from normal to iconic.
+If the WM_CHANGE_STATE property cannot be interned, 
+.PN XIconifyWindow
+does not send a message and returns a zero status.
+It returns a nonzero status if the client message is sent successfully;
+otherwise, it returns a zero status.
+.sp
+.LP
+To request that a top-level window be withdrawn, use
+.PN XWithdrawWindow .
+.IN "XWithdrawWindow" "" "@DEF@"
+.sM
+.FD 0
+Status XWithdrawWindow\^(\^\fIdisplay\fP, \fIw\fP, \fIscreen_number\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      int \fIscreen_number\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.LP
+.eM
+The 
+.PN XWithdrawWindow 
+function unmaps the specified window 
+and sends a synthetic 
+.PN UnmapNotify 
+event to the root window of the specified screen.
+Window managers may elect to receive this message 
+and may treat it as a request to change the window's state to withdrawn.
+When a window is in the withdrawn state, 
+neither its normal nor its iconic representations is visible.
+It returns a nonzero status if the 
+.PN UnmapNotify 
+event is successfully sent; 
+otherwise, it returns a zero status.
+.LP
+.PN XWithdrawWindow
+can generate a
+.PN BadWindow
+error.
+.sp
+.LP
+To request that a top-level window be reconfigured, use
+.PN XReconfigureWMWindow .
+.IN "XReconfigureWMWindow" "" "@DEF@"
+.sM
+.FD 0
+Status XReconfigureWMWindow\^(\^\fIdisplay\fP, \fIw\fP, \fIscreen_number\fP, \
+\fIvalue_mask\fP, \fIvalues\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      int \fIscreen_number\fP\^;
+.br
+      unsigned int \fIvalue_mask\fP\^;
+.br
+      XWindowChanges *\fIvalues\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIscreen_number\fP 1i
+Specifies the appropriate screen number on the host server.
+.IP \fIvalue_mask\fP 1i
+Specifies which values are to be set using information in
+the values structure.
+This mask is the bitwise inclusive OR of the valid configure window values bits.
+.IP \fIvalues\fP 1i
+Specifies the 
+.PN XWindowChanges 
+structure.
+.LP
+.eM
+The 
+.PN XReconfigureWMWindow 
+function issues a 
+.PN ConfigureWindow 
+request on the specified top-level window.
+If the stacking mode is changed and the request fails with a 
+.PN BadMatch 
+error, 
+the error is trapped by Xlib and a synthetic 
+.PN ConfigureRequestEvent 
+containing the same configuration parameters is sent to the root 
+of the specified window.
+Window managers may elect to receive this event 
+and treat it as a request to reconfigure the indicated window.
+It returns a nonzero status if the request or event is successfully sent;
+otherwise, it returns a zero status.
+.LP
+.PN XReconfigureWMWindow 
+can generate
+.PN BadValue 
+and 
+.PN BadWindow 
+errors.
+.NH 3
+Converting String Lists
+.XS
+\*(SN Converting String Lists
+.XE
+.LP
+Many of the text properties allow a variety of types and formats.
+Because the data stored in these properties are not
+simple null-terminated strings, an
+.PN XTextProperty
+structure is used to describe the encoding, type, and length of the text 
+as well as its value.
+The
+.PN XTextProperty
+structure contains:
+.IN "XTextProperty" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	unsigned char *value;	/* property data */
+	Atom encoding;	/* type of property */
+	int format;	/* 8, 16, or 32 */
+	unsigned long nitems;	/* number of items in value */
+} XTextProperty;
+.De
+.LP
+.eM
+Xlib provides functions to convert localized text to or from encodings
+that support the inter-client communication conventions for text.
+In addition, functions are provided for converting between lists of pointers 
+to character strings and text properties in the STRING encoding.
+.LP
+The functions for localized text return a signed integer error status 
+that encodes 
+.PN Success
+as zero, specific error conditions as negative numbers, and partial conversion
+as a count of unconvertible characters.
+.LP
+.IN "XICCEncodingStyle" "" "@DEF@"
+.sM
+.TS
+lw(.5i) lw(2i) lw(2.5i).
+T{
+#define
+T}	T{
+.PN XNoMemory
+T}	T{
+\-1
+T}
+T{
+#define
+T}	T{
+.PN XLocaleNotSupported
+T}	T{
+\-2
+T}
+T{
+#define
+T}	T{
+.PN XConverterNotFound
+T}	T{
+\-3
+T}
+.TE
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef enum {
+	XStringStyle,		/* STRING */
+	XCompoundTextStyle,	/* COMPOUND_TEXT */
+	XTextStyle,		/* text in owner's encoding (current locale) */
+	XStdICCTextStyle	/* STRING, else COMPOUND_TEXT */
+} XICCEncodingStyle;
+.De
+.LP
+.eM
+.sp
+.LP
+To convert a list of text strings to an 
+.PN XTextProperty
+structure, use
+.PN XmbTextListToTextProperty
+or
+.PN XwcTextListToTextProperty .
+.IN "XmbTextListToTextProperty" "" "@DEF@"
+.IN "XwcTextListToTextProperty" "" "@DEF@"
+.sM
+.FD 0
+int XmbTextListToTextProperty\^(\^\fIdisplay\fP\^, \fIlist\fP\^, \fIcount\fP\^, \fIstyle\fP\^, \fItext_prop_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      char **\fIlist\fP\^;
+.br
+      int \fIcount\fP\^;
+.br
+      XICCEncodingStyle \fIstyle\fP\^;
+.br
+      XTextProperty *\fItext_prop_return\fP\^;
+.FN
+.FD 0
+int XwcTextListToTextProperty\^(\^\fIdisplay\fP\^, \fIlist\fP\^, \fIcount\fP\^, \fIstyle\fP\^, \fItext_prop_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      wchar_t **\fIlist\fP\^;
+.br
+      int \fIcount\fP\^;
+.br
+      XICCEncodingStyle \fIstyle\fP\^;
+.br
+      XTextProperty *\fItext_prop_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIlist\fP 1i
+Specifies a list of null-terminated character strings.
+.IP \fIcount\fP 1i
+Specifies the number of strings specified.
+.IP \fIstyle\fP 1i
+Specifies the manner in which the property is encoded.
+.IP \fItext_prop_return\fP 1i
+Returns the
+.PN XTextProperty
+structure.
+.LP
+.eM
+The
+.PN XmbTextListToTextProperty
+and
+.PN XwcTextListToTextProperty
+functions set the specified 
+.PN XTextProperty
+value to a set of null-separated elements representing the concatenation
+of the specified list of null-terminated text strings.
+A final terminating null is stored at the end of the value field 
+of text_prop_return but is not included in the nitems member.
+.LP
+The functions set the encoding field of text_prop_return to an
+.PN Atom 
+for the specified display 
+naming the encoding determined by the specified style
+and convert the specified text list to this encoding for storage in
+the text_prop_return value field.
+If the style 
+.PN XStringStyle
+or 
+.PN XCompoundTextStyle
+is specified,
+this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively.
+If the style 
+.PN XTextStyle
+is specified,
+this encoding is the encoding of the current locale.
+If the style 
+.PN XStdICCTextStyle
+is specified,
+this encoding is ``STRING'' if the text is fully convertible to STRING,
+else ``COMPOUND_TEXT''.
+.LP
+If insufficient memory is available for the new value string,
+the functions return 
+.PN XNoMemory .
+If the current locale is not supported,
+the functions return 
+.PN XLocaleNotSupported .
+In both of these error cases,
+the functions do not set text_prop_return.
+.LP
+To determine if the functions are guaranteed not to return
+.PN XLocaleNotSupported ,
+use
+.PN XSupportsLocale .
+.LP
+If the supplied text is not fully convertible to the specified encoding,
+the functions return the number of unconvertible characters.
+Each unconvertible character is converted to an implementation-defined and
+encoding-specific default string.
+Otherwise, the functions return 
+.PN Success .
+Note that full convertibility to all styles except 
+.PN XStringStyle
+is guaranteed.
+.LP
+To free the storage for the value field, use
+.PN XFree .
+.sp
+.LP
+To obtain a list of text strings from an 
+.PN XTextProperty 
+structure, use
+.PN XmbTextPropertyToTextList
+or
+.PN XwcTextPropertyToTextList .
+.IN "XmbTextPropertyToTextList" "" "@DEF@"
+.IN "XwcTextPropertyToTextList" "" "@DEF@"
+.sM
+.FD 0
+int XmbTextPropertyToTextList\^(\^\fIdisplay\fP\^, \fItext_prop\fP\^, \fIlist_return\fP\^, \fIcount_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XTextProperty *\fItext_prop\fP\^;
+.br
+      char ***\fIlist_return\fP\^;
+.br
+      int *\fIcount_return\fP\^;
+.FN
+.FD 0
+int XwcTextPropertyToTextList\^(\^\fIdisplay\fP\^, \fItext_prop\fP\^, \fIlist_return\fP\^, \fIcount_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XTextProperty *\fItext_prop\fP\^;
+.br
+      wchar_t ***\fIlist_return\fP\^;
+.br
+      int *\fIcount_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fItext_prop\fP 1i
+Specifies the
+.PN XTextProperty
+structure to be used.
+.IP \fIlist_return\fP 1i
+Returns a list of null-terminated character strings.
+.ds Cn strings
+.IP \fIcount_return\fP 1i
+Returns the number of \*(Cn.
+.LP
+.eM
+The 
+.PN XmbTextPropertyToTextList
+and 
+.PN XwcTextPropertyToTextList
+functions return a list of text strings in the current locale representing the
+null-separated elements of the specified
+.PN XTextProperty
+structure.
+The data in text_prop must be format 8.
+.LP
+Multiple elements of the property (for example, the strings in a disjoint
+text selection) are separated by a null byte.
+The contents of the property are not required to be null-terminated;
+any terminating null should not be included in text_prop.nitems.
+.LP
+If insufficient memory is available for the list and its elements,
+.PN XmbTextPropertyToTextList
+and
+.PN XwcTextPropertyToTextList
+return 
+.PN XNoMemory .
+If the current locale is not supported,
+the functions return
+.PN XLocaleNotSupported .
+Otherwise, if the encoding field of text_prop is not convertible 
+to the encoding of the current locale,
+the functions return
+.PN XConverterNotFound .
+For supported locales,
+existence of a converter from COMPOUND_TEXT, STRING
+or the encoding of the current locale is guaranteed if
+.PN XSupportsLocale 
+returns 
+.PN True
+for the current locale (but the actual text
+may contain unconvertible characters).
+Conversion of other encodings is implementation-dependent.
+In all of these error cases,
+the functions do not set any return values.
+.LP
+Otherwise, 
+.PN XmbTextPropertyToTextList
+and
+.PN XwcTextPropertyToTextList
+return the list of null-terminated text strings to list_return
+and the number of text strings to count_return.
+.LP
+If the value field of text_prop is not fully convertible to the encoding of
+the current locale,
+the functions return the number of unconvertible characters.
+Each unconvertible character is converted to a string in the
+current locale that is specific to the current locale.
+To obtain the value of this string, 
+use
+.PN XDefaultString .
+Otherwise,
+.PN XmbTextPropertyToTextList
+and
+.PN XwcTextPropertyToTextList
+return 
+.PN Success .
+.LP
+To free the storage for the list and its contents returned by
+.PN XmbTextPropertyToTextList ,
+use
+.PN XFreeStringList .
+To free the storage for the list and its contents returned by
+.PN XwcTextPropertyToTextList ,
+use
+.PN XwcFreeStringList .
+.sp
+.LP
+To free the in-memory data associated with the specified
+wide character string list, use
+.PN XwcFreeStringList .
+.IN "XwcFreeStringList" "" "@DEF@"
+.sM
+.FD 0
+void XwcFreeStringList\^(\^\fIlist\fP\^)
+.br
+      wchar_t **\fIlist\fP\^;
+.FN
+.IP \fIlist\fP 1i
+Specifies the list of strings to be freed.
+.LP
+.eM
+The
+.PN XwcFreeStringList
+function frees memory allocated by
+.PN XwcTextPropertyToTextList .
+.sp
+.LP
+To obtain the default string for text conversion in the current locale,
+use
+.PN XDefaultString .
+.IN "XDefaultString" "" "@DEF@"
+.sM
+.FD 0
+char *XDefaultString\^(\|)
+.FN
+.LP
+.eM
+The
+.PN XDefaultString
+function returns the default string used by Xlib for text conversion
+(for example, in 
+.PN XmbTextPropertyToTextList ).
+The default string is the string in the current locale that is output 
+when an unconvertible character is found during text conversion.
+If the string returned by
+.PN XDefaultString
+is the empty string ("\^"),
+no character is output in the converted text.
+.PN XDefaultString
+does not return NULL.
+.LP
+The string returned by 
+.PN XDefaultString
+is independent of the default string for text drawing;
+see 
+.PN XCreateFontSet
+to obtain the default string for an
+.PN XFontSet .
+.LP
+The behavior when an invalid codepoint is supplied to any Xlib function is
+undefined.
+.LP
+The returned string is null-terminated.
+It is owned by Xlib and should not be modified or freed by the client.
+It may be freed after the current locale is changed.
+Until freed, it will not be modified by Xlib.
+.sp
+.LP
+To set the specified list of strings in the STRING encoding to a 
+.PN XTextProperty
+structure, use
+.PN XStringListToTextProperty .
+.IN "XStringListToTextProperty" "" "@DEF@"
+.sM
+.FD 0
+Status XStringListToTextProperty\^(\^\fIlist\fP, \fIcount\fP, \
+\fItext_prop_return\fP\^)
+.br
+      char **\fIlist\fP\^;
+.br
+      int \fIcount\fP\^;
+.br
+      XTextProperty *\fItext_prop_return\fP\^;
+.FN
+.IP \fIlist\fP 1i
+Specifies a list of null-terminated character strings.
+.ds Cn strings
+.IP \fIcount\fP 1i
+Specifies the number of \*(Cn.
+.IP \fItext_prop_return\fP 1i
+Returns the
+.PN XTextProperty
+structure.
+.LP
+.eM
+The 
+.PN XStringListToTextProperty 
+function sets the specified 
+.PN XTextProperty
+to be of type STRING (format 8) with a value representing the
+concatenation of the specified list of null-separated character strings.
+An extra null byte (which is not included in the nitems member) 
+is stored at the end of the value field of text_prop_return.
+The strings are assumed (without verification) to be in the STRING encoding.
+If insufficient memory is available for the new value string, 
+.PN XStringListToTextProperty
+does not set any fields in the
+.PN XTextProperty
+structure and returns a zero status.
+Otherwise, it returns a nonzero status.
+To free the storage for the value field, use 
+.PN XFree .
+.sp
+.LP
+To obtain a list of strings from a specified
+.PN XTextProperty
+structure in the STRING encoding, use
+.PN XTextPropertyToStringList .
+.IN "XTextPropertyToStringList" "" "@DEF@"
+.sM
+.FD 0
+Status XTextPropertyToStringList\^(\^\fItext_prop\fP, \fIlist_return\fP, \
+\fIcount_return\fP\^)
+.br
+       XTextProperty *\fItext_prop\fP\^;
+.br
+       char ***\fIlist_return\fP\^;
+.br
+       int *\fIcount_return\fP\^;
+.FN
+.IP \fItext_prop\fP 1i
+Specifies the
+.PN XTextProperty
+structure to be used.
+.IP \fIlist_return\fP 1i
+Returns a list of null-terminated character strings.
+.ds Cn strings
+.IP \fIcount_return\fP 1i
+Returns the number of \*(Cn.
+.LP
+.eM
+The 
+.PN XTextPropertyToStringList 
+function returns a list of strings representing the null-separated elements 
+of the specified
+.PN XTextProperty
+structure.
+The data in text_prop must be of type STRING and format 8. 
+Multiple elements of the property 
+(for example, the strings in a disjoint text selection) 
+are separated by NULL (encoding 0).
+The contents of the property are not null-terminated.
+If insufficient memory is available for the list and its elements, 
+.PN XTextPropertyToStringList
+sets no return values and returns a zero status.
+Otherwise, it returns a nonzero status.
+To free the storage for the list and its contents, use 
+.PN XFreeStringList .
+.sp
+.LP
+To free the in-memory data associated with the specified string list, use
+.PN XFreeStringList .
+.IN "XFreeStringList" "" "@DEF@"
+.sM
+.FD 0
+void XFreeStringList\^(\^\fIlist\fP\^)
+.br
+      char **\fIlist\fP\^;
+.FN
+.IP \fIlist\fP 1i
+Specifies the list of strings to be freed.
+.LP
+.eM
+The 
+.PN XFreeStringList 
+function releases memory allocated by 
+.PN XmbTextPropertyToTextList
+and
+.PN XTextPropertyToStringList
+and the missing charset list allocated by 
+.PN XCreateFontSet .
+.NH 3
+Setting and Reading Text Properties
+.XS
+\*(SN Setting and Reading Text Properties
+.XE
+.LP
+Xlib provides two functions that you can use to set and read
+the text properties for a given window.
+You can use these functions to set and read those properties of type TEXT
+(WM_NAME, WM_ICON_NAME, WM_COMMAND, and WM_CLIENT_MACHINE).
+In addition,
+Xlib provides separate convenience functions that you can use to set each 
+of these properties.
+For further information about these convenience functions,
+see sections 14.1.4, 14.1.5, 14.2.1, and 14.2.2, respectively.
+.sp
+.LP
+To set one of a window's text properties, use
+.PN XSetTextProperty .
+.IN "XSetTextProperty" "" "@DEF@"
+.sM
+.FD 0
+void XSetTextProperty\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP, \
+\fIproperty\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XTextProperty *\fItext_prop\fP\^;
+.br
+      Atom \fIproperty\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fItext_prop\fP 1i
+Specifies the
+.PN XTextProperty
+structure to be used.
+.IP \fIproperty\fP 1i
+Specifies the property name.
+.LP
+.eM
+The
+.PN XSetTextProperty
+function replaces the existing specified property for the named window 
+with the data, type, format, and number of items determined 
+by the value field, the encoding field, the format field, 
+and the nitems field, respectively, of the specified
+.PN XTextProperty
+structure.
+If the property does not already exist,
+.PN XSetTextProperty
+sets it for the specified window.
+.LP
+.PN XSetTextProperty
+can generate
+.PN BadAlloc ,
+.PN BadAtom , 
+.PN BadValue , 
+and 
+.PN BadWindow  
+errors.
+.sp
+.LP
+To read one of a window's text properties, use
+.PN XGetTextProperty .
+.IN "XGetTextProperty" "" "@DEF@"
+.sM
+.FD 0
+Status XGetTextProperty\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP, \
+\fIproperty\fP\^)
+.br
+       Display *\fIdisplay\fP\^;
+.br
+       Window \fIw\fP\^;
+.br
+       XTextProperty *\fItext_prop_return\fP\^;
+.br
+       Atom \fIproperty\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fItext_prop_return\fP 1i
+Returns the
+.PN XTextProperty
+structure.
+.IP \fIproperty\fP 1i
+Specifies the property name.
+.LP
+.eM
+The
+.PN XGetTextProperty 
+function reads the specified property from the window
+and stores the data in the returned
+.PN XTextProperty
+structure.
+It stores the data in the value field,
+the type of the data in the encoding field,
+the format of the data in the format field, 
+and the number of items of data in the nitems field.
+An extra byte containing null (which is not included in the nitems member) 
+is stored at the end of the value field of text_prop_return.
+The particular interpretation of the property's encoding 
+and data as text is left to the calling application.
+If the specified property does not exist on the window,
+.PN XGetTextProperty
+sets the value field to NULL, 
+the encoding field to
+.PN None , 
+the format field to zero, 
+and the nitems field to zero.
+.LP
+If it was able to read and store the data in the
+.PN XTextProperty
+structure,
+.PN XGetTextProperty
+returns a nonzero status; 
+otherwise, it returns a zero status.
+.LP
+.PN XGetTextProperty
+can generate
+.PN BadAtom 
+and 
+.PN BadWindow 
+errors.
+.NH 3
+Setting and Reading the WM_NAME Property
+.XS
+\*(SN Setting and Reading the WM_NAME Property
+.XE
+.LP
+Xlib provides convenience functions that you can use to set and read 
+the WM_NAME property for a given window.
+.sp
+.LP
+To set a window's WM_NAME property with the supplied convenience function, use
+.PN XSetWMName .
+.IN "XSetWMName" "" "@DEF@"
+.sM
+.FD 0
+void XSetWMName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XTextProperty *\fItext_prop\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fItext_prop\fP 1i
+Specifies the
+.PN XTextProperty
+structure to be used.
+.LP
+.eM
+The
+.PN XSetWMName
+convenience function calls
+.PN XSetTextProperty 
+to set the WM_NAME property.
+.sp
+.LP
+To read a window's WM_NAME property with the supplied convenience function, use
+.PN XGetWMName .
+.IN "XGetWMName" "" "@DEF@"
+.sM
+.FD 0
+Status XGetWMName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XTextProperty *\fItext_prop_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fItext_prop_return\fP 1i
+Returns the
+.PN XTextProperty
+structure.
+.LP
+.eM
+The
+.PN XGetWMName 
+convenience function calls
+.PN XGetTextProperty 
+to obtain the WM_NAME property.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+.LP
+The following two functions have been superseded by
+.PN XSetWMName
+and
+.PN XGetWMName ,
+respectively. 
+You can use these additional convenience functions 
+for window names that are encoded as STRING properties.
+.sp
+.LP
+To assign a name to a window, use
+.PN XStoreName .
+.IN "Window" "name"
+.IN "XStoreName" "" "@DEF@"
+.sM
+.FD 0
+XStoreName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_name\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      char *\fIwindow_name\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIwindow_name\fP 1i
+Specifies the window name,
+which should be a null-terminated string.
+.LP
+.eM
+The
+.PN XStoreName
+function assigns the name passed to window_name to the specified window.
+A window manager can display the window name in some prominent
+place, such as the title bar, to allow users to identify windows easily.
+Some window managers may display a window's name in the window's icon,
+although they are encouraged to use the window's icon name
+if one is provided by the application.
+If the string is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+.LP
+.PN XStoreName
+can generate
+.PN BadAlloc
+and
+.PN BadWindow
+errors.
+.LP
+.sp
+To get the name of a window, use
+.PN XFetchName .
+.IN "XFetchName" "" "@DEF@"
+.sM
+.FD 0
+Status XFetchName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_name_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      char **\fIwindow_name_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIwindow_name_return\fP 1i
+Returns the window name, which is a null-terminated string.
+.LP
+.eM
+The
+.PN XFetchName
+function returns the name of the specified window.
+If it succeeds,
+it returns a nonzero status; 
+otherwise, no name has been set for the window,
+and it returns zero.
+If the WM_NAME property has not been set for this window,
+.PN XFetchName
+sets window_name_return to NULL.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned string is in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+When finished with it, a client must free
+the window name string using
+.PN XFree .
+.LP
+.PN XFetchName
+can generate a
+.PN BadWindow
+error.
+.NH 3
+Setting and Reading the WM_ICON_NAME Property
+.XS
+\*(SN Setting and Reading the WM_ICON_NAME Property
+.XE
+.LP
+Xlib provides convenience functions that you can use to set and read 
+the WM_ICON_NAME property for a given window.
+.LP
+.sp
+To set a window's WM_ICON_NAME property,
+use
+.PN XSetWMIconName .
+.IN "XSetWMIconName" "" "@DEF@"
+.sM
+.FD 0
+void XSetWMIconName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XTextProperty *\fItext_prop\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fItext_prop\fP 1i
+Specifies the
+.PN XTextProperty
+structure to be used.
+.LP
+.eM
+The
+.PN XSetWMIconName
+convenience function calls
+.PN XSetTextProperty
+to set the WM_ICON_NAME property.
+.sp
+.LP
+To read a window's WM_ICON_NAME property,
+use
+.PN XGetWMIconName .
+.IN "XGetWMIconName" "" "@DEF@"
+.sM
+.FD 0
+Status XGetWMIconName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XTextProperty *\fItext_prop_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fItext_prop_return\fP 1i
+Returns the
+.PN XTextProperty
+structure.
+.LP
+.eM
+The 
+.PN XGetWMIconName 
+convenience function calls
+.PN XGetTextProperty 
+to obtain the WM_ICON_NAME property.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+.LP
+The next two functions have been superseded by
+.PN XSetWMIconName
+and
+.PN XGetWMIconName ,
+respectively.
+You can use these additional convenience functions 
+for window names that are encoded as STRING properties.
+.sp
+.LP
+.sp
+To set the name to be displayed in a window's icon, use
+.PN XSetIconName .
+.IN "Window" "icon name"
+.IN "XSetIconName" "" "@DEF@"
+.sM
+.FD 0
+XSetIconName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIicon_name\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      char *\fIicon_name\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIicon_name\fP 1i
+Specifies the icon name,
+which should be a null-terminated string.
+.LP
+.eM
+If the string is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+.PN XSetIconName
+can generate
+.PN BadAlloc
+and
+.PN BadWindow
+errors.
+.LP
+.sp
+To get the name a window wants displayed in its icon, use
+.PN XGetIconName .
+.IN "XGetIconName" "" "@DEF@"
+.sM
+.FD 0
+Status XGetIconName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIicon_name_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      char **\fIicon_name_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIicon_name_return\fP 1i
+Returns the window's icon name,
+which is a null-terminated string.
+.LP
+.eM
+The
+.PN XGetIconName
+function returns the name to be displayed in the specified window's icon.
+If it succeeds, it returns a nonzero status; otherwise, 
+if no icon name has been set for the window,
+it returns zero.
+If you never assigned a name to the window,
+.PN XGetIconName
+sets icon_name_return to NULL.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned string is in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+When finished with it, a client must free
+the icon name string using
+.PN XFree .
+.LP
+.PN XGetIconName
+can generate a
+.PN BadWindow
+error.
+.NH 3
+Setting and Reading the WM_HINTS Property
+.XS
+\*(SN Setting and Reading the WM_HINTS Property
+.XE
+.LP
+Xlib provides functions that you can use to set and read 
+the WM_HINTS property for a given window.
+These functions use the flags and the
+.PN XWMHints 
+structure, as defined in the
+.hN X11/Xutil.h
+header file.
+.sp
+.LP
+To allocate an
+.PN XWMHints
+structure, use
+.PN XAllocWMHints .
+.IN "XAllocWMHints" "" "@DEF@"
+.sM
+.FD 0
+XWMHints *XAllocWMHints\^(\|)
+.FN
+.LP
+.eM
+The
+.PN XAllocWMHints
+function allocates and returns a pointer to an
+.PN XWMHints
+structure.
+Note that all fields in the
+.PN XWMHints
+structure are initially set to zero.
+If insufficient memory is available, 
+.PN XAllocWMHints
+returns NULL.
+To free the memory allocated to this structure,
+use
+.PN XFree .
+.LP
+The
+.PN XWMHints
+structure contains:
+.LP
+.sM
+/* Window manager hints mask bits */
+.TS
+lw(.5i) lw(2.5i) lw(2.5i).
+T{
+#define
+T}	T{
+.PN InputHint
+T}	T{
+(1L << 0)
+T}
+T{
+#define
+T}	T{
+.PN StateHint
+T}	T{
+(1L << 1)
+T}
+T{
+#define
+T}	T{
+.PN IconPixmapHint
+T}	T{
+(1L << 2)
+T}
+T{
+#define
+T}	T{
+.PN IconWindowHint
+T}	T{
+(1L << 3)
+T}
+T{
+#define
+T}	T{
+.PN IconPositionHint
+T}	T{
+(1L << 4)
+T}
+T{
+#define
+T}	T{
+.PN IconMaskHint
+T}	T{
+(1L << 5)
+T}
+T{
+#define
+T}	T{
+.PN WindowGroupHint
+T}	T{
+(1L << 6)
+T}
+T{
+#define
+T}	T{
+.PN UrgencyHint
+T}	T{
+(1L << 8)
+T}
+T{
+#define
+T}	T{
+.PN AllHints
+T}	T{
+(InputHint|StateHint|IconPixmapHint|
+.br
+IconWindowHint|IconPositionHint|
+.br
+IconMaskHint|WindowGroupHint)
+T}
+.TE
+.IN "XWMHints" "" "@DEF@"
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+/* Values */
+
+typedef struct {
+	long flags;	/* marks which fields in this structure are defined */
+	Bool input;	/* does this application rely on the window manager to
+			get keyboard input? */
+	int initial_state;	/* see below */
+	Pixmap icon_pixmap;	/* pixmap to be used as icon */
+	Window icon_window;	/* window to be used as icon */
+	int icon_x, icon_y;	/* initial position of icon */
+	Pixmap icon_mask;	/* pixmap to be used as mask for icon_pixmap */
+	XID window_group;	/* id of related window group */
+	/* this structure may be extended in the future */
+} XWMHints;
+.De
+.LP
+.eM
+The input member is used to communicate to the window manager the input focus
+model used by the application.
+Applications that expect input but never explicitly set focus to any 
+of their subwindows (that is, use the push model of focus management), 
+such as X Version 10 style applications that use real-estate
+driven focus, should set this member to 
+.PN True .  
+Similarly, applications
+that set input focus to their subwindows only when it is given to their
+top-level window by a window manager should also set this member to 
+.PN True .
+Applications that manage their own input focus by explicitly setting
+focus to one of their subwindows whenever they want keyboard input 
+(that is, use the pull model of focus management) should set this member to 
+.PN False .
+Applications that never expect any keyboard input also should set this member
+to 
+.PN False .
+.LP
+Pull model window managers should make it possible for push model
+applications to get input by setting input focus to the top-level windows of
+applications whose input member is 
+.PN True .  
+Push model window managers should
+make sure that pull model applications do not break them 
+by resetting input focus to 
+.PN PointerRoot 
+when it is appropriate (for example, whenever an application whose
+input member is 
+.PN False 
+sets input focus to one of its subwindows).
+.LP
+The definitions for the initial_state flag are:
+.TS
+lw(.5i) lw(2i) lw(.2i) lw(2.8i).
+T{
+#define
+T}	T{
+.PN WithdrawnState
+T}	T{
+0
+T}	T{
+T}
+T{
+#define
+T}	T{
+.PN NormalState
+T}	T{
+1
+T}	T{
+/* most applications start this way */
+T}
+T{
+#define
+T}	T{
+.PN IconicState
+T}	T{
+3
+T}	T{
+/* application wants to start as an icon */
+T}
+.TE
+The icon_mask specifies which pixels of the icon_pixmap should be used as the
+icon.  
+This allows for nonrectangular icons.
+Both icon_pixmap and icon_mask must be bitmaps.
+The icon_window lets an application provide a window for use as an icon
+for window managers that support such use.
+The window_group lets you specify that this window belongs to a group
+of other windows.
+For example, if a single application manipulates multiple 
+top-level windows, this allows you to provide enough
+information that a window manager can iconify all of the windows
+rather than just the one window.
+.LP
+The
+.PN UrgencyHint
+flag, if set in the flags field, indicates that the client deems the window
+contents to be urgent, requiring the timely response of the user.  The
+window manager will make some effort to draw the user's attention to this
+window while this flag is set.  The client must provide some means by which the
+user can cause the urgency flag to be cleared (either mitigating
+the condition that made the window urgent or merely shutting off the alarm)
+or the window to be withdrawn.
+.LP
+.sp
+To set a window's WM_HINTS property, use
+.PN XSetWMHints .
+.IN "XSetWMHints" "" "@DEF@"
+.sM
+.FD 0
+XSetWMHints\^(\^\fIdisplay\fP, \fIw\fP, \fIwmhints\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XWMHints *\fIwmhints\fP\^;
+
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIwmhints\fP 1i
+Specifies the 
+.PN XWMHints
+structure to be used.
+.LP
+.eM
+The
+.PN XSetWMHints
+function sets the window manager hints that include icon information and location,
+the initial state of the window, and whether the application relies on the
+window manager to get keyboard input.
+.LP
+.PN XSetWMHints
+can generate
+.PN BadAlloc
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To read a window's WM_HINTS property, use
+.PN XGetWMHints .
+.IN "XGetWMHints" "" "@DEF@"
+.sM
+.FD 0
+XWMHints *XGetWMHints\^(\^\fIdisplay\fP, \fIw\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.LP
+.eM
+The
+.PN XGetWMHints
+function reads the window manager hints and 
+returns NULL if no WM_HINTS property was set on the window 
+or returns a pointer to an 
+.PN XWMHints 
+structure if it succeeds.
+When finished with the data,
+free the space used for it by calling
+.PN XFree .
+.LP
+.PN XGetWMHints
+can generate a
+.PN BadWindow 
+error.
+.NH 3
+Setting and Reading the WM_NORMAL_HINTS Property
+.XS
+\*(SN Setting and Reading the WM_NORMAL_HINTS Property
+.XE
+.LP
+Xlib provides functions that you can use to set or read 
+the WM_NORMAL_HINTS property for a given window.
+The functions use the flags and the
+.PN XSizeHints 
+structure, as defined in the
+.hN X11/Xutil.h
+header file.
+.LP
+The size of the
+.PN XSizeHints
+structure may grow in future releases, as new components are
+added to support new ICCCM features.
+Passing statically allocated instances of this structure into
+Xlib may result in memory corruption when running against a
+future release of the library.
+As such, it is recommended that only dynamically allocated
+instances of the structure be used.
+.sp
+.LP
+To allocate an
+.PN XSizeHints
+structure, use
+.PN XAllocSizeHints .
+.IN "XAllocSizeHints" "" "@DEF@"
+.sM
+.FD 0
+XSizeHints *XAllocSizeHints\^(\|)
+.FN
+.LP
+.eM
+The
+.PN XAllocSizeHints
+function allocates and returns a pointer to an
+.PN XSizeHints
+structure.
+Note that all fields in the
+.PN XSizeHints
+structure are initially set to zero.
+If insufficient memory is available, 
+.PN XAllocSizeHints
+returns NULL.
+To free the memory allocated to this structure,
+use
+.PN XFree .
+.LP
+The
+.PN XSizeHints
+structure contains:
+.LP
+.sM
+/* Size hints mask bits */
+.TS
+lw(.5i) lw(1.1i) lw(1.5i) lw(3.1i).
+T{
+#define
+T}	T{
+.PN USPosition
+T}	T{
+(1L << 0)
+T}	T{
+/* user specified x, y */
+T}
+T{
+#define
+T}	T{
+.PN USSize
+T}	T{
+(1L << 1)
+T}	T{
+/* user specified width, height */
+T}
+T{
+#define
+T}	T{
+.PN PPosition
+T}	T{
+(1L << 2)
+T}	T{
+/* program specified position */
+T}
+T{
+#define
+T}	T{
+.PN PSize
+T}	T{
+(1L << 3)
+T}	T{
+/* program specified size */
+T}
+T{
+#define
+T}	T{
+.PN PMinSize
+T}	T{
+(1L << 4)
+T}	T{
+/* program specified minimum size */
+T}
+T{
+#define
+T}	T{
+.PN PMaxSize
+T}	T{
+(1L << 5)
+T}	T{
+/* program specified maximum size */
+T}
+T{
+#define
+T}	T{
+.PN PResizeInc
+T}	T{
+(1L << 6)
+T}	T{
+/* program specified resize increments */
+T}
+T{
+#define
+T}	T{
+.PN PAspect
+T}	T{
+(1L << 7)
+T}	T{
+/* program specified min and max aspect ratios */
+T}
+T{
+#define
+T}	T{
+.PN PBaseSize
+T}	T{
+(1L << 8)
+T}
+T{
+#define
+T}	T{
+.PN PWinGravity
+T}	T{
+(1L << 9)
+T}
+T{
+#define
+T}	T{
+.PN PAllHints
+T}	T{
+(PPosition|PSize|
+.br
+PMinSize|PMaxSize|
+.br
+PResizeInc|PAspect)
+T}	T{
+T}
+.TE
+.IN "XSizeHints" "" "@DEF@"
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+/* Values */
+
+typedef struct {
+	long flags;	/* marks which fields in this structure are defined */
+	int x, y;	/* Obsolete */
+	int width, height;	/* Obsolete */
+	int min_width, min_height;
+	int max_width, max_height;
+	int width_inc, height_inc;
+	struct {
+	       int x;	/* numerator */
+	       int y;	/* denominator */
+	} min_aspect, max_aspect;
+	int base_width, base_height;
+	int win_gravity;
+	/* this structure may be extended in the future */
+} XSizeHints;
+.De
+.LP
+.eM
+The x, y, width, and height members are now obsolete
+and are left solely for compatibility reasons.
+The min_width and min_height members specify the
+minimum window size that still allows the application to be useful.
+The max_width and max_height members specify the maximum window size.
+The width_inc and height_inc members define an arithmetic progression of
+sizes (minimum to maximum) into which the window prefers to be resized.
+The min_aspect and max_aspect members are expressed
+as ratios of x and y, 
+and they allow an application to specify the range of aspect
+ratios it prefers.
+The base_width and base_height members define the desired size of the window.
+The window manager will interpret the position of the window 
+and its border width to position the point of the outer rectangle 
+of the overall window specified by the win_gravity member.
+The outer rectangle of the window includes any borders or decorations
+supplied by the window manager.
+In other words,
+if the window manager decides to place the window where the client asked,
+the position on the parent window's border named by the win_gravity 
+will be placed where the client window would have been placed 
+in the absence of a window manager.
+.LP
+Note that use of the
+.PN PAllHints
+macro is highly discouraged.
+.sp
+.LP
+To set a window's WM_NORMAL_HINTS property, use
+.PN XSetWMNormalHints .
+.IN "XSetWMNormalHints" "" "@DEF@"
+.sM
+.FD 0
+void XSetWMNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XSizeHints *\fIhints\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIhints\fP 1i
+Specifies the size hints for the window in its normal state.
+.LP
+.eM
+The 
+.PN XSetWMNormalHints 
+function replaces the size hints for the WM_NORMAL_HINTS property 
+on the specified window.
+If the property does not already exist,
+.PN XSetWMNormalHints
+sets the size hints for the WM_NORMAL_HINTS property on the specified window.
+The property is stored with a type of WM_SIZE_HINTS and a format of 32.
+.LP
+.PN XSetWMNormalHints
+can generate
+.PN BadAlloc
+and
+.PN BadWindow
+errors.
+.sp
+.LP
+To read a window's WM_NORMAL_HINTS property, use
+.PN XGetWMNormalHints .
+.IN "XGetWMNormalHints" "" "@DEF@"
+.sM
+.FD 0
+Status XGetWMNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP, \
+\fIsupplied_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XSizeHints *\fIhints_return\fP\^;
+.br
+      long *\fIsupplied_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIhints_return\fP 1i
+Returns the size hints for the window in its normal state.
+.IP \fIsupplied_return\fP 1i
+Returns the hints that were supplied by the user.
+.LP
+.eM
+The 
+.PN XGetWMNormalHints 
+function returns the size hints stored in the WM_NORMAL_HINTS property 
+on the specified window.
+If the property is of type WM_SIZE_HINTS, is of format 32,
+and is long enough to contain either an old (pre-ICCCM) 
+or new size hints structure, 
+.PN XGetWMNormalHints
+sets the various fields of the 
+.PN XSizeHints
+structure, sets the supplied_return argument to the list of fields 
+that were supplied by the user (whether or not they contained defined values),
+and returns a nonzero status.
+Otherwise, it returns a zero status.
+.LP
+If 
+.PN XGetWMNormalHints
+returns successfully and a pre-ICCCM size hints property is read, 
+the supplied_return argument will contain the following bits:
+.LP
+.Ds
+(USPosition|USSize|PPosition|PSize|PMinSize|
+ PMaxSize|PResizeInc|PAspect)
+.De
+.LP
+If the property is large enough to contain the base size 
+and window gravity fields as well, 
+the supplied_return argument will also contain the following bits:
+.LP
+.Ds
+PBaseSize|PWinGravity
+.De
+.LP
+.PN XGetWMNormalHints
+can generate a
+.PN BadWindow
+error.
+.sp
+.LP
+To set a window's WM_SIZE_HINTS property, use
+.PN XSetWMSizeHints .
+.IN "XSetWMSizeHints" "" "@DEF@"
+.sM
+.FD 0
+void XSetWMSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP, \fIproperty\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XSizeHints *\fIhints\fP\^;
+.br
+      Atom \fIproperty\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIhints\fP 1i
+Specifies the
+.PN XSizeHints
+structure to be used.
+.IP \fIproperty\fP 1i
+Specifies the property name.
+.LP
+.eM
+The 
+.PN XSetWMSizeHints 
+function replaces the size hints for the specified property 
+on the named window.
+If the specified property does not already exist,
+.PN XSetWMSizeHints
+sets the size hints for the specified property
+on the named window.
+The property is stored with a type of WM_SIZE_HINTS and a format of 32.
+To set a window's normal size hints, 
+you can use the 
+.PN XSetWMNormalHints
+function.
+.LP
+.PN XSetWMSizeHints
+can generate
+.PN BadAlloc ,
+.PN BadAtom , 
+and 
+.PN BadWindow
+errors.
+.sp
+.LP
+To read a window's WM_SIZE_HINTS property, use
+.PN XGetWMSizeHints .
+.IN "XGetWMSizeHints" "" "@DEF@"
+.sM
+.FD 0
+Status XGetWMSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP, \
+\fIsupplied_return\fP, \fIproperty\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XSizeHints *\fIhints_return\fP\^;
+.br
+      long *\fIsupplied_return\fP\^;
+.br
+      Atom \fIproperty\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIhints_return\fP 1i
+Returns the
+.PN XSizeHints
+structure.
+.IP \fIsupplied_return\fP 1i
+Returns the hints that were supplied by the user.
+.IP \fIproperty\fP 1i
+Specifies the property name.
+.LP
+.eM
+The 
+.PN XGetWMSizeHints
+function returns the size hints stored in the specified property 
+on the named window.
+If the property is of type WM_SIZE_HINTS, is of format 32, 
+and is long enough to contain either an old (pre-ICCCM) 
+or new size hints structure, 
+.PN XGetWMSizeHints
+sets the various fields of the 
+.PN XSizeHints
+structure, sets the supplied_return argument to the
+list of fields that were supplied by the user 
+(whether or not they contained defined values), 
+and returns a nonzero status.
+Otherwise, it returns a zero status.
+To get a window's normal size hints, 
+you can use the 
+.PN XGetWMNormalHints 
+function.
+.LP
+If 
+.PN XGetWMSizeHints
+returns successfully and a pre-ICCCM size hints property is read, 
+the supplied_return argument will contain the following bits:
+.LP
+.Ds
+(USPosition|USSize|PPosition|PSize|PMinSize|
+ PMaxSize|PResizeInc|PAspect)
+.De
+.LP
+If the property is large enough to contain the base size 
+and window gravity fields as well, 
+the supplied_return argument will also contain the following bits:
+.LP
+.Ds
+PBaseSize|PWinGravity
+.De
+.LP
+.PN XGetWMSizeHints
+can generate
+.PN BadAtom 
+and 
+.PN BadWindow
+errors.
+.NH 3
+Setting and Reading the WM_CLASS Property
+.XS
+\*(SN Setting and Reading the WM_CLASS Property
+.XE
+.LP
+Xlib provides functions that you can use to set and get 
+the WM_CLASS property for a given window.
+These functions use the
+.PN XClassHint 
+structure, which is defined in the
+.hN X11/Xutil.h
+header file.
+.sp
+.LP
+To allocate an
+.PN XClassHint
+structure, use
+.PN XAllocClassHint .
+.IN "XAllocClassHint" "" "@DEF@"
+.sM
+.FD 0
+XClassHint *XAllocClassHint\^(\|)
+.FN
+.LP
+.eM
+The
+.PN XAllocClassHint
+function allocates and returns a pointer to an
+.PN XClassHint
+structure.
+Note that the pointer fields in the
+.PN XClassHint
+structure are initially set to NULL.
+If insufficient memory is available, 
+.PN XAllocClassHint
+returns NULL.
+To free the memory allocated to this structure,
+use
+.PN XFree .
+.LP
+The
+.PN XClassHint
+contains:
+.LP
+.sM
+.IN "XClassHint" "" "@DEF@"
+.Ds 0
+.TA .5i
+.ta .5i
+typedef struct {
+	char *res_name;
+	char *res_class;
+} XClassHint;
+.De
+.LP
+.eM
+The res_name member contains the application name, 
+and the res_class member contains the application class. 
+Note that the name set in this property may differ from the name set as WM_NAME.
+That is, WM_NAME specifies what should be displayed in the title bar and,
+therefore, can contain temporal information (for example, the name of
+a file currently in an editor's buffer).
+On the other hand, 
+the name specified as part of WM_CLASS is the formal name of the application
+that should be used when retrieving the application's resources from the 
+resource database.
+.LP
+.sp
+To set a window's WM_CLASS property, use
+.PN XSetClassHint .
+.IN "XSetClassHint" "" "@DEF@"
+.sM
+.FD 0
+XSetClassHint\^(\^\fIdisplay\fP, \fIw\fP, \fIclass_hints\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XClassHint *\fIclass_hints\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIclass_hints\fP 1i
+Specifies the
+.PN XClassHint
+structure that is to be used.
+.LP
+.eM
+The
+.PN XSetClassHint
+function sets the class hint for the specified window.
+If the strings are not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+.LP
+.PN XSetClassHint
+can generate
+.PN BadAlloc
+and
+.PN BadWindow
+errors. 
+.LP
+.sp
+To read a window's WM_CLASS property, use
+.PN XGetClassHint .
+.IN "XGetClassHint" "" "@DEF@"
+.sM
+.FD 0
+Status XGetClassHint\^(\^\fIdisplay\fP, \fIw\fP, \fIclass_hints_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP;
+.br
+      XClassHint *\fIclass_hints_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIclass_hints_return\fP 1i
+Returns the 
+.PN XClassHint
+structure.
+.LP
+.eM
+The
+.PN XGetClassHint
+function returns the class hint of the specified window to the members
+of the supplied structure.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned strings are in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+To free res_name and res_class when finished with the strings,
+use
+.PN XFree
+on each individually.
+.LP
+.PN XGetClassHint
+can generate a
+.PN BadWindow 
+error.
+.NH 3
+Setting and Reading the WM_TRANSIENT_FOR Property
+.XS
+\*(SN Setting and Reading the WM_TRANSIENT_FOR Property
+.XE
+.LP
+Xlib provides functions that you can use to set and read
+the WM_TRANSIENT_FOR property for a given window.
+.LP
+.sp
+To set a window's WM_TRANSIENT_FOR property, use
+.PN XSetTransientForHint .
+.IN "XSetTransientForHint" "" "@DEF@"
+.sM
+.FD 0
+XSetTransientForHint\^(\^\fIdisplay\fP, \fIw\fP, \fIprop_window\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Window \fIprop_window\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIprop_window\fP 1i
+Specifies the window that the WM_TRANSIENT_FOR property is to be set to.
+.LP
+.eM
+The
+.PN XSetTransientForHint
+function sets the WM_TRANSIENT_FOR property of the specified window to the 
+specified prop_window.
+.LP
+.PN XSetTransientForHint
+can generate
+.PN BadAlloc
+and
+.PN BadWindow
+errors.
+.LP
+.sp
+To read a window's WM_TRANSIENT_FOR property, use
+.PN XGetTransientForHint .
+.IN "XGetTransientForHint" "" "@DEF@"
+.sM
+.FD 0
+Status XGetTransientForHint\^(\^\fIdisplay\fP, \fIw\fP, \fIprop_window_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Window *\fIprop_window_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIprop_window_return\fP 1i
+Returns the WM_TRANSIENT_FOR property of the specified window.
+.LP
+.eM
+The
+.PN XGetTransientForHint
+function returns the WM_TRANSIENT_FOR property for the specified window.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+.LP
+.PN XGetTransientForHint
+can generate a
+.PN BadWindow 
+error.
+.NH 3
+Setting and Reading the WM_PROTOCOLS Property
+.XS
+\*(SN Setting and Reading the WM_PROTOCOLS Property
+.XE
+.LP
+Xlib provides functions that you can use to set and read
+the WM_PROTOCOLS property for a given window.
+.LP
+.sp
+To set a window's WM_PROTOCOLS property, use
+.PN XSetWMProtocols .
+.IN "XSetWMProtocols" "" "@DEF@"
+.sM
+.FD 0
+Status XSetWMProtocols\^(\^\fIdisplay\fP, \fIw\fP, \fIprotocols\fP, \
+\fIcount\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Atom *\fIprotocols\fP\^;
+.br
+      int \fIcount\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIprotocols\fP 1i
+Specifies the list of protocols.
+.ds Cn protocols in the list
+.IP \fIcount\fP 1i
+Specifies the number of \*(Cn.
+.LP
+.eM
+The 
+.PN XSetWMProtocols 
+function replaces the WM_PROTOCOLS property on the specified window 
+with the list of atoms specified by the protocols argument.
+If the property does not already exist,
+.PN XSetWMProtocols
+sets the WM_PROTOCOLS property on the specified window
+to the list of atoms specified by the protocols argument.
+The property is stored with a type of ATOM and a format of 32.
+If it cannot intern the WM_PROTOCOLS atom, 
+.PN XSetWMProtocols
+returns a zero status.
+Otherwise, it returns a nonzero status.
+.LP
+.PN XSetWMProtocols
+can generate
+.PN BadAlloc
+and
+.PN BadWindow
+errors.
+.sp
+.LP
+To read a window's WM_PROTOCOLS property, use
+.PN XGetWMProtocols .
+.IN "XGetWMProtocols" "" "@DEF@"
+.sM
+.FD 0
+Status XGetWMProtocols\^(\^\fIdisplay\fP, \fIw\fP, \fIprotocols_return\fP, \
+\fIcount_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Atom **\fIprotocols_return\fP\^;
+.br
+      int *\fIcount_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIprotocols_return\fP 1i
+Returns the list of protocols.
+.ds Cn protocols in the list
+.IP \fIcount_return\fP 1i
+Returns the number of \*(Cn.
+.LP
+.eM
+The 
+.PN XGetWMProtocols 
+function returns the list of atoms stored in the WM_PROTOCOLS property 
+on the specified window.
+These atoms describe window manager protocols in which the owner 
+of this window is willing to participate.
+If the property exists, is of type ATOM, is of format 32, 
+and the atom WM_PROTOCOLS can be interned, 
+.PN XGetWMProtocols
+sets the protocols_return argument to a list of atoms, 
+sets the count_return argument to the number of elements in the list, 
+and returns a nonzero status.
+Otherwise, it sets neither of the return arguments
+and returns a zero status.
+To release the list of atoms, use
+.PN XFree .
+.LP
+.PN XGetWMProtocols
+can generate a
+.PN BadWindow
+error.
+.NH 3
+Setting and Reading the WM_COLORMAP_WINDOWS Property
+.XS
+\*(SN Setting and Reading the WM_COLORMAP_WINDOWS Property
+.XE
+.LP
+Xlib provides functions that you can use to set and read
+the WM_COLORMAP_WINDOWS property for a given window.
+.sp
+.LP
+To set a window's WM_COLORMAP_WINDOWS property, use
+.PN XSetWMColormapWindows .
+.IN "XSetWMColormapWindows" "" "@DEF@"
+.sM
+.FD 0
+Status XSetWMColormapWindows\^(\^\fIdisplay\fP, \fIw\fP, \
+\fIcolormap_windows\fP, \fIcount\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Window *\fIcolormap_windows\fP\^;
+.br
+      int \fIcount\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIcolormap_windows\fP 1i
+Specifies the list of windows.
+.ds Cn windows in the list
+.IP \fIcount\fP 1i
+Specifies the number of \*(Cn.
+.LP
+.eM
+The 
+.PN XSetWMColormapWindows 
+function replaces the WM_COLORMAP_WINDOWS property on the specified
+window with the list of windows specified by the colormap_windows argument.
+If the property does not already exist,
+.PN XSetWMColormapWindows
+sets the WM_COLORMAP_WINDOWS property on the specified
+window to the list of windows specified by the colormap_windows argument.
+The property is stored with a type of WINDOW and a format of 32.
+If it cannot intern the WM_COLORMAP_WINDOWS atom,
+.PN XSetWMColormapWindows
+returns a zero status.
+Otherwise, it returns a nonzero status.
+.LP
+.PN XSetWMColormapWindows
+can generate
+.PN BadAlloc
+and
+.PN BadWindow
+errors.
+.sp
+.LP
+To read a window's WM_COLORMAP_WINDOWS property, use
+.PN XGetWMColormapWindows .
+.IN "XGetWMColormapWindows" "" "@DEF@"
+.sM
+.FD 0
+Status XGetWMColormapWindows\^(\^\fIdisplay\fP, \fIw\fP, \
+\fIcolormap_windows_return\fP, \fIcount_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      Window **\fIcolormap_windows_return\fP\^;
+.br
+      int *\fIcount_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIcolormap_windows_return\fP 1i
+Returns the list of windows.
+.ds Cn windows in the list
+.IP \fIcount_return\fP 1i
+Returns the number of \*(Cn.
+.LP
+.eM
+The 
+.PN XGetWMColormapWindows 
+function returns the list of window identifiers stored 
+in the WM_COLORMAP_WINDOWS property on the specified window.
+These identifiers indicate the colormaps that the window manager
+may need to install for this window.
+If the property exists, is of type WINDOW, is of format 32, 
+and the atom WM_COLORMAP_WINDOWS can be interned, 
+.PN XGetWMColormapWindows
+sets the windows_return argument to a list of window identifiers, 
+sets the count_return argument to the number of elements in the list, 
+and returns a nonzero status.
+Otherwise, it sets neither of the return arguments
+and returns a zero status.
+To release the list of window identifiers, use
+.PN XFree . 
+.LP
+.PN XGetWMColormapWindows
+can generate a
+.PN BadWindow
+error.
+.NH 3
+Setting and Reading the WM_ICON_SIZE Property
+.XS
+\*(SN Setting and Reading the WM_ICON_SIZE Property
+.XE
+.LP
+Xlib provides functions that you can use to set and read 
+the WM_ICON_SIZE property for a given window.
+These functions use the 
+.PN XIconSize 
+.IN "XIconSize"
+structure, which is defined in the
+.hN X11/Xutil.h
+header file.
+.sp
+.LP
+To allocate an
+.PN XIconSize
+structure, use
+.PN XAllocIconSize .
+.IN "XAllocIconSize" "" "@DEF@"
+.sM
+.FD 0
+XIconSize *XAllocIconSize\^(\|)
+.FN
+.LP
+.eM
+The
+.PN XAllocIconSize 
+function allocates and returns a pointer to an
+.PN XIconSize 
+structure.
+Note that all fields in the
+.PN XIconSize
+structure are initially set to zero.
+If insufficient memory is available, 
+.PN XAllocIconSize
+returns NULL.
+To free the memory allocated to this structure,
+use
+.PN XFree .
+.LP
+The
+.PN XIconSize
+structure contains:
+.LP
+.sM
+.IN "XIconSize" "" "@DEF@"
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	int min_width, min_height;
+	int max_width, max_height;
+	int width_inc, height_inc;
+} XIconSize;
+.De
+.LP
+.eM
+The width_inc and height_inc members define an arithmetic progression of
+sizes (minimum to maximum) that represent the supported icon sizes.
+.LP
+.sp
+To set a window's WM_ICON_SIZE property, use
+.PN XSetIconSizes .
+.IN "XSetIconSizes" "" "@DEF@"
+.sM
+.FD 0
+XSetIconSizes\^(\^\fIdisplay\fP, \fIw\fP, \fIsize_list\fP, \fIcount\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XIconSize *\fIsize_list\fP\^;
+.br
+      int \fIcount\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIsize_list\fP 1i
+Specifies the size list.
+.IP \fIcount\fP 1i
+Specifies the number of items in the size list.
+.LP
+.eM
+The
+.PN XSetIconSizes
+function is used only by window managers to set the supported icon sizes.
+.LP
+.PN XSetIconSizes
+can generate
+.PN BadAlloc
+and
+.PN BadWindow 
+errors.
+.LP
+.sp
+To read a window's WM_ICON_SIZE property, use
+.PN XGetIconSizes .
+.IN "XGetIconSizes" "" "@DEF@"
+.sM
+.FD 0
+Status XGetIconSizes\^(\^\fIdisplay\fP, \fIw\fP, \fIsize_list_return\fP, \fIcount_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XIconSize **\fIsize_list_return\fP\^;
+.br
+      int *\fIcount_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIsize_list_return\fP 1i
+Returns the size list.
+.IP \fIcount_return\fP 1i
+Returns the number of items in the size list.
+.LP
+.eM
+The
+.PN XGetIconSizes
+function returns zero if a window manager has not set icon sizes;
+otherwise, it returns nonzero.
+.PN XGetIconSizes
+should be called by an application that
+wants to find out what icon sizes would be most appreciated by the
+window manager under which the application is running.
+The application
+should then use
+.PN XSetWMHints
+to supply the window manager with an icon pixmap or window in one of the
+supported sizes.
+To free the data allocated in size_list_return, use
+.PN XFree .
+.LP
+.PN XGetIconSizes
+can generate a
+.PN BadWindow 
+error.
+.NH 3
+Using Window Manager Convenience Functions
+.XS
+\*(SN Using Window Manager Convenience Functions
+.XE
+.LP
+The 
+.PN XmbSetWMProperties
+function stores the standard set of window manager properties,
+with text properties in standard encodings
+for internationalized text communication.
+The standard window manager properties for a given window are
+WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS,
+WM_COMMAND, WM_CLIENT_MACHINE, and WM_LOCALE_NAME.
+.IN "XmbSetWMProperties" "" "@DEF@"
+.sM
+.FD 0
+void XmbSetWMProperties\^(\^\fIdisplay\fP\^, \fIw\fP\^, \fIwindow_name\fP\^, \fIicon_name\fP\^, \fIargv\fP\^, \fIargc\fP\^,
+.br
+                      \fInormal_hints\fP\^, \fIwm_hints\fP\^, \fIclass_hints\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      char *\fIwindow_name\fP\^;
+.br
+      char *\fIicon_name\fP\^;
+.br
+      char *\fIargv\fP\^[];
+.br
+      int \fIargc\fP\^;
+.br
+      XSizeHints *\fInormal_hints\fP\^;
+.br
+      XWMHints *\fIwm_hints\fP\^;
+.br
+      XClassHint *\fIclass_hints\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIwindow_name\fP 1i
+Specifies the window name,
+which should be a null-terminated string.
+.IP \fIicon_name\fP 1i
+Specifies the icon name,
+which should be a null-terminated string.
+.IP \fIargv\fP 1i
+Specifies the application's argument list.
+.IP \fIargc\fP 1i
+Specifies the number of arguments.
+.IP \fIhints\fP 1i
+Specifies the size hints for the window in its normal state.
+.IP \fIwm_hints\fP 1i
+Specifies the
+.PN XWMHints
+structure to be used.
+.IP \fIclass_hints\fP 1i
+Specifies the
+.PN XClassHint
+structure to be used.
+.LP
+.eM
+The
+.PN XmbSetWMProperties
+convenience function provides a simple programming interface 
+for setting those essential window properties that are used 
+for communicating with other clients
+(particularly window and session managers).
+.LP
+If the window_name argument is non-NULL,
+.PN XmbSetWMProperties
+sets the WM_NAME property.
+If the icon_name argument is non-NULL,
+.PN XmbSetWMProperties
+sets the WM_ICON_NAME property.
+The window_name and icon_name arguments are null-terminated strings
+in the encoding of the current locale.
+If the arguments can be fully converted to the STRING encoding,
+the properties are created with type ``STRING''; 
+otherwise, the arguments are converted to Compound Text, 
+and the properties are created with type ``COMPOUND_TEXT''.
+.LP
+If the normal_hints argument is non-NULL,
+.PN XmbSetWMProperties
+calls
+.PN XSetWMNormalHints ,
+which sets the WM_NORMAL_HINTS property (see section 14.1.7).
+If the wm_hints argument is non-NULL, 
+.PN XmbSetWMProperties
+calls
+.PN XSetWMHints ,
+which sets the WM_HINTS property (see section 14.1.6).
+.LP
+If the argv argument is non-NULL,
+.PN XmbSetWMProperties
+sets the WM_COMMAND property from argv and argc.
+An argc of zero indicates a zero-length command.
+.LP
+The hostname of the machine is stored using 
+.PN XSetWMClientMachine 
+(see section 14.2.2).
+.LP
+If the class_hints argument is non-NULL,
+.PN XmbSetWMProperties
+sets the WM_CLASS property.
+If the res_name member in the 
+.PN XClassHint
+structure is set to the NULL pointer and the RESOURCE_NAME
+environment variable is set,
+the value of the environment variable is substituted for res_name.
+If the res_name member is NULL,
+the environment variable is not set, and argv and argv[0] are set,
+then the value of argv[0], stripped of any directory prefixes,
+is substituted for res_name.
+.LP
+It is assumed that the supplied class_hints.res_name and argv,
+the RESOURCE_NAME environment variable, and the hostname of the machine
+are in the encoding of the locale announced for the LC_CTYPE category
+(on POSIX-compliant systems, the LC_CTYPE, else LANG environment variable).
+The corresponding WM_CLASS, WM_COMMAND, and WM_CLIENT_MACHINE properties
+are typed according to the local host locale announcer.
+No encoding conversion is performed prior to storage in the properties.
+.LP
+For clients that need to process the property text in a locale,
+.PN XmbSetWMProperties
+sets the WM_LOCALE_NAME property to be the name of the current locale.
+The name is assumed to be in the Host Portable Character Encoding
+and is converted to STRING for storage in the property.
+.LP
+.PN XmbSetWMProperties
+can generate
+.PN BadAlloc
+and
+.PN BadWindow
+errors.
+.sp
+.LP
+To set a window's standard window manager properties
+with strings in client-specified encodings, use
+.PN XSetWMProperties .
+The standard window manager properties for a given window are
+WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS,
+WM_COMMAND, and WM_CLIENT_MACHINE.
+.IN "XSetWMProperties" "" "@DEF@"
+.sM
+.FD 0
+void XSetWMProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIwindow_name\fP, \
+\fIicon_name\fP, \fIargv\fP, \fIargc\fP, \fInormal_hints\fP, \fIwm_hints\fP, \
+\fIclass_hints\fP\^)
+.br
+      Display *\fIdisplay\fP\^; 
+.br
+      Window \fIw\fP\^;
+.br
+      XTextProperty *\fIwindow_name\fP\^;
+.br
+      XTextProperty *\fIicon_name\fP\^;
+.br
+      char **\fIargv\fP\^;
+.br
+      int \fIargc\fP\^;
+.br
+      XSizeHints *\fInormal_hints\fP\^;
+.br
+      XWMHints *\fIwm_hints\fP\^;
+.br
+      XClassHint *\fIclass_hints\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIwindow_name\fP 1i
+Specifies the window name,
+which should be a null-terminated string.
+.IP \fIicon_name\fP 1i
+Specifies the icon name,
+which should be a null-terminated string.
+.IP \fIargv\fP 1i
+Specifies the application's argument list.
+.IP \fIargc\fP 1i
+Specifies the number of arguments.
+.IP \fInormal_hints\fP 1i
+Specifies the size hints for the window in its normal state.
+.IP \fIwm_hints\fP 1i
+Specifies the
+.PN XWMHints
+structure to be used.
+.IP \fIclass_hints\fP 1i
+Specifies the
+.PN XClassHint
+structure to be used.
+.LP
+.eM
+The 
+.PN XSetWMProperties 
+convenience function provides a single programming interface 
+for setting those essential window properties that are used 
+for communicating with other clients (particularly window and session
+managers).
+.LP
+If the window_name argument is non-NULL, 
+.PN XSetWMProperties
+calls
+.PN XSetWMName ,
+which, in turn, sets the WM_NAME property (see section 14.1.4).
+If the icon_name argument is non-NULL,
+.PN XSetWMProperties
+calls
+.PN XSetWMIconName ,
+which sets the WM_ICON_NAME property (see section 14.1.5).
+If the argv argument is non-NULL, 
+.PN XSetWMProperties
+calls
+.PN XSetCommand ,
+which sets the WM_COMMAND property (see section 14.2.1).
+Note that an argc of zero is allowed to indicate a zero-length command.
+Note also that the hostname of this machine is stored using
+.PN XSetWMClientMachine 
+(see section 14.2.2).
+.LP
+If the normal_hints argument is non-NULL, 
+.PN XSetWMProperties
+calls
+.PN XSetWMNormalHints ,
+which sets the WM_NORMAL_HINTS property (see section 14.1.7).
+If the wm_hints argument is non-NULL, 
+.PN XSetWMProperties
+calls
+.PN XSetWMHints ,
+which sets the WM_HINTS property (see section 14.1.6).
+.LP
+If the class_hints argument is non-NULL, 
+.PN XSetWMProperties
+calls
+.PN XSetClassHint ,
+which sets the WM_CLASS property (see section 14.1.8).
+If the res_name member in the
+.PN XClassHint
+structure is set to the NULL pointer and the RESOURCE_NAME environment 
+variable is set, 
+then the value of the environment variable is substituted for res_name.
+If the res_name member is NULL, 
+the environment variable is not set, 
+and argv and argv[0] are set, 
+then the value of argv[0], stripped of
+any directory prefixes, is substituted for res_name.
+.LP
+.PN XSetWMProperties
+can generate
+.PN BadAlloc
+and
+.PN BadWindow
+errors.
+.NH 2
+Client to Session Manager Communication
+.XS
+\*(SN Client to Session Manager Communication
+.XE
+.LP
+This section discusses how to:
+.IP \(bu 5
+Set and read the WM_COMMAND property
+.IP \(bu 5
+Set and read the WM_CLIENT_MACHINE property
+.NH 3
+Setting and Reading the WM_COMMAND Property
+.XS
+\*(SN Setting and Reading the WM_COMMAND Property
+.XE
+.LP
+Xlib provides functions that you can use to set and read
+the WM_COMMAND property for a given window.
+.sp
+.LP
+To set a window's WM_COMMAND property, use
+.PN XSetCommand .
+.IN "XSetCommand" "" "@DEF@"
+.sM
+.FD 0
+XSetCommand\^(\^\fIdisplay\fP, \fIw\fP, \fIargv\fP, \fIargc\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      char **\fIargv\fP\^;
+.br
+      int \fIargc\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIargv\fP 1i
+Specifies the application's argument list.
+.IP \fIargc\fP 1i
+Specifies the number of arguments.
+.LP
+.eM
+The
+.PN XSetCommand
+function sets the command and arguments used to invoke the
+application.
+(Typically, argv is the argv array of your main program.)
+If the strings are not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+.LP
+.PN XSetCommand
+can generate
+.PN BadAlloc
+and
+.PN BadWindow 
+errors.
+.sp
+.LP
+To read a window's WM_COMMAND property, use
+.PN XGetCommand .
+.IN "XGetCommand" "" "@DEF@"
+.sM
+.FD 0
+Status XGetCommand\^(\^\fIdisplay\fP, \fIw\fP, \fIargv_return\fP, \
+\fIargc_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      char ***\fIargv_return\fP\^;
+.br
+      int *\fIargc_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIargv_return\fP 1i
+Returns the application's argument list.
+.IP \fIargc_return\fP 1i
+Returns the number of arguments returned.
+.LP
+.eM
+The 
+.PN XGetCommand 
+function reads the WM_COMMAND property from the specified window 
+and returns a string list.
+If the WM_COMMAND property exists, 
+it is of type STRING and format 8.
+If sufficient memory can be allocated to contain the string list, 
+.PN XGetCommand
+fills in the argv_return and argc_return arguments
+and returns a nonzero status.
+Otherwise, it returns a zero status.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned strings are in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+To free the memory allocated to the string list, use
+.PN XFreeStringList .
+.NH 3
+Setting and Reading the WM_CLIENT_MACHINE Property
+.XS
+\*(SN Setting and Reading the WM_CLIENT_MACHINE Property
+.XE
+.LP
+Xlib provides functions that you can use to set and read 
+the WM_CLIENT_MACHINE property for a given window.
+.sp
+.LP
+To set a window's WM_CLIENT_MACHINE property, use
+.PN XSetWMClientMachine .
+.IN "XSetWMClientMachine" "" "@DEF@"
+.sM
+.FD 0
+void XSetWMClientMachine\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XTextProperty *\fItext_prop\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fItext_prop\fP 1i
+Specifies the
+.PN XTextProperty
+structure to be used.
+.LP
+.eM
+The
+.PN XSetWMClientMachine
+convenience function calls
+.PN XSetTextProperty
+to set the WM_CLIENT_MACHINE property.
+.sp
+.LP
+To read a window's WM_CLIENT_MACHINE property, use
+.PN XGetWMClientMachine .
+.IN "XGetWMClientMachine" "" "@DEF@"
+.sM
+.FD 0
+Status XGetWMClientMachine\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XTextProperty *\fItext_prop_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fItext_prop_return\fP 1i
+Returns the
+.PN XTextProperty
+structure.
+.LP
+.eM
+The
+.PN XGetWMClientMachine
+convenience function performs an 
+.PN XGetTextProperty 
+on the WM_CLIENT_MACHINE property.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+.NH 2
+Standard Colormaps
+.XS
+\*(SN Standard Colormaps 
+.XE
+.LP
+Applications with color palettes, smooth-shaded drawings, or digitized
+images demand large numbers of colors.  
+In addition, these applications often require an efficient mapping 
+from color triples to pixel values that display the appropriate colors.
+.LP
+As an example, consider a three-dimensional display program that wants 
+to draw a smoothly shaded sphere.  
+At each pixel in the image of the sphere, 
+the program computes the intensity and color of light
+reflected back to the viewer.  
+The result of each computation is a triple of red, green, and blue (RGB)
+coefficients in the range 0.0 to 1.0.  
+To draw the sphere, the program needs a colormap that provides a
+large range of uniformly distributed colors.  
+The colormap should be arranged so that the program can
+convert its RGB triples into pixel values very quickly,
+because drawing the entire sphere requires many such
+conversions.
+.LP
+On many current workstations,
+the display is limited to 256 or fewer colors.  
+Applications must allocate colors carefully, 
+not only to make sure they cover the entire range they need 
+but also to make use of as many of the available colors as possible.
+On a typical X display, 
+many applications are active at once.
+Most workstations have only one hardware look-up table for colors,
+so only one application colormap can be installed at a given time.
+The application using the installed colormap is displayed correctly, 
+and the other applications go technicolor and are
+displayed with false colors.
+.LP
+As another example, consider a user who is running an 
+image processing program to display earth-resources data.  
+The image processing program needs a colormap set up with 8 reds, 
+8 greens, and 4 blues, for a total of 256 colors.
+Because some colors are already in use in the default colormap, 
+the image processing program allocates and installs a new colormap.
+.LP
+The user decides to alter some of the colors in the image
+by invoking a color palette program to mix and choose colors.
+The color palette program also needs a
+colormap with eight reds, eight greens, and four blues, so just like
+the image processing program, it must allocate and
+install a new colormap.
+.LP
+Because only one colormap can be installed at a time,
+the color palette may be displayed incorrectly
+whenever the image processing program is active.
+Conversely, whenever the palette program is active, 
+the image may be displayed incorrectly.  
+The user can never match or compare colors in the palette and image.
+Contention for colormap resources can be reduced if applications
+with similar color needs share colormaps.
+.LP
+The image processing program and the color palette program 
+could share the same colormap if there existed a convention that described
+how the colormap was set up.  
+Whenever either program was active, 
+both would be displayed correctly.
+.LP
+The standard colormap properties define a set of commonly used
+colormaps.  
+Applications that share these colormaps and conventions display 
+true colors more often and provide a better interface to the user.
+.LP
+Standard colormaps allow applications to share commonly used color
+resources.  
+This allows many applications to be displayed in true colors
+simultaneously, even when each application needs an entirely filled
+colormap.
+.LP
+Several standard colormaps are described in this section.
+Usually, a window manager creates these colormaps.
+Applications should use the standard colormaps if they already exist.
+.sp
+.LP
+To allocate an
+.PN XStandardColormap
+structure, use
+.PN XAllocStandardColormap .
+.IN "XAllocStandardColormap" "" "@DEF@"
+.sM
+.FD 0
+XStandardColormap *XAllocStandardColormap\^(\|)
+.FN
+.LP
+.eM
+The
+.PN XAllocStandardColormap
+function allocates and returns a pointer to an
+.PN XStandardColormap
+structure.
+Note that all fields in the
+.PN XStandardColormap
+structure are initially set to zero.
+If insufficient memory is available, 
+.PN XAllocStandardColormap
+returns NULL.
+To free the memory allocated to this structure,
+use
+.PN XFree .
+.LP
+The 
+.PN XStandardColormap 
+structure contains:
+.LP
+.sM
+/* Hints */
+.TS
+lw(.5i) lw(2i) lw(1i).
+T{
+#define
+T}	T{
+.PN ReleaseByFreeingColormap
+T}	T{
+( (XID) 1L)
+T}
+.TE
+/* Values */
+.IN "XStandardColormap" "" "@DEF@"
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	Colormap colormap;
+	unsigned long red_max;
+	unsigned long red_mult;
+	unsigned long green_max;
+	unsigned long green_mult;
+	unsigned long blue_max;
+	unsigned long blue_mult;
+	unsigned long base_pixel;
+	VisualID visualid;
+	XID killid;
+} XStandardColormap;
+.De
+.LP
+.eM
+The colormap member is the colormap created by the
+.PN XCreateColormap
+function.
+The red_max, green_max, and blue_max members give the maximum
+red, green, and blue values, respectively.  
+Each color coefficient ranges from zero to its max, inclusive.  
+For example,
+a common colormap allocation is 3/3/2 (3 planes for red, 3
+planes for green, and 2 planes for blue).  
+This colormap would have red_max = 7, green_max = 7, 
+and blue_max = 3.  
+An alternate allocation that uses only 216 colors is red_max = 5, 
+green_max = 5, and blue_max = 5.
+.LP
+The red_mult, green_mult, and blue_mult members give the
+scale factors used to compose a full pixel value. 
+(See the discussion of the base_pixel members for further information.)
+For a 3/3/2 allocation, red_mult might be 32,
+green_mult might be 4, and blue_mult might be 1.  
+For a 6-colors-each allocation, red_mult might be 36, 
+green_mult might be 6, and blue_mult might be 1.
+.LP
+The base_pixel member gives the base pixel value used to
+compose a full pixel value.  
+Usually, the base_pixel is obtained from a call to the 
+.PN XAllocColorPlanes
+function.  
+Given integer red, green, and blue coefficients in their appropriate 
+ranges, one then can compute a corresponding pixel value by
+using the following expression:
+.LP
+.Ds
+.TA .5i 1.5i
+.ta .5i 1.5i
+(r * red_mult + g * green_mult + b * blue_mult + base_pixel) & 0xFFFFFFFF
+.De
+.LP
+For 
+.PN GrayScale
+colormaps, 
+only the colormap, red_max, red_mult, 
+and base_pixel members are defined. 
+The other members are ignored.  
+To compute a 
+.PN GrayScale 
+pixel value, use the following expression:
+.LP
+.Ds
+.TA .5i 1.5i
+.ta .5i 1.5i
+(gray * red_mult + base_pixel) & 0xFFFFFFFF
+.De
+.LP
+Negative multipliers can be represented by converting the 2's
+complement representation of the multiplier into an unsigned long and
+storing the result in the appropriate _mult field.
+The step of masking by 0xFFFFFFFF effectively converts the resulting
+positive multiplier into a negative one.
+The masking step will take place automatically on many machine architectures,
+depending on the size of the integer type used to do the computation.
+.LP
+The visualid member gives the ID number of the visual from which the
+colormap was created.
+The killid member gives a resource ID that indicates whether
+the cells held by this standard colormap are to be released 
+by freeing the colormap ID or by calling the
+.PN XKillClient
+function on the indicated resource.
+(Note that this method is necessary for allocating out of an existing colormap.)
+.LP
+The properties containing the 
+.PN XStandardColormap 
+information have 
+the type RGB_COLOR_MAP.
+.LP
+The remainder of this section discusses standard colormap properties and atoms
+as well as how to manipulate standard colormaps.
+.NH 3
+Standard Colormap Properties and Atoms
+.XS
+\*(SN Standard Colormap Properties and Atoms 
+.XE
+.LP
+.IN "Standard Colormaps"
+.IN "Colormaps" "standard"
+Several standard colormaps are available.  
+Each standard colormap is defined by a property, 
+and each such property is identified by an atom.  
+The following list names the atoms and describes the colormap
+associated with each one.
+The
+.hN X11/Xatom.h
+header file contains the definitions for each of the following atoms,
+which are prefixed with XA_.
+.IP RGB_DEFAULT_MAP 5
+This atom names a property.
+The value of the property is an array of
+.PN XStandardColormap
+structures.
+Each entry in the array describes an RGB subset of the default color
+map for the Visual specified by visual_id.
+.IP
+Some applications only need a few RGB colors and
+may be able to allocate them from the system default colormap.
+This is the ideal situation because the fewer colormaps that are
+active in the system the more applications are displayed
+with correct colors at all times.
+.IP
+A typical allocation for the RGB_DEFAULT_MAP on 8-plane displays
+is 6 reds, 6 greens, and 6 blues.  
+This gives 216 uniformly distributed colors 
+(6 intensities of 36 different hues) and still leaves 40 elements 
+of a 256-element colormap available for special-purpose colors 
+for text, borders, and so on.
+.IP RGB_BEST_MAP 5
+.br
+This atom names a property.
+The value of the property is an 
+.PN XStandardColormap .
+.IP 
+The property defines the best RGB colormap available on
+the screen.
+(Of course, this is a subjective evaluation.)
+Many image processing and three-dimensional applications need to
+use all available colormap cells and to distribute as many
+perceptually distinct colors as possible over those cells.
+This implies that there may be more green values available than
+red, as well as more green or red than blue.
+.IP
+For an 8-plane 
+.PN PseudoColor 
+visual, 
+RGB_BEST_MAP is likely to be a 3/3/2 allocation.  
+For a 24-plane 
+.PN DirectColor 
+visual, 
+RGB_BEST_MAP is normally an 8/8/8 allocation.  
+.IP RGB_RED_MAP 5
+.br
+.ns
+.IP RGB_GREEN_MAP 5
+.br
+.ns
+.IP RGB_BLUE_MAP 5
+These atoms name properties.
+The value of each property is an
+.PN XStandardColormap . 
+.IP
+The properties define all-red, all-green, and all-blue
+colormaps, respectively.  
+These maps are used by applications that want to make color-separated 
+images.  
+For example, a user might generate a full-color image 
+on an 8-plane display both by rendering an image three times 
+(once with high color resolution in red, once with green, 
+and once with blue) and by multiply exposing a single frame in a camera.
+.IP RGB_GRAY_MAP 5
+This atom names a property.
+The value of the property is an 
+.PN XStandardColormap .
+.IP
+The property describes the best 
+.PN GrayScale 
+colormap available on the screen.  
+As previously mentioned, 
+only the colormap, red_max, red_mult, and base_pixel members of the
+.PN XStandardColormap 
+structure are used for 
+.PN GrayScale 
+colormaps.
+.NH 3
+Setting and Obtaining Standard Colormaps
+.XS
+\*(SN Setting and Obtaining Standard Colormaps
+.XE
+.LP
+Xlib provides functions that you can use to set and obtain an
+.PN XStandardColormap
+structure.
+.sp
+.LP
+To set an
+.PN XStandardColormap
+structure, use
+.PN XSetRGBColormaps .
+.IN "XSetRGBColormaps" "" "@DEF@"
+.sM
+.FD 0
+void XSetRGBColormaps\^(\^\fIdisplay\fP, \fIw\fP, \fIstd_colormap\fP, \
+\fIcount\fP, \fIproperty\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XStandardColormap *\fIstd_colormap\fP\^;
+.br
+      int \fIcount\fP\^;
+.br
+      Atom \fIproperty\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIstd_colormap\fP 1i
+Specifies the
+.PN XStandardColormap
+structure to be used.
+.ds Cn colormaps
+.IP \fIcount\fP 1i
+Specifies the number of \*(Cn.
+.IP \fIproperty\fP 1i
+Specifies the property name.
+.LP
+.eM
+The 
+.PN XSetRGBColormaps 
+function replaces the RGB colormap definition in the specified property 
+on the named window.
+If the property does not already exist,
+.PN XSetRGBColormaps
+sets the RGB colormap definition in the specified property
+on the named window.
+The property is stored with a type of RGB_COLOR_MAP and a format of 32.
+Note that it is the caller's responsibility to honor the ICCCM
+restriction that only RGB_DEFAULT_MAP contain more than one definition.
+.LP
+The
+.PN XSetRGBColormaps
+function usually is only used by window or session managers.
+To create a standard colormap, 
+follow this procedure:
+.IP 1. 5
+Open a new connection to the same server.
+.IP 2. 5
+Grab the server.
+.IP 3. 5
+See if the property is on the property list of the root window for the screen.
+.IP 4. 5
+If the desired property is not present:
+.RS
+.IP \(bu 5
+Create a colormap (unless you are using the default colormap of the screen).
+.IP \(bu 5
+Determine the color characteristics of the visual.
+.IP \(bu 5
+Allocate cells in the colormap (or create it with
+.PN AllocAll ).
+.IP \(bu 5
+Call 
+.PN XStoreColors
+to store appropriate color values in the colormap.
+.IP \(bu 5
+Fill in the descriptive members in the 
+.PN XStandardColormap
+structure.
+.IP \(bu 5
+Attach the property to the root window.
+.IP \(bu 5
+Use
+.PN XSetCloseDownMode
+to make the resource permanent.
+.RE
+.IP 5. 5
+Ungrab the server.
+.LP
+.PN XSetRGBColormaps
+can generate
+.PN BadAlloc ,
+.PN BadAtom ,
+and
+.PN BadWindow
+errors.
+.sp
+.LP
+To obtain the 
+.PN XStandardColormap 
+structure associated with the specified property, use
+.PN XGetRGBColormaps .
+.IN "XGetRGBColormaps" "" "@DEF@"
+.sM
+.FD 0
+Status XGetRGBColormaps\^(\^\fIdisplay\fP, \fIw\fP, \fIstd_colormap_return\fP, \
+\fIcount_return\fP, \fIproperty\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Window \fIw\fP\^;
+.br
+      XStandardColormap **\fIstd_colormap_return\fP\^;
+.br
+      int *\fIcount_return\fP\^;
+.br
+      Atom \fIproperty\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIw\fP 1i
+Specifies the window.
+.IP \fIstd_colormap_return\fP 1i
+Returns the
+.PN XStandardColormap
+structure.
+.ds Cn colormaps
+.IP \fIcount_return\fP 1i
+Returns the number of \*(Cn.
+.IP \fIproperty\fP 1i
+Specifies the property name.
+.LP
+.eM
+The 
+.PN XGetRGBColormaps
+function returns the RGB colormap definitions stored 
+in the specified property on the named window.
+If the property exists, is of type RGB_COLOR_MAP, is of format 32, 
+and is long enough to contain a colormap definition,
+.PN XGetRGBColormaps
+allocates and fills in space for the returned colormaps
+and returns a nonzero status.
+If the visualid is not present, 
+.PN XGetRGBColormaps 
+assumes the default visual for the screen on which the window is located; 
+if the killid is not present, 
+.PN None
+is assumed, which indicates that the resources cannot be released.
+Otherwise, 
+none of the fields are set, and 
+.PN XGetRGBColormaps
+returns a zero status.
+Note that it is the caller's responsibility to honor the ICCCM
+restriction that only RGB_DEFAULT_MAP contain more than one definition.
+.LP
+.PN XGetRGBColormaps
+can generate
+.PN BadAtom
+and
+.PN BadWindow
+errors.
+.bp
diff --git a/specs/libX11/CH15 b/specs/libX11/CH15
new file mode 100644
index 00000000..a10df0a5
--- /dev/null
+++ b/specs/libX11/CH15
@@ -0,0 +1,1628 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 15\fP\s-1
+
+\s+1\fBResource Manager Functions\fP\s-1
+.sp 2
+.nr H1 15
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.na
+.LP
+.XS
+Chapter 15: Resource Manager Functions
+.XE
+A program often needs a variety of options in the X environment
+(for example, fonts, colors, icons, and cursors).
+Specifying all of these options on the command line is awkward
+because users may want to customize many aspects of the program
+and need a convenient way to establish these customizations as
+the default settings.
+The resource manager is provided for this purpose.
+Resource specifications are usually stored in human-readable files
+and in server properties.
+.LP
+The resource manager is a database manager with a twist.
+In most database systems, 
+you perform a query using an imprecise specification,
+and you get back a set of records.
+The resource manager, however, allows you to specify a large
+set of values with an imprecise specification, to query the database 
+with a precise specification, and to get back only a single value.
+This should be used by applications that need to know what the
+user prefers for colors, fonts, and other resources.
+It is this use as a database for dealing with X resources that
+inspired the name ``Resource Manager,''
+although the resource manager can be and is used in other ways.
+.LP
+For example, 
+a user of your application may want to specify 
+that all windows should have a blue background 
+but that all mail-reading windows should have a red background.
+With well-engineered and coordinated applications,
+a user can define this information using only two lines of specifications.
+.LP
+As an example of how the resource manager works,
+consider a mail-reading application called xmh.
+Assume that it is designed so that it uses a
+complex window hierarchy all the way down to individual command buttons,
+which may be actual small subwindows in some toolkits.
+These are often called objects or widgets.
+In such toolkit systems,
+each user interface object can be composed of other objects
+and can be assigned a name and a class.
+Fully qualified names or classes can have arbitrary numbers of component names,
+but a fully qualified name always has the same number of component names as a
+fully qualified class.
+This generally reflects the structure of the application as composed
+of these objects, starting with the application itself.
+.LP
+For example, the xmh mail program has a name ``xmh'' and is one
+of a class of ``Mail'' programs.
+By convention, the first character of class components is capitalized,
+and the first letter of name components is in lowercase.
+Each name and class finally has an attribute
+(for example, ``foreground'' or ``font'').
+If each window is properly assigned a name and class,
+it is easy for the user to specify attributes of any portion 
+of the application.
+.LP
+At the top level, 
+the application might consist of a paned window (that is, a window divided
+into several sections) named ``toc''.
+One pane of the paned window is a button box window named ``buttons''
+and is filled with command buttons. 
+One of these command buttons is used to incorporate
+new mail and has the name ``incorporate''.
+This window has a fully qualified name, ``xmh.toc.buttons.incorporate'',
+and a fully qualified class, ``Xmh.Paned.Box.Command''.
+Its fully qualified name is the name of its parent, ``xmh.toc.buttons'', 
+followed by its name, ``incorporate''.
+Its class is the class of its parent, ``Xmh.Paned.Box'', 
+followed by its particular class, ``Command''.  
+The fully qualified name of a resource is
+the attribute's name appended to the object's fully qualified
+name, and the fully qualified class is its class appended to the object's
+class.
+.LP
+The incorporate button might need the following resources: 
+Title string,
+Font,
+Foreground color for its inactive state,
+Background color for its inactive state,
+Foreground color for its active state, and
+Background color for its active state.
+Each resource is considered
+to be an attribute of the button and, as such, has a name and a class.
+For example, the foreground color for the button in
+its active state might be named ``activeForeground'',
+and its class might be ``Foreground''.
+.LP
+When an application looks up a resource (for example, a color),
+it passes the complete name and complete class of the resource
+to a look-up routine.
+The resource manager compares this complete specification
+against the incomplete specifications of entries in the resource
+database, finds the best match, and returns the corresponding
+value for that entry.
+.LP
+The definitions for the resource manager are contained in
+.hN X11/Xresource.h .
+.NH 2
+Resource File Syntax
+.XS
+\*(SN Resource File Syntax
+.XE
+.LP
+The syntax of a resource file is a sequence of resource lines
+terminated by newline characters or the end of the file.
+The syntax of an individual resource line is:
+.LP
+.\" Start marker code here
+.Ds 0
+.TA 1.5i 1.75i
+.ta 1.5i 1.75i
+ResourceLine	=	Comment | IncludeFile | ResourceSpec | <empty line>
+Comment	=	"!" {<any character except null or newline>}
+IncludeFile	=	"#" WhiteSpace "include" WhiteSpace FileName WhiteSpace
+FileName	=	<valid filename for operating system>
+ResourceSpec	=	WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value
+ResourceName	=	[Binding] {Component Binding} ComponentName
+Binding	=	"\&." | "*"
+WhiteSpace	=	{<space> | <horizontal tab>}
+Component	=	"?" | ComponentName
+ComponentName	=	NameChar {NameChar}
+NameChar	=	"a"\-"z" | "A"\-"Z" | "0"\-"9" | "_" | "-"
+Value	=	{<any character except null or unescaped newline>}
+.De
+.\" End marker code here
+.LP
+Elements separated by vertical bar (|) are alternatives.
+Curly braces ({\&.\&.\&.}) indicate zero or more repetitions
+of the enclosed elements.
+Square brackets ([\&.\&.\&.]) indicate that the enclosed element is optional.
+Quotes ("\&.\&.\&.") are used around literal characters.
+.LP
+IncludeFile lines are interpreted by replacing the line with the
+contents of the specified file.
+The word ``include'' must be in lowercase.
+The file name is interpreted relative to the directory of the file in
+which the line occurs (for example, if the file name contains no
+directory or contains a relative directory specification).
+.LP
+If a ResourceName contains a contiguous sequence of two or more Binding
+characters, the sequence will be replaced with a single ``\&.'' character
+if the sequence contains only ``\&.'' characters;
+otherwise, the sequence will be replaced with a single ``*'' character.
+.LP
+A resource database never contains more than one entry for a given
+ResourceName.  If a resource file contains multiple lines with the
+same ResourceName, the last line in the file is used.
+.LP
+Any white space characters before or after the name or colon in a ResourceSpec
+are ignored.
+To allow a Value to begin with white space,
+the two-character sequence ``\^\\\^\fIspace\fP'' (backslash followed by space)
+is recognized and replaced by a space character,
+and the two-character sequence ``\^\\\^\fItab\fP''
+(backslash followed by horizontal tab)
+is recognized and replaced by a horizontal tab character.
+To allow a Value to contain embedded newline characters,
+the two-character sequence ``\^\\\^n'' is recognized and replaced by a
+newline character.
+To allow a Value to be broken across multiple lines in a text file,
+the two-character sequence ``\^\\\^\fInewline\fP''
+(backslash followed by newline) is
+recognized and removed from the value.
+To allow a Value to contain arbitrary character codes,
+the four-character sequence ``\^\\\^\fInnn\fP'',
+where each \fIn\fP is a digit character in the range of ``0''\^\-``7'',
+is recognized and replaced with a single byte that contains
+the octal value specified by the sequence.
+Finally, the two-character sequence ``\^\\\\'' is recognized
+and replaced with a single backslash.
+.LP
+As an example of these sequences,
+the following resource line contains a value consisting of four
+characters: a backslash, a null, a ``z'', and a newline:
+.Ds 
+magic.values: \\\\\\\^000\^\\
+z\\\^n
+.De
+.NH 2
+Resource Manager Matching Rules
+.XS
+\*(SN Resource Manager Matching Rules
+.XE
+.LP
+The algorithm for determining which resource database entry
+matches a given query is the heart of the resource manager.
+All queries must fully specify the name and class of the desired resource
+(use of the characters ``*'' and ``?'' is not permitted).
+The library supports up to 100 components in a full name or class.
+Resources are stored in the database with only partially specified
+names and classes, using pattern matching constructs.
+An asterisk (*) is a loose binding and is used to represent any number
+of intervening components, including none.
+A period (.) is a tight binding and is used to separate immediately
+adjacent components.
+A question mark (?) is used to match any single component name or class.
+A database entry cannot end in a loose binding;
+the final component (which cannot be the character ``?'') must be specified.
+The lookup algorithm searches the database for the entry that most
+closely matches (is most specific for) the full name and class being queried.
+When more than one database entry matches the full name and class,
+precedence rules are used to select just one.
+.LP
+The full name and class are scanned from left to right (from highest
+level in the hierarchy to lowest), one component at a time.
+At each level, the corresponding component and/or binding of each
+matching entry is determined, and these matching components and
+bindings are compared according to precedence rules.
+Each of the rules is applied at each level before moving to the next level,
+until a rule selects a single entry over all others.
+The rules, in order of precedence, are:
+.IP 1. 5
+An entry that contains a matching component (whether name, class,
+or the character ``?'')
+takes precedence over entries that elide the level (that is, entries
+that match the level in a loose binding).
+.IP 2. 5
+An entry with a matching name takes precedence over both
+entries with a matching class and entries that match using the character ``?''.
+An entry with a matching class takes precedence over
+entries that match using the character ``?''.
+.IP 3. 5
+An entry preceded by a tight binding takes precedence over entries
+preceded by a loose binding.
+.LP
+To illustrate these rules,
+consider the following resource database entries:
+.Ds 
+.TA 2.5i 3.5i
+.ta 2.5i 3.5i
+xmh*Paned*activeForeground:	red	\fI(entry A)\fP
+*incorporate.Foreground:	blue	\fI(entry B)\fP
+xmh.toc*Command*activeForeground:	green	\fI(entry C)\fP
+xmh.toc*?.Foreground:	white	\fI(entry D)\fP
+xmh.toc*Command.activeForeground:	black	\fI(entry E)\fP
+.De
+.LP
+Consider a query for the resource:
+.LP
+.Ds 
+.TA 3.5i
+.ta 3.5i
+xmh.toc.messagefunctions.incorporate.activeForeground	\fI(name)\fP
+Xmh.Paned.Box.Command.Foreground	\fI(class)\fP
+.De
+.LP
+At the first level (xmh, Xmh), rule 1 eliminates entry B.
+At the second level (toc, Paned), rule 2 eliminates entry A.
+At the third level (messagefunctions, Box), no entries are eliminated.
+At the fourth level (incorporate, Command), rule 2 eliminates entry D.
+At the fifth level (activeForeground, Foreground), rule 3 eliminates entry C.
+.NH 2
+Quarks
+.XS
+\*(SN Quarks
+.XE
+.LP
+Most uses of the resource manager involve defining names,
+classes, and representation types as string constants.
+However, always referring to strings in the resource manager can be slow,
+because it is so heavily used in some toolkits.
+To solve this problem, 
+a shorthand for a string is used in place of the string
+in many of the resource manager functions.
+Simple comparisons can be performed rather than string comparisons.
+The shorthand name for a string is called a quark and is the
+type 
+.PN XrmQuark .
+On some occasions,
+you may want to allocate a quark that has no string equivalent.
+.LP
+A quark is to a string what an atom is to a string in the server,
+but its use is entirely local to your application.
+.LP
+.sp
+To allocate a new quark, use
+.PN XrmUniqueQuark .
+.IN "XrmUniqueQuark" "" "@DEF@"
+.sM
+.FD 0
+XrmQuark XrmUniqueQuark\^(\|)
+.FN
+.LP
+.eM
+The
+.PN XrmUniqueQuark
+function allocates a quark that is guaranteed not to represent any string that
+is known to the resource manager.
+.LP
+.sp
+Each name, class, and representation type is typedef'd as an
+.PN XrmQuark .
+.LP
+.sM
+.Ds 0
+typedef int XrmQuark, *XrmQuarkList;
+typedef XrmQuark XrmName;
+typedef XrmQuark XrmClass;
+typedef XrmQuark XrmRepresentation;
+#define NULLQUARK ((XrmQuark) 0)
+.De
+.LP
+.eM
+Lists are represented as null-terminated arrays of quarks.
+The size of the array must be large enough for the number of components used.
+.LP
+.sM
+.Ds 0
+typedef XrmQuarkList XrmNameList;
+typedef XrmQuarkList XrmClassList;
+.De
+.LP
+.eM
+.sp
+To convert a string to a quark, use
+.PN XrmStringToQuark
+or
+.PN XrmPermStringToQuark .
+.IN "XrmStringToQuark" "" "@DEF@"
+.IN "XrmPermStringToQuark" "" "@DEF@"
+.sM
+.FD 0
+#define XrmStringToName(string) XrmStringToQuark(string)
+#define XrmStringToClass(string) XrmStringToQuark(string)
+#define XrmStringToRepresentation(string) XrmStringToQuark(string)
+.sp
+XrmQuark XrmStringToQuark\^(\^\fIstring\fP\^)
+.br
+     char *\fIstring\fP\^;
+.sp
+XrmQuark XrmPermStringToQuark\^(\^\fIstring\fP\^)
+.br
+     char *\fIstring\fP\^;
+.FN
+.ds Ql
+.IP \fIstring\fP 1i
+Specifies the string for which a quark\*(Ql is to be allocated.
+.LP
+.eM
+These functions can be used to convert from string to quark representation.
+If the string is not in the Host Portable Character Encoding,
+the conversion is implementation-dependent.
+The string argument to
+.PN XrmStringToQuark
+need not be permanently allocated storage.
+.PN XrmPermStringToQuark
+is just like
+.PN XrmStringToQuark ,
+except that Xlib is permitted to assume the string argument is permanently
+allocated,
+and, hence, that it can be used as the value to be returned by
+.PN XrmQuarkToString .
+.LP
+For any given quark, if
+.PN XrmStringToQuark
+returns a non-NULL value,
+all future calls will return the same value (identical address).
+.LP
+.sp
+To convert a quark to a string, use 
+.PN XrmQuarkToString .
+.IN "XrmQuarkToString" "" "@DEF@"
+.sM
+.FD 0
+#define XrmNameToString(name) XrmQuarkToString(name)
+#define XrmClassToString(class) XrmQuarkToString(class)
+#define XrmRepresentationToString(type) XrmQuarkToString(type)
+.sp
+char *XrmQuarkToString\^(\^\fIquark\fP\^)
+.br
+     XrmQuark \fIquark\fP\^;
+.FN
+.IP \fIquark\fP 1i
+Specifies the quark for which the equivalent string is desired.
+.LP
+.eM
+These functions can be used to convert from quark representation to string.
+The string pointed to by the return value must not be modified or freed.
+The returned string is byte-for-byte equal to the original
+string passed to one of the string-to-quark routines.
+If no string exists for that quark,
+.PN XrmQuarkToString
+returns NULL.
+For any given quark, if
+.PN XrmQuarkToString
+returns a non-NULL value,
+all future calls will return the same value (identical address).
+.LP
+.sp
+To convert a string with one or more components to a quark list, use
+.PN XrmStringToQuarkList .
+.IN "XrmStringToQuarkList" "" "@DEF@"
+.sM
+.FD 0
+#define XrmStringToNameList(str, name)  XrmStringToQuarkList((str), (name))
+#define XrmStringToClassList(str, class) XrmStringToQuarkList((str), (class))
+.sp
+void XrmStringToQuarkList\^(\^\fIstring\fP, \fIquarks_return\fP\^)
+.br
+     char *\fIstring\fP\^;
+.br
+     XrmQuarkList \fIquarks_return\fP\^;
+.FN
+.ds Ql \ list
+.IP \fIstring\fP 1i
+Specifies the string for which a quark\*(Ql is to be allocated.
+.IP \fIquarks_return\fP 1i
+Returns the list of quarks.
+The caller must allocate sufficient space for the quarks list before calling 
+.PN XrmStringToQuarkList .
+.LP
+.eM
+The
+.PN XrmStringToQuarkList
+function converts the null-terminated string (generally a fully qualified name)
+to a list of quarks.
+Note that the string must be in the valid ResourceName format 
+(see section 15.1).
+If the string is not in the Host Portable Character Encoding,
+the conversion is implementation-dependent.
+.LP
+A binding list is a list of type
+.PN XrmBindingList
+and indicates if components of name or class lists are bound tightly or loosely
+(that is, if wildcarding of intermediate components is specified).
+.LP
+.Ds 0
+typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList;
+.De
+.LP
+.PN XrmBindTightly
+indicates that a period separates the components, and
+.PN XrmBindLoosely
+indicates that an asterisk separates the components.
+.LP
+.sp
+To convert a string with one or more components to a binding list
+and a quark list, use
+.PN XrmStringToBindingQuarkList .
+.IN "XrmStringToBindingQuarkList" "" "@DEF@"
+.sM
+.FD 0
+XrmStringToBindingQuarkList\^(\^\fIstring\fP, \fIbindings_return\fP, \
+\fIquarks_return\fP\^)
+.br
+     char *\fIstring\fP\^;
+.br
+     XrmBindingList \fIbindings_return\fP\^;
+.br
+     XrmQuarkList \fIquarks_return\fP\^;
+.FN
+.ds Ql \ list
+.IP \fIstring\fP 1i
+Specifies the string for which a quark\*(Ql is to be allocated.
+.IP \fIbindings_return\fP 1i
+Returns the binding list.
+The caller must allocate sufficient space for the binding list before calling 
+.PN XrmStringToBindingQuarkList .
+.IP \fIquarks_return\fP 1i
+Returns the list of quarks.
+The caller must allocate sufficient space for the quarks list before calling 
+.PN XrmStringToBindingQuarkList .
+.LP
+.eM
+Component names in the list are separated by a period or 
+an asterisk character.
+The string must be in the format of a valid ResourceName (see section 15.1).
+If the string does not start with a period or an asterisk, 
+a tight binding is assumed.
+For example, the string ``*a.b*c'' becomes:
+.LP
+.Ds 0
+.TA .75i 1.5i 2.25i
+.ta .75i 1.5i 2.25i
+quarks:	a	b	c
+bindings:	loose	tight	loose
+.De
+.NH 2
+Creating and Storing Databases
+.XS
+\*(SN Creating and Storing Databases
+.XE
+.LP
+.IN "XrmDatabase" "" "@DEF@"
+A resource database is an opaque type,
+.PN XrmDatabase .
+Each database value is stored in an
+.PN XrmValue 
+structure.
+This structure consists of a size, an address, and a representation type.
+The size is specified in bytes.
+The representation type is a way for you to store data tagged by some 
+application-defined type (for example, the strings ``font'' or ``color'').
+It has nothing to do with the C data type or with its class. 
+The
+.PN XrmValue 
+structure is defined as:
+.LP
+.IN "XrmValue" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+typedef struct {
+	unsigned int size;
+	XPointer addr;
+} XrmValue, *XrmValuePtr;
+.De
+.LP
+.eM
+.sp
+To initialize the resource manager, use
+.PN XrmInitialize .
+.IN "XrmInitialize" "" "@DEF@"
+.sM
+.FD 0
+void XrmInitialize\^(\|);
+.FN
+.LP
+.eM
+To retrieve a database from disk, use
+.PN XrmGetFileDatabase .
+.IN "XrmGetFileDatabase" "" "@DEF@"
+.sM
+.FD 0
+XrmDatabase XrmGetFileDatabase\^(\^\fIfilename\fP\^)
+.br
+     char *\fIfilename\fP\^;
+.FN
+.IP \fIfilename\fP 1i
+Specifies the resource database file name.
+.LP
+.eM
+The
+.PN XrmGetFileDatabase
+function opens the specified file,
+creates a new resource database, and loads it with the specifications
+read in from the specified file.
+The specified file should contain a sequence of entries in valid ResourceLine
+format (see section 15.1); the database that results from reading a file
+with incorrect syntax is implementation-dependent.
+The file is parsed in the current locale, 
+and the database is created in the current locale.
+If it cannot open the specified file,
+.PN XrmGetFileDatabase
+returns NULL.
+.LP
+.sp
+To store a copy of a database to disk, use
+.PN XrmPutFileDatabase .
+.IN "XrmPutFileDatabase" "" "@DEF@"
+.sM
+.FD 0
+void XrmPutFileDatabase\^(\^\fIdatabase\fP, \fIstored_db\fP\^)
+.br
+     XrmDatabase \fIdatabase\fP\^;
+.br
+     char *\fIstored_db\fP\^;
+.FN
+.IP \fIdatabase\fP 1i
+Specifies the database that is to be used.
+.IP \fIstored_db\fP 1i
+Specifies the file name for the stored database.
+.LP
+.eM
+The
+.PN XrmPutFileDatabase
+function stores a copy of the specified database in the specified file.
+Text is written to the file as a sequence of entries in valid
+ResourceLine format (see section 15.1).
+The file is written in the locale of the database.
+Entries containing resource names that are not in the Host Portable Character
+Encoding or containing values that are not in the encoding of the database
+locale, are written in an implementation-dependent manner.
+The order in which entries are written is implementation-dependent.
+Entries with representation types other than ``String'' are ignored.
+.LP
+.sp
+To obtain a pointer to the screen-independent resources of a display, use
+.PN XResourceManagerString .
+.IN "XResourceManagerString" "" "@DEF@"
+.sM
+.FD 0
+char *XResourceManagerString\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+The
+.PN XResourceManagerString
+function returns the RESOURCE_MANAGER property from the server's root
+window of screen zero, which was returned when the connection was opened using
+.PN XOpenDisplay .
+The property is converted from type STRING to the current locale.
+The conversion is identical to that produced by 
+.PN XmbTextPropertyToTextList
+for a single element STRING property.
+The returned string is owned by Xlib and should not be freed by the client.
+The property value must be in a format that is acceptable to
+.PN XrmGetStringDatabase .
+If no property exists, NULL is returned.
+.LP
+.sp
+To obtain a pointer to the screen-specific resources of a screen, use
+.PN XScreenResourceString .
+.IN "XScreenResourceString" "" "@DEF@"
+.sM
+.FD 0
+char *XScreenResourceString\^(\^\fIscreen\fP\^)
+.br
+      Screen *\fIscreen\fP\^;
+.FN
+.IP \fIscreen\fP 1i
+Specifies the screen.
+.LP
+.eM
+The
+.PN XScreenResourceString
+function returns the SCREEN_RESOURCES property from the root window of the
+specified screen.
+The property is converted from type STRING to the current locale.
+The conversion is identical to that produced by 
+.PN XmbTextPropertyToTextList
+for a single element STRING property.
+The property value must be in a format that is acceptable to
+.PN XrmGetStringDatabase .
+If no property exists, NULL is returned.
+The caller is responsible for freeing the returned string by using
+.PN XFree .
+.LP
+.sp
+To create a database from a string, use
+.PN XrmGetStringDatabase .
+.IN "XrmGetStringDatabase" "" "@DEF@"
+.sM
+.FD 0
+XrmDatabase XrmGetStringDatabase\^(\^\fIdata\fP\^)
+.br
+     char *\fIdata\fP\^;
+.FN
+.IP \fIdata\fP 1i
+Specifies the database contents using a string.
+.LP
+.eM
+The
+.PN XrmGetStringDatabase
+function creates a new database and stores the resources specified
+in the specified null-terminated string.
+.PN XrmGetStringDatabase
+is similar to
+.PN XrmGetFileDatabase
+except that it reads the information out of a string instead of out of a file.
+The string should contain a sequence of entries in valid ResourceLine
+format (see section 15.1) terminated by a null character;
+the database that results from using a string
+with incorrect syntax is implementation-dependent.
+The string is parsed in the current locale, 
+and the database is created in the current locale.
+.LP
+.sp
+To obtain the locale name of a database, use
+.PN XrmLocaleOfDatabase .
+.IN "XrmLocaleOfDatabase" "" "@DEF@"
+.sM
+.FD 0
+char *XrmLocaleOfDatabase\^(\^\fIdatabase\fP\^)
+.br
+      XrmDatabase \fIdatabase\fP\^;
+.FN
+.IP \fIdatabase\fP 1i
+Specifies the resource database.
+.LP
+.eM
+The
+.PN XrmLocaleOfDatabase
+function returns the name of the locale bound to the specified
+database, as a null-terminated string.
+The returned locale name string is owned by Xlib and should not be
+modified or freed by the client.
+Xlib is not permitted to free the string until the database is destroyed.
+Until the string is freed,
+it will not be modified by Xlib.
+.LP
+.sp
+To destroy a resource database and free its allocated memory, use
+.PN XrmDestroyDatabase .
+.IN "XrmDestroyDatabase" "" "@DEF@"
+.sM
+.FD 0
+void XrmDestroyDatabase\^(\^\fIdatabase\fP\^)
+.br
+      XrmDatabase \fIdatabase\fP\^;
+.FN
+.IP \fIdatabase\fP 1i
+Specifies the resource database.
+.LP
+.eM
+If database is NULL,
+.PN XrmDestroyDatabase
+returns immediately.
+.LP
+.sp
+To associate a resource database with a display, use
+.PN XrmSetDatabase .
+.IN "XrmSetDatabase" "" "@DEF@"
+.sM
+.FD 0
+void XrmSetDatabase\^(\^\fIdisplay\fP\^, \fIdatabase\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XrmDatabase \fIdatabase\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIdatabase\fP 1i
+Specifies the resource database.
+.LP
+.eM
+The
+.PN XrmSetDatabase
+function associates the specified resource database (or NULL)
+with the specified display.
+The database previously associated with the display (if any) is not destroyed.
+A client or toolkit may find this function convenient for retaining a database
+once it is constructed.
+.LP
+.sp
+To get the resource database associated with a display, use
+.PN XrmGetDatabase .
+.IN "XrmGetDatabase" "" "@DEF@"
+.sM
+.FD 0
+XrmDatabase XrmGetDatabase\^(\^\fIdisplay\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.LP
+.eM
+The
+.PN XrmGetDatabase
+function returns the database associated with the specified display.
+It returns NULL if a database has not yet been set.
+.NH 2
+Merging Resource Databases
+.XS
+\*(SN Merging Resource Databases
+.XE
+.LP
+To merge the contents of a resource file into a database, use
+.PN XrmCombineFileDatabase .
+.IN "XrmCombineFileDatabase" "" "@DEF@"
+.sM
+.FD 0
+Status XrmCombineFileDatabase(\^\fIfilename\fP, \fItarget_db\fP, \fIoverride\fP\^)
+.br
+      char *\fIfilename\fP;
+.br
+      XrmDatabase *\fItarget_db\fP\^;
+.br
+      Bool \fIoverride\fP;
+.FN
+.IP \fIfilename\fP 1i
+Specifies the resource database file name.
+.IP \fItarget_db\fP 1i
+Specifies the resource database into which the source 
+database is to be merged.
+.IP \fIoverride\fP 1i
+Specifies whether source entries override target ones.
+.LP
+.eM 
+The
+.PN XrmCombineFileDatabase
+function merges the contents of a resource file into a database.
+If the same specifier is used for an entry in both the file and
+the database,
+the entry in the file will replace the entry in the database
+if override is
+.PN True ;
+otherwise, the entry in the file is discarded.
+The file is parsed in the current locale.
+If the file cannot be read,
+a zero status is returned;
+otherwise, a nonzero status is returned.
+If target_db contains NULL,
+.PN XrmCombineFileDatabase
+creates and returns a new database to it.
+Otherwise, the database pointed to by target_db is not destroyed by the merge.
+The database entries are merged without changing values or types,
+regardless of the locale of the database.
+The locale of the target database is not modified.
+.LP
+.sp
+To merge the contents of one database into another database, use
+.PN XrmCombineDatabase .
+.IN "XrmCombineDatabase" "" "@DEF@"
+.sM
+.FD 0
+void XrmCombineDatabase(\^\fIsource_db\fP, \fItarget_db\fP, \fIoverride\fP\^)
+.br
+      XrmDatabase \fIsource_db\fP, *\fItarget_db\fP\^;
+.br
+      Bool \fIoverride\fP;
+.FN
+.IP \fIsource_db\fP 1i
+Specifies the resource database that is to be merged into the target database.
+.IP \fItarget_db\fP 1i
+Specifies the resource database into which the source 
+database is to be merged.
+.IP \fIoverride\fP 1i
+Specifies whether source entries override target ones.
+.LP
+.eM 
+The
+.PN XrmCombineDatabase
+function merges the contents of one database into another.
+If the same specifier is used for an entry in both databases,
+the entry in the source_db will replace the entry in the target_db
+if override is
+.PN True ;
+otherwise, the entry in source_db is discarded.
+If target_db contains NULL,
+.PN XrmCombineDatabase
+simply stores source_db in it.
+Otherwise, source_db is destroyed by the merge, but the database pointed
+to by target_db is not destroyed.
+The database entries are merged without changing values or types,
+regardless of the locales of the databases.
+The locale of the target database is not modified.
+.LP
+.sp
+To merge the contents of one database into another database with override
+semantics, use
+.PN XrmMergeDatabases .
+.IN "XrmMergeDatabases" "" "@DEF@"
+.sM
+.FD 0
+void XrmMergeDatabases(\^\fIsource_db\fP, \fItarget_db\fP\^)
+.br
+      XrmDatabase \fIsource_db\fP, *\fItarget_db\fP\^;
+.FN
+.IP \fIsource_db\fP 1i
+Specifies the resource database that is to be merged into the target database.
+.IP \fItarget_db\fP 1i
+Specifies the resource database into which the source 
+database is to be merged.
+.LP
+.eM 
+Calling the
+.PN XrmMergeDatabases
+function is equivalent to calling the
+.PN XrmCombineDatabase
+function with an override argument of
+.PN True .
+.NH 2
+Looking Up Resources
+.XS
+\*(SN Looking Up Resources
+.XE
+.LP
+To retrieve a resource from a resource database, use
+.PN XrmGetResource ,
+.PN XrmQGetResource ,
+or
+.PN XrmQGetSearchResource .
+.LP
+.sp
+.IN "XrmGetResource" "" "@DEF@"
+.sM
+.FD 0
+Bool XrmGetResource\^(\^\fIdatabase\fP, \fIstr_name\fP, \fIstr_class\fP, \
+\fIstr_type_return\fP, \fIvalue_return\fP\^)
+.br
+     XrmDatabase \fIdatabase\fP\^;
+.br
+     char *\fIstr_name\fP\^;
+.br
+     char *\fIstr_class\fP\^;
+.br
+     char **\fIstr_type_return\fP\^;
+.br
+     XrmValue *\fIvalue_return\fP\^; 
+.FN
+.IP \fIdatabase\fP 1i
+Specifies the database that is to be used.
+.IP \fIstr_name\fP 1i
+Specifies the fully qualified name of the value being retrieved (as a string).
+.IP \fIstr_class\fP 1i
+Specifies the fully qualified class of the value being retrieved (as a string).
+.IP \fIstr_type_return\fP 1i
+Returns the representation type of the destination (as a string).
+.IP \fIvalue_return\fP 1i
+Returns the value in the database.
+.LP
+.eM
+.sp
+.IN "XrmQGetResource" "" "@DEF@"
+.sM
+.FD 0
+Bool XrmQGetResource\^(\^\fIdatabase\fP, \fIquark_name\fP, \fIquark_class\fP, \
+\fIquark_type_return\fP, \fIvalue_return\fP\^)
+.br
+     XrmDatabase \fIdatabase\fP\^;
+.br
+     XrmNameList \fIquark_name\fP\^;
+.br
+     XrmClassList \fIquark_class\fP\^;
+.br
+     XrmRepresentation *\fIquark_type_return\fP\^;
+.br
+     XrmValue *\fIvalue_return\fP\^; 
+.FN
+.IP \fIdatabase\fP 1i
+Specifies the database that is to be used.
+.IP \fIquark_name\fP 1i
+Specifies the fully qualified name of the value being retrieved (as a quark).
+.IP \fIquark_class\fP 1i
+Specifies the fully qualified class of the value being retrieved (as a quark).
+.IP \fIquark_type_return\fP 1i
+Returns the representation type of the destination (as a quark).
+.IP \fIvalue_return\fP 1i
+Returns the value in the database.
+.LP
+.eM
+The 
+.PN XrmGetResource 
+and 
+.PN XrmQGetResource 
+functions retrieve a resource from the specified database.
+Both take a fully qualified name/class pair, a destination
+resource representation, and the address of a value
+(size/address pair).  
+The value and returned type point into database memory;
+therefore, you must not modify the data.
+.LP
+The database only frees or overwrites entries on
+.PN XrmPutResource , 
+.PN XrmQPutResource ,
+or 
+.PN XrmMergeDatabases .
+A client that is not storing new values into the database or
+is not merging the database should be safe using the address passed 
+back at any time until it exits.
+If a resource was found, both
+.PN XrmGetResource 
+and
+.PN XrmQGetResource 
+return 
+.PN True ;
+otherwise, they return 
+.PN False .
+.LP
+.sp
+.EQ
+delim %%
+.EN
+Most applications and toolkits do not make random probes
+into a resource database to fetch resources.
+The X toolkit access pattern for a resource database is quite stylized.
+A series of from 1 to 20 probes is made with only the 
+last name/class differing in each probe.
+The 
+.PN XrmGetResource 
+function is at worst a %2 sup n% algorithm,
+where \fIn\fP is the length of the name/class list.
+This can be improved upon by the application programmer by prefetching a list
+of database levels that might match the first part of a name/class list.
+.LP
+.sp
+To obtain a list of database levels, use
+.PN XrmQGetSearchList .
+.IN "XrmQGetSearchList" "" "@DEF@"
+.sM
+.FD 0
+typedef XrmHashTable *XrmSearchList;
+.sp
+Bool XrmQGetSearchList\^(\^\fIdatabase\fP, \fInames\fP, \fIclasses\fP, \
+\fIlist_return\fP, \fIlist_length\fP\^)
+.br
+     XrmDatabase \fIdatabase\fP\^;
+.br
+     XrmNameList \fInames\fP\^;
+.br
+     XrmClassList \fIclasses\fP\^;
+.br
+     XrmSearchList \fIlist_return\fP\^;
+.br
+     int \fIlist_length\fP\^;
+.FN
+.IP \fIdatabase\fP 1i
+Specifies the database that is to be used.
+.IP \fInames\fP 1i
+Specifies a list of resource names.
+.IP \fIclasses\fP 1i
+Specifies a list of resource classes.
+.IP \fIlist_return\fP 1i
+Returns a search list for further use.
+The caller must allocate sufficient space for the list before calling 
+.PN XrmQGetSearchList .
+.IP \fIlist_length\fP 1i
+Specifies the number of entries (not the byte size) allocated for list_return.
+.LP
+.eM
+The
+.PN XrmQGetSearchList
+function takes a list of names and classes
+and returns a list of database levels where a match might occur.
+The returned list is in best-to-worst order and
+uses the same algorithm as 
+.PN XrmGetResource 
+for determining precedence.
+If list_return was large enough for the search list,
+.PN XrmQGetSearchList
+returns 
+.PN True ;
+otherwise, it returns
+.PN False .
+.LP
+The size of the search list that the caller must allocate is
+dependent upon the number of levels and wildcards in the resource specifiers 
+that are stored in the database.
+The worst case length is %3 sup n%,
+where \fIn\fP is the number of name or class components in names or classes.
+.LP
+When using 
+.PN XrmQGetSearchList 
+followed by multiple probes for resources with a common name and class prefix,
+only the common prefix should be specified in the name and class list to 
+.PN XrmQGetSearchList .
+.LP
+.sp
+To search resource database levels for a given resource, use
+.PN XrmQGetSearchResource .
+.IN "XrmQGetSearchResource" "" "@DEF@"
+.sM
+.FD 0
+Bool XrmQGetSearchResource\^(\^\fIlist\fP, \fIname\fP, \fIclass\fP, \
+\fItype_return\fP, \fIvalue_return\fP\^)
+.br
+     XrmSearchList \fIlist\fP\^;
+.br
+     XrmName \fIname\fP\^;
+.br
+     XrmClass \fIclass\fP\^;
+.br
+     XrmRepresentation *\fItype_return\fP\^;
+.br
+     XrmValue *\fIvalue_return\fP\^;
+.FN
+.IP \fIlist\fP 1i
+Specifies the search list returned by
+.PN XrmQGetSearchList .
+.IP \fIname\fP 1i
+Specifies the resource name.
+.IP \fIclass\fP 1i
+Specifies the resource class.
+.IP \fItype_return\fP 1i
+Returns data representation type.
+.IP \fIvalue_return\fP 1i
+Returns the value in the database.
+.LP
+.eM
+The
+.PN XrmQGetSearchResource
+function searches the specified database levels for the resource 
+that is fully identified by the specified name and class.
+The search stops with the first match.
+.PN XrmQGetSearchResource
+returns 
+.PN True 
+if the resource was found;
+otherwise, it returns
+.PN False .
+.LP
+A call to 
+.PN XrmQGetSearchList 
+with a name and class list containing all but the last component 
+of a resource name followed by a call to 
+.PN XrmQGetSearchResource 
+with the last component name and class returns the same database entry as 
+.PN XrmGetResource 
+and 
+.PN XrmQGetResource 
+with the fully qualified name and class.
+.NH 2
+Storing into a Resource Database
+.XS
+\*(SN Storing into a Resource Database
+.XE
+.LP
+To store resources into the database, use
+.PN XrmPutResource 
+or
+.PN XrmQPutResource .
+Both functions take a partial resource specification, a
+representation type, and a value.
+This value is copied into the specified database.
+.LP
+.sp
+.IN "XrmPutResource" "" "@DEF@"
+.sM
+.FD 0
+void XrmPutResource\^(\^\fIdatabase\fP, \fIspecifier\fP, \fItype\fP, \fIvalue\fP\^)
+.br
+     XrmDatabase *\fIdatabase\fP\^;
+.br
+     char *\fIspecifier\fP\^;
+.br
+     char *\fItype\fP\^;
+.br
+     XrmValue *\fIvalue\fP\^;
+.FN
+.IP \fIdatabase\fP 1i
+Specifies the resource database.
+.IP \fIspecifier\fP 1i
+Specifies a complete or partial specification of the resource.
+.IP \fItype\fP 1i
+Specifies the type of the resource.
+.IP \fIvalue\fP 1i
+Specifies the value of the resource, which is specified as a string.
+.LP
+.eM
+If database contains NULL,
+.PN XrmPutResource
+creates a new database and returns a pointer to it.
+.PN XrmPutResource
+is a convenience function that calls
+.PN XrmStringToBindingQuarkList
+followed by:
+.LP
+.Ds
+XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), value)
+.De
+If the specifier and type are not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+The value is stored in the database without modification.
+.LP
+.sp
+.IN "XrmQPutResource" "" "@DEF@"
+.sM
+.FD 0
+void XrmQPutResource\^(\^\fIdatabase\fP, \fIbindings\fP, \fIquarks\fP, \
+\fItype\fP, \fIvalue\fP\^)
+.br
+     XrmDatabase *\fIdatabase\fP\^;
+.br
+     XrmBindingList \fIbindings\fP\^;
+.br
+     XrmQuarkList \fIquarks\fP\^;
+.br
+     XrmRepresentation \fItype\fP\^;
+.br
+     XrmValue *\fIvalue\fP\^;
+.FN
+.IP \fIdatabase\fP 1i
+Specifies the resource database.
+.IP \fIbindings\fP 1i
+Specifies a list of bindings.
+.IP \fIquarks\fP 1i
+Specifies the complete or partial name or the class list of the resource.
+.IP \fItype\fP 1i
+Specifies the type of the resource.
+.IP \fIvalue\fP 1i
+Specifies the value of the resource, which is specified as a string.
+.LP
+.eM
+If database contains NULL,
+.PN XrmQPutResource
+creates a new database and returns a pointer to it.
+If a resource entry with the identical bindings and quarks already
+exists in the database, the previous type and value are replaced by the new
+specified type and value.
+The value is stored in the database without modification.
+.LP
+.sp
+To add a resource that is specified as a string, use
+.PN XrmPutStringResource .
+.IN "XrmPutStringResource" "" "@DEF@"
+.sM
+.FD 0
+void XrmPutStringResource\^(\^\fIdatabase\fP, \fIspecifier\fP, \fIvalue\fP\^)
+.br
+     XrmDatabase *\fIdatabase\fP\^;
+.br
+     char *\fIspecifier\fP\^;
+.br
+     char *\fIvalue\fP\^;
+.FN
+.IP \fIdatabase\fP 1i
+Specifies the resource database.
+.IP \fIspecifier\fP 1i
+Specifies a complete or partial specification of the resource.
+.IP \fIvalue\fP 1i
+Specifies the value of the resource, which is specified as a string.
+.LP
+.eM
+If database contains NULL,
+.PN XrmPutStringResource
+creates a new database and returns a pointer to it.
+.PN XrmPutStringResource
+adds a resource with the specified value to the specified database.
+.PN XrmPutStringResource
+is a convenience function that first calls
+.PN XrmStringToBindingQuarkList
+on the specifier and then calls
+.PN XrmQPutResource ,
+using a ``String'' representation type.
+If the specifier is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+The value is stored in the database without modification.
+.LP
+.sp
+To add a string resource using quarks as a specification, use
+.PN XrmQPutStringResource .
+.IN "XrmQPutStringResource" "" "@DEF@"
+.sM
+.FD 0
+void XrmQPutStringResource\^(\^\fIdatabase\fP, \fIbindings\fP, \fIquarks\fP, \
+\fIvalue\fP\^)
+.br
+     XrmDatabase *\fIdatabase\fP\^;
+.br
+     XrmBindingList \fIbindings\fP\^;
+.br
+     XrmQuarkList \fIquarks\fP\^;
+.br
+     char *\fIvalue\fP\^;
+.FN
+.IP \fIdatabase\fP 1i
+Specifies the resource database.
+.IP \fIbindings\fP 1i
+Specifies a list of bindings.
+.IP \fIquarks\fP 1i
+Specifies the complete or partial name or the class list of the resource.
+.IP \fIvalue\fP 1i
+Specifies the value of the resource, which is specified as a string.
+.LP
+.eM
+If database contains NULL,
+.PN XrmQPutStringResource
+creates a new database and returns a pointer to it.
+.PN XrmQPutStringResource
+is a convenience routine that constructs an
+.PN XrmValue
+for the value string (by calling
+.PN strlen
+to compute the size) and
+then calls
+.PN XrmQPutResource ,
+using a ``String'' representation type.
+The value is stored in the database without modification.
+.LP
+.sp
+To add a single resource entry that is specified as a string that contains
+both a name and a value, use
+.PN XrmPutLineResource .
+.IN "XrmPutLineResource" "" "@DEF@"
+.sM
+.FD 0
+void XrmPutLineResource\^(\^\fIdatabase\fP, \fIline\fP\^)
+.br
+     XrmDatabase *\fIdatabase\fP\^;
+.br
+     char *\fIline\fP\^;
+.FN
+.IP \fIdatabase\fP 1i
+Specifies the resource database.
+.IP \fIline\fP 1i
+Specifies the resource name and value pair as a single string.
+.LP
+.eM
+If database contains NULL,
+.PN XrmPutLineResource
+creates a new database and returns a pointer to it.
+.PN XrmPutLineResource
+adds a single resource entry to the specified database.
+The line should be in valid ResourceLine format (see section 15.1)
+terminated by a newline or null character;
+the database that results from using a string
+with incorrect syntax is implementation-dependent.
+The string is parsed in the locale of the database.
+If the
+.PN ResourceName
+is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Note that comment lines are not stored.
+.NH 2
+Enumerating Database Entries
+.XS
+\*(SN Enumerating Database Entries
+.XE
+.LP
+To enumerate the entries of a database, use
+.PN XrmEnumerateDatabase .
+.IN "XrmEnumerateDatabase" "" "@DEF@"
+.sM
+.TS
+lw(.5i) lw(2i) lw(2.5i).
+T{
+#define
+T}	T{
+.PN XrmEnumAllLevels
+T}	T{
+0
+T}
+T{
+#define
+T}	T{
+.PN XrmEnumOneLevel
+T}	T{
+1
+T}
+.TE
+.FD 0
+Bool XrmEnumerateDatabase\^(\^\fIdatabase\fP, \fIname_prefix\fP, \fIclass_prefix\fP, \fImode\fP, \fIproc\fP, \fIarg\fP\^)
+.br
+      XrmDatabase \fIdatabase\fP\^;
+.br
+      XrmNameList \fIname_prefix\fP\^;
+.br
+      XrmClassList \fIclass_prefix\fP\^;
+.br
+      int \fImode\fP\^;
+.br
+      Bool (\^*\fIproc\fP\^)\^(\^)\^;
+.br
+      XPointer \fIarg\fP\^;
+.FN
+.IP \fIdatabase\fP 1i
+Specifies the resource database.
+.IP \fIname_prefix\fP 1i
+Specifies the resource name prefix.
+.IP \fIclass_prefix\fP 1i
+Specifies the resource class prefix.
+.IP \fImode\fP 1i
+Specifies the number of levels to enumerate.
+.IP \fIproc\fP 1i
+Specifies the procedure that is to be called for each matching entry.
+.IP \fIarg\fP 1i
+Specifies the user-supplied argument that will be passed to the procedure.
+.LP
+.eM
+The
+.PN XrmEnumerateDatabase
+function calls the specified procedure for each resource in the database
+that would match some completion of the given name/class resource prefix.
+The order in which resources are found is implementation-dependent.
+If mode is
+.PN XrmEnumOneLevel ,
+a resource must match the given name/class prefix with
+just a single name and class appended.  If mode is
+.PN XrmEnumAllLevels ,
+the resource must match the given name/class prefix with one or more names and
+classes appended.
+If the procedure returns
+.PN True ,
+the enumeration terminates and the function returns
+.PN True . 
+If the procedure always returns
+.PN False ,
+all matching resources are enumerated and the function returns
+.PN False .
+.LP
+The procedure is called with the following arguments:
+.LP
+.\" Start marker code here
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+(*\fIproc\fP\^)(\^\fIdatabase\fP, \fIbindings\fP, \fIquarks\fP, \fItype\fP, \fIvalue\fP, \fIarg\fP\^)
+	XrmDatabase *\fIdatabase\fP\^;
+	XrmBindingList \fIbindings\fP\^;
+	XrmQuarkList \fIquarks\fP\^;
+	XrmRepresentation *\fItype\fP\^;
+	XrmValue *\fIvalue\fP\^;
+	XPointer \fIarg\fP\^;
+.De
+.\" End marker code here
+.LP
+The bindings and quarks lists are terminated by
+.PN NULLQUARK .
+Note that pointers
+to the database and type are passed, but these values should not be modified.
+.LP
+The procedure must not modify the database.
+If Xlib has been initialized for threads, the procedure is called with
+the database locked and the result of a call by the procedure to any
+Xlib function using the same database is not defined.
+.NH 2
+Parsing Command Line Options
+.XS
+\*(SN Parsing Command Line Options 
+.XE
+.LP
+The
+.PN XrmParseCommand
+function can be used to parse the command line arguments to a program
+and modify a resource database with selected entries from the command line.
+.LP
+.IN "XrmOptionKind" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef enum {
+	XrmoptionNoArg,	/* Value is specified in XrmOptionDescRec.value */
+	XrmoptionIsArg,	/* Value is the option string itself */
+	XrmoptionStickyArg,	/* Value is characters immediately following option */
+	XrmoptionSepArg,	/* Value is next argument in argv */
+	XrmoptionResArg,	/* Resource and value in next argument in argv */
+	XrmoptionSkipArg,	/* Ignore this option and the next argument in argv */
+	XrmoptionSkipLine,	/* Ignore this option and the rest of argv */
+	XrmoptionSkipNArgs	/* Ignore this option and the next
+		\ \ \ XrmOptionDescRec.value arguments in argv */
+} XrmOptionKind;
+.De
+.LP
+.eM
+Note that
+.PN XrmoptionSkipArg
+is equivalent to 
+.PN XrmoptionSkipNArgs
+with the
+.PN XrmOptionDescRec.value
+field containing the value one.
+Note also that the value zero for
+.PN XrmoptionSkipNArgs
+indicates that only the option itself is to be skipped.
+.LP
+.IN "XrmOptionDescRec" "" "@DEF@"
+.sM
+.Ds 0
+.TA .5i 2.5i
+.ta .5i 2.5i
+typedef struct {
+	char *option;	/* Option specification string in argv		    */
+	char *specifier;	/* Binding and resource name (sans application name)    */
+	XrmOptionKind argKind;	/* Which style of option it is	    */
+	XPointer value;	/* Value to provide if XrmoptionNoArg or 
+		\ \ \ XrmoptionSkipNArgs   */
+} XrmOptionDescRec, *XrmOptionDescList;
+.De
+.LP
+.eM
+.sp
+To load a resource database from a C command line, use
+.PN XrmParseCommand .
+.IN "XrmParseCommand" "" "@DEF@"
+.sM
+.FD 0
+void XrmParseCommand\^(\^\fIdatabase\fP\^, \^\fItable\fP\^, \^\fItable_count\fP\^, \
+\^\fIname\fP\^, \^\fIargc_in_out\fP\^, \^\fIargv_in_out\fP\^)
+.br
+      XrmDatabase *\fIdatabase\fP\^;
+.br
+      XrmOptionDescList \fItable\fP\^;
+.br
+      int \fItable_count\fP\^;
+.br
+      char *\fIname\fP\^;
+.br
+      int *\fIargc_in_out\fP\^;
+.br
+      char **\fIargv_in_out\fP\^;
+.FN
+.IP \fIdatabase\fP 1i
+Specifies the resource database.
+.IP \fItable\fP 1i
+Specifies the table of command line arguments to be parsed.
+.IP \fItable_count\fP 1i
+Specifies the number of entries in the table.
+.IP \fIname\fP 1i
+Specifies the application name.
+.IP \fIargc_in_out\fP 1i
+Specifies the number of arguments and returns the number of remaining arguments.
+.IP \fIargv_in_out\fP 1i
+Specifies the command line arguments
+and returns the remaining arguments.
+.LP
+.eM
+The
+.PN XrmParseCommand
+function parses an (argc, argv) pair according to the specified option table,
+loads recognized options into the specified database with type ``String,''
+and modifies the (argc, argv) pair to remove all recognized options.
+If database contains NULL,
+.PN XrmParseCommand
+creates a new database and returns a pointer to it.
+Otherwise, entries are added to the database specified.
+If a database is created, it is created in the current locale.
+.LP
+The specified table is used to parse the command line.
+Recognized options in the table are removed from argv,
+and entries are added to the specified resource database
+in the order they occur in argv.
+The table entries contain information on the option string,
+the option name, the style of option, 
+and a value to provide if the option kind is 
+.PN XrmoptionNoArg .
+The option names are compared byte-for-byte to arguments in argv,
+independent of any locale.
+The resource values given in the table are stored in the resource database
+without modification.
+All resource database entries are created
+using a ``String'' representation type.
+The argc argument specifies the number of arguments in argv
+and is set on return to the remaining number of arguments that were not parsed.
+The name argument should be the name of your application
+for use in building the database entry.
+The name argument is prefixed to the resourceName in the option table
+before storing a database entry.
+The name argument is treated as a single component, even if it
+has embedded periods.
+No separating (binding) character is inserted,
+so the table must contain either a period (.) or an asterisk (*)
+as the first character in each resourceName entry.
+To specify a more completely qualified resource name,
+the resourceName entry can contain multiple components.
+If the name argument and the resourceNames are not in the
+Host Portable Character Encoding,
+the result is implementation-dependent.
+.LP
+The following provides a sample option table:
+.LP
+.Ds 0
+.TA 1.25i 3.25i 4.75i
+.ta 1.25i 3.25i 4.75i
+static XrmOptionDescRec opTable[] = {
+{"\-background",	"*background",	XrmoptionSepArg,	(XPointer) NULL},
+{"\-bd",	"*borderColor",	XrmoptionSepArg,	(XPointer) NULL},
+{"\-bg",	"*background",	XrmoptionSepArg,	(XPointer) NULL},
+{"\-borderwidth",	"*TopLevelShell.borderWidth",	XrmoptionSepArg,	(XPointer) NULL},
+{"\-bordercolor",	"*borderColor",	XrmoptionSepArg,	(XPointer) NULL},
+{"\-bw",	"*TopLevelShell.borderWidth",	XrmoptionSepArg,	(XPointer) NULL},
+{"\-display",	".display",	XrmoptionSepArg,	(XPointer) NULL},
+{"\-fg",	"*foreground",	XrmoptionSepArg,	(XPointer) NULL},
+{"\-fn",	"*font",	XrmoptionSepArg,	(XPointer) NULL},
+{"\-font",	"*font",	XrmoptionSepArg,	(XPointer) NULL},
+{"\-foreground",	"*foreground",	XrmoptionSepArg,	(XPointer) NULL},
+{"\-geometry",	".TopLevelShell.geometry",	XrmoptionSepArg,	(XPointer) NULL},
+{"\-iconic",	".TopLevelShell.iconic",	XrmoptionNoArg,	(XPointer) "on"},
+{"\-name",	".name",	XrmoptionSepArg,	(XPointer) NULL},
+{"\-reverse",	"*reverseVideo",	XrmoptionNoArg,	(XPointer) "on"},
+{"\-rv",	"*reverseVideo",	XrmoptionNoArg,	(XPointer) "on"},
+{"\-synchronous",	"*synchronous",	XrmoptionNoArg,	(XPointer) "on"},
+{"\-title",	".TopLevelShell.title",	XrmoptionSepArg,	(XPointer) NULL},
+{"\-xrm",	NULL,	XrmoptionResArg,	(XPointer) NULL},
+};
+.De
+.LP
+In this table, if the \-background (or \-bg) option is used to set
+background colors, the stored resource specifier matches all
+resources of attribute background.  
+If the \-borderwidth option is used, 
+the stored resource specifier applies only to border width
+attributes of class TopLevelShell (that is, outer-most windows, including
+pop-up windows).  
+If the \-title option is used to set a window name,
+only the topmost application windows receive the resource.
+.LP
+When parsing the command line,
+any unique unambiguous abbreviation for an option name in the table is 
+considered a match for the option.
+Note that uppercase and lowercase matter.
+.bp
diff --git a/specs/libX11/CH16 b/specs/libX11/CH16
new file mode 100644
index 00000000..3a21a229
--- /dev/null
+++ b/specs/libX11/CH16
@@ -0,0 +1,2364 @@
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
+.\"
+.\" 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:
+.\"
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\"
+.\" 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.
+.\"
+.\" 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.
+.\"
+.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+.\" Digital Equipment Corporation
+.\"
+.\" Portions Copyright \(co 1990, 1991 by
+.\" Tektronix, Inc.
+.\"
+.\" Permission to use, copy, modify and distribute this documentation for
+.\" any purpose and without fee is hereby granted, provided that the above
+.\" copyright notice appears in all copies and that both that copyright notice
+.\" and this permission notice appear in all copies, and that the names of
+.\" Digital and Tektronix not be used in in advertising or publicity pertaining
+.\" to this documentation without specific, written prior permission.
+.\" Digital and Tektronix makes no representations about the suitability
+.\" of this documentation for any purpose.
+.\" It is provided ``as is'' without express or implied warranty.
+.\" 
+\&
+.sp 1
+.ce 3
+\s+1\fBChapter 16\fP\s-1
+
+\s+1\fBApplication Utility Functions\fP\s-1
+.sp 2
+.nr H1 16
+.nr H2 0
+.nr H3 0
+.nr H4 0
+.nr H5 0
+.na
+.LP
+.XS
+Chapter 16: Application Utility Functions 
+.XE
+Once you have initialized the X system,
+you can use the Xlib utility functions to:
+.IP \(bu 5
+Use keyboard utility functions
+.IP \(bu 5
+Use Latin-1 keyboard event functions
+.IP \(bu 5
+Allocate permanent storage
+.IP \(bu 5
+Parse the window geometry
+.IP \(bu 5
+Manipulate regions
+.IP \(bu 5
+Use cut buffers
+.IP \(bu 5
+Determine the appropriate visual type
+.IP \(bu 5
+Manipulate images
+.IP \(bu 5
+Manipulate bitmaps
+.IP \(bu 5
+Use the context manager
+.LP
+As a group,
+the functions discussed in this chapter provide the functionality that 
+is frequently needed and that spans toolkits.
+Many of these functions do not generate actual protocol requests to the server.
+.NH 2
+Using Keyboard Utility Functions
+.XS
+\*(SN Using Keyboard Utility Functions 
+.XE
+.LP
+This section discusses mapping between KeyCodes and KeySyms,
+classifying KeySyms, and mapping between KeySyms and string names.
+The first three functions in this section operate on a cached copy of the
+server keyboard mapping.
+The first four KeySyms for each KeyCode
+are modified according to the rules given in section 12.7.
+To obtain the untransformed KeySyms defined for a key,
+use the functions described in section 12.7.
+.LP
+.sp
+To obtain a KeySym for the KeyCode of an event, use
+.PN XLookupKeysym .
+.IN "XLookupKeysym" "" "@DEF@"
+.sM
+.FD 0
+KeySym XLookupKeysym(\^\fIkey_event\fP, \fIindex\fP\^)
+.br
+      XKeyEvent *\fIkey_event\fP\^;
+.br
+      int \fIindex\fP\^;
+.FN
+.IP \fIkey_event\fP 1i
+Specifies the 
+.PN KeyPress
+or
+.PN KeyRelease
+event.
+.IP \fIindex\fP 1i
+Specifies the index into the KeySyms list for the event's KeyCode.
+.LP
+.eM
+The
+.PN XLookupKeysym
+function uses a given keyboard event and the index you specified to return
+the KeySym from the list that corresponds to the KeyCode member in the
+.PN XKeyPressedEvent
+or
+.PN XKeyReleasedEvent
+structure.
+If no KeySym is defined for the KeyCode of the event,
+.PN XLookupKeysym
+returns
+.PN NoSymbol .
+.LP
+.sp
+To obtain a KeySym for a specific KeyCode, use
+.PN XKeycodeToKeysym .
+.IN "XKeycodeToKeysym" "" "@DEF@"
+.sM
+.FD 0
+KeySym XKeycodeToKeysym\^(\^\fIdisplay\fP, \fIkeycode\fP, \fIindex\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      KeyCode \fIkeycode\fP\^;
+.br
+      int \fIindex\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIkeycode\fP 1i
+Specifies the KeyCode.
+.IP \fIindex\fP 1i
+Specifies the element of KeyCode vector.
+.LP
+.eM
+The
+.PN XKeycodeToKeysym
+function uses internal Xlib tables
+and returns the KeySym defined for the specified KeyCode and
+the element of the KeyCode vector.
+If no symbol is defined,
+.PN XKeycodeToKeysym
+returns
+.PN NoSymbol .
+.LP
+.sp
+To obtain a KeyCode for a key having a specific KeySym, use
+.PN XKeysymToKeycode .
+.IN "XKeysymToKeycode" "" "@DEF@"
+.sM
+.FD 0
+KeyCode XKeysymToKeycode\^(\^\fIdisplay\fP, \fIkeysym\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      KeySym \fIkeysym\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIkeysym\fP 1i
+Specifies the KeySym that is to be searched for.
+.LP
+.eM
+If the specified KeySym is not defined for any KeyCode,
+.PN XKeysymToKeycode
+returns zero.
+.LP
+.sp
+The mapping between KeyCodes and KeySyms is cached internal to Xlib.
+When this information is changed at the server, an Xlib function must
+be called to refresh the cache.
+To refresh the stored modifier and keymap information, use
+.PN XRefreshKeyboardMapping .
+.IN "XRefreshKeyboardMapping" "" "@DEF@"
+.sM
+.FD 0
+XRefreshKeyboardMapping(\^\fIevent_map\fP\^)
+.br
+      XMappingEvent *\fIevent_map\fP\^;
+.FN
+.IP \fIevent_map\fP 1i
+Specifies the mapping event that is to be used.
+.LP
+.eM
+The
+.PN XRefreshKeyboardMapping
+function refreshes the stored modifier and keymap information.
+You usually call this function when a
+.PN MappingNotify
+event with a request member of
+.PN MappingKeyboard
+or
+.PN MappingModifier
+occurs.
+The result is to update Xlib's knowledge of the keyboard.
+.LP
+.sp
+To obtain the uppercase and lowercase forms of a KeySym, use
+.PN XConvertCase .
+.IN "XConvertCase" "" "@DEF@"
+.sM
+.FD 0
+void XConvertCase(\^\fIkeysym\fP, \fIlower_return\fP, \fIupper_return\fP\^)
+.br
+      KeySym \fIkeysym\fP\^;
+.br
+      KeySym *\fIlower_return\fP\^;
+.br
+      KeySym *\fIupper_return\fP\^;
+.FN
+.ds Fn converted
+.IP \fIkeysym\fP 1i
+Specifies the KeySym that is to be \*(Fn.
+.IP \fIlower_return\fP 1i
+Returns the lowercase form of keysym, or keysym.
+.IP \fIupper_return\fP 1i
+Returns the uppercase form of keysym, or keysym.
+.LP
+.eM
+The
+.PN XConvertCase
+function returns the uppercase and lowercase forms of the specified Keysym,
+if the KeySym is subject to case conversion;
+otherwise, the specified KeySym is returned to both lower_return and
+upper_return.
+Support for conversion of other than Latin and Cyrillic KeySyms is
+implementation-dependent.
+.LP
+.sp
+KeySyms have string names as well as numeric codes.
+To convert the name of the KeySym to the KeySym code, use
+.PN XStringToKeysym .
+.IN "XStringToKeysym" "" "@DEF@"
+.sM
+.FD 0
+KeySym XStringToKeysym\^(\^\fIstring\fP\^)
+.br
+      char *\fIstring\fP\^;
+.FN
+.IP \fIstring\fP 1i
+Specifies the name of the KeySym that is to be converted.
+.LP
+.eM
+Standard KeySym names are obtained from
+.hN X11/keysymdef.h
+by removing the XK_ prefix from each name.
+KeySyms that are not part of the Xlib standard also may be obtained
+with this function.
+The set of KeySyms that are available in this manner 
+and the mechanisms by which Xlib obtains them is implementation-dependent.
+.LP
+If the KeySym name is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+If the specified string does not match a valid KeySym,
+.PN XStringToKeysym
+returns
+.PN NoSymbol .
+.LP
+.sp
+To convert a KeySym code to the name of the KeySym, use
+.PN XKeysymToString .
+.IN "XKeysymToString" "" "@DEF@"
+.sM
+.FD 0
+char *XKeysymToString\^(\^\fIkeysym\fP\^)
+.br
+      KeySym \fIkeysym\fP\^;
+.FN
+.ds Fn converted
+.IP \fIkeysym\fP 1i
+Specifies the KeySym that is to be \*(Fn.
+.LP
+.eM
+The returned string is in a static area and must not be modified.
+The returned string is in the Host Portable Character Encoding.
+If the specified KeySym is not defined,
+.PN XKeysymToString
+returns a NULL.
+.NH 3
+KeySym Classification Macros
+.XS
+\*(SN KeySym Classification Macros
+.XE
+.LP
+You may want to test if a KeySym is, for example, 
+on the keypad or on one of the function keys.
+You can use KeySym macros to perform the following tests.
+.LP
+.sp
+.sM
+.FD 0
+IsCursorKey\^(\^\fIkeysym\fP\^)
+.FN
+.ds Fn tested
+.IP \fIkeysym\fP 1i
+Specifies the KeySym that is to be \*(Fn.
+.LP
+.eM
+.IN "IsCursorKey" "" "@DEF@"
+Returns
+.PN True
+if the specified KeySym is a cursor key.
+.LP
+.sp
+.sM
+.FD 0
+IsFunctionKey\^(\^\fIkeysym\fP\^)
+.FN
+.ds Fn tested
+.IP \fIkeysym\fP 1i
+Specifies the KeySym that is to be \*(Fn.
+.LP
+.eM
+.IN "IsFunctionKey" "" "@DEF@"
+Returns 
+.PN True
+if the specified KeySym is a function key.
+.LP
+.sp
+.sM
+.FD 0
+IsKeypadKey\^(\^\fIkeysym\fP\^)
+.FN
+.ds Fn tested
+.IP \fIkeysym\fP 1i
+Specifies the KeySym that is to be \*(Fn.
+.LP
+.eM
+.IN "IsKeypadKey" "" "@DEF@"
+Returns
+.PN True
+if the specified KeySym is a standard keypad key.
+.LP
+.sp
+.sM
+.FD 0
+IsPrivateKeypadKey\^(\^\fIkeysym\fP\^)
+.FN
+.ds Fn tested
+.IP \fIkeysym\fP 1i
+Specifies the KeySym that is to be \*(Fn.
+.LP
+.eM
+.IN "IsPrivateKeypadKey" "" "@DEF@"
+Returns
+.PN True
+if the specified KeySym is a vendor-private keypad key.
+.LP
+.sp
+.sM
+.FD 0
+IsMiscFunctionKey\^(\^\fIkeysym\fP\^)
+.FN
+.ds Fn tested
+.IP \fIkeysym\fP 1i
+Specifies the KeySym that is to be \*(Fn.
+.LP
+.eM
+.IN "IsMiscFunctionKey" "" "@DEF@"
+Returns 
+.PN True
+if the specified KeySym is a miscellaneous function key.
+.LP
+.sp
+.sM
+.FD 0
+IsModifierKey\^(\^\fIkeysym\fP\^)
+.FN
+.ds Fn tested
+.IP \fIkeysym\fP 1i
+Specifies the KeySym that is to be \*(Fn.
+.LP
+.eM
+.IN "IsModifierKey" "" "@DEF@"
+Returns 
+.PN True
+if the specified KeySym is a modifier key.
+.LP
+.sp
+.sM
+.FD 0
+IsPFKey\^(\^\fIkeysym\fP\^)
+.FN
+.ds Fn tested
+.IP \fIkeysym\fP 1i
+Specifies the KeySym that is to be \*(Fn.
+.LP
+.eM
+.IN "IsPFKey" "" "@DEF@"
+Returns 
+.PN True
+if the specified KeySym is a PF key.
+.NH 2
+Using Latin-1 Keyboard Event Functions
+.XS
+\*(SN Using Latin-1 Keyboard Event Functions 
+.XE
+.LP
+Chapter 13 describes internationalized text input facilities,
+but sometimes it is expedient to write an application that
+only deals with Latin-1 characters and ASCII controls,
+so Xlib provides a simple function for that purpose.
+.PN XLookupString
+handles the standard modifier semantics described in section 12.7.
+This function does not use any of the input method facilities
+described in chapter 13 and does not depend on the current locale.
+.LP
+.sp
+To map a key event to an ISO Latin-1 string, use
+.PN XLookupString .
+.IN "XLookupString" "" "@DEF@"
+.sM
+.FD 0
+int XLookupString(\^\fIevent_struct\fP, \fIbuffer_return\fP,\
+ \fIbytes_buffer\fP, \fIkeysym_return\fP, \fIstatus_in_out\fP\^)
+.br
+      XKeyEvent *\fIevent_struct\fP\^;
+.br
+      char *\fIbuffer_return\fP\^;
+.br
+      int \fIbytes_buffer\fP\^;
+.br
+      KeySym *\fIkeysym_return\fP\^;
+.br
+      XComposeStatus *\fIstatus_in_out\fP\^;
+.FN
+.IP \fIevent_struct\fP 1i
+Specifies the key event structure to be used.
+You can pass
+.PN XKeyPressedEvent
+or
+.PN XKeyReleasedEvent .
+.IP \fIbuffer_return\fP 1i
+Returns the translated characters.
+.IP \fIbytes_buffer\fP 1i
+Specifies the length of the buffer.
+No more than bytes_buffer of translation are returned.
+.IP \fIkeysym_return\fP 1i
+Returns the KeySym computed from the event if this argument is not NULL.
+.IP \fIstatus_in_out\fP 1i
+Specifies or returns the 
+.PN XComposeStatus 
+structure or NULL.
+.LP
+.eM
+The
+.PN XLookupString
+function translates a key event to a KeySym and a string.
+The KeySym is obtained by using the standard interpretation of the
+.PN Shift ,
+.PN Lock ,
+group, and numlock modifiers as defined in the X Protocol specification.
+If the KeySym has been rebound (see
+.PN XRebindKeysym ),
+the bound string will be stored in the buffer.
+Otherwise, the KeySym is mapped, if possible, to an ISO Latin-1 character
+or (if the Control modifier is on) to an ASCII control character,
+and that character is stored in the buffer.
+.PN XLookupString
+returns the number of characters that are stored in the buffer.
+.LP
+If present (non-NULL),
+the
+.PN XComposeStatus
+structure records the state,
+which is private to Xlib,
+that needs preservation across calls to
+.PN XLookupString
+to implement compose processing.
+The creation of
+.PN XComposeStatus
+structures is implementation-dependent;
+a portable program must pass NULL for this argument.
+.LP
+.PN XLookupString
+depends on the cached keyboard information mentioned in the
+previous section, so it is necessary to use
+.PN XRefreshKeyboardMapping
+to keep this information up-to-date.
+.LP
+.sp
+To rebind the meaning of a KeySym for
+.PN XLookupString ,
+use
+.PN XRebindKeysym .
+.IN "XRebindKeysym" "" "@DEF@"
+.sM
+.FD 0
+XRebindKeysym(\^\fIdisplay\fP, \fIkeysym\fP, \fIlist\fP, \fImod_count\fP, \fIstring\fP, \fInum_bytes\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      KeySym \fIkeysym\fP\^;
+.br
+      KeySym \fIlist\fP\^[\^]\^;
+.br
+      int \fImod_count\fP\^;
+.br
+      unsigned char *\fIstring\fP\^;
+.br
+      int \fInum_bytes\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Fn rebound
+.IP \fIkeysym\fP 1i
+Specifies the KeySym that is to be \*(Fn.
+.IP \fIlist\fP 1i
+Specifies the KeySyms to be used as modifiers.
+.IP \fImod_count\fP 1i
+Specifies the number of modifiers in the modifier list.
+.IP \fIstring\fP 1i
+Specifies the string that is copied and will be returned by 
+.PN XLookupString .
+.IP \fInum_bytes\fP 1i
+Specifies the number of bytes in the string argument.
+.LP
+.eM
+The
+.PN XRebindKeysym
+function can be used to rebind the meaning of a KeySym for the client.
+It does not redefine any key in the X server but merely
+provides an easy way for long strings to be attached to keys.
+.PN XLookupString
+returns this string when the appropriate set of
+modifier keys are pressed and when the KeySym would have been used for
+the translation.
+No text conversions are performed;
+the client is responsible for supplying appropriately encoded strings.
+Note that you can rebind a KeySym that may not exist.
+.NH 2
+Allocating Permanent Storage
+.XS
+\*(SN Allocating Permanent Storage
+.XE
+.LP
+To allocate some memory you will never give back, use
+.PN Xpermalloc .
+.IN "Xpermalloc" "" "@DEF@"
+.sM
+.FD 0
+char *Xpermalloc\^(\^\fIsize\fP\^)
+.br
+     unsigned int \fIsize\fP\^;
+.FN
+.LP
+.eM
+The
+.PN Xpermalloc
+function allocates storage that can never be freed for the life of the
+program.  The memory is allocated with alignment for the C type double.
+This function may provide some performance and space savings over
+the standard operating system memory allocator.
+.NH 2
+Parsing the Window Geometry
+.XS
+\*(SN Parsing the Window Geometry 
+.XE
+.LP
+To parse standard window geometry strings, use
+.PN XParseGeometry .
+.IN "Window" "determining location"
+.IN "XParseGeometry" "" "@DEF@"
+.LP
+.sM
+.FD 0
+int XParseGeometry\^(\^\fIparsestring\fP\^, \fIx_return\fP\^, \fIy_return\fP\^, \fIwidth_return\fP\^, \fIheight_return\fP\^)
+.br
+      char *\fIparsestring\fP\^;
+.br
+      int *\fIx_return\fP\^, *\fIy_return\fP\^; 
+.br
+      unsigned int *\fIwidth_return\fP\^, *\fIheight_return\fP\^;
+.FN
+.IP \fIparsestring\fP 1i
+Specifies the string you want to parse.
+.IP \fIx_return\fP 1i
+.br
+.ns
+.IP \fIy_return\fP 1i
+Return the x and y offsets.
+.IP \fIwidth_return\fP 1i
+.br
+.ns
+.IP \fIheight_return\fP 1i
+Return the width and height determined.
+.LP
+.eM
+By convention,
+X applications use a standard string to indicate window size and placement.
+.PN XParseGeometry
+makes it easier to conform to this standard because it allows you
+to parse the standard window geometry.
+Specifically, this function lets you parse strings of the form:
+.LP
+.\" Start marker code here
+.Ds
+[=][<\fIwidth\fP>{xX}<\fIheight\fP>][{+-}<\fIxoffset\fP>{+-}<\fIyoffset\fP>] 
+.De
+.\" End marker code here
+.LP
+The fields map into the arguments associated with this function.
+(Items enclosed in <\^> are integers, items in [\^] are optional, and
+items enclosed in {\^} indicate ``choose one of.''
+Note that the brackets should not appear in the actual string.)
+If the string is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+.LP
+The
+.PN XParseGeometry
+function returns a bitmask that indicates which of the four values (width,
+height, xoffset, and yoffset) were actually found in the string 
+and whether the x and y values are negative. 
+By convention, \-0 is not equal to +0, because the user needs to
+be able to say ``position the window relative to the right or bottom edge.''
+For each value found, the corresponding argument is updated.
+For each value not found, the argument is left unchanged.
+The bits are represented by
+.PN XValue , 
+.PN YValue , 
+.PN WidthValue , 
+.PN HeightValue ,
+.PN XNegative , 
+or
+.PN YNegative
+and are defined in 
+.hN X11/Xutil.h .
+They will be set whenever one of the values is defined 
+or one of the signs is set.
+.LP
+If the function returns either the 
+.PN XValue 
+or 
+.PN YValue 
+flag,
+you should place the window at the requested position.
+.sp
+.LP
+To construct a window's geometry information, use
+.PN XWMGeometry .
+.IN "XWMGeometry" "" "@DEF@"
+.sM
+.FD 0
+int XWMGeometry\^(\^\fIdisplay\fP, \fIscreen\fP, \fIuser_geom\fP, \
+\fIdef_geom\fP, \fIbwidth\fP, \fIhints\fP, \fIx_return\fP, \fIy_return\fP,
+.br
+                \fIwidth_return\fP, \fIheight_return\fP, \fIgravity_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen\fP\^;
+.br
+      char *\fIuser_geom\fP\^;
+.br
+      char *\fIdef_geom\fP\^;
+.br
+      unsigned int \fIbwidth\fP\^;
+.br
+      XSizeHints *\fIhints\fP\^;
+.br
+      int *\fIx_return\fP, *\fIy_return\fP\^; 
+.br
+      int *\fIwidth_return\fP\^;
+.br
+      int *\fIheight_return\fP\^;
+.br
+      int *\fIgravity_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen\fP 1i
+Specifies the screen.
+.IP \fIuser_geom\fP 1i
+Specifies the user-specified geometry or NULL.
+.IP \fIdef_geom\fP 1i
+Specifies the application's default geometry or NULL.
+.IP \fIbwidth\fP 1i
+Specifies the border width.
+.IP \fIhints\fP 1i
+Specifies the size hints for the window in its normal state.
+.IP \fIx_return\fP 1i
+.br
+.ns
+.IP \fIy_return\fP 1i
+Return the x and y offsets.
+.IP \fIwidth_return\fP 1i
+.br
+.ns
+.IP \fIheight_return\fP 1i
+Return the width and height determined.
+.IP \fIgravity_return\fP 1i
+Returns the window gravity.
+.LP
+.eM
+The 
+.PN XWMGeometry 
+function combines any geometry information (given in the format used by 
+.PN XParseGeometry )
+specified by the user and by the calling program with size hints 
+(usually the ones to be stored in WM_NORMAL_HINTS) and returns the position, 
+size, and gravity
+.Pn ( NorthWestGravity , 
+.PN NorthEastGravity , 
+.PN SouthEastGravity ,
+or
+.PN SouthWestGravity ) 
+that describe the window.
+If the base size is not set in the 
+.PN XSizeHints
+structure, 
+the minimum size is used if set.
+Otherwise, a base size of zero is assumed.
+If no minimum size is set in the hints structure, 
+the base size is used.
+A mask (in the form returned by 
+.PN XParseGeometry ) 
+that describes which values came from the user specification 
+and whether or not the position coordinates are relative
+to the right and bottom edges is returned.
+Note that these coordinates will have already been accounted for 
+in the x_return and y_return values.
+.LP
+Note that invalid geometry specifications can cause a width or height 
+of zero to be returned.
+The caller may pass the address of the hints win_gravity field 
+as gravity_return to update the hints directly.
+.NH 2
+Manipulating Regions
+.XS
+\*(SN Manipulating Regions 
+.XE
+.LP
+Regions are arbitrary sets of pixel locations.
+Xlib provides functions for manipulating regions.
+The opaque type 
+.PN Region
+is defined in 
+.hN X11/Xutil.h .
+Xlib provides functions that you can use to manipulate regions.
+This section discusses how to:
+.IP \(bu 5
+Create, copy, or destroy regions
+.IP \(bu 5
+Move or shrink regions
+.IP \(bu 5
+Compute with regions
+.IP \(bu 5
+Determine if regions are empty or equal
+.IP \(bu 5
+Locate a point or rectangle in a region
+.NH 3
+Creating, Copying, or Destroying Regions
+.XS
+\*(SN Creating, Copying, or Destroying Regions 
+.XE
+.LP
+To create a new empty region, use
+.PN XCreateRegion .
+.IN "XCreateRegion" "" "@DEF@"
+.sM
+.FD 0
+Region XCreateRegion\^()
+.FN
+.LP
+.eM
+.sp
+To generate a region from a polygon, use
+.PN XPolygonRegion .
+.IN "XPolygonRegion" "" "@DEF@"
+.sM
+.FD 0
+Region XPolygonRegion\^(\^\fIpoints\fP\^, \fIn\fP\^, \fIfill_rule\fP\^)
+.br
+      XPoint \fIpoints[]\fP\^;
+.br
+      int \fIn\fP\^;
+.br
+      int \fIfill_rule\fP\^;	
+.FN
+.IP \fIpoints\fP 1i
+Specifies an array of points.
+.IP \fIn\fP 1i
+Specifies the number of points in the polygon. 
+.IP \fIfill_rule\fP 1i
+Specifies the fill-rule you want to set for the specified GC.
+You can pass 
+.PN EvenOddRule
+or
+.PN WindingRule .
+.LP
+.eM 
+The
+.PN XPolygonRegion
+function returns a region for the polygon defined by the points array.
+For an explanation of fill_rule,
+see
+.PN XCreateGC .
+.LP
+.sp
+To set the clip-mask of a GC to a region, use
+.PN XSetRegion .
+.IN "XSetRegion" "" "@DEF@"
+.sM
+.FD 0
+XSetRegion\^(\^\fIdisplay\fP, \fIgc\fP\^, \fIr\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      GC \fIgc\fP\^;
+.br
+      Region \fIr\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIgc\fP 1i
+Specifies the GC.
+.IP \fIr\fP 1i
+Specifies the region.
+.LP
+.eM
+The
+.PN XSetRegion
+function sets the clip-mask in the GC to the specified region.
+The region is specified relative to the drawable's origin.
+The resulting GC clip origin is implementation-dependent.
+Once it is set in the GC,
+the region can be destroyed.
+.LP 
+.sp
+To deallocate the storage associated with a specified region, use
+.PN XDestroyRegion .
+.IN "XDestroyRegion" "" "@DEF@"
+.sM
+.FD 0
+XDestroyRegion\^(\^\fIr\fP\^)
+.br
+      Region \fIr\fP\^;
+.FN
+.IP \fIr\fP 1i
+Specifies the region.
+.LP
+.eM
+.NH 3
+Moving or Shrinking Regions
+.XS
+\*(SN Moving or Shrinking Regions 
+.XE
+.LP
+To move a region by a specified amount, use 
+.PN XOffsetRegion .
+.IN "XOffsetRegion" "" "@DEF@"
+.sM
+.FD 0
+XOffsetRegion\^(\^\fIr\fP\^, \fIdx\fP\^, \fIdy\fP\^)
+.br
+      Region \fIr\fP\^;
+.br
+      int \fIdx\fP\^, \fIdy\fP\^;
+.FN
+.IP \fIr\fP 1i
+Specifies the region.
+.ds Dy move
+.IP \fIdx\fP 1i
+.br
+.ns
+.IP \fIdy\fP 1i
+Specify the x and y coordinates,
+which define the amount you want to \*(Dy the specified region.
+.LP
+.eM 
+.sp
+To reduce a region by a specified amount, use
+.PN XShrinkRegion .
+.IN "XShrinkRegion" "" "@DEF@"
+.sM
+.FD 0
+XShrinkRegion\^(\^\fIr\fP\^, \fIdx\fP\^, \fIdy\fP\^)
+.br
+      Region \fIr\fP\^;
+.br
+      int \fIdx\fP\^, \fIdy\fP\^;
+.FN
+.IP \fIr\fP 1i
+Specifies the region.
+.ds Dy shrink
+.IP \fIdx\fP 1i
+.br
+.ns
+.IP \fIdy\fP 1i
+Specify the x and y coordinates,
+which define the amount you want to \*(Dy the specified region.
+.LP
+.eM
+Positive values shrink the size of the region, 
+and negative values expand the region.
+.NH 3
+Computing with Regions
+.XS
+\*(SN Computing with Regions 
+.XE
+.LP
+.sp
+To generate the smallest rectangle enclosing a region, use
+.PN XClipBox .
+.IN "XClipBox" "" "@DEF@"
+.sM
+.FD 0
+XClipBox\^(\^\fIr\fP\^, \fIrect_return\fP\^)
+.br
+      Region \fIr\fP\^;
+.br
+      XRectangle *\fIrect_return\fP\^;
+.FN
+.IP \fIr\fP 1i
+Specifies the region.
+.IP \fIrect_return\fP 1i
+Returns the smallest enclosing rectangle.
+.LP
+.eM
+The
+.PN XClipBox
+function returns the smallest rectangle enclosing the specified region.
+.sp
+.LP
+To compute the intersection of two regions, use
+.PN XIntersectRegion .
+.IN "XIntersectRegion" "" "@DEF@"
+.sM
+.FD 0
+XIntersectRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^)
+.br
+      Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^;
+.FN
+.IP \fIsra\fP 1i
+.br
+.ns
+.IP \fIsrb\fP 1i
+Specify the two regions with which you want to perform the computation.
+.IP \fIdr_return\fP 1i
+Returns the result of the computation.
+.LP
+.eM
+.sp
+To compute the union of two regions, use
+.PN XUnionRegion .
+.IN "XUnionRegion" "" "@DEF@"
+.sM
+.FD 0
+XUnionRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^)
+.br
+      Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^;
+.FN
+.IP \fIsra\fP 1i
+.br
+.ns
+.IP \fIsrb\fP 1i
+Specify the two regions with which you want to perform the computation.
+.IP \fIdr_return\fP 1i
+Returns the result of the computation.
+.LP
+.eM
+.sp
+To create a union of a source region and a rectangle, use
+.PN XUnionRectWithRegion .
+.IN "XUnionRectWithRegion" "" "@DEF@"
+.sM
+.FD 0
+XUnionRectWithRegion\^(\^\fIrectangle\fP, \fIsrc_region\fP, \
+\fIdest_region_return\fP\^)
+.br
+     XRectangle *\fIrectangle\fP\^;
+.br
+     Region \fIsrc_region\fP\^;
+.br
+     Region \fIdest_region_return\fP\^;
+.FN
+.IP \fIrectangle\fP 1i
+Specifies the rectangle.
+.IP \fIsrc_region\fP 1i
+Specifies the source region to be used.
+.IP \fIdest_region_return\fP 1i
+Returns the destination region.
+.LP
+.eM
+The
+.PN XUnionRectWithRegion
+function updates the destination region from a union of the specified rectangle
+and the specified source region.
+.LP
+.sp
+To subtract two regions, use
+.PN XSubtractRegion .
+.IN "XSubtractRegion" "" "@DEF@"
+.sM
+.FD 0
+XSubtractRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^)
+.br
+      Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^;
+.FN
+.IP \fIsra\fP 1i
+.br
+.ns
+.IP \fIsrb\fP 1i
+Specify the two regions with which you want to perform the computation.
+.IP \fIdr_return\fP 1i
+Returns the result of the computation.
+.LP
+.eM
+The
+.PN XSubtractRegion
+function subtracts srb from sra and stores the results in dr_return.
+.LP
+.sp
+To calculate the difference between the union and intersection 
+of two regions, use
+.PN XXorRegion .
+.IN "XXorRegion" "" "@DEF@"
+.sM
+.FD 0
+XXorRegion\^(\^\fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^)
+.br
+      Region \fIsra\fP\^, \fIsrb\fP\^, \fIdr_return\fP\^;
+.FN
+.IP \fIsra\fP 1i
+.br
+.ns
+.IP \fIsrb\fP 1i
+Specify the two regions with which you want to perform the computation.
+.IP \fIdr_return\fP 1i
+Returns the result of the computation.
+.LP
+.eM
+.NH 3
+Determining if Regions Are Empty or Equal
+.XS
+\*(SN Determining if Regions Are Empty or Equal 
+.XE
+.LP
+To determine if the specified region is empty, use
+.PN XEmptyRegion .
+.IN "XEmptyRegion" "" "@DEF@"
+.sM
+.FD 0
+Bool XEmptyRegion\^(\^\fIr\fP\^)
+.br
+      Region \fIr\fP\^;
+.FN
+.IP \fIr\fP 1i
+Specifies the region.
+.LP
+.eM 
+The
+.PN XEmptyRegion
+function returns
+.PN True
+if the region is empty.
+.LP
+.sp
+To determine if two regions have the same offset, size, and shape, use
+.PN XEqualRegion .
+.IN "XEqualRegion" "" "@DEF@"
+.sM
+.FD 0
+Bool XEqualRegion\^(\^\fIr1\fP\^, \fIr2\fP\^)
+.br
+      Region \fIr1\fP\^, \fIr2\fP\^;
+.FN
+.IP \fIr1\fP 1i
+.br
+.ns
+.IP \fIr2\fP 1i
+Specify the two regions.
+.LP
+.eM
+The
+.PN XEqualRegion
+function returns
+.PN True
+if the two regions have the same offset, size, and shape.
+.NH 3
+Locating a Point or a Rectangle in a Region
+.XS
+\*(SN Locating a Point or a Rectangle in a Region 
+.XE
+.LP
+To determine if a specified point resides in a specified region, use
+.PN XPointInRegion .
+.IN "XPointInRegion" "" "@DEF@"
+.sM
+.FD 0
+Bool XPointInRegion\^(\^\fIr\fP\^, \fIx\fP\^, \fIy\fP\^)
+.br
+      Region \fIr\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^;
+.FN
+.IP \fIr\fP 1i
+Specifies the region.
+.ds Xy , which define the point
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.LP
+.eM
+The
+.PN XPointInRegion
+function returns 
+.PN True
+if the point (x, y) is contained in the region r.
+.LP
+.sp
+To determine if a specified rectangle is inside a region, use
+.PN XRectInRegion .
+.IN "XRectInRegion" "" "@DEF@"
+.sM
+.FD 0
+int XRectInRegion\^(\^\fIr\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
+.br
+      Region \fIr\fP\^;
+.br
+      int \fIx\fP\^, \fIy\fP\^; 
+.br
+      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
+.FN
+.IP \fIr\fP 1i
+Specifies the region.
+.ds Xy , which define the coordinates of the upper-left corner of the rectangle
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates\*(Xy.
+.ds Wh , which define the rectangle
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height\*(Wh.
+.LP
+.eM 
+The
+.PN XRectInRegion
+function returns
+.PN RectangleIn
+if the rectangle is entirely in the specified region,
+.PN RectangleOut
+if the rectangle is entirely out of the specified region,
+and
+.PN RectanglePart
+if the rectangle is partially in the specified region.
+.NH 2
+Using Cut Buffers
+.XS
+\*(SN Using Cut Buffers 
+.XE
+.LP
+.IN "Cut Buffers"
+Xlib provides functions to manipulate cut buffers,
+a very simple form of cut-and-paste inter-client communication.
+Selections are a much more powerful and useful mechanism for
+interchanging data between clients (see section 4.5)
+and generally should be used instead of cut buffers.
+.LP
+Cut buffers are implemented as properties on the first root window
+of the display.
+The buffers can only contain text, in the STRING encoding.
+The text encoding is not changed by Xlib when fetching or storing.
+Eight buffers are provided
+and can be accessed as a ring or as explicit buffers (numbered 0 through 7).
+.LP
+.sp
+To store data in cut buffer 0, use 
+.PN XStoreBytes .
+.IN "XStoreBytes" "" "@DEF@"
+.sM
+.FD 0
+XStoreBytes\^(\^\fIdisplay\fP, \fIbytes\fP\^, \fInbytes\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      char *\fIbytes\fP\^;
+.br
+      int \^\fInbytes\fP\^;
+.br
+.FN 
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIbytes\fP 1i
+Specifies the bytes, which are not necessarily ASCII or null-terminated.
+.IP \fInbytes\fP 1i
+Specifies the number of bytes to be stored.
+.LP
+.eM
+The data can have embedded null characters
+and need not be null-terminated.
+The cut buffer's contents can be retrieved later by
+any client calling
+.PN XFetchBytes .
+.LP
+.PN XStoreBytes
+can generate a
+.PN BadAlloc
+error.
+.LP
+.sp
+To store data in a specified cut buffer, use
+.PN XStoreBuffer .
+.IN "XStoreBuffer" "" "@DEF@"
+.sM
+.FD 0
+XStoreBuffer\^(\^\fIdisplay\fP, \fIbytes\fP\^, \fInbytes\fP\^, \fIbuffer\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      char *\fIbytes\fP\^;
+.br
+      int \^\fInbytes\fP\^;
+.br
+      int \fIbuffer\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIbytes\fP 1i
+Specifies the bytes, which are not necessarily ASCII or null-terminated.
+.IP \fInbytes\fP 1i
+Specifies the number of bytes to be stored.
+.ds Fn in which you want to store the bytes
+.IP \fIbuffer\fP 1i
+Specifies the buffer \*(Fn.
+.LP
+.eM
+If an invalid buffer is specified, the call has no effect.
+The data can have embedded null characters
+and need not be null-terminated.
+.LP
+.PN XStoreBuffer
+can generate a
+.PN BadAlloc 
+error.
+.LP
+.sp
+To return data from cut buffer 0, use 
+.PN XFetchBytes .
+.IN "XFetchBytes" "" "@DEF@"
+.sM
+.FD 0
+char *XFetchBytes\^(\^\fIdisplay\fP, \fInbytes_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int *\fInbytes_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fInbytes_return\fP 1i
+Returns the number of bytes in the buffer.
+.LP
+.eM
+The
+.PN XFetchBytes
+function
+returns the number of bytes in the nbytes_return argument,
+if the buffer contains data.
+Otherwise, the function
+returns NULL and sets nbytes to 0.
+The appropriate amount of storage is allocated and the pointer returned.
+The client must free this storage when finished with it by calling
+.PN XFree .
+.LP
+.sp
+To return data from a specified cut buffer, use 
+.PN XFetchBuffer .
+.IN "XFetchBuffer" "" "@DEF@"
+.sM
+.FD 0
+char *XFetchBuffer\^(\^\fIdisplay\fP, \fInbytes_return\fP\^, \fIbuffer\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int *\fInbytes_return\fP\^;
+.br
+      int \fIbuffer\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fInbytes_return\fP 1i
+Returns the number of bytes in the buffer.
+.ds Fn from which you want the stored data returned
+.IP \fIbuffer\fP 1i
+Specifies the buffer \*(Fn.
+.LP
+.eM
+The
+.PN XFetchBuffer
+function returns zero to the nbytes_return argument 
+if there is no data in the buffer or if an invalid
+buffer is specified.
+.LP
+.sp
+To rotate the cut buffers, use 
+.PN XRotateBuffers .
+.IN "XRotateBuffers" "" "@DEF@"
+.sM
+.FD 0
+XRotateBuffers\^(\^\fIdisplay\fP, \fIrotate\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIrotate\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIrotate\fP 1i
+Specifies how much to rotate the cut buffers.
+.LP
+.eM 
+The
+.PN XRotateBuffers
+function rotates the cut
+buffers, such that buffer 0 becomes buffer n, 
+buffer 1 becomes n + 1 mod 8, and so on.
+This cut buffer numbering is global to the display.
+Note that
+.PN XRotateBuffers
+generates
+.PN BadMatch
+errors if any of the eight buffers have not been created.
+.NH 2
+Determining the Appropriate Visual Type
+.XS
+\*(SN Determining the Appropriate Visual Type
+.XE
+.LP
+A single display can support multiple screens.
+Each screen can have several different visual types supported 
+at different depths.
+You can use the functions described in this section to determine
+which visual to use for your application.
+.LP
+The functions in this section use the visual information masks and the
+.PN XVisualInfo 
+structure,
+which is defined in
+.hN X11/Xutil.h
+and contains:
+.sM
+.LP
+/* Visual information mask bits */
+.TS
+lw(.5i) lw(2.5i) lw(.8i).
+T{
+#define
+T}	T{
+.PN VisualNoMask
+T}	T{
+0x0
+T}
+T{
+#define
+T}	T{
+.PN VisualIDMask
+T}	T{
+0x1
+T}
+T{
+#define
+T}	T{
+.PN VisualScreenMask
+T}	T{
+0x2
+T}
+T{
+#define
+T}	T{
+.PN VisualDepthMask
+T}	T{
+0x4
+T}
+T{
+#define
+T}	T{
+.PN VisualClassMask
+T}	T{
+0x8
+T}
+T{
+#define
+T}	T{
+.PN VisualRedMaskMask
+T}	T{
+0x10
+T}
+T{
+#define
+T}	T{
+.PN VisualGreenMaskMask
+T}	T{
+0x20
+T}
+T{
+#define
+T}	T{
+.PN VisualBlueMaskMask
+T}	T{
+0x40
+T}
+T{
+#define
+T}	T{
+.PN VisualColormapSizeMask
+T}	T{
+0x80
+T}
+T{
+#define
+T}	T{
+.PN VisualBitsPerRGBMask
+T}	T{
+0x100
+T}
+T{
+#define
+T}	T{
+.PN VisualAllMask
+T}	T{
+0x1FF
+T}
+.TE
+.IN "XVisualInfo" "" "@DEF@"
+.Ds 0
+.TA .5i 3i
+.ta .5i 3i
+/* Values */
+
+typedef struct {
+	Visual *visual;
+	VisualID visualid;
+	int screen;
+	unsigned int depth;
+	int class;
+	unsigned long red_mask;
+	unsigned long green_mask;
+	unsigned long blue_mask;
+	int colormap_size;
+	int bits_per_rgb;
+} XVisualInfo;
+.De
+.LP
+.eM
+To obtain a list of visual information structures that match a specified
+template, use
+.PN XGetVisualInfo .
+.IN "XGetVisualInfo" "" "@DEF@"
+.sM
+.FD 0
+XVisualInfo *XGetVisualInfo\^(\^\fIdisplay\fP, \fIvinfo_mask\fP, \fIvinfo_template\fP, \fInitems_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      long \fIvinfo_mask\fP\^;
+.br
+      XVisualInfo *\fIvinfo_template\fP\^;
+.br
+      int *\fInitems_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIvinfo_mask\fP 1i
+Specifies the visual mask value.
+.IP \fIvinfo_template\fP 1i
+Specifies the visual attributes that are to be used in matching the visual
+structures.
+.IP \fInitems_return\fP 1i
+Returns the number of matching visual structures.
+.LP
+.eM
+The
+.PN XGetVisualInfo
+function returns a list of visual structures that have attributes 
+equal to the attributes specified by vinfo_template.
+If no visual structures match the template using the specified vinfo_mask,
+.PN XGetVisualInfo
+returns a NULL.
+To free the data returned by this function, use
+.PN XFree .
+.LP
+.sp
+To obtain the visual information that matches the specified depth and
+class of the screen, use
+.PN XMatchVisualInfo .
+.IN "XMatchVisualInfo" "" "@DEF@"
+.sM
+.FD 0
+Status XMatchVisualInfo\^(\^\fIdisplay\fP, \fIscreen\fP, \fIdepth\fP, \fIclass\fP, \fIvinfo_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      int \fIscreen\fP\^;
+.br
+      int \fIdepth\fP\^;
+.br
+      int \fIclass\fP\^;
+.br
+      XVisualInfo *\fIvinfo_return\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIscreen\fP 1i
+Specifies the screen.
+.IP \fIdepth\fP 1i
+Specifies the depth of the screen.
+.IP \fIclass\fP 1i
+Specifies the class of the screen.
+.IP \fIvinfo_return\fP 1i
+Returns the matched visual information.
+.LP
+.eM
+The
+.PN XMatchVisualInfo
+function returns the visual information for a visual that matches the specified
+depth and class for a screen.
+Because multiple visuals that match the specified depth and class can exist,
+the exact visual chosen is undefined.
+If a visual is found,
+.PN XMatchVisualInfo
+returns nonzero and the information on the visual to vinfo_return.
+Otherwise, when a visual is not found,
+.PN XMatchVisualInfo
+returns zero.
+.NH 2
+Manipulating Images
+.XS
+\*(SN Manipulating Images 
+.XE
+.LP
+Xlib provides several functions that perform basic operations on images.
+All operations on images are defined using an 
+.PN XImage 
+structure, 
+as defined in
+.hN X11/Xlib.h .
+Because the number of different types of image formats can be very large,
+this hides details of image storage properly from applications.
+.LP
+This section describes the functions for generic operations on images.
+Manufacturers can provide very fast implementations of these for the
+formats frequently encountered on their hardware.
+These functions are neither sufficient nor desirable to use for general image
+processing.
+Rather, they are here to provide minimal functions on screen format
+images.
+The basic operations for getting and putting images are
+.PN XGetImage
+and 
+.PN XPutImage .
+.LP
+Note that no functions have been defined, as yet, to read and write images 
+to and from disk files.
+.LP
+The
+.PN XImage 
+structure describes an image as it exists in the client's memory.  
+The user can request that some of the members such as height, width, 
+and xoffset be changed when the image is sent to the server.
+Note that bytes_per_line in concert with offset can be used to
+extract a subset of the image.
+Other members (for example, byte order, bitmap_unit, and so forth)
+are characteristics of both the image and the server.  
+If these members
+differ between the image and the server, 
+.PN XPutImage 
+makes the appropriate conversions.
+The first byte of the first line of
+plane n must be located at the address (data + (n * height * bytes_per_line)).
+For a description of the 
+.PN XImage 
+structure,
+see section 8.7.
+.LP
+.sp
+To allocate an 
+.PN XImage 
+structure and initialize it with image format values from a display, use
+.PN XCreateImage .
+.IN "XCreateImage" "" "@DEF@"
+.sM
+.FD 0
+XImage *XCreateImage\^(\^\fIdisplay\fP, \fIvisual\fP, \fIdepth\fP, \fIformat\fP, \fIoffset\fP, \fIdata\fP, \fIwidth\fP, \fIheight\fP\^, \fIbitmap_pad\fP, 
+.br
+                        \fIbytes_per_line\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Visual *\fIvisual\fP\^;
+.br
+      unsigned int \fIdepth\fP\^;
+.br
+      int \fIformat\fP\^;
+.br
+      int \fIoffset\fP\^;
+.br
+      char *\fIdata\fP\^;
+.br
+      unsigned int \fIwidth\fP\^;
+.br
+      unsigned int \fIheight\fP\^;
+.br
+      int \fIbitmap_pad\fP\^;
+.br
+      int \fIbytes_per_line\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIvisual\fP 1i
+Specifies the
+.PN Visual
+structure.
+.IP \fIdepth\fP 1i
+Specifies the depth of the image.
+.IP \fIformat\fP 1i
+Specifies the format for the image.
+You can pass
+.PN XYBitmap ,
+.PN XYPixmap ,
+or 
+.PN ZPixmap .
+.IP \fIoffset\fP 1i
+Specifies the number of pixels to ignore at the beginning of the scanline.
+.IP \fIdata\fP 1i
+Specifies the image data.
+.IP \fIwidth\fP 1i
+Specifies the width of the image, in pixels.
+.IP \fIheight\fP 1i
+Specifies the height of the image, in pixels.
+.IP \fIbitmap_pad\fP 1i
+Specifies the quantum of a scanline (8, 16, or 32).
+In other words, the start of one scanline is separated in client memory from 
+the start of the next scanline by an integer multiple of this many bits.  
+.IP \fIbytes_per_line\fP 1i
+Specifies the number of bytes in the client image between
+the start of one scanline and the start of the next.  
+.LP
+.eM
+The
+.PN XCreateImage
+function allocates the memory needed for an
+.PN XImage
+structure for the
+specified display but does not allocate space for the image itself.
+Rather, it initializes the structure byte-order, bit-order, and bitmap-unit
+values from the display and returns a pointer to the 
+.PN XImage 
+structure.
+The red, green, and blue mask values are defined for Z format images only
+and are derived from the 
+.PN Visual 
+structure passed in.
+Other values also are passed in.
+The offset permits the rapid displaying of the image without requiring each 
+scanline to be shifted into position.
+If you pass a zero value in bytes_per_line,
+Xlib assumes that the scanlines are contiguous
+in memory and calculates the value of bytes_per_line itself.
+.LP
+Note that when the image is created using
+.PN XCreateImage ,
+.PN XGetImage ,
+or
+.PN XSubImage ,
+the destroy procedure that the 
+.PN XDestroyImage
+function calls frees both the image structure 
+and the data pointed to by the image structure.
+.LP
+The basic functions used to get a pixel, set a pixel, create a subimage,
+and add a constant value to an image are defined in the image object.
+The functions in this section are really macro invocations of the functions
+in the image object and are defined in
+.hN X11/Xutil.h .
+.LP
+.sp
+To obtain a pixel value in an image, use
+.PN XGetPixel .
+.IN "XGetPixel" "" "@DEF@"
+.sM
+.FD 0
+unsigned long XGetPixel\^(\^\fIximage\fP, \fIx\fP, \fIy\fP\^)
+.br
+      XImage *\fIximage\fP\^;
+.br
+      int \fIx\fP\^;
+.br
+      int \fIy\fP\^;
+.FN
+.IP \fIximage\fP 1i
+Specifies the image.
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates.
+.LP
+.eM
+The
+.PN XGetPixel
+function returns the specified pixel from the named image.
+The pixel value is returned in normalized format (that is,
+the least significant byte of the long is the least significant byte
+of the pixel).
+The image must contain the x and y coordinates.
+.LP
+.sp
+To set a pixel value in an image, use
+.PN XPutPixel .
+.IN "XPutPixel" "" "@DEF@"
+.sM
+.FD 0
+XPutPixel\^(\^\fIximage\fP, \fIx\fP, \fIy\fP, \fIpixel\fP\^)
+.br
+      XImage *\fIximage\fP\^;
+.br
+      int \fIx\fP\^;
+.br
+      int \fIy\fP\^;
+.br
+      unsigned long \fIpixel\fP\^;
+.FN
+.IP \fIximage\fP 1i
+Specifies the image.
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates.
+.IP \fIpixel\fP 1i
+Specifies the new pixel value.
+.LP
+.eM
+The
+.PN XPutPixel
+function overwrites the pixel in the named image with the specified pixel value.
+The input pixel value must be in normalized format
+(that is, the least significant byte of the long is the least significant
+byte of the pixel).
+The image must contain the x and y coordinates.
+.LP
+.sp
+To create a subimage, use
+.PN XSubImage .
+.IN "XSubImage" "" "@DEF@"
+.sM
+.FD 0
+XImage *XSubImage\^(\^\fIximage\fP, \fIx\fP, \fIy\fP, \fIsubimage_width\fP, \fIsubimage_height\fP\^)
+.br
+      XImage *\fIximage\fP\^;
+.br
+      int \fIx\fP\^;
+.br
+      int \fIy\fP\^;
+.br
+      unsigned int \fIsubimage_width\fP\^;
+.br
+      unsigned int \fIsubimage_height\fP\^;
+.FN
+.IP \fIximage\fP 1i
+Specifies the image.
+.IP \fIx\fP 1i
+.br
+.ns
+.IP \fIy\fP 1i
+Specify the x and y coordinates.
+.IP \fIsubimage_width\fP 1i
+Specifies the width of the new subimage, in pixels.
+.IP \fIsubimage_height\fP 1i
+Specifies the height of the new subimage, in pixels.
+.LP
+.eM
+The
+.PN XSubImage
+function creates a new image that is a subsection of an existing one.
+It allocates the memory necessary for the new
+.PN XImage
+structure
+and returns a pointer to the new image.
+The data is copied from the source image,
+and the image must contain the rectangle defined by x, y, subimage_width,
+and subimage_height.
+.LP
+.sp
+To increment each pixel in an image by a constant value, use
+.PN XAddPixel .
+.IN "XAddPixel" "" "@DEF@"
+.sM
+.FD 0
+XAddPixel\^(\^\fIximage\fP, \fIvalue\fP\^)
+.br
+      XImage *\fIximage\fP\^;
+.br
+      long \fIvalue\fP\^;
+.FN
+.IP \fIximage\fP 1i
+Specifies the image.
+.IP \fIvalue\fP 1i
+Specifies the constant value that is to be added.
+.LP
+.eM
+The
+.PN XAddPixel
+function adds a constant value to every pixel in an image.
+It is useful when you have a base pixel value from allocating
+color resources and need to manipulate the image to that form.
+.LP
+.sp
+To deallocate the memory allocated in a previous call to
+.PN XCreateImage ,
+use
+.PN XDestroyImage .
+.IN "XDestroyImage" "" "@DEF@"
+.sM
+.FD 0
+XDestroyImage\^(\^\fIximage\fP\^)
+.br
+        XImage *\^\fIximage\fP\^; 
+.FN
+.IP \fIximage\fP 1i
+Specifies the image.
+.LP
+.eM
+The
+.PN XDestroyImage
+function deallocates the memory associated with the
+.PN XImage
+structure.
+.LP
+Note that when the image is created using
+.PN XCreateImage ,
+.PN XGetImage ,
+or 
+.PN XSubImage ,
+the destroy procedure that this macro calls
+frees both the image structure and the data pointed to by the image structure. 
+.NH 2
+Manipulating Bitmaps
+.XS
+\*(SN Manipulating Bitmaps 
+.XE
+.LP
+Xlib provides functions that you can use to read a bitmap from a file,
+save a bitmap to a file, or create a bitmap. 
+This section describes those functions that transfer bitmaps to and
+from the client's file system, thus allowing their reuse in a later
+connection (for example, from an entirely different client or to a
+different display or server).
+.LP
+The X version 11 bitmap file format is:
+.LP
+.sM
+.Ds 0
+#define \fIname\fP_width \fIwidth\fP
+#define \fIname\fP_height \fIheight\fP
+#define \fIname\fP_x_hot \fIx\fP
+#define \fIname\fP_y_hot \fIy\fP
+static unsigned char \fIname\fP_bits[] = { 0x\fINN\fP,... }
+.De
+.LP
+.eM
+The lines for the variables ending with _x_hot and _y_hot suffixes are optional
+because they are present only if a hotspot has been defined for this bitmap.
+The lines for the other variables are required.
+The word ``unsigned'' is optional;
+that is, the type of the _bits array can be ``char'' or ``unsigned char''.
+The _bits array must be large enough to contain the size bitmap.
+The bitmap unit is 8.
+.LP
+.sp
+To read a bitmap from a file and store it in a pixmap, use
+.PN XReadBitmapFile .
+.IN "XReadBitmapFile" "" "@DEF@"
+.sM
+.FD 0
+int XReadBitmapFile(\^\fIdisplay\fP, \fId\fP, \fIfilename\fP, \fIwidth_return\fP, \fIheight_return\fP, \fIbitmap_return\fP, \fIx_hot_return\fP, 
+.br
+                       \fIy_hot_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      char *\fIfilename\fP\^;
+.br
+      unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^;
+.br
+      Pixmap *\fIbitmap_return\fP\^;
+.br
+      int *\fIx_hot_return\fP, *\fIy_hot_return\fP\^;	
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Dr \ that indicates the screen
+.IP \fId\fP 1i
+Specifies the drawable\*(Dr. 
+.IP \fIfilename\fP 1i
+Specifies the file name to use.
+The format of the file name is operating-system dependent.
+.IP \fIwidth_return\fP 1i
+.br
+.ns
+.IP \fIheight_return\fP 1i
+Return the width and height values of the read in bitmap file.
+.IP \fIbitmap_return\fP 1i
+Returns the bitmap that is created.
+.IP \fIx_hot_return\fP 1i
+.br
+.ns
+.IP \fIy_hot_return\fP 1i
+Return the hotspot coordinates.
+.LP
+.eM
+The
+.PN XReadBitmapFile
+function reads in a file containing a bitmap.
+The file is parsed in the encoding of the current locale.
+The ability to read other than the standard format 
+is implementation-dependent.
+If the file cannot be opened, 
+.PN XReadBitmapFile 
+returns 
+.PN BitmapOpenFailed .  
+If the file can be opened but does not contain valid bitmap data, 
+it returns 
+.PN BitmapFileInvalid .  
+If insufficient working storage is allocated,
+it returns
+.PN BitmapNoMemory .  
+If the file is readable and valid,
+it returns 
+.PN BitmapSuccess .
+.LP
+.PN XReadBitmapFile 
+returns the bitmap's height and width, as read
+from the file, to width_return and height_return.
+It then creates a pixmap of the appropriate size, 
+reads the bitmap data from the file into the pixmap,
+and assigns the pixmap to the caller's variable bitmap.  
+The caller must free the bitmap using 
+.PN XFreePixmap 
+when finished.
+If \fIname\fP_x_hot and \fIname\fP_y_hot exist,
+.PN XReadBitmapFile 
+returns them to x_hot_return and y_hot_return;
+otherwise, it returns \-1,\-1.
+.LP
+.PN XReadBitmapFile
+can generate
+.PN BadAlloc ,
+.PN BadDrawable ,
+and
+.PN BadGC
+errors.
+.LP
+.sp
+To read a bitmap from a file and return it as data, use
+.PN XReadBitmapFileData .
+.IN "XReadBitmapFileData" "" "@DEF@"
+.sM
+.FD 0
+int XReadBitmapFileData(\^\fIfilename\fP, \fIwidth_return\fP, \fIheight_return\fP, \fIdata_return\fP, \fIx_hot_return\fP, \fIy_hot_return\fP\^)
+.br
+      char *\fIfilename\fP\^;
+.br
+      unsigned int *\fIwidth_return\fP, *\fIheight_return\fP\^;
+.br
+      unsigned char *\fIdata_return\fP\^;
+.br
+      int *\fIx_hot_return\fP, *\fIy_hot_return\fP\^;	
+.FN
+.IP \fIfilename\fP 1i
+Specifies the file name to use.
+The format of the file name is operating-system dependent.
+.IP \fIwidth_return\fP 1i
+.br
+.ns
+.IP \fIheight_return\fP 1i
+Return the width and height values of the read in bitmap file.
+.IP \fIdata_return\fP 1i
+Returns the bitmap data.
+.IP \fIx_hot_return\fP 1i
+.br
+.ns
+.IP \fIy_hot_return\fP 1i
+Return the hotspot coordinates.
+.LP
+.eM
+The
+.PN XReadBitmapFileData
+function reads in a file containing a bitmap, in the same manner as
+.PN XReadBitmapFile ,
+but returns the data directly rather than creating a pixmap in the server.
+The bitmap data is returned in data_return; the client must free this
+storage when finished with it by calling
+.PN XFree .
+The status and other return values are the same as for
+.PN XReadBitmapFile .
+.LP
+.sp
+To write out a bitmap from a pixmap to a file, use
+.PN XWriteBitmapFile .
+.IN "XWriteBitmapFile" "" "@DEF@"
+.sM
+.FD 0
+int XWriteBitmapFile(\^\fIdisplay\fP, \fIfilename\fP, \fIbitmap\fP, \fIwidth\fP, \fIheight\fP, \fIx_hot\fP, \fIy_hot\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      char *\fIfilename\fP\^;
+.br
+      Pixmap \fIbitmap\fP\^;
+.br
+      unsigned int \fIwidth\fP, \fIheight\fP\^;
+.br
+      int \fIx_hot\fP, \fIy_hot\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIfilename\fP 1i
+Specifies the file name to use.
+The format of the file name is operating-system dependent.
+.IP \fIbitmap\fP 1i
+Specifies the bitmap.
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height.
+.IP \fIx_hot\fP 1i
+.br
+.ns
+.IP \fIy_hot\fP 1i
+Specify where to place the hotspot coordinates (or \-1,\-1 if none are present)
+in the file.
+.LP
+.eM
+The
+.PN XWriteBitmapFile
+function writes a bitmap out to a file in the X Version 11 format.
+The name used in the output file is derived from the file name
+by deleting the directory prefix.
+The file is written in the encoding of the current locale.
+If the file cannot be opened for writing, 
+it returns 
+.PN BitmapOpenFailed .  
+If insufficient memory is allocated,
+.PN XWriteBitmapFile
+returns
+.PN BitmapNoMemory ;
+otherwise, on no error,
+it returns
+.PN BitmapSuccess .
+If x_hot and y_hot are not \-1, \-1, 
+.PN XWriteBitmapFile
+writes them out as the hotspot coordinates for the bitmap.
+.LP
+.PN XWriteBitmapFile
+can generate
+.PN BadDrawable
+and
+.PN BadMatch
+errors.
+.LP
+.sp
+To create a pixmap and then store bitmap-format data into it, use
+.PN XCreatePixmapFromBitmapData .
+.IN "XCreatePixmapFromBitmapData" "" "@DEF@"
+.sM
+.FD 0
+Pixmap XCreatePixmapFromBitmapData\^(\^\fIdisplay\fP, \fId\fP, \fIdata\fP, \fIwidth\fP, \fIheight\fP, \fIfg\fP, \fIbg\fP, \fIdepth\fP\^)
+.br
+     Display *\fIdisplay\fP\^;
+.br
+     Drawable \fId\fP\^;
+.br
+     char *\fIdata\fP\^;
+.br
+     unsigned int \fIwidth\fP, \fIheight\fP\^;
+.br
+     unsigned long \fIfg\fP, \fIbg\fP\^;
+.br
+     unsigned int \fIdepth\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Dr \ that indicates the screen
+.IP \fId\fP 1i
+Specifies the drawable\*(Dr. 
+.IP \fIdata\fP 1i
+Specifies the data in bitmap format.
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height.
+.IP \fIfg\fP 1i
+.br
+.ns
+.IP \fIbg\fP 1i
+Specify the foreground and background pixel values to use.
+.IP \fIdepth\fP 1i
+Specifies the depth of the pixmap.
+.LP
+.eM
+The
+.PN XCreatePixmapFromBitmapData
+function creates a pixmap of the given depth and then does a bitmap-format
+.PN XPutImage
+of the data into it.
+The depth must be supported by the screen of the specified drawable,
+or a
+.PN BadMatch
+error results.
+.LP
+.PN XCreatePixmapFromBitmapData
+can generate
+.PN BadAlloc ,
+.PN BadDrawable ,
+.PN BadGC ,
+and
+.PN BadValue
+errors.
+.LP
+.sp
+To include a bitmap written out by 
+.PN XWriteBitmapFile 
+.IN "XWriteBitmapFile"
+in a program directly, as opposed to reading it in every time at run time, use
+.PN XCreateBitmapFromData .
+.IN "XCreateBitmapFromData" "" "@DEF@"
+.sM
+.FD 0
+Pixmap XCreateBitmapFromData(\^\fIdisplay\fP, \fId\fP, \fIdata\fP, \fIwidth\fP, \fIheight\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      Drawable \fId\fP\^;
+.br
+      char *\fIdata\fP\^;
+.br
+      unsigned int \fIwidth\fP, \fIheight\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.ds Dr \ that indicates the screen
+.IP \fId\fP 1i
+Specifies the drawable\*(Dr. 
+.IP \fIdata\fP 1i
+Specifies the location of the bitmap data.
+.IP \fIwidth\fP 1i
+.br
+.ns
+.IP \fIheight\fP 1i
+Specify the width and height.
+.LP
+.eM
+The
+.PN XCreateBitmapFromData
+function allows you to include in your C program (using
+.PN #include )
+a bitmap file that was written out by
+.PN XWriteBitmapFile
+(X version 11 format only) without reading in the bitmap file.
+The following example creates a gray bitmap:
+.LP
+.Ds 0
+#include "gray.bitmap"
+.sp 6p
+Pixmap bitmap;
+bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height);
+.De
+.LP
+If insufficient working storage was allocated,
+.PN XCreateBitmapFromData
+returns
+.PN None .
+It is your responsibility to free the
+bitmap using
+.PN XFreePixmap
+when finished.
+.LP
+.PN XCreateBitmapFromData
+can generate
+.PN BadAlloc
+and
+.PN BadGC
+errors.
+.NH 2
+Using the Context Manager
+.XS
+\*(SN Using the Context Manager 
+.XE
+.LP
+The context manager provides a way of associating data with an X resource ID
+(mostly typically a window) in your program.  
+Note that this is local to your program;
+the data is not stored in the server on a property list.
+Any amount of data in any number of pieces can be associated with a
+resource ID,
+and each piece of data has a type associated with it.  
+The context manager requires knowledge of the resource ID
+and type to store or retrieve data.
+.LP
+Essentially, the context manager can be viewed as a two-dimensional, 
+sparse array:  one dimension is subscripted by the X resource ID
+and the other by a context type field.
+Each entry in the array contains a pointer to the data.
+Xlib provides context management functions with which you can
+save data values, get data values, delete entries, and create a unique
+context type.
+The symbols used are in
+.hN X11/Xutil.h .
+.LP
+.sp
+To save a data value that corresponds to a resource ID and context type, use
+.PN XSaveContext .
+.IN "XSaveContext" "" "@DEF@"
+.sM
+.FD 0
+int XSaveContext(\^\fIdisplay\fP, \fIrid\fP, \fIcontext\fP, \fIdata\fP\^)
+.br
+      Display *\fIdisplay\fP\^;	
+.br
+      XID \fIrid\fP\^;
+.br
+      XContext \fIcontext\fP\^;
+.br
+      XPointer \fIdata\fP\^;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIrid\fP 1i
+Specifies the resource ID with which the data is associated.
+.IP \fIcontext\fP 1i
+Specifies the context type to which the data belongs.
+.IP \fIdata\fP 1i
+Specifies the data to be associated with the window and type.
+.LP
+.eM
+If an entry with the specified resource ID and type already exists,
+.PN XSaveContext
+overrides it with the specified context.
+The
+.PN XSaveContext
+function returns a nonzero error code if an error has occurred
+and zero otherwise.
+Possible errors are
+.PN XCNOMEM
+(out of memory).
+.LP
+.sp
+To get the data associated with a resource ID and type, use
+.PN XFindContext .
+.IN "XFindContext" "" "@DEF@"
+.sM
+.FD 0
+int XFindContext(\^\fIdisplay\fP, \fIrid\fP, \fIcontext\fP, \fIdata_return\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XID \fIrid\fP\^;
+.br
+      XContext \fIcontext\fP\^;
+.br
+      XPointer *\fIdata_return\fP\^;	
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIrid\fP 1i
+Specifies the resource ID with which the data is associated.
+.IP \fIcontext\fP 1i
+Specifies the context type to which the data belongs.
+.IP \fIdata_return\fP 1i
+Returns the data.
+.LP
+.eM
+Because it is a return value,
+the data is a pointer.
+The
+.PN XFindContext
+function returns a nonzero error code if an error has occurred
+and zero otherwise.
+Possible errors are
+.PN XCNOENT
+(context-not-found).
+.LP
+.sp
+To delete an entry for a given resource ID and type, use
+.PN XDeleteContext .
+.IN "XDeleteContext" "" "@DEF@"
+.sM
+.FD 0
+int XDeleteContext(\^\fIdisplay\fP, \fIrid\fP, \fIcontext\fP\^)
+.br
+      Display *\fIdisplay\fP\^;
+.br
+      XID \fIrid\fP;
+.br
+      XContext \fIcontext\fP;
+.FN
+.IP \fIdisplay\fP 1i
+Specifies the connection to the X server.
+.IP \fIrid\fP 1i
+Specifies the resource ID with which the data is associated.
+.IP \fIcontext\fP 1i
+Specifies the context type to which the data belongs.
+.LP
+.eM
+The
+.PN XDeleteContext
+function deletes the entry for the given resource ID 
+and type from the data structure.
+This function returns the same error codes that
+.PN XFindContext
+returns if called with the same arguments.
+.PN XDeleteContext
+does not free the data whose address was saved.
+.LP
+.sp
+To create a unique context type that may be used in subsequent calls to
+.PN XSaveContext 
+and
+.PN XFindContext ,
+use
+.PN XUniqueContext .
+.IN "XUniqueContext" "" "@DEF@"
+.sM
+.FD 0
+XContext XUniqueContext(\^)
+.FN
+.LP
+.eM
+.bp
diff --git a/specs/libX11/Makefile.am b/specs/libX11/Makefile.am
new file mode 100644
index 00000000..7d244584
--- /dev/null
+++ b/specs/libX11/Makefile.am
@@ -0,0 +1,44 @@
+#
+# Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
+#
+# Permission to use, copy, modify, distribute, and sell this software and its
+# documentation for any purpose is hereby granted without fee, provided that
+# the above copyright notice appear in all copies and that both that
+# copyright notice and this permission notice appear in supporting
+# documentation.
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# 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 OPEN GROUP 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.
+#
+# Except as contained in this notice, the name of the copyright holders 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 copyright holders.
+#
+
+# Based on xc/doc/specs/X11/Makefile from X11R6.9
+
+doc_sources = libX11.ms
+
+doc_includes = \
+	abstract.t \
+        credits.t \
+        CH[01][0123456789] \
+        App[ABCD] \
+        glossary \
+        postproc
+
+include $(top_srcdir)/specs/troffrules.in
+
+EXTRA_DIST += $(doc_includes)
+
+
+
diff --git a/specs/libX11/abstract.t b/specs/libX11/abstract.t
new file mode 100644
index 00000000..fe15d1fb
--- /dev/null
+++ b/specs/libX11/abstract.t
@@ -0,0 +1,106 @@
+.\" $XFree86: xc/doc/specs/X11/abstract.t,v 1.2 2003/07/09 15:27:26 tsi Exp $
+.EH ''''
+.OH ''''
+.EF ''''
+.OF ''''
+.ps 11
+.nr PS 11
+\&
+.sp 5
+.ce 6
+\s+2\fBXlib \- C Language X Interface\fP\s-2
+
+\s+1\fBX Window System Standard\fP\s-1
+
+\s+1\fBX Version 11, Release 7\fP\s-1
+
+\s+1\fB\*(xV\fP\s-1
+.sp 6
+.ce 4
+\s-1James Gettys
+.sp 6p
+Cambridge Research Laboratory
+Digital Equipment Corporation
+.sp 2
+.ce 4
+Robert W. Scheifler
+.sp 6p
+Laboratory for Computer Science
+Massachusetts Institute of Technology
+.sp 3
+.ce 1
+\fIwith contributions from\fP
+.sp 3
+.ce 11
+Chuck Adams, Tektronix, Inc.
+.sp 1
+Vania Joloboff, Open Software Foundation
+.sp 1
+Hideki Hiura, Sun Microsystems, Inc.
+.sp 1
+Bill McMahon, Hewlett-Packard Company
+.sp 1
+Ron Newman, Massachusetts Institute of Technology
+.sp 1
+Al Tabayoyon, Tektronix, Inc.
+.sp 1
+Glenn Widener, Tektronix, Inc.
+.sp 1
+Shigeru Yamada, Fujitsu OSSI
+.bp
+\&
+.ps 9
+.nr PS 9
+.sp 8
+.LP
+The X Window System is a trademark of The Open Group.
+.LP
+TekHVC is a trademark of Tektronix, Inc.
+.sp 2
+.LP
+Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996, 2002
+The Open Group
+.LP
+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:
+.LP
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+.LP
+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.
+.LP
+Except as contained in this notice, the name of The Open Group 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 Open Group.
+.sp 3
+.LP
+Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
+Digital Equipment Corporation
+.LP
+Portions Copyright \(co 1990, 1991 by
+Tektronix, Inc.
+.LP
+Permission to use, copy, modify and distribute this documentation for
+any purpose and without fee is hereby granted, provided that the above
+copyright notice appears in all copies and that both that copyright notice and
+this permission notice appear in all copies, and that the names of
+Digital and Tektronix not be used in in advertising or publicity
+pertaining to this documentation without specific, written prior permission.
+Digital and Tektronix makes no representations about the suitability
+of this documentation for any purpose.
+It is provided ``as is'' without express or implied warranty.
+.ps 11
+.nr PS 11
+.bp
diff --git a/specs/libX11/credits.t b/specs/libX11/credits.t
new file mode 100644
index 00000000..5d9909d7
--- /dev/null
+++ b/specs/libX11/credits.t
@@ -0,0 +1,216 @@
+.EH ''''
+.OH ''''
+.EF ''''
+.OF ''''
+.XS ii
+Table of Contents
+.XE
+.XS iii
+Acknowledgments
+.XE
+\&
+.sp 1
+.ce 3
+\s+1\fBAcknowledgments\fP\s-1
+.sp 2
+.na
+.LP
+The design and implementation of the first 10 versions of X
+were primarily the work of three individuals: Robert Scheifler of the
+MIT Laboratory for Computer Science and Jim Gettys of Digital
+Equipment Corporation and Ron Newman of MIT, both at MIT
+Project Athena. 
+X version 11, however, is the result of the efforts of 
+dozens of individuals at almost as many locations and organizations.
+At the risk of offending some of the players by exclusion, 
+we would like to acknowledge some of the people who deserve special credit 
+and recognition for their work on Xlib.
+Our apologies to anyone inadvertently overlooked.
+.SH
+Release 1
+.LP
+Our thanks does to Ron Newman (MIT Project Athena),
+who contributed substantially to the
+design and implementation of the Version 11 Xlib interface.
+.LP
+Our thanks also goes to Ralph Swick (Project Athena and Digital) who kept 
+it all together for us during the early releases.
+He handled literally thousands of requests from people everywhere
+and saved the sanity of at least one of us.
+His calm good cheer was a foundation on which we could build.
+.LP
+Our thanks also goes to Todd Brunhoff (Tektronix) who was ``loaned'' 
+to Project Athena at exactly the right moment to provide very capable 
+and much-needed assistance during the alpha and beta releases.
+He was responsible for the successful integration of sources
+from multiple sites;
+we would not have had a release without him.
+.LP
+Our thanks also goes to Al Mento and Al Wojtas of Digital's ULTRIX 
+Documentation Group.
+With good humor and cheer,
+they took a rough draft and made it an infinitely better and more useful 
+document.
+The work they have done will help many everywhere.
+We also would like to thank Hal Murray (Digital SRC) and
+Peter George (Digital VMS) who contributed much
+by proofreading the early drafts of this document.
+.LP
+Our thanks also goes to Jeff Dike (Digital UEG), Tom Benson, 
+Jackie Granfield, and Vince Orgovan (Digital VMS) who helped with the 
+library utilities implementation;
+to Hania Gajewska (Digital UEG-WSL) who,
+along with Ellis Cohen (CMU and Siemens),
+was instrumental in the semantic design of the window manager properties;
+and to Dave Rosenthal (Sun Microsystems) who also contributed to the protocol 
+and provided the sample generic color frame buffer device-dependent code.
+.LP
+The alpha and beta test participants deserve special recognition and thanks
+as well.
+It is significant
+that the bug reports (and many fixes) during alpha and beta test came almost
+exclusively from just a few of the alpha testers, mostly hardware vendors
+working on product implementations of X.  
+The continued public
+contribution of vendors and universities is certainly to the benefit 
+of the entire X community.
+.LP
+Our special thanks must go to Sam Fuller, Vice-President of Corporate
+Research at Digital, who has remained committed to the widest public 
+availability of X and who made it possible to greatly supplement MIT's
+resources with the Digital staff in order to make version 11 a reality.
+Many of the people mentioned here are part of the Western
+Software Laboratory (Digital UEG-WSL) of the ULTRIX Engineering group
+and work for Smokey Wallace, who has been vital to the project's success. 
+Others not mentioned here worked on the toolkit and are acknowledged 
+in the X Toolkit documentation.
+.LP
+Of course, 
+we must particularly thank Paul Asente, formerly of Stanford University
+and now of Digital UEG-WSL, who wrote W, the predecessor to X,
+and Brian Reid, formerly of Stanford University and now of Digital WRL,
+who had much to do with W's design.
+.LP
+Finally, our thanks goes to MIT,  Digital Equipment Corporation,
+and IBM for providing the environment where it could happen.
+.SH
+Release 4
+.LP
+Our thanks go to Jim Fulton (MIT X Consortium) for designing and
+specifying the new Xlib functions for Inter-Client Communication
+Conventions (ICCCM) support.
+.LP
+We also thank Al Mento of Digital for his continued effort in
+maintaining this document and Jim Fulton and Donna Converse (MIT X Consortium)
+for their much-appreciated efforts in reviewing the changes.
+.SH
+Release 5
+.LP
+The principal authors of the Input Method facilities are
+Vania Joloboff (Open Software Foundation) and Bill McMahon (Hewlett-Packard).
+The principal author of the rest of the internationalization facilities
+is Glenn Widener (Tektronix).  Our thanks to them for keeping their
+sense of humor through a long and sometimes difficult design process.
+Although the words and much of the design are due to them, many others
+have contributed substantially to the design and implementation.
+Tom McFarland (HP) and Frank Rojas (IBM) deserve particular recognition
+for their contributions.   Other contributors were:
+Tim Anderson (Motorola), Alka Badshah (OSF), Gabe Beged-Dov (HP),
+Chih-Chung Ko (III), Vera Cheng (III), Michael Collins (Digital),
+Walt Daniels (IBM), Noritoshi Demizu (OMRON), Keisuke Fukui (Fujitsu),
+Hitoshoi Fukumoto (Nihon Sun), Tim Greenwood (Digital), John Harvey (IBM),
+Hideki Hiura (Sun), Fred Horman (AT&T), Norikazu Kaiya (Fujitsu),
+Yuji Kamata (IBM),
+Yutaka Kataoka (Waseda University), Ranee Khubchandani (Sun), Akira Kon (NEC),
+Hiroshi Kuribayashi (OMRON), Teruhiko Kurosaka (Sun), Seiji Kuwari (OMRON),
+Sandra Martin (OSF), Narita Masahiko (Fujitsu), Masato Morisaki (NTT),
+Nelson Ng (Sun),
+Takashi Nishimura (NTT America), Makato Nishino (IBM),
+Akira Ohsone (Nihon Sun), Chris Peterson (MIT), Sam Shteingart (AT&T),
+Manish Sheth (AT&T), Muneiyoshi Suzuki (NTT), Cori Mehring (Digital),
+Shoji Sugiyama (IBM), and Eiji Tosa (IBM).
+.LP
+We are deeply indebted to Tatsuya Kato (NTT),
+Hiroshi Kuribayashi (OMRON), Seiji Kuwari (OMRON), Muneiyoshi Suzuki (NTT),
+and Li Yuhong (OMRON) for producing one of the first complete
+sample implementation of the internationalization facilities, and 
+Hiromu Inukai (Nihon Sun), Takashi Fujiwara (Fujitsu), Hideki Hiura (Sun), 
+Yasuhiro Kawai (Oki Technosystems Laboratory), Kazunori Nishihara (Fuji Xerox),
+Masaki Takeuchi (Sony), Katsuhisa Yano (Toshiba),
+Makoto Wakamatsu (Sony Corporation) for producing the another complete
+sample implementation of the internationalization facilities.
+.LP
+The principal authors (design and implementation) of the Xcms color
+management facilities are Al Tabayoyon (Tektronix)
+and Chuck Adams (Tektronix).  
+Joann Taylor (Tektronix), Bob Toole (Tektronix),
+and Keith Packard (MIT X Consortium) also
+contributed significantly to the design.  Others who contributed are:
+Harold Boll (Kodak), Ken Bronstein (HP), Nancy Cam (SGI),
+Donna Converse (MIT X Consortium), Elias Israel (ISC), Deron Johnson (Sun),
+Jim King (Adobe), Ricardo Motta (HP), Chuck Peek (IBM),
+Wil Plouffe (IBM), Dave Sternlicht (MIT X Consortium), Kumar Talluri (AT&T),
+and Richard Verberg (IBM).
+.LP
+We also once again thank Al Mento of Digital for his work in formatting
+and reformatting text for this manual, and for producing man pages.
+Thanks also to Clive Feather (IXI) for proof-reading and finding a
+number of small errors.
+.SH
+Release 6
+.LP
+Stephen Gildea (X Consortium) authored the threads support.
+Ovais Ashraf (Sun) and Greg Olsen (Sun) contributed substantially
+by testing the facilities and reporting bugs in a timely fashion.
+.LP
+The principal authors of the internationalization facilities, including
+Input and Output Methods, are Hideki Hiura (SunSoft) and
+Shigeru Yamada (Fujitsu OSSI).
+Although the words and much of the design are due to them, many others
+have contributed substantially to the design and implementation.
+They are: Takashi Fujiwara (Fujitsu), Yoshio Horiuchi (IBM),
+Makoto Inada (Digital), Hiromu Inukai (Nihon SunSoft),
+Song JaeKyung (KAIST), Franky Ling (Digital), Tom McFarland (HP),
+Hiroyuki Miyamoto (Digital), Masahiko Narita (Fujitsu),
+Frank Rojas (IBM), Hidetoshi Tajima (HP), Masaki Takeuchi (Sony),
+Makoto Wakamatsu (Sony), Masaki Wakao (IBM), Katsuhisa Yano(Toshiba) and
+Jinsoo Yoon (KAIST).
+.LP
+The principal producers of the sample implementation of the 
+internationalization facilities are: 
+Jeffrey Bloomfield (Fujitsu OSSI), Takashi Fujiwara (Fujitsu),
+Hideki Hiura (SunSoft), Yoshio Horiuchi (IBM), 
+Makoto Inada (Digital), Hiromu Inukai (Nihon SunSoft), 
+Song JaeKyung (KAIST), Riki Kawaguchi (Fujitsu), 
+Franky Ling (Digital), Hiroyuki Miyamoto (Digital), 
+Hidetoshi Tajima (HP), Toshimitsu Terazono (Fujitsu), 
+Makoto Wakamatsu (Sony), Masaki Wakao (IBM), 
+Shigeru Yamada (Fujitsu OSSI) and Katsuhisa Yano (Toshiba).
+.LP
+The coordinators of the integration, testing, and release of this 
+implementation of the internationalization facilities are
+Nobuyuki Tanaka (Sony) and Makoto Wakamatsu (Sony).
+.LP
+Others who have contributed to the architectural design or
+testing of the sample implementation of the
+internationalization facilities are:
+Hector Chan (Digital), Michael Kung (IBM), Joseph Kwok (Digital),
+Hiroyuki Machida (Sony), Nelson Ng (SunSoft), Frank Rojas (IBM), 
+Yoshiyuki Segawa (Fujitsu OSSI), Makiko Shimamura (Fujitsu), 
+Shoji Sugiyama (IBM), Lining Sun (SGI), Masaki Takeuchi (Sony),
+Jinsoo Yoon (KAIST) and Akiyasu Zen (HP).
+.sp 2
+.LP
+.Ds 0
+.TA 1.5i 3i
+.ta 1.5i 3i
+.R
+Jim Gettys
+Cambridge Research Laboratory
+Digital Equipment Corporation
+
+Robert W. Scheifler
+Laboratory for Computer Science
+Massachusetts Institute of Technology
+.DE
+.bp 1
diff --git a/specs/libX11/glossary b/specs/libX11/glossary
new file mode 100644
index 00000000..a130928a
--- /dev/null
+++ b/specs/libX11/glossary
@@ -0,0 +1,1484 @@
+\&
+.sp 1
+.ce 1
+\s+1\fBGlossary\fP\s-1
+.sp 2
+.na
+.LP
+.XS
+Glossary
+.XE
+.KS
+\fBAccess control list\fP
+.IN "Access control list" "" "@DEF@"
+.IP
+X maintains a list of hosts from which client programs can be run.  
+By default, 
+only programs on the local host and hosts specified in an initial list read
+by the server can use the display.
+This access control list can be changed by clients on the local host.  
+Some server implementations can also implement other authorization mechanisms
+in addition to or in place of this mechanism.
+The action of this mechanism can be conditional based on the authorization 
+protocol name and data received by the server at connection setup. 
+.KE
+.LP
+.KS
+\fBActive grab\fP
+.IN "Active grab" "" "@DEF@"
+.IP
+A grab is active when the pointer or keyboard is actually owned by the 
+single grabbing client.
+.KE
+.LP
+.KS
+\fBAncestors\fP
+.IN "Ancestors" "" "@DEF@"
+.IP
+If W is an inferior of A, then A is an ancestor of W.
+.KE
+.LP
+.KS
+\fBAtom\fP
+.IN "Atom" "" "@DEF@"
+.IP
+An atom is a unique ID corresponding to a string name.
+Atoms are used to identify properties, types, and selections.
+.KE
+.LP
+.KS
+\fBBackground\fP
+.IN "Background" "" "@DEF@"
+.IP
+An
+.PN InputOutput
+window can have a background, which is defined as a pixmap.
+When regions of the window have their contents lost 
+or invalidated,
+the server automatically tiles those regions with the background.
+.KE
+.LP
+.KS
+\fBBacking store\fP
+.IN "Backing store" "" "@DEF@"
+.IP
+When a server maintains the contents of a window, 
+the pixels saved off-screen are known as a backing store.
+.KE
+.LP
+.KS
+\fBBase font name\fP
+.IN "Base font name" "" "@DEF@"
+.IP
+A font name used to select a family of fonts whose members may be encoded 
+in various charsets.
+The
+.PN CharSetRegistry
+and 
+.PN CharSetEncoding
+fields of an XLFD name identify the charset of the font.
+A base font name may be a full XLFD name, with all fourteen '-' delimiters, 
+or an abbreviated XLFD name containing only the first 12 fields of an XLFD name,
+up to but not including 
+.PN CharSetRegistry ,
+with or without the thirteenth '-', or a non-XLFD name.
+Any XLFD fields may contain wild cards.
+.IP
+When creating an 
+.PN XFontSet ,
+Xlib accepts from the client a list of one or more base font names 
+which select one or more font families.
+They are combined with charset names obtained from the encoding of the locale
+to load the fonts required to render text.
+.KE
+.LP
+.KS
+\fBBit gravity\fP
+.IN "Bit" "gravity" "@DEF@"
+.IP
+When a window is resized, 
+the contents of the window are not necessarily discarded.  
+It is possible to request that the server relocate the previous contents 
+to some region of the window (though no guarantees are made).
+This attraction of window contents for some location of
+a window is known as bit gravity.
+.KE
+.LP
+.KS
+\fBBit plane\fP
+.IN "Bit" "plane" "@DEF@"
+.IP
+When a pixmap or window is thought of as a stack of bitmaps,
+each bitmap is called a bit plane or plane.
+.KE
+.LP
+.KS
+\fBBitmap\fP
+.IN "Bitmap" "" "@DEF@"
+.IP
+A bitmap is a pixmap of depth one.
+.KE
+.LP
+.KS
+\fBBorder\fP
+.IN "Border" "" "@DEF@"
+.IP
+An
+.PN InputOutput
+window can have a border of equal thickness on all four sides of the window.
+The contents of the border are defined by a pixmap,
+and the server automatically maintains the contents of the border.
+Exposure events are never generated for border regions.
+.KE
+.LP
+.KS
+\fBButton grabbing\fP
+.IN "Button" "grabbing" "@DEF@"
+.IP
+Buttons on the pointer can be passively grabbed by a client.
+When the button is pressed, 
+the pointer is then actively grabbed by the client.
+.KE
+.LP
+.KS
+\fBByte order\fP
+.IN "Byte" "order" "@DEF@"
+.IP
+For image (pixmap/bitmap) data, 
+the server defines the byte order,
+and clients with different native byte ordering must swap bytes as
+necessary.  
+For all other parts of the protocol, 
+the client defines the byte order,
+and the server swaps bytes as necessary.
+.KE
+.LP
+.KS
+\fBCharacter\fP
+.IN "Character" "" "@DEF@"
+.IP
+A member of a set of elements used for the organization,
+control, or representation of text (ISO2022, as adapted by XPG3).
+Note that in ISO2022 terms, a character is not bound to a coded value 
+until it is identified as part of a coded character set.
+.KE
+.LP
+.KS
+\fBCharacter glyph\fP
+.IN "Character glyph" "" "@DEF@"
+.IP
+The abstract graphical symbol for a character.
+Character glyphs may or may not map one-to-one to font glyphs,
+and may be context-dependent, varying with the adjacent characters.
+Multiple characters may map to a single character glyph.
+.KE
+.LP
+.KS
+\fBCharacter set\fP
+.IN "Character set" "" "@DEF@"
+.IP
+A collection of characters.
+.KE
+.LP
+.KS
+\fBCharset\fP
+.IN "Charset" "" "@DEF@"
+.IP
+An encoding with a uniform, state-independent mapping from characters 
+to codepoints.
+A coded character set.
+.IP
+For display in X,
+there can be a direct mapping from a charset to one font,
+if the width of all characters in the charset is either one or two bytes.
+A text string encoded in an encoding such as Shift-JIS cannot be passed
+directly to the X server, because the text imaging requests accept only
+single-width charsets (either 8 or 16 bits).
+Charsets which meet these restrictions can serve as ``font charsets''.
+Font charsets strictly speaking map font indices to font glyphs,
+not characters to character glyphs.
+.IP
+Note that a single font charset is sometimes used as the encoding of a locale,
+for example, ISO8859-1.
+.KE
+.LP
+.KS
+\fBChildren\fP
+.IN "Children" "" "@DEF@"
+.IP
+The children of a window are its first-level subwindows.
+.KE
+.LP
+.KS
+\fBClass\fP
+.IN "Class" "" "@DEF@"
+.IP
+Windows can be of different classes or types.
+See the entries for
+.PN InputOnly
+and
+.PN InputOutput
+windows for further information about valid window types.
+.KE
+.LP
+.KS
+\fBClient\fP
+.IN "Client" "" "@DEF@"
+.IP
+An application program connects to the window system server by some
+interprocess communication (IPC) path, such as a TCP connection or a
+shared memory buffer.  
+This program is referred to as a client of the window system server.  
+More precisely, 
+the client is the IPC path itself. 
+A program with multiple paths open to the server is viewed as
+multiple clients by the protocol.  
+Resource lifetimes are controlled by
+connection lifetimes, not by program lifetimes.
+.KE
+.LP
+.KS
+\fBClipping region\fP
+.IN "Clipping region" "" "@DEF@"
+.IP
+In a graphics context, 
+a bitmap or list of rectangles can be specified
+to restrict output to a particular region of the window.  
+The image defined by the bitmap or rectangles is called a clipping region.
+.KE
+.LP
+.KS
+\fBCoded character\fP
+.IN "Coded character" "" "@DEF@"
+.IP
+A character bound to a codepoint.
+.KE
+.LP
+.KS
+\fBCoded character set\fP
+.IN "Coded character set" "" "@DEF@"
+.IP
+A set of unambiguous rules that establishes a character set 
+and the one-to-one relationship between each character of the set 
+and its bit representation.
+(ISO2022, as adapted by XPG3)
+A definition of a one-to-one mapping of a set of characters to a set of
+codepoints.
+.KE
+.LP
+.KS
+\fBCodepoint\fP
+.IN "Codepoint" "" "@DEF@"
+.IP
+The coded representation of a single character in a coded character set.
+.KE
+.LP
+.KS
+\fBColormap\fP
+.IN "Colormap" "" "@DEF@"
+.IP
+A colormap consists of a set of entries defining color values.
+The colormap associated with a window is used to display the contents of
+the window; each pixel value indexes the colormap to produce an RGB value
+that drives the guns of a monitor.
+Depending on hardware limitations, 
+one or more colormaps can be installed at one time so
+that windows associated with those maps display with true colors.
+.KE
+.LP
+.KS
+\fBConnection\fP
+.IN "Connection" "" "@DEF@"
+.IP
+The IPC path between the server and client program is known as a connection.
+A client program typically (but not necessarily) has one
+connection to the server over which requests and events are sent.
+.KE
+.LP
+.KS
+\fBContainment\fP
+.IN "Containment" "" "@DEF@"
+.IP
+A window contains the pointer if the window is viewable and the
+hotspot of the cursor is within a visible region of the window or a
+visible region of one of its inferiors.  
+The border of the window is included as part of the window for containment.  
+The pointer is in a window if the window contains the pointer
+but no inferior contains the pointer.
+.KE
+.LP
+.KS
+\fBCoordinate system\fP
+.IN "Coordinate system" "" "@DEF@"
+.IP
+The coordinate system has X horizontal and Y vertical, 
+with the origin [0, 0] at the upper left.  
+Coordinates are integral and coincide with pixel centers.
+Each window and pixmap has its own coordinate system.  
+For a window, 
+the origin is inside the border at the inside upper-left corner.
+.KE
+.LP
+.KS
+\fBCursor\fP
+.IN "Cursor" "" "@DEF@"
+.IP
+A cursor is the visible shape of the pointer on a screen.  
+It consists of a hotspot, a source bitmap, a shape bitmap, 
+and a pair of colors.  
+The cursor defined for a window controls the visible
+appearance when the pointer is in that window.
+.KE
+.LP
+.KS
+\fBDepth\fP
+.IN "Depth" "" "@DEF@"
+.IP
+The depth of a window or pixmap is the number of bits per pixel it has.
+The depth of a graphics context is the depth of the drawables it can be
+used in conjunction with graphics output.
+.KE
+.LP
+.KS
+\fBDevice\fP
+.IN "Device" "" "@DEF@"
+.IP
+Keyboards, mice, tablets, track-balls, button boxes, and so on are all
+collectively known as input devices.
+Pointers can have one or more buttons 
+(the most common number is three).
+The core protocol only deals with two devices: the keyboard 
+and the pointer.
+.KE
+.LP
+.KS
+\fBDirectColor\fP
+.IN "DirectColor" "" "@DEF@"
+.IP
+.PN DirectColor
+is a class of colormap in which a pixel value is decomposed into three
+separate subfields for indexing.
+The first subfield indexes an array to produce red intensity values. 
+The second subfield indexes a second array to produce blue intensity values.
+The third subfield indexes a third array to produce green intensity values.
+The RGB (red, green, and blue) values in the colormap entry can be 
+changed dynamically.
+.KE
+.LP
+.KS
+\fBDisplay\fP
+.IN "Display" "" "@DEF@"
+.IP
+A server, together with its screens and input devices, is called a display.
+The Xlib
+.PN Display
+.IN "Display" "structure"
+structure contains all information about the particular display and its screens
+as well as the state that Xlib needs to communicate with the display over a
+particular connection.
+.KE
+.LP
+.KS
+\fBDrawable\fP
+.IN "Drawable" "" "@DEF@"
+.IP
+Both windows and pixmaps can be used as sources and destinations 
+in graphics operations.  
+These windows and pixmaps are collectively known as drawables.
+However, an 
+.PN InputOnly 
+window cannot be used as a source or destination in a
+graphics operation.
+.KE
+.LP
+.KS
+\fBEncoding\fP
+.IN "Encoding" "" "@DEF@"
+.IP
+A set of unambiguous rules that establishes a character set 
+and a relationship between the characters and their representations.
+The character set does not have to be fixed to a finite pre-defined set of
+characters.
+The representations do not have to be of uniform length.
+Examples are an ISO2022 graphic set, a state-independent 
+or state-dependent combination of graphic sets, possibly including control
+sets, and the X Compound Text encoding.
+.IP
+In X, encodings are identified by a string
+which appears as: the
+.PN CharSetRegistry
+and
+.PN CharSetEncoding
+components of an XLFD
+name; the name of a charset of the locale for which a font could not be
+found; or an atom which identifies the encoding of a text property or
+which names an encoding for a text selection target type.
+Encoding names should be composed of characters from the X Portable 
+Character Set.
+.KE
+.LP
+.KS
+\fBEscapement\fP
+.IN "Escapement" "" "@DEF@"
+.IP
+The escapement of a string is the distance in pixels in the
+primary draw direction from the drawing origin to the origin of the next
+character (that is, the one following the given string) to be drawn.
+.KE
+.LP
+.KS
+\fBEvent\fP
+.IN "Event" "" "@DEF@"
+.IP
+Clients are informed of information asynchronously by means of events.
+These events can be either asynchronously generated from devices or
+generated as side effects of client requests.  
+Events are grouped into types. 
+The server never sends an event to a client unless the
+client has specifically asked to be informed of that type of event.
+However, clients can force events to be sent to other clients.  
+Events are typically reported relative to a window.
+.KE
+.LP
+.KS
+\fBEvent mask\fP
+.IN "Event" "mask" "@DEF@"
+.IP
+Events are requested relative to a window.  
+The set of event types a client requests relative to a window is described 
+by using an event mask.
+.KE
+.LP
+.KS
+\fBEvent propagation\fP
+.IN "Event" "propagation" "@DEF@"
+.IP
+Device-related events propagate from the source window to ancestor
+windows until some client has expressed interest in handling that type
+of event or until the event is discarded explicitly.
+.KE
+.LP
+.KS
+\fBEvent source\fP
+.IN "Event" "source" "@DEF@"
+.IP
+The deepest viewable window that the pointer is in is called
+the source of a device-related event.
+.KE
+.LP
+.KS
+\fBEvent synchronization\fP
+.IN "Event" "synchronization" "@DEF@"
+.IP
+There are certain race conditions possible when demultiplexing device
+events to clients (in particular, deciding where pointer and keyboard
+events should be sent when in the middle of window management
+operations).  
+The event synchronization mechanism allows synchronous processing of 
+device events.
+.KE
+.LP
+.KS
+\fBExposure event\fP
+.IN "Event" "Exposure" "@DEF@"
+.IP
+Servers do not guarantee to preserve the contents of windows when
+windows are obscured or reconfigured.  
+Exposure events are sent to clients to inform them when contents of regions
+of windows have been lost.
+.KE
+.LP
+.KS
+\fBExtension\fP
+.IN "Extension" "" "@DEF@"
+.IP
+Named extensions to the core protocol can be defined to extend the system.  
+Extensions to output requests, resources, and event types are all possible
+and expected.
+.KE
+.LP
+.KS
+\fBFont\fP
+.IN "Font" "" "@DEF@"
+.IP
+A font is an array of glyphs (typically characters).  
+The protocol does no translation or interpretation of character sets.  
+The client simply indicates values used to index the glyph array.  
+A font contains additional metric information to determine interglyph 
+and interline spacing.
+.KE
+.LP
+.KS
+\fBFont glyph\fP
+.IN "Font glyph" "" "@DEF@"
+.IP
+The abstract graphical symbol for an index into a font.
+.KE
+.LP
+.KS
+\fBFrozen events\fP
+.IN "Frozen events" "" "@DEF@"
+.IP
+Clients can freeze event processing during keyboard and pointer grabs.
+.KE
+.LP
+.KS
+\fBGC\fP
+.IN "GC" "" "@DEF@"
+.IP
+GC is an abbreviation for graphics context.
+See \fBGraphics context\fP.
+.KE
+.LP
+.KS
+\fBGlyph\fP
+.IN "Glyph" "" "@DEF@"
+.IP
+An identified abstract graphical symbol independent of any actual image.
+(ISO/IEC/DIS 9541-1)
+An abstract visual representation of a graphic character,
+not bound to a codepoint.
+.KE
+.LP
+.KS
+\fBGlyph image\fP
+.IN "Glyph image" "" "@DEF@"
+.IP
+An image of a glyph, as obtained from a glyph representation displayed 
+on a presentation surface.
+(ISO/IEC/DIS 9541-1)
+.KE
+.LP
+.KS
+\fBGrab\fP
+.IN "Grab" "" "@DEF@"
+.IP
+Keyboard keys, the keyboard, pointer buttons, the pointer, 
+and the server can be grabbed for exclusive use by a client.  
+In general, 
+these facilities are not intended to be used by normal applications
+but are intended for various input and window managers to implement various
+styles of user interfaces.
+.KE
+.LP
+.KS
+\fBGraphics context\fP
+.IN "Graphics context" "" "@DEF@"
+.IP
+Various information for graphics output is stored in a graphics
+context (GC), such as foreground pixel, background
+pixel, line width, clipping region, and so on.
+A graphics context can only
+be used with drawables that have the same root and the same depth as
+the graphics context. 
+.KE
+.LP
+.KS
+\fBGravity\fP
+.IN "Gravity" "" "@DEF@"
+.IP
+The contents of windows and windows themselves have a gravity,
+which determines how the contents move when a window is resized.
+See \fBBit gravity\fP and \fBWindow gravity\fP.
+.KE
+.LP
+.KS
+\fBGrayScale\fP
+.IN "GrayScale" "" "@DEF@"
+.IP
+.PN GrayScale 
+can be viewed as a degenerate case of 
+.PN PseudoColor , 
+in which the red, green, and blue values in any given colormap entry 
+are equal and thus, produce shades of gray.
+The gray values can be changed dynamically.
+.KE
+.LP
+.KS
+\fBHost Portable Character Encoding\fP
+.IN "Host Portable Character Encoding" "" "@DEF@"
+.IP
+The encoding of the X Portable Character Set on the host.
+The encoding itself is not defined by this standard,
+but the encoding must be the same in all locales supported by Xlib on the host.
+If a string is said to be in the Host Portable Character Encoding,
+then it only contains characters from the X Portable Character Set,
+in the host encoding.
+.KE
+.LP
+.KS
+\fBHotspot\fP
+.IN "Hotspot" "" "@DEF@"
+.IP
+A cursor has an associated hotspot, which defines the point in the
+cursor corresponding to the coordinates reported for the pointer.
+.KE
+.LP
+.KS
+\fBIdentifier\fP
+.IN "Identifier" "" "@DEF@"
+.IP
+An identifier is a unique value associated with a resource
+that clients use to name that resource.  
+The identifier can be used over any connection to name the resource.
+.KE
+.LP
+.KS
+\fBInferiors\fP
+.IN "Inferiors" "" "@DEF@"
+.IP
+The inferiors of a window are all of the subwindows nested below it:
+the children, the children's children, and so on.
+.KE
+.LP
+.KS
+\fBInput focus\fP
+.IN "Input" "focus" "@DEF@"
+.IP
+The input focus is usually a window defining the scope for processing
+of keyboard input.
+If a generated keyboard event usually would be reported to this window 
+or one of its inferiors,
+the event is reported as usual.
+Otherwise, the event is reported with respect to the focus window.
+The input focus also can be set such that all keyboard events are discarded
+and such that the focus window is dynamically taken to be the root window
+of whatever screen the pointer is on at each keyboard event.
+.KE
+.LP
+.KS
+\fBInput manager\fP
+.IN "Input" "manager" "@DEF@"
+.IP
+Control over keyboard input is typically provided by an input manager 
+client, which usually is part of a window manager.
+.KE
+.LP
+.KS
+\fBInputOnly window\fP
+.IN "Window" "InputOnly" "@DEF@"
+.IP
+An
+.PN InputOnly
+window is a window that cannot be used for graphics requests.  
+.PN InputOnly 
+windows are invisible and are used to control such things as cursors,
+input event generation, and grabbing.
+.PN InputOnly 
+windows cannot have 
+.PN InputOutput 
+windows as inferiors.
+.KE
+.LP
+.KS
+\fBInputOutput window\fP
+.IN "Window" "InputOutput" "@DEF@"
+.IP
+An
+.PN InputOutput
+window is the normal kind of window that is used for both input and output.
+.PN InputOutput 
+windows can have both 
+.PN InputOutput 
+and 
+.PN InputOnly 
+windows as inferiors.
+.KE
+.LP
+.KS
+\fBInternationalization\fP
+.IN "Internationalization" "" "@DEF@"
+.IP
+The process of making software adaptable to the requirements
+of different native languages, local customs, and character string encodings.
+Making a computer program adaptable to different locales 
+without program source modifications or recompilation.
+.KE
+.LP
+.KS
+\fBISO2022\fP
+.IN "ISO2022" "" "@DEF@"
+.IP
+ISO standard for code extension techniques for 7-bit and 8-bit coded 
+character sets.
+.KE
+.LP
+.KS
+\fBKey grabbing\fP
+.IN "Key" "grabbing" "@DEF@"
+.IP
+Keys on the keyboard can be passively grabbed by a client.  
+When the key is pressed, 
+the keyboard is then actively grabbed by the client.
+.KE
+.LP
+.KS
+\fBKeyboard grabbing\fP
+.IN "Keyboard" "grabbing" "@DEF@"
+.IP
+A client can actively grab control of the keyboard, and key events
+will be sent to that client rather than the client the events would
+normally have been sent to.
+.KE
+.LP
+.KS
+\fBKeysym\fP
+.IN "Keysym" "" "@DEF@"
+.IP
+An encoding of a symbol on a keycap on a keyboard.
+.KE
+.LP
+.KS
+\fBLatin-1\fP
+.IN "Latin-1" "" "@DEF@"
+.IP
+The coded character set defined by the ISO8859-1 standard.
+.KE
+.LP
+.KS
+\fBLatin Portable Character Encoding\fP
+.IN "Latin Portable Character Encoding" "" "@DEF@"
+.IP
+The encoding of the X Portable Character Set using the Latin-1 codepoints
+plus ASCII control characters.
+If a string is said to be in the Latin Portable Character Encoding,
+then it only contains characters from the X Portable Character Set,
+not all of Latin-1.
+.KE
+.LP
+.KS
+\fBLocale\fP
+.IN "Locale" "" "@DEF@"
+.IP
+The international environment of a computer program defining the ``localized''
+behavior of that program at run-time.
+This information can be established from one or more sets of localization data.
+ANSI C defines locale-specific processing by C system library calls.
+See ANSI C and the X/Open Portability Guide specifications for more details.
+In this specification, on implementations that conform to the ANSI C library,
+the ``current locale'' is the current setting of the LC_CTYPE
+.PN setlocale
+category.
+Associated with each locale is a text encoding.  When text is processed
+in the context of a locale, the text must be in the encoding of the locale.
+The current locale affects Xlib in its:
+.RS
+.IP \(bu 5
+Encoding and processing of input method text
+.IP \(bu 5
+Encoding of resource files and values
+.IP \(bu 5
+Encoding and imaging of text strings
+.IP \(bu 5
+Encoding and decoding for inter-client text communication
+.RE
+.KE
+.LP
+.KS
+\fBLocale name\fP
+.IN "Locale name" "" "@DEF@"
+.IP
+The identifier used to select the desired locale for the host C library 
+and X library functions.
+On ANSI C library compliant systems,
+the locale argument to the
+.PN setlocale
+function.
+.KE
+.LP
+.KS
+\fBLocalization\fP
+.IN "Localization" "" "@DEF@"
+.IP
+The process of establishing information within a computer system specific 
+to the operation of particular native languages, local customs 
+and coded character sets.
+(XPG3)
+.KE
+.LP
+.KS
+\fBMapped\fP
+.IN "Mapped window" "" "@DEF@"
+.IP
+A window is said to be mapped if a map call has been performed on it.
+Unmapped windows and their inferiors are never viewable or visible.
+.KE
+.LP
+.KS
+\fBModifier keys\fP
+.IN "Modifier keys" "" "@DEF@"
+.IP
+Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple, CapsLock,
+ShiftLock, and similar keys are called modifier keys.
+.KE
+.LP
+.KS
+\fBMonochrome\fP
+.IN "Monochrome" "" "@DEF@"
+.IP
+Monochrome is a special case of 
+.PN StaticGray
+in which there are only two colormap entries.
+.KE
+.LP
+.KS
+\fBMultibyte\fP
+.IN "Multibyte" "" "@DEF@"
+.IP
+A character whose codepoint is stored in more than one byte;
+any encoding which can contain multibyte characters;
+text in a multibyte encoding.
+The ``char *'' null-terminated string datatype in ANSI C.
+Note that references in this document to multibyte strings
+imply only that the strings \fImay\fP contain multibyte characters.
+.KE
+.LP
+.KS
+\fBObscure\fP
+.IN "Obscure" "" "@DEF@"
+.IP
+A window is obscured if some other window obscures it.
+A window can be partially obscured and so still have visible regions.
+Window A obscures window B if both are viewable 
+.PN InputOutput 
+windows, if A is higher in the global stacking order, 
+and if the rectangle defined by the outside
+edges of A intersects the rectangle defined by the outside edges of B.
+Note the distinction between obscures and occludes.
+Also note that window borders are included in the calculation.
+.KE
+.LP
+.KS
+\fBOcclude\fP
+.IN "Occlude" "" "@DEF@"
+.IP
+A window is occluded if some other window occludes it.
+Window A occludes window B if both are mapped, 
+if A is higher in the global stacking order, 
+and if the rectangle defined by the outside edges of A intersects the rectangle defined 
+by the outside edges of B.  
+Note the distinction between occludes and obscures.
+Also note that window borders are included in the calculation
+and that
+.PN InputOnly
+windows never obscure other windows but can occlude other windows.
+.KE
+.LP
+.KS
+\fBPadding\fP
+.IN "Padding" "" "@DEF@"
+.IP
+Some padding bytes are inserted in the data stream to maintain
+alignment of the protocol requests on natural boundaries.  
+This increases ease of portability to some machine architectures.
+.KE
+.LP
+.KS
+\fBParent window\fP
+.IN "Window" "parent" "@DEF@"
+.IP
+If C is a child of P, then P is the parent of C.
+.KE
+.LP
+.KS
+\fBPassive grab\fP
+.IN "Passive grab" "" "@DEF@"
+.IP
+Grabbing a key or button is a passive grab.  
+The grab activates when the key or button is actually pressed.
+.KE
+.LP
+.KS
+\fBPixel value\fP
+.IN "Pixel value" "" "@DEF@"
+.IP
+A pixel is an N-bit value,
+where N is the number of bit planes used in a particular window or pixmap
+(that is, is the depth of the window or pixmap).  
+A pixel in a window indexes a colormap to derive an actual color to be 
+displayed.
+.KE
+.LP
+.KS
+\fBPixmap\fP
+.IN "Pixmap" "" "@DEF@"
+.EQ
+delim %%
+.EN
+.IP
+A pixmap is a three-dimensional array of bits.  
+A pixmap is normally thought of as a two-dimensional array of pixels, 
+where each pixel can be a value from 0 to %2 sup N %\-1, 
+and where N is the depth (z axis) of the pixmap.  
+A pixmap can also be thought of as a stack of N bitmaps.
+A pixmap can only be used on the screen that it was created in.
+.KE
+.LP
+.KS
+\fBPlane\fP
+.IN "Plane" "" "@DEF@"
+.IP
+When a pixmap or window is thought of as a stack of bitmaps, each
+bitmap is called a plane or bit plane.
+.KE
+.LP
+.KS
+\fBPlane mask\fP
+.IN "Plane" "mask" "@DEF@"
+.IP
+Graphics operations can be restricted to only affect a subset of bit
+planes of a destination.  
+A plane mask is a bit mask describing which planes are to be modified.
+The plane mask is stored in a graphics context.
+.KE
+.LP
+.KS
+\fBPointer\fP
+.IN "Pointer" "" "@DEF@"
+.IP
+The pointer is the pointing device currently attached to the cursor
+and tracked on the screens.
+.KE
+.LP
+.KS
+\fBPointer grabbing\fP
+.IN "Pointer" "grabbing" "@DEF@"
+.IP
+A client can actively grab control of the pointer. 
+Then button and motion events will be sent to that client 
+rather than the client the events would normally have been sent to.
+.KE
+.LP
+.KS
+\fBPointing device\fP
+.IN "Pointing device"  "" "@DEF@"
+.IP
+A pointing device is typically a mouse, tablet, or some other
+device with effective dimensional motion.  
+The core protocol defines only one visible cursor,
+which tracks whatever pointing device is attached as the pointer.
+.KE
+.LP
+.KS
+\fBPOSIX\fP
+.IN "POSIX" "" "@DEF@"
+.IP
+Portable Operating System Interface, ISO/IEC 9945-1 (IEEE Std 1003.1).
+.KE
+.LP
+.KS
+\fBPOSIX Portable Filename Character Set\fP
+.IN "POSIX Portable Filename Character Set" "" "@DEF@"
+.IP
+The set of 65 characters which can be used in naming files on a POSIX-compliant
+host that are correctly processed in all locales.
+The set is:
+.IP
+.Ds 0
+a..z A..Z 0..9 ._-
+.De
+.KE
+.LP
+.KS
+\fBProperty\fP
+.IN "Property" "" "@DEF@"
+.IP
+Windows can have associated properties that consist of a name, a type,
+a data format, and some data. 
+The protocol places no interpretation on properties. 
+They are intended as a general-purpose naming mechanism for clients.  
+For example, clients might use properties to share information such as resize
+hints, program names, and icon formats with a window manager.
+.KE
+.LP
+.KS
+\fBProperty list\fP
+.IN "Property list" "" "@DEF@"
+.IP
+The property list of a window is the list of properties that have
+been defined for the window.
+.KE
+.LP
+.KS
+\fBPseudoColor\fP
+.IN "PseudoColor" "" "@DEF@"
+.IP
+.PN PseudoColor
+is a class of colormap in which a pixel value indexes the colormap entry to
+produce an independent RGB value;
+that is, the colormap is viewed as an array of triples (RGB values).
+The RGB values can be changed dynamically.
+.KE
+.LP
+.KS
+\fBRectangle\fP
+.IN "Rectangle" "" "@DEF@"
+.IP
+A rectangle specified by [x,y,w,h] has an infinitely thin
+outline path with corners at [x,y], [x+w,y], [x+w,y+h], and [x, y+h].
+When a rectangle is filled,
+the lower-right edges are not drawn.
+For example,
+if w=h=0,
+nothing would be drawn.
+For w=h=1,
+a single pixel would be drawn.
+.KE
+.LP
+.KS
+\fBRedirecting control\fP
+.IN "Redirecting control" "" "@DEF@"
+.IP
+Window managers (or client programs) may enforce window layout
+policy in various ways.  
+When a client attempts to change the size or position of a window, 
+the operation may be redirected to a specified client
+rather than the operation actually being performed.
+.KE
+.LP
+.KS
+\fBReply\fP
+.IN "Reply" "" "@DEF@"
+.IP
+Information requested by a client program using the X protocol 
+is sent back to the client with a reply.
+Both events and replies are multiplexed on the same connection.  
+Most requests do not generate replies,
+but some requests generate multiple replies.
+.KE
+.LP
+.KS
+\fBRequest\fP
+.IN "Request" "" "@DEF@"
+.IP
+A command to the server is called a request.
+It is a single block of data sent over a connection.
+.KE
+.LP
+.KS
+\fBResource\fP
+.IN "Resource" "" "@DEF@"
+.IP
+Windows, pixmaps, cursors, fonts, graphics contexts, and colormaps are
+known as resources.  
+They all have unique identifiers associated with them for naming purposes.  
+The lifetime of a resource usually is bounded by the lifetime of the 
+connection over which the resource was created.
+.KE
+.LP
+.KS
+\fBRGB values\fP
+.IN "RGB values" "" "@DEF@"
+.IP
+RGB values are the red, green, and blue intensity values that are used
+to define a color.
+These values are always represented as 16-bit, unsigned numbers, with 0
+the minimum intensity and 65535 the maximum intensity.
+The X server scales these values to match the display hardware.
+.KE
+.LP
+.KS
+\fBRoot\fP
+.IN "Root" "" "@DEF@"
+.IP
+The root of a pixmap or graphics context is the same as the root 
+of whatever drawable was used when the pixmap or GC was created.  
+The root of a window is the root window under which the window was created.
+.KE
+.LP
+.KS
+\fBRoot window\fP
+.IN "Window" "root" "@DEF@"
+.IP
+Each screen has a root window covering it.
+The root window cannot be reconfigured or unmapped, 
+but otherwise it acts as a full-fledged window.
+A root window has no parent.
+.KE
+.LP
+.KS
+\fBSave set\fP
+.IN "Save set" "" "@DEF@"
+.IP
+The save set of a client is a list of other clients' windows that,
+if they are inferiors of one of the client's windows at connection
+close, should not be destroyed and that should be remapped 
+if currently unmapped.
+Save sets are typically used by window managers to avoid
+lost windows if the manager should terminate abnormally.
+.KE
+.LP
+.KS
+\fBScanline\fP
+.IN "Scanline" "" "@DEF@"
+.IP
+A scanline is a list of pixel or bit values viewed as a horizontal
+row (all values having the same y coordinate) of an image, with the
+values ordered by increasing the x coordinate.
+.KE
+.LP
+.KS
+\fBScanline order\fP
+.IN "Scanline" "order" "@DEF@"
+.IP
+An image represented in scanline order contains scanlines ordered by
+increasing the y coordinate.
+.KE
+.LP
+.KS
+\fBScreen\fP
+.IN "Screen" "" "@DEF@"
+.IP
+A server can provide several independent screens, 
+which typically have physically independent monitors.  
+This would be the expected configuration when there is only a single keyboard 
+and pointer shared among the screens.
+A 
+.PN Screen 
+.IN "Screen" "structure"
+structure contains the information about that screen
+and is linked to the 
+.PN Display
+.IN "Display" "structure"
+structure.
+.KE
+.LP
+.KS
+\fBSelection\fP
+.IN "Selection" "" "@DEF@"
+.IP
+A selection can be thought of as an indirect property with dynamic
+type.
+That is, rather than having the property stored in the X server,
+it is maintained by some client (the owner).
+A selection is global and is thought of as belonging to the user 
+and being maintained by clients, 
+rather than being private to a particular window subhierarchy
+or a particular set of clients.
+When a client asks for the contents of
+a selection, it specifies a selection target type,
+which can be used to control the transmitted representation of the contents.
+For example, if the selection is ``the last thing the user clicked on,''
+and that is currently an image, then the target type might specify
+whether the contents of the image should be sent in XY format or
+Z format.
+.IP
+The target type can also be used to control the class of
+contents transmitted; for example, 
+asking for the ``looks'' (fonts, line
+spacing, indentation, and so forth) of a paragraph selection, rather than the
+text of the paragraph.
+The target type can also be used for other
+purposes.
+The protocol does not constrain the semantics.
+.KE
+.LP
+.KS
+\fBServer\fP
+.IN "Server" "" "@DEF@"
+.IP
+The server, which is also referred to as the X server, 
+provides the basic windowing mechanism.  
+It handles IPC connections from clients, 
+multiplexes graphics requests onto the screens, 
+and demultiplexes input back to the appropriate clients.
+.KE
+.LP
+.KS
+\fBServer grabbing\fP
+.IN "Server" "grabbing" "@DEF@"
+.IP
+The server can be grabbed by a single client for exclusive use.  
+This prevents processing of any requests from other client connections until
+the grab is completed.
+This is typically only a transient state for such things as rubber-banding,
+pop-up menus, or executing requests indivisibly.
+.KE
+.LP
+.KS
+\fBShift sequence\fP
+.IN "Shift sequence" "" "@DEF@"
+.IP
+ISO2022 defines control characters and escape sequences 
+which temporarily (single shift) or permanently (locking shift) cause a
+different character set to be in effect (``invoking'' a character set).
+.KE
+.LP
+.KS
+\fBSibling\fP
+.IN "Sibling" "" "@DEF@"
+.IP
+Children of the same parent window are known as sibling windows.
+.KE
+.LP
+.KS
+\fBStacking order\fP
+.IN "Stacking order" "" "@DEF@"
+.IP
+Sibling windows, similar to sheets of paper on a desk,
+can stack on top of each other.  
+Windows above both obscure and occlude lower windows.  
+The relationship between sibling windows is known as the stacking order.
+.KE
+.LP
+.KS
+\fBState-dependent encoding\fP
+.IN "State-dependent encoding" "" "@DEF@"
+.IP
+An encoding in which an invocation of a charset can apply to multiple
+characters in sequence.
+A state-dependent encoding begins in an ``initial state'' 
+and enters other ``shift states'' when specific ``shift sequences'' 
+are encountered in the byte sequence.
+In ISO2022 terms,
+this means use of locking shifts, not single shifts.
+.KE
+.LP
+.KS
+\fBState-independent encoding\fP
+.IN "State-independent encoding" "" "@DEF@"
+.IP
+Any encoding in which the invocations of the charsets are fixed,
+or span only a single character.
+In ISO2022 terms,
+this means use of at most single shifts, not locking shifts.
+.KE
+.LP
+.KS
+\fBStaticColor\fP
+.IN "StaticColor" "" "@DEF@"
+.IP
+.PN StaticColor 
+can be viewed as a degenerate case of 
+.PN PseudoColor
+in which the RGB values are predefined and read-only.
+.KE
+.LP
+.KS
+\fBStaticGray\fP
+.IN "StaticGray" "" "@DEF@"
+.IP
+.PN StaticGray 
+can be viewed as a degenerate case of 
+.PN GrayScale
+in which the gray values are predefined and read-only.
+The values are typically linear or near-linear increasing ramps.
+.KE
+.LP
+.KS
+\fBStatus\fP
+.IN "Status" "" "@DEF@"
+.IP
+Many Xlib functions return a success status.
+If the function does not succeed,
+however, its arguments are not disturbed.
+.KE
+.LP
+.KS
+\fBStipple\fP
+.IN "Stipple" "" "@DEF@"
+.IP
+A stipple pattern is a bitmap that is used to tile a region to serve
+as an additional clip mask for a fill operation with the foreground
+color.
+.KE
+.KS
+.LP
+.KS
+\fBSTRING encoding\fP
+.IN "STRING encoding" "" "@DEF@"
+.IP
+Latin-1, plus tab and newline.
+.KE
+.LP
+\fBString Equivalence\fP
+.IN "String Equivalence" "" "@DEF@"
+.IP
+Two ISO Latin-1 STRING8 values are considered equal if they are the same
+length and if corresponding bytes are either equal or are equivalent as
+follows:  decimal values 65 to 90 inclusive (characters ``A'' to ``Z'') are
+pairwise equivalent to decimal values 97 to 122 inclusive
+(characters ``a'' to ``z''), decimal values 192 to 214 inclusive
+(characters ``A grave'' to ``O diaeresis'') are pairwise equivalent to decimal
+values 224 to 246 inclusive (characters ``a grave'' to ``o diaeresis''),
+and decimal values 216 to 222 inclusive (characters ``O oblique'' to ``THORN'')
+are pairwise equivalent to decimal values 246 to 254 inclusive
+(characters ``o oblique'' to ``thorn'').
+.KE
+.LP
+.KS
+\fBTile\fP
+.IN "Tile" "" "@DEF@"
+.IP
+A pixmap can be replicated in two dimensions to tile a region.  
+The pixmap itself is also known as a tile.
+.KE
+.LP
+.KS
+\fBTimestamp\fP
+.IN "Timestamp" "" "@DEF@"
+.IP
+A timestamp is a time value expressed in milliseconds. 
+It is typically the time since the last server reset.
+Timestamp values wrap around (after about 49.7 days).
+The server, given its current time is represented by timestamp T, 
+always interprets timestamps from clients by treating half 
+of the timestamp space as being earlier in time than T 
+and half of the timestamp space as being later in time than T.
+One timestamp value, represented by the constant 
+.PN CurrentTime ,
+is never generated by the server. 
+This value is reserved for use in requests to represent the current server time.
+.KE
+.LP
+.KS
+\fBTrueColor\fP
+.IN "TrueColor" "" "@DEF@"
+.IP
+.PN TrueColor
+can be viewed as a degenerate case of 
+.PN DirectColor
+in which the subfields in the pixel value directly encode the corresponding RGB
+values.
+That is, the colormap has predefined read-only RGB values.
+The values are typically linear or near-linear increasing ramps.
+.KE
+.LP
+.KS
+\fBType\fP
+.IN "Type" "" "@DEF@"
+.IP
+A type is an arbitrary atom used to identify the interpretation of property 
+data.  
+Types are completely uninterpreted by the server. 
+They are solely for the benefit of clients.
+X predefines type atoms for many frequently used types,
+and clients also can define new types.
+.KE
+.LP
+.KS
+\fBViewable\fP
+.IN "Viewable" "" "@DEF@"
+.IP
+A window is viewable if it and all of its ancestors are mapped.  
+This does not imply that any portion of the window is actually visible.
+Graphics requests can be performed on a window when it is not
+viewable, but output will not be retained unless the server is maintaining
+backing store. 
+.KE
+.LP
+.KS
+\fBVisible\fP
+.IN "Visible" "" "@DEF@"
+.IP
+A region of a window is visible if someone looking at the screen can
+actually see it; that is, the window is viewable and the region is not occluded
+by any other window.
+.KE
+.LP
+.KS
+\fBWhitespace\fP
+.IN "Whitespace" "" "@DEF@"
+.IP
+Any spacing character.
+On implementations that conform to the ANSI C library,
+whitespace is any character for which
+.PN isspace
+returns true.
+.KE
+.LP
+.KS
+\fBWindow gravity\fP
+.IN "Window" "gravity" "@DEF@"
+.IP
+When windows are resized, 
+subwindows may be repositioned automatically relative to some position in the 
+window.
+This attraction of a subwindow to some part of its parent is known 
+as window gravity.
+.KE
+.LP
+.KS
+\fBWindow manager\fP
+.IN "Window" "manager" "@DEF@"
+.IP
+Manipulation of windows on the screen and much of the user interface
+(policy) is typically provided by a window manager client.
+.KE
+.LP
+.KS
+\fBX Portable Character Set\fP
+.IN "X Portable Character Set" "" "@DEF@"
+.IP
+A basic set of 97 characters which are assumed to exist in all
+locales supported by Xlib.  This set contains the following characters:
+.IP
+.Ds 0
+.EQ
+delim DD
+.EN
+a..z A..Z 0..9
+!"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~
+<space>, <tab>, and <newline>
+.EQ
+delim %%
+.EN
+.De
+.IP
+This is the left/lower half (also called the G0 set)
+of the graphic character set of ISO8859-1 plus <space>, <tab>, and <newline>.
+It is also the set of graphic characters in 7-bit ASCII plus the same
+three control characters.
+The actual encoding of these characters on the host is system dependent;
+see the Host Portable Character Encoding.
+.KE
+.LP
+.KS
+\fBXLFD\fP
+.IN "XLFD" "" "@DEF@"
+.IP
+The X Logical Font Description Conventions that define a standard syntax 
+for structured font names.
+.KE
+.LP
+.KS
+\fBXY format\fP
+.IN "XY format" "" "@DEF@"
+.IP
+The data for a pixmap is said to be in XY format if it is organized as
+a set of bitmaps representing individual bit planes with the planes
+appearing from most-significant to least-significant bit order.
+.KE
+.LP
+.KS
+\fBZ format\fP
+.IN "Z format" "" "@DEF@"
+.IP
+The data for a pixmap is said to be in Z format if it is organized as
+a set of pixel values in scanline order.
+.KE
+.LP
+\fBReferences\fP
+.LP
+ANSI Programming Language - C: ANSI X3.159-1989, December 14, 1989.
+.LP
+Draft Proposed Multibyte Extension of ANSI C, Draft 1.1, November 30,
+1989, SC22/C WG/SWG IPSJ/ITSCJ Japan.
+.LP
+ISO2022: Information processing - ISO 7-bit and 8-bit coded character
+sets - Code extension techniques.
+.LP
+ISO8859-1: Information processing - 8-bit single-byte coded graphic
+character sets - Part 1: Latin alphabet No. 1.
+.LP
+POSIX: Information Technology - Portable Operating System Interface (POSIX) -
+Part 1: System Application Program Interface (API) [C Language],
+ISO/IEC 9945-1.
+.LP
+Text of ISO/IEC/DIS 9541-1, Information Processing - Font Information
+Interchange - Part 1:  Architecture.
+.LP
+X/Open Portability Guide, Issue 3, December 1988 (XPG3), X/Open Company,
+Ltd, Prentice-Hall, Inc. 1989. ISBN 0-13-685835-8.
+(See especially Volume 3:  XSI Supplementary Definitions.)
+.bp
diff --git a/specs/libX11/indexmacros.t b/specs/libX11/indexmacros.t
new file mode 100644
index 00000000..362f1614
--- /dev/null
+++ b/specs/libX11/indexmacros.t
@@ -0,0 +1,3 @@
+.eh '\fBXlib \- C Library\fP''\fB\*(xV\fP'
+.oh '\fBXlib \- C Library\fP''\fB\*(xV\fP'
+.so index.pageno
diff --git a/specs/libX11/libX11.ms b/specs/libX11/libX11.ms
new file mode 100644
index 00000000..b4442562
--- /dev/null
+++ b/specs/libX11/libX11.ms
@@ -0,0 +1,24 @@
+.so abstract.t
+.so credits.t
+.so CH01
+.so CH02
+.so CH03
+.so CH04
+.so CH05
+.so CH06
+.so CH07
+.so CH08
+.so CH09
+.so CH10
+.so CH11
+.so CH12
+.so CH13
+.so CH14
+.so CH15
+.so CH16
+.so AppA
+.so AppB
+.so AppC
+.so AppD
+.so glossary
+.so postproc
diff --git a/specs/libX11/postproc b/specs/libX11/postproc
new file mode 100644
index 00000000..0f45a5a0
--- /dev/null
+++ b/specs/libX11/postproc
@@ -0,0 +1,17 @@
+.\"
+.\" print Table of Contents
+.if e \& \" Force blank page to begin TOC on an odd (right-hand) page.
+.EH ''''
+.OH ''''
+.bp
+\& \" Want old footings if blank page was forced.
+.EF ''''
+.OF ''''
+.XS
+Index
+.XE
+.EQ
+delim $$
+.EN
+.tm .pn \n%
+.PX
diff --git a/specs/macros.t b/specs/macros.t
new file mode 100644
index 00000000..cbc599b3
--- /dev/null
+++ b/specs/macros.t
@@ -0,0 +1,226 @@
+.\" $Xorg: macros.t,v 1.3 2000/08/17 19:42:51 cpqbld Exp $
+.\" macros.t -- macros for X Consortium documents
+.\" Revised and commented by smarks 93.12.20.
+.\"
+.\" global setup: set ragged right, assign string variables
+.\"
+.na
+.ie n \{\
+.ds Q \&"
+.ds U \&"
+.ds - \%--
+.\}
+.el \{\
+.ds Q `\h'-\w'\^'u'`
+.ds U '\h'-\w'\^'u''
+.ds - \(em
+.\}
+.\"
+.\" --- Ds --- displayed text (like .DS) with no keep
+.\" .Ds is obsolete.  Change to something from this table:
+.\" for this	use instead
+.\" .Ds		.ID
+.\" .Ds n	.LD		(where "n" is a number)
+.\" (Numbers don't work in these macros, so ".Ds 5"
+.\" comes out the same as ".Ds 0".)
+.\"
+.de Ds
+.nf
+.\\$1D \\$2 \\$1
+.ft 1
+.ps \\n(PS
+.if \\n(VS>=40 .vs \\n(VSu
+.if \\n(VS<=39 .vs \\n(VSp
+..
+.de D
+.ID \\$1
+..
+.de 0D
+.LD
+..
+.\" backward compatibility for the Xt spec
+.de 5D
+.LD
+..
+.\"
+.\" --- De --- obsolete: use .DE instead
+.\"
+.de De
+.DE
+..
+.\"
+.\" --- FD ---
+.\"
+.de FD
+.LP
+.KS
+.TA .5i 3i
+.ta .5i 3i
+.nf
+..
+.\"
+.\" --- FN ---
+.\"
+.de FN
+.fi
+.KE
+.LP
+..
+.\"
+.\" --- IN --- send an index entry to the stderr
+.\"
+.de IN
+.tm \\n%:\\$1:\\$2:\\$3
+..
+.\"
+.\" --- C{ ---
+.\"
+.de C{
+.KS
+.nf
+.D
+.\"
+.\"	choose appropriate monospace font
+.\"	the imagen conditional, 480,
+.\"	may be changed to L if LB is too
+.\"	heavy for your eyes...
+.\"
+.ie "\\*(.T"480" .ft L
+.el .ie "\\*(.T"300" .ft L
+.el .ie "\\*(.T"202" .ft PO
+.el .ie "\\*(.T"aps" .ft CW
+.el .ft R
+.ps \\n(PS
+.ie \\n(VS>40 .vs \\n(VSu
+.el .vs \\n(VSp
+..
+.\"
+.\" --- C} ---
+.\"
+.de C}
+.DE
+.R
+..
+.\"
+.\" --- Pn --- like PN, but use $2; $1 and $3 abut
+.\"
+.de Pn
+.IN \\$2
+.ie t \\$1\fB\^\\$2\^\fR\\$3
+.el \\$1\fI\^\\$2\^\fP\\$3
+..
+.\"
+.\" --- PN --- put $1 in boldface and add index entry; $2 abuts
+.\"
+.de PN
+.IN \\$1
+.ie t \fB\^\\$1\^\fR\\$2
+.el \fI\^\\$1\^\fP\\$2
+..
+.\"
+.\" --- hI --- add index entry for $1 as header file
+.\"
+.de hI
+.IN         <\\$1>
+.IN Files   <\\$1>
+.IN Headers <\\$1>
+..
+.\"
+.\" --- hN --- put $1 in boldface as header and add index entry; $2 abuts
+.\"
+.de hN
+.hI \\$1
+.ie t <\fB\\$1\fR>\\$2
+.el <\fI\\$1\fP>\\$2
+..
+.\"
+.\" --- NT ---
+.\"
+.de NT
+.br
+.ne 7
+.ds NO Note
+.if \\n(.$ .ds NO \\$1
+.ie n .sp
+.el .sp 10p
+.ce
+\\*(NO
+.ie n .sp
+.el .sp 5p
+.if '\\$1'C' .ce 99
+.if '\\$2'C' .ce 99
+.\" .QS/.QE macros don't exist in older versions of -ms
+.ie \\n(GS .QS
+.el \{\
+.	in +5n
+.	ll -5n
+.\}
+.R
+..
+.\"
+.\" --- NE --- Note End (doug kraft 3/85)
+.\"
+.de NE
+.ce 0
+.ie \\n(GS .QE
+.el \{\
+.	in -5n
+.	ll +5n
+.\}
+.ie n .sp
+.el .sp 10p
+..
+.\"
+.\" --- nH --- numbered header (like NH) but with automatic TOC entry
+.\" usage: .nH level "section title, preferable in quotes"
+.\"
+.de nH
+.NH \\$1
+\\$2
+.XS
+\\*(SN \\$2
+.XE
+..
+.\"
+.\" --- sM --- put start-marker in margin
+.\"
+.de sM
+.KS
+.sp 1
+\\h'-0.5i'\\L'-1v'\\v'1p'\\l'1v'\\v'1v-1p'
+.sp -1
+..
+.\"
+.\" --- eM --- put end-marker in margin
+.\"
+.de eM
+.sp -1
+\\h'-0.5i'\\L'-1v'\\v'1v+1p'\\l'1v'\\v'-1p'
+.sp 1
+.KE
+..
+.\"
+.\" --- YZ --- finish up; $1 is the starting page number of the TOC
+.\"
+.de YZ
+.		\" Force there to be an even number of pages, so the table of
+.		\" contents doesn't end up on the back of the last page in
+.		\" the case of duplex printing.
+.if o .bp
+.		\" Emit a .pn directive with one plus the last page number.
+		\" This will be the number of the first page of the index.
+.nr YZ \\n%+1
+.tm .pn \\n(YZ
+.		\" Issue the table of contents, setting roman numerals,
+.		\" and redefining the footer to use them.
+.bp \\$1
+.af PN i
+.EF ''\\\\\\\\n(PN''
+.OF ''\\\\\\\\n(PN''
+.		\" Why all the backslashes?  This string is evaluated
+.		\" three times: 1) during the definition of this macro,
+.		\" 2) when the .EF and .OF macros are expanded, and 3)
+.		\" when the bottom-of-page trap is invoked.  Thus,
+.		\" eight backslashes are reduced to one in the final output.
+.PX
+..
diff --git a/specs/troffrules.in b/specs/troffrules.in
new file mode 100644
index 00000000..03d8463e
--- /dev/null
+++ b/specs/troffrules.in
@@ -0,0 +1,68 @@
+#
+# Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
+#
+# Permission to use, copy, modify, distribute, and sell this software and its
+# documentation for any purpose is hereby granted without fee, provided that
+# the above copyright notice appear in all copies and that both that
+# copyright notice and this permission notice appear in supporting
+# documentation.
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# 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 OPEN GROUP 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.
+#
+# Except as contained in this notice, the name of the copyright holders 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 copyright holders.
+#
+
+# Based on xc/doc/specs/*/Makefile from X11R6.9
+
+EXTRA_DIST = $(doc_sources)
+
+if HAVE_PS2PDF
+printable_format = .pdf
+else
+printable_format = .ps
+endif
+
+if BUILD_SPECS
+doc_DATA =	$(doc_sources:.ms=.txt) \
+		$(doc_sources:.ms=$(printable_format)) \
+		$(doc_sources:.ms=.html)
+
+CLEANFILES = $(doc_DATA)
+MOSTLYCLEANFILES = index.*
+
+# Pass version string as a troff string for substitution
+GROFF_DEFS = -dxV="$(PACKAGE_STRING)"
+
+# -e to run through eqn, -t to run through tbl
+GROFF_FLAGS = -e -t -ms $(GROFF_DEFS) $(top_srcdir)/specs/macros.t
+
+SUFFIXES = .ms .ps .txt .html .pdf
+
+.ms.ps:
+	-$(AM_V_GEN) $(GROFF) -Tps $(GROFF_FLAGS) $< 2> index.$@.raw > $@
+	@if grep '^[^1-9.]' index.$@.raw | grep -v warning; then exit 1; \
+	 else test $$? -le 1; fi
+
+.ms.txt:
+	$(AM_V_GEN) env GROFF_NO_SGR=TRUE $(GROFF) -Tutf8 $(GROFF_FLAGS) \
+	 $< 2> index.$@.raw > $@
+
+.ms.html:
+	$(AM_V_GEN) $(GROFF) -Thtml $(GROFF_FLAGS) $< 2> index.$@.raw > $@
+
+.ps.pdf:
+	$(AM_V_GEN) $(PS2PDF) $< $@
+
+endif BUILD_SPECS