diff options
Diffstat (limited to 'libX11/specs')
| -rw-r--r-- | libX11/specs/XIM/Makefile.am | 46 | ||||
| -rw-r--r-- | libX11/specs/i18n/framework/Makefile.am | 32 | ||||
| -rw-r--r-- | libX11/specs/i18n/localedb/Makefile.am | 26 | ||||
| -rw-r--r-- | libX11/specs/i18n/localedb/localedb.xml | 1554 | ||||
| -rw-r--r-- | libX11/specs/i18n/trans/Makefile.am | 26 | ||||
| -rw-r--r-- | libX11/specs/i18n/trans/trans.xml | 3958 | ||||
| -rw-r--r-- | libX11/specs/libX11/CH02.xml | 6978 | ||||
| -rw-r--r-- | libX11/specs/libX11/Makefile.am | 76 |
8 files changed, 6348 insertions, 6348 deletions
diff --git a/libX11/specs/XIM/Makefile.am b/libX11/specs/XIM/Makefile.am index 68b0b3f48..a7da39b6f 100644 --- a/libX11/specs/XIM/Makefile.am +++ b/libX11/specs/XIM/Makefile.am @@ -1,23 +1,23 @@ - -if ENABLE_SPECS - -# Main DocBook/XML files (DOCTYPE book) -docbook = xim.xml - -# Included chapters, appendix, images -chapters = \ - dynamicflowsampleseq.svg \ - dynamicflow.svg \ - eventflow.svg \ - sampleprotocolflow1.svg \ - sampleprotocolflow2.svg \ - staticflowsampleseq.svg \ - staticflow.svg - -# The location where the DocBook/XML files and their generated formats are installed -shelfdir = $(docdir)/XIM - -# Generate DocBook/XML output formats with or without stylesheets -include $(top_srcdir)/docbook.am - -endif ENABLE_SPECS +
+if ENABLE_SPECS
+
+# Main DocBook/XML files (DOCTYPE book)
+docbook = xim.xml
+
+# Included chapters, appendix, images
+chapters = \
+ dynamicflowsampleseq.svg \
+ dynamicflow.svg \
+ eventflow.svg \
+ sampleprotocolflow1.svg \
+ sampleprotocolflow2.svg \
+ staticflowsampleseq.svg \
+ staticflow.svg
+
+# The location where the DocBook/XML files and their generated formats are installed
+shelfdir = $(docdir)/XIM
+
+# Generate DocBook/XML output formats with or without stylesheets
+include $(top_srcdir)/docbook.am
+
+endif ENABLE_SPECS
diff --git a/libX11/specs/i18n/framework/Makefile.am b/libX11/specs/i18n/framework/Makefile.am index af7ae1d0e..38db989db 100644 --- a/libX11/specs/i18n/framework/Makefile.am +++ b/libX11/specs/i18n/framework/Makefile.am @@ -1,16 +1,16 @@ - -if ENABLE_SPECS - -# Main DocBook/XML files (DOCTYPE book) -docbook = framework.xml - -# Included chapters, appendix, images -chapters = framework.svg - -# The location where the DocBook/XML files and their generated formats are installed -shelfdir = $(docdir)/i18n/framework - -# Generate DocBook/XML output formats with or without stylesheets -include $(top_srcdir)/docbook.am - -endif ENABLE_SPECS +
+if ENABLE_SPECS
+
+# Main DocBook/XML files (DOCTYPE book)
+docbook = framework.xml
+
+# Included chapters, appendix, images
+chapters = framework.svg
+
+# The location where the DocBook/XML files and their generated formats are installed
+shelfdir = $(docdir)/i18n/framework
+
+# Generate DocBook/XML output formats with or without stylesheets
+include $(top_srcdir)/docbook.am
+
+endif ENABLE_SPECS
diff --git a/libX11/specs/i18n/localedb/Makefile.am b/libX11/specs/i18n/localedb/Makefile.am index 68a917c95..e7ae3523f 100644 --- a/libX11/specs/i18n/localedb/Makefile.am +++ b/libX11/specs/i18n/localedb/Makefile.am @@ -1,13 +1,13 @@ - -if ENABLE_SPECS - -# Main DocBook/XML files (DOCTYPE book) -docbook = localedb.xml - -# The location where the DocBook/XML files and their generated formats are installed -shelfdir = $(docdir)/i18n/localedb - -# Generate DocBook/XML output formats with or without stylesheets -include $(top_srcdir)/docbook.am - -endif ENABLE_SPECS +
+if ENABLE_SPECS
+
+# Main DocBook/XML files (DOCTYPE book)
+docbook = localedb.xml
+
+# The location where the DocBook/XML files and their generated formats are installed
+shelfdir = $(docdir)/i18n/localedb
+
+# Generate DocBook/XML output formats with or without stylesheets
+include $(top_srcdir)/docbook.am
+
+endif ENABLE_SPECS
diff --git a/libX11/specs/i18n/localedb/localedb.xml b/libX11/specs/i18n/localedb/localedb.xml index c4f6d1377..7b27d9f0c 100644 --- a/libX11/specs/i18n/localedb/localedb.xml +++ b/libX11/specs/i18n/localedb/localedb.xml @@ -1,777 +1,777 @@ -<?xml version="1.0" encoding="UTF-8" ?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" - "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> - -<book id="localedb"> - -<bookinfo> - <title>X Locale Database Specification</title> - <authorgroup> - <author> - <firstname>Yoshio</firstname><surname>Horiuchi</surname> - <affiliation><orgname>IBM Japan</orgname></affiliation> - </author> - </authorgroup> - <copyright><year>1994</year><holder>IBM Corporation</holder></copyright> - <copyright><year>1994</year><holder>X Consortium</holder></copyright> - - -<legalnotice> - -<para> -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. -</para> -<para> -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. -</para> - -<para> -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files -(the “Software”), to deal in the Software without restriction, -including without limitation the rights to use, copy, modify, merge, publish, -distribute, sublicense, and/or sell copies of the Software, and to permit -persons to whom the Software is furnished to do so, subject to the following -conditions: -</para> - -<para> -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. -</para> - -<para> -THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN -NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. -</para> - -<para> -Except as contained in this notice, the name of The 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 X Consortium. -</para> - -<para>X Window System is a trademark of The Open Group.</para> - -</legalnotice> -</bookinfo> - -<chapter id="localeDatabase"> -<title>LocaleDB</title> - -<sect1 id="General"> -<title>General</title> -<para> -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. -</para> - -<para> -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. -</para> - -<para> -This document describes; -</para> - -<itemizedlist> - <listitem> - <para> -Database Format Definition - </para> - </listitem> - <listitem> - <para> -Contents of Database in sample implementation -<!-- .RE --> - </para> - </listitem> -</itemizedlist> - -<para> -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. -</para> - -</sect1> -<sect1 id="Database_Format_Definition"> -<title>Database Format Definition</title> -<para> -The X Locale Database contains one or more category definitions. -This section describes the format of each category definition. -</para> - -<para> -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 (}). -</para> - -<para> -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. -</para> - -<para> -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(}). -</para> - -<para> -The format of category definition is; -</para> - -<informaltable frame="none"> - <tgroup cols='3' align='left'> - <colspec colname='c1' colwidth="3*" colsep="0"/> - <colspec colname='c2' colwidth="1*" colsep="0"/> - <colspec colname='c3' colwidth="6*" colsep="0"/> - <tbody> - <row rowsep="0"> - <entry>CategoryDefinition</entry> - <entry>::=</entry> - <entry>CategoryHeader CategorySpec CategoryTrailer</entry> - </row> - <row rowsep="0"> - <entry>CategoryHeader</entry> - <entry>::=</entry> - <entry>CategoryName NL</entry> - </row> - <row rowsep="0"> - <entry>CategorySpec</entry> - <entry>::=</entry> - <entry>{ ClassSpec }</entry> - </row> - <row rowsep="0"> - <entry>CategoryTrailer</entry> - <entry>::=</entry> - <entry>"END" Delimiter CategoryName NL</entry> - </row> - <row rowsep="0"> - <entry>CategoryName</entry> - <entry>::=</entry> - <entry>String</entry> - </row> - <row rowsep="0"> - <entry>ClassSpec</entry> - <entry>::=</entry> - <entry>ClassName Delimiter ClassValue NL</entry> - </row> - <row rowsep="0"> - <entry>ClassName</entry> - <entry>::=</entry> - <entry>String</entry> - </row> - <row rowsep="0"> - <entry>ClassValue</entry> - <entry>::=</entry> - <entry>ValueList | "{" NL { ClassSpec } "}"</entry> - </row> - <row rowsep="0"> - <entry>ValueList</entry> - <entry>::=</entry> - <entry>Value | Value ";" ValueList</entry> - </row> - <row rowsep="0"> - <entry>Value</entry> - <entry>::=</entry> - <entry>ValuePiece | ValuePiece Value</entry> - </row> - <row rowsep="0"> - <entry>ValuePiece</entry> - <entry>::=</entry> - <entry>String | QuotedString | NumericString</entry> - </row> - <row rowsep="0"> - <entry>String</entry> - <entry>::=</entry> - <entry>Char { Char }</entry> - </row> - <row rowsep="0"> - <entry>QuotedString</entry> - <entry>::=</entry> - <entry>""" QuotedChar { QuotedChar } """</entry> - </row> - <row rowsep="0"> - <entry>NumericString</entry> - <entry>::=</entry> - <entry>"\\o" OctDigit { OctDigit }</entry> - </row> - <row rowsep="0"> - <entry></entry> - <entry>|</entry> - <entry>"\\d" DecDigit { DecDigit }</entry> - </row> - <row rowsep="0"> - <entry></entry> - <entry>|</entry> - <entry>"\\x" HexDigit { HexDigit }</entry> - </row> - <row rowsep="0"> - <entry>Char</entry> - <entry>::=</entry> - <entry><XPCS except NL, Space or unescaped reserved symbols></entry> - </row> - <row rowsep="0"> - <entry>QuotedChar</entry> - <entry>::=</entry> - <entry><XPCS except unescaped """></entry> - </row> - <row rowsep="0"> - <entry>OctDigit</entry> - <entry>::=</entry> - <entry><character in the range of "0" - "7"></entry> - </row> - <row rowsep="0"> - <entry>DecDigit</entry> - <entry>::=</entry> - <entry><character in the range of "0" - "9"></entry> - </row> - <row rowsep="0"> - <entry>HexDigit</entry> - <entry>::=</entry> - <entry><character in the range of "0" - "9", "a" - "f", "A" - "F"></entry> - </row> - <row rowsep="0"> - <entry>Delimiter</entry> - <entry>::=</entry> - <entry>Space { Space }</entry> - </row> - <row rowsep="0"> - <entry>Space</entry> - <entry>::=</entry> - <entry><space> | <horizontal tab></entry> - </row> - <row rowsep="0"> - <entry>NL</entry> - <entry>::=</entry> - <entry><newline></entry> - </row> - </tbody> - </tgroup> -</informaltable> - -<para> -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. -</para> - -<para> -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. -</para> - -</sect1> -<sect1 id="Contents_of_Database_"> -<title>Contents of Database </title> -<para> -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. -</para> - -<para> -In current sample implementation, categories listed below are available. -</para> - -<informaltable frame="none"> - <tgroup cols='3' align='left'> - <colspec colname='c1' colwidth="2*" colsep="0"/> - <colspec colname='c2' colwidth="1*" colsep="0"/> - <tbody> - <row rowsep="0"> - <entry>XLC_FONTSET:XFontSet relative information</entry> - </row> - <row rowsep="0"> - <entry>XLC_XLOCALE:Character classification and conversion information</entry> - </row> - </tbody> - </tgroup> -</informaltable> - -</sect1> -<sect1 id="XLC_FONTSET_Category"> -<title>XLC_FONTSET Category</title> -<para> -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). -</para> - -<informaltable frame="none"> - <tgroup cols='3' align='left'> - <thead> - <colspec colname='c1' colwidth="3*" colsep="0"/> - <colspec colname='c2' colwidth="1*" colsep="0"/> - <colspec colname='c3' colwidth="3*" colsep="0"/> - <row> - <entry>class</entry> - <entry>super class</entry> - <entry>description</entry> - </row> - </thead> - <tbody> - <row rowsep="0"> - <entry>fsN</entry> - <entry></entry> - <entry>Nth fontset (N=0,1,2, ...)</entry> - </row> - <row rowsep="0"> - <entry>charset</entry> - <entry>fsN</entry> - <entry>list of encoding name</entry> - </row> - <row rowsep="0"> - <entry>font</entry> - <entry>fsN</entry> - <entry>list of font encoding name</entry> - </row> - </tbody> - </tgroup> -</informaltable> - -<variablelist> - <varlistentry> - <term>fsN</term> - <listitem> - <para> -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'. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>charset</term> - <listitem> - <para> -Specifies an encoding information to be used internally in Xlib -for this fontset. The format of value is; - </para> -<informaltable frame="none"> - <tgroup cols='3' align='left'> - <colspec colname='c1' colwidth="3*" colsep="0"/> - <colspec colname='c2' colwidth="1*" colsep="0"/> - <colspec colname='c3' colwidth="4*" colsep="0"/> - <tbody> - <row rowsep="0"> - <entry>EncodingInfo</entry> - <entry>::=</entry> - <entry>EncodingName [ ":" EncodingSide ]</entry> - </row> - <row rowsep="0"> - <entry>EncodingName</entry> - <entry>::=</entry> - <entry>CHARSET_REGISTRY-CHARSET_ENCODING</entry> - </row> - <row rowsep="0"> - <entry>EncodingSide</entry> - <entry>::=</entry> - <entry>"GL" | "GR"</entry> - </row> - </tbody> - </tgroup> -</informaltable> - -<para> -For detail definition of CHARSET_REGISTRY-CHARSET_ENCODING, refer -"X Logical Font Descriptions" document. -</para> -<literallayout> -example: - ISO8859-1:GL -</literallayout> - </listitem> - </varlistentry> - <varlistentry> - <term>font</term> - <listitem> - <para> -Specifies a list of encoding information which is used for searching -appropriate font for this fontset. The left most entry has highest -priority. - </para> - </listitem> - </varlistentry> -</variablelist> - -</sect1> -<sect1 id="XLC_XLOCALE_Category"> -<title>XLC_XLOCALE Category</title> -<para> -The XLC_XLOCALE category defines character classification, conversion -and other character attributes. -</para> - -<informaltable frame="none"> - <tgroup cols='3' align='left'> - <colspec colname='c1' colwidth="3*" colsep="0"/> - <colspec colname='c2' colwidth="1*" colsep="0"/> - <colspec colname='c3' colwidth="3*" colsep="0"/> - <thead> - <row> - <entry>class</entry> - <entry>super class</entry> - <entry>description</entry> - </row> - </thead> - <tbody> - <row rowsep="0"> - <entry>encoding_name</entry> - <entry></entry> - <entry>codeset name</entry> - </row> - <row rowsep="0"> - <entry>mb_cur_max</entry> - <entry></entry> - <entry>MB_CUR_MAX</entry> - </row> - <row rowsep="0"> - <entry>state_depend_encoding</entry> - <entry></entry> - <entry>state dependent or not</entry> - </row> - <row rowsep="0"> - <entry>wc_encoding_mask</entry> - <entry></entry> - <entry>for parsing wc string</entry> - </row> - <row rowsep="0"> - <entry>wc_shift_bits</entry> - <entry></entry> - <entry>for conversion between wc and mb</entry> - </row> - <row rowsep="0"> - <entry>csN</entry> - <entry></entry> - <entry>Nth charset (N=0,1,2,...)</entry> - </row> - <row rowsep="0"> - <entry>side</entry> - <entry>csN</entry> - <entry>mapping side (GL, etc)</entry> - </row> - <row rowsep="0"> - <entry>length</entry> - <entry>csN</entry> - <entry>length of a character</entry> - </row> - <row rowsep="0"> - <entry>mb_encoding</entry> - <entry>csN</entry> - <entry>for parsing mb string</entry> - </row> - <row rowsep="0"> - <entry>wc_encoding</entry> - <entry>csN</entry> - <entry>for parsing wc string</entry> - </row> - <row rowsep="0"> - <entry>ct_encoding</entry> - <entry>csN</entry> - <entry>list of encoding name for ct</entry> - </row> - </tbody> - </tgroup> -</informaltable> - -<variablelist> - <varlistentry> - <term>encoding_name</term> - <listitem> - <para> -Specifies a codeset name of current locale. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>mb_cur_max</term> - <listitem> - <para> -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". - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>state_depend_encoding</term> - <listitem> - <para> -Indicates a current locale is state dependent. The value should be -specified "True" or "False". - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>wc_encoding_mask</term> - <listitem> - <para> -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'. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>wc_shift_bits</term> - <listitem> - <para> -Specifies a number of bit to be shifted for converting from a multi-byte -character to a wide character, and vice-versa. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>csN</term> - <listitem> - <para> -<!-- .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'. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>side</term> - <listitem> - <para> -Specifies a mapping side of this charset. The format of this value is; - </para> - <literallayout> - Side ::= EncodingSide[":Default"] - </literallayout> - <para> -The suffix ":Default" can be specified. It indicates that a character -belongs to the specified side is mapped to this charset in initial state. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>length</term> - <listitem> - <para> -<!-- .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. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>mb_encoding</term> - <listitem> - <para> -Specifies a list of shift sequence for parsing multi-byte string. -The format of this value is; - </para> -<informaltable frame="none"> - <tgroup cols='3' align='left'> - <colspec colname='c1' colwidth="3*" colsep="0"/> - <colspec colname='c2' colwidth="1*" colsep="0"/> - <colspec colname='c3' colwidth="5*" colsep="0"/> - <tbody> - <row rowsep="0"> - <entry>MBEncoding</entry> - <entry>::=</entry> - <entry>ShiftType ShiftSequence</entry> - </row> - <row rowsep="0"> - <entry></entry> - <entry>|</entry> - <entry>ShiftType ShiftSequence ";" MBEncoding</entry> - </row> - <row rowsep="0"> - <entry>ShiftType</entry> - <entry>::=</entry> - <entry>"<SS>"|"<LSL>"|"<LSR>"</entry> - </row> - <row rowsep="0"> - <entry>ShiftSequence</entry> - <entry>::=</entry> - <entry>SequenceValue|SequenceValue ShiftSequence</entry> - </row> - <row rowsep="0"> - <entry>SequenceValue</entry> - <entry>::=</entry> - <entry>NumericString</entry> - </row> - </tbody> - </tgroup> -</informaltable> - - <literallayout> -example: - <LSL> \x1b \x28 \x4a; <LSL> \x1b \x28 \x42 - </literallayout> - </listitem> - </varlistentry> - <varlistentry> - <term>wc_encoding</term> - <listitem> - <para> -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. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>ct_encoding</term> - <listitem> - <para> -Specifies a list of encoding information that can be used for Compound -Text. - </para> - </listitem> - </varlistentry> -</variablelist> -</sect1> - -<sect1 id="Sample_of_X_Locale_Database"> -<title>Sample of X Locale Database</title> -<para> -The following is sample X Locale Database file. -</para> - -<literallayout class="monospaced"> -# 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 -</literallayout> -</sect1> - -<sect1 id="Reference"> -<title>Reference</title> -<para> -[1] <emphasis remap='I'>ISO/IEC 9899:1990 C Language Standard</emphasis> -</para> -<para> -[2] <emphasis remap='I'>X Logical Font Descriptions</emphasis> -</para> - -</sect1> -</chapter> -</book> +<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<book id="localedb">
+
+<bookinfo>
+ <title>X Locale Database Specification</title>
+ <authorgroup>
+ <author>
+ <firstname>Yoshio</firstname><surname>Horiuchi</surname>
+ <affiliation><orgname>IBM Japan</orgname></affiliation>
+ </author>
+ </authorgroup>
+ <copyright><year>1994</year><holder>IBM Corporation</holder></copyright>
+ <copyright><year>1994</year><holder>X Consortium</holder></copyright>
+
+
+<legalnotice>
+
+<para>
+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.
+</para>
+<para>
+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.
+</para>
+
+<para>
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files
+(the “Software”), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following
+conditions:
+</para>
+
+<para>
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+</para>
+
+<para>
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+</para>
+
+<para>
+Except as contained in this notice, the name of The 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 X Consortium.
+</para>
+
+<para>X Window System is a trademark of The Open Group.</para>
+
+</legalnotice>
+</bookinfo>
+
+<chapter id="localeDatabase">
+<title>LocaleDB</title>
+
+<sect1 id="General">
+<title>General</title>
+<para>
+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.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+This document describes;
+</para>
+
+<itemizedlist>
+ <listitem>
+ <para>
+Database Format Definition
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Contents of Database in sample implementation
+<!-- .RE -->
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+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.
+</para>
+
+</sect1>
+<sect1 id="Database_Format_Definition">
+<title>Database Format Definition</title>
+<para>
+The X Locale Database contains one or more category definitions.
+This section describes the format of each category definition.
+</para>
+
+<para>
+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 (}).
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+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(}).
+</para>
+
+<para>
+The format of category definition is;
+</para>
+
+<informaltable frame="none">
+ <tgroup cols='3' align='left'>
+ <colspec colname='c1' colwidth="3*" colsep="0"/>
+ <colspec colname='c2' colwidth="1*" colsep="0"/>
+ <colspec colname='c3' colwidth="6*" colsep="0"/>
+ <tbody>
+ <row rowsep="0">
+ <entry>CategoryDefinition</entry>
+ <entry>::=</entry>
+ <entry>CategoryHeader CategorySpec CategoryTrailer</entry>
+ </row>
+ <row rowsep="0">
+ <entry>CategoryHeader</entry>
+ <entry>::=</entry>
+ <entry>CategoryName NL</entry>
+ </row>
+ <row rowsep="0">
+ <entry>CategorySpec</entry>
+ <entry>::=</entry>
+ <entry>{ ClassSpec }</entry>
+ </row>
+ <row rowsep="0">
+ <entry>CategoryTrailer</entry>
+ <entry>::=</entry>
+ <entry>"END" Delimiter CategoryName NL</entry>
+ </row>
+ <row rowsep="0">
+ <entry>CategoryName</entry>
+ <entry>::=</entry>
+ <entry>String</entry>
+ </row>
+ <row rowsep="0">
+ <entry>ClassSpec</entry>
+ <entry>::=</entry>
+ <entry>ClassName Delimiter ClassValue NL</entry>
+ </row>
+ <row rowsep="0">
+ <entry>ClassName</entry>
+ <entry>::=</entry>
+ <entry>String</entry>
+ </row>
+ <row rowsep="0">
+ <entry>ClassValue</entry>
+ <entry>::=</entry>
+ <entry>ValueList | "{" NL { ClassSpec } "}"</entry>
+ </row>
+ <row rowsep="0">
+ <entry>ValueList</entry>
+ <entry>::=</entry>
+ <entry>Value | Value ";" ValueList</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Value</entry>
+ <entry>::=</entry>
+ <entry>ValuePiece | ValuePiece Value</entry>
+ </row>
+ <row rowsep="0">
+ <entry>ValuePiece</entry>
+ <entry>::=</entry>
+ <entry>String | QuotedString | NumericString</entry>
+ </row>
+ <row rowsep="0">
+ <entry>String</entry>
+ <entry>::=</entry>
+ <entry>Char { Char }</entry>
+ </row>
+ <row rowsep="0">
+ <entry>QuotedString</entry>
+ <entry>::=</entry>
+ <entry>""" QuotedChar { QuotedChar } """</entry>
+ </row>
+ <row rowsep="0">
+ <entry>NumericString</entry>
+ <entry>::=</entry>
+ <entry>"\\o" OctDigit { OctDigit }</entry>
+ </row>
+ <row rowsep="0">
+ <entry></entry>
+ <entry>|</entry>
+ <entry>"\\d" DecDigit { DecDigit }</entry>
+ </row>
+ <row rowsep="0">
+ <entry></entry>
+ <entry>|</entry>
+ <entry>"\\x" HexDigit { HexDigit }</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Char</entry>
+ <entry>::=</entry>
+ <entry><XPCS except NL, Space or unescaped reserved symbols></entry>
+ </row>
+ <row rowsep="0">
+ <entry>QuotedChar</entry>
+ <entry>::=</entry>
+ <entry><XPCS except unescaped """></entry>
+ </row>
+ <row rowsep="0">
+ <entry>OctDigit</entry>
+ <entry>::=</entry>
+ <entry><character in the range of "0" - "7"></entry>
+ </row>
+ <row rowsep="0">
+ <entry>DecDigit</entry>
+ <entry>::=</entry>
+ <entry><character in the range of "0" - "9"></entry>
+ </row>
+ <row rowsep="0">
+ <entry>HexDigit</entry>
+ <entry>::=</entry>
+ <entry><character in the range of "0" - "9", "a" - "f", "A" - "F"></entry>
+ </row>
+ <row rowsep="0">
+ <entry>Delimiter</entry>
+ <entry>::=</entry>
+ <entry>Space { Space }</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Space</entry>
+ <entry>::=</entry>
+ <entry><space> | <horizontal tab></entry>
+ </row>
+ <row rowsep="0">
+ <entry>NL</entry>
+ <entry>::=</entry>
+ <entry><newline></entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+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.
+</para>
+
+<para>
+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.
+</para>
+
+</sect1>
+<sect1 id="Contents_of_Database_">
+<title>Contents of Database </title>
+<para>
+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.
+</para>
+
+<para>
+In current sample implementation, categories listed below are available.
+</para>
+
+<informaltable frame="none">
+ <tgroup cols='3' align='left'>
+ <colspec colname='c1' colwidth="2*" colsep="0"/>
+ <colspec colname='c2' colwidth="1*" colsep="0"/>
+ <tbody>
+ <row rowsep="0">
+ <entry>XLC_FONTSET:XFontSet relative information</entry>
+ </row>
+ <row rowsep="0">
+ <entry>XLC_XLOCALE:Character classification and conversion information</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+</sect1>
+<sect1 id="XLC_FONTSET_Category">
+<title>XLC_FONTSET Category</title>
+<para>
+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).
+</para>
+
+<informaltable frame="none">
+ <tgroup cols='3' align='left'>
+ <thead>
+ <colspec colname='c1' colwidth="3*" colsep="0"/>
+ <colspec colname='c2' colwidth="1*" colsep="0"/>
+ <colspec colname='c3' colwidth="3*" colsep="0"/>
+ <row>
+ <entry>class</entry>
+ <entry>super class</entry>
+ <entry>description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row rowsep="0">
+ <entry>fsN</entry>
+ <entry></entry>
+ <entry>Nth fontset (N=0,1,2, ...)</entry>
+ </row>
+ <row rowsep="0">
+ <entry>charset</entry>
+ <entry>fsN</entry>
+ <entry>list of encoding name</entry>
+ </row>
+ <row rowsep="0">
+ <entry>font</entry>
+ <entry>fsN</entry>
+ <entry>list of font encoding name</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<variablelist>
+ <varlistentry>
+ <term>fsN</term>
+ <listitem>
+ <para>
+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'.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>charset</term>
+ <listitem>
+ <para>
+Specifies an encoding information to be used internally in Xlib
+for this fontset. The format of value is;
+ </para>
+<informaltable frame="none">
+ <tgroup cols='3' align='left'>
+ <colspec colname='c1' colwidth="3*" colsep="0"/>
+ <colspec colname='c2' colwidth="1*" colsep="0"/>
+ <colspec colname='c3' colwidth="4*" colsep="0"/>
+ <tbody>
+ <row rowsep="0">
+ <entry>EncodingInfo</entry>
+ <entry>::=</entry>
+ <entry>EncodingName [ ":" EncodingSide ]</entry>
+ </row>
+ <row rowsep="0">
+ <entry>EncodingName</entry>
+ <entry>::=</entry>
+ <entry>CHARSET_REGISTRY-CHARSET_ENCODING</entry>
+ </row>
+ <row rowsep="0">
+ <entry>EncodingSide</entry>
+ <entry>::=</entry>
+ <entry>"GL" | "GR"</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+For detail definition of CHARSET_REGISTRY-CHARSET_ENCODING, refer
+"X Logical Font Descriptions" document.
+</para>
+<literallayout>
+example:
+ ISO8859-1:GL
+</literallayout>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>font</term>
+ <listitem>
+ <para>
+Specifies a list of encoding information which is used for searching
+appropriate font for this fontset. The left most entry has highest
+priority.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</sect1>
+<sect1 id="XLC_XLOCALE_Category">
+<title>XLC_XLOCALE Category</title>
+<para>
+The XLC_XLOCALE category defines character classification, conversion
+and other character attributes.
+</para>
+
+<informaltable frame="none">
+ <tgroup cols='3' align='left'>
+ <colspec colname='c1' colwidth="3*" colsep="0"/>
+ <colspec colname='c2' colwidth="1*" colsep="0"/>
+ <colspec colname='c3' colwidth="3*" colsep="0"/>
+ <thead>
+ <row>
+ <entry>class</entry>
+ <entry>super class</entry>
+ <entry>description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row rowsep="0">
+ <entry>encoding_name</entry>
+ <entry></entry>
+ <entry>codeset name</entry>
+ </row>
+ <row rowsep="0">
+ <entry>mb_cur_max</entry>
+ <entry></entry>
+ <entry>MB_CUR_MAX</entry>
+ </row>
+ <row rowsep="0">
+ <entry>state_depend_encoding</entry>
+ <entry></entry>
+ <entry>state dependent or not</entry>
+ </row>
+ <row rowsep="0">
+ <entry>wc_encoding_mask</entry>
+ <entry></entry>
+ <entry>for parsing wc string</entry>
+ </row>
+ <row rowsep="0">
+ <entry>wc_shift_bits</entry>
+ <entry></entry>
+ <entry>for conversion between wc and mb</entry>
+ </row>
+ <row rowsep="0">
+ <entry>csN</entry>
+ <entry></entry>
+ <entry>Nth charset (N=0,1,2,...)</entry>
+ </row>
+ <row rowsep="0">
+ <entry>side</entry>
+ <entry>csN</entry>
+ <entry>mapping side (GL, etc)</entry>
+ </row>
+ <row rowsep="0">
+ <entry>length</entry>
+ <entry>csN</entry>
+ <entry>length of a character</entry>
+ </row>
+ <row rowsep="0">
+ <entry>mb_encoding</entry>
+ <entry>csN</entry>
+ <entry>for parsing mb string</entry>
+ </row>
+ <row rowsep="0">
+ <entry>wc_encoding</entry>
+ <entry>csN</entry>
+ <entry>for parsing wc string</entry>
+ </row>
+ <row rowsep="0">
+ <entry>ct_encoding</entry>
+ <entry>csN</entry>
+ <entry>list of encoding name for ct</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<variablelist>
+ <varlistentry>
+ <term>encoding_name</term>
+ <listitem>
+ <para>
+Specifies a codeset name of current locale.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>mb_cur_max</term>
+ <listitem>
+ <para>
+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".
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>state_depend_encoding</term>
+ <listitem>
+ <para>
+Indicates a current locale is state dependent. The value should be
+specified "True" or "False".
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>wc_encoding_mask</term>
+ <listitem>
+ <para>
+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'.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>wc_shift_bits</term>
+ <listitem>
+ <para>
+Specifies a number of bit to be shifted for converting from a multi-byte
+character to a wide character, and vice-versa.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>csN</term>
+ <listitem>
+ <para>
+<!-- .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'.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>side</term>
+ <listitem>
+ <para>
+Specifies a mapping side of this charset. The format of this value is;
+ </para>
+ <literallayout>
+ Side ::= EncodingSide[":Default"]
+ </literallayout>
+ <para>
+The suffix ":Default" can be specified. It indicates that a character
+belongs to the specified side is mapped to this charset in initial state.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>length</term>
+ <listitem>
+ <para>
+<!-- .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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>mb_encoding</term>
+ <listitem>
+ <para>
+Specifies a list of shift sequence for parsing multi-byte string.
+The format of this value is;
+ </para>
+<informaltable frame="none">
+ <tgroup cols='3' align='left'>
+ <colspec colname='c1' colwidth="3*" colsep="0"/>
+ <colspec colname='c2' colwidth="1*" colsep="0"/>
+ <colspec colname='c3' colwidth="5*" colsep="0"/>
+ <tbody>
+ <row rowsep="0">
+ <entry>MBEncoding</entry>
+ <entry>::=</entry>
+ <entry>ShiftType ShiftSequence</entry>
+ </row>
+ <row rowsep="0">
+ <entry></entry>
+ <entry>|</entry>
+ <entry>ShiftType ShiftSequence ";" MBEncoding</entry>
+ </row>
+ <row rowsep="0">
+ <entry>ShiftType</entry>
+ <entry>::=</entry>
+ <entry>"<SS>"|"<LSL>"|"<LSR>"</entry>
+ </row>
+ <row rowsep="0">
+ <entry>ShiftSequence</entry>
+ <entry>::=</entry>
+ <entry>SequenceValue|SequenceValue ShiftSequence</entry>
+ </row>
+ <row rowsep="0">
+ <entry>SequenceValue</entry>
+ <entry>::=</entry>
+ <entry>NumericString</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+ <literallayout>
+example:
+ <LSL> \x1b \x28 \x4a; <LSL> \x1b \x28 \x42
+ </literallayout>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>wc_encoding</term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ct_encoding</term>
+ <listitem>
+ <para>
+Specifies a list of encoding information that can be used for Compound
+Text.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect1>
+
+<sect1 id="Sample_of_X_Locale_Database">
+<title>Sample of X Locale Database</title>
+<para>
+The following is sample X Locale Database file.
+</para>
+
+<literallayout class="monospaced">
+# 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
+</literallayout>
+</sect1>
+
+<sect1 id="Reference">
+<title>Reference</title>
+<para>
+[1] <emphasis remap='I'>ISO/IEC 9899:1990 C Language Standard</emphasis>
+</para>
+<para>
+[2] <emphasis remap='I'>X Logical Font Descriptions</emphasis>
+</para>
+
+</sect1>
+</chapter>
+</book>
diff --git a/libX11/specs/i18n/trans/Makefile.am b/libX11/specs/i18n/trans/Makefile.am index 40a135a2f..e3c499744 100644 --- a/libX11/specs/i18n/trans/Makefile.am +++ b/libX11/specs/i18n/trans/Makefile.am @@ -1,13 +1,13 @@ - -if ENABLE_SPECS - -# Main DocBook/XML files (DOCTYPE book) -docbook = trans.xml - -# The location where the DocBook/XML files and their generated formats are installed -shelfdir = $(docdir)/i18n/trans - -# Generate DocBook/XML output formats with or without stylesheets -include $(top_srcdir)/docbook.am - -endif ENABLE_SPECS +
+if ENABLE_SPECS
+
+# Main DocBook/XML files (DOCTYPE book)
+docbook = trans.xml
+
+# The location where the DocBook/XML files and their generated formats are installed
+shelfdir = $(docdir)/i18n/trans
+
+# Generate DocBook/XML output formats with or without stylesheets
+include $(top_srcdir)/docbook.am
+
+endif ENABLE_SPECS
diff --git a/libX11/specs/i18n/trans/trans.xml b/libX11/specs/i18n/trans/trans.xml index c8447f934..5018c9192 100644 --- a/libX11/specs/i18n/trans/trans.xml +++ b/libX11/specs/i18n/trans/trans.xml @@ -1,1979 +1,1979 @@ -<?xml version="1.0" encoding="UTF-8" ?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" - "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> - -<book id="trans"> - -<bookinfo> - <title>The XIM Transport Specification</title> - <subtitle>Revision 0.1</subtitle> - <releaseinfo>X Version 11, Release 7</releaseinfo> - <authorgroup> - <author> - <firstname>Takashi</firstname><surname>Fujiwara</surname> - <affiliation><orgname>FUJITSU LIMITED</orgname></affiliation> - </author> - </authorgroup> - <copyright><year>1994</year><holder>FUJITSU LIMITED</holder></copyright> - <copyright><year>1994</year><holder>X Consortium</holder></copyright> - - <productnumber>Revision 0.1</productnumber> - - -<abstract> -<para> -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. -</para> -</abstract> - -<legalnotice> - -<para> -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files -(the “Software”), to deal in the Software without restriction, -including without limitation the rights to use, copy, modify, merge, publish, -distribute, sublicense, and/or sell copies of the Software, and to permit -persons to whom the Software is furnished to do so, subject to the following -conditions: -</para> - -<para> -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. -</para> - -<para> -THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN -NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. -</para> - -<para> -Except as contained in this notice, the name of The 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 X Consortium. -</para> - -<para>X Window System is a trademark of The Open Group.</para> - -</legalnotice> -</bookinfo> - -<chapter id="xim_transport_specification"> -<title>X Transport Specification</title> - -<sect1 id="Introduction"> -<title>Introduction</title> -<!-- .XS --> -<!-- (SN Introduction --> -<!-- .XE --> -<para> -<!-- .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 --> -</para> -<variablelist> - <varlistentry> - <term><emphasis>The protocol layer</emphasis></term> - <listitem> - <para> -implements overall function of XIM and calls the interface layer -functions when it needs to communicate to IM Server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><emphasis>The interface layer</emphasis></term> - <listitem> - <para> -separates the implementation of the transport layer from the protocol -layer, in other words, it provides implementation independent hook for -the transport layer functions. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><emphasis>The transport layer</emphasis></term> - <listitem> - <para> -handles actual data communication with IM Server. It is done by a set -of several functions named transporters. - </para> - </listitem> - </varlistentry> -</variablelist> - -<para> -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. <!-- xref --> -</para> -</sect1> - -<sect1 id="Initialization"> -<title>Initialization</title> - -<sect2 id="Registering_structure_to_initialize"> -<title>Registering structure to initialize</title> - -<para> -The structure typed as TransportSW contains the list of the transport -layer the specific implementations supports. -</para> - -<literallayout class="monospaced"> -typedef struct { - char *transport_name; - Bool (*config); -} TransportSW; -</literallayout> - -<informaltable frame="none"> - <tgroup cols="2"> - <colspec colname="col1" colwidth="1*" colsep="0"/> - <colspec colname="col2" colwidth="1*" colsep="0"/> - <tbody> - <row rowsep="0"> - <entry><emphasis>transport_name</emphasis></entry> - <entry>name of transport<footnote><para>Refer to "The Input Method Protocol: Appendix B</para></footnote></entry> - </row> - <row rowsep="0"> - <entry><emphasis>config</emphasis></entry> - <entry>initial configuration function</entry> - </row> - </tbody> - </tgroup> -</informaltable> - -<para> -A sample entry for the Xlib supporting transporters is shown below: -</para> - -<literallayout class="monospaced"> -TransportSW _XimTransportRec[] = { -/* char <emphasis remap='I'>*</emphasis>: - * transport_name, Bool <emphasis remap='I'>(*config)()</emphasis> - */ - "X", _XimXConf, - "tcp", _XimTransConf, - "local", _XimTransConf, - "decnet", _XimTransConf, - "streams", _XimTransConf, - (char *)NULL, (Bool (*)())NULL, -}; -</literallayout> - -</sect2> -<sect2 id="Initialization_function"> -<title>Initialization function</title> -<!-- .XS --> -<!-- (SN Initialization function --> -<!-- .XE --> -<para> -The following function will be called once when Xlib configures the -transporter functions. -</para> - -<funcsynopsis> -<funcprototype> - <funcdef>Bool <function>(*config)</function></funcdef> - <paramdef>XIM<parameter> im</parameter></paramdef> - <paramdef>char<parameter> *transport_data</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>im</emphasis> - </term> - <listitem> - <para> -Specifies XIM structure address. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>transport_data</emphasis> - </term> - <listitem> - <para> -Specifies the data specific to the transporter, in IM Server address.<footnote><para>Refer to "The Input Method Protocol: Appendix B</para></footnote> - </para> - </listitem> - </varlistentry> -</variablelist> - -<para> -This function must setup the transporter function pointers. -</para> - -<para> -<!-- .LP --> -The actual <emphasis remap='I'>config</emphasis> function will be chosen by IM Server at the -pre-connection time, matching by the <emphasis remap='I'>transport_name</emphasis> specified -in the <function>_XimTransportRec</function> array; The specific members of XimProto -structure listed below must be initialized so that point they -appropriate transporter functions. -</para> - -<para> -If the specified transporter has been configured successfully, this -function returns True. There is no Alternative Entry for config -function itself. -</para> - -<para> -The structure XimProto contains the following function pointers: -</para> - -<literallayout class="monospaced"> -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 */ -</literallayout> - -<para> -These functions are called when Xlib needs to communicate the -IM Server. These functions must process the appropriate procedure -described below. -</para> - -</sect2> -</sect1> -<sect1 id="The_interface_transport_layer_functions"> -<title>The interface/transport layer functions</title> -<para> -Following functions are used for the transport interface. -</para> - -<table frame="all" id="transport_layer_functions_2"> - <title>The Transport Layer Functions</title> - <tgroup cols="3"> - <colspec colname="col1" colwidth="3*" colsep="1"/> - <colspec colname="col2" colwidth="3*" colsep="1"/> - <colspec colname="col3" colwidth="1*" colsep="1"/> - <thead> - <row> - <entry align="center">Alternate Entry (Interface Layer)</entry> - <entry align="center">XimProto member (Transport Layer)</entry> - <entry align="center">Section</entry> - </row> - </thead> - <tbody> - <row> - <entry>_XimConnect</entry> - <entry>connect</entry> - <entry>3.1</entry> - </row> - <row> - <entry>_XimShutdown</entry> - <entry>shutdown</entry> - <entry>3.2</entry> - </row> - <row> - <entry>_XimWrite</entry> - <entry>write</entry> - <entry>3.3</entry> - </row> - <row> - <entry>_XimRead</entry> - <entry>read</entry> - <entry>3.4</entry> - </row> - <row> - <entry>_XimFlush</entry> - <entry>flush</entry> - <entry>3.5</entry> - </row> - <row> - <entry>_XimRegisterDispatcher</entry> - <entry>register_dispatcher</entry> - <entry>3.6</entry> - </row> - <row> - <entry>_XimCallDispatcher</entry> - <entry>call_dispatcher</entry> - <entry>3.7</entry> - </row> - </tbody> - </tgroup> -</table> - -<para> -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. -</para> - -<sect2 id="Opening_connection"> -<title>Opening connection</title> -<para> -<!-- .LP --> -When <function>XOpenIM</function> is called, the following function is called to connect -with the IM Server. -</para> - -<funcsynopsis> -<funcprototype> - <funcdef>Bool <function>(*connect)</function></funcdef> - <paramdef>XIM<parameter> im</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>im</emphasis> - </term> - <listitem> - <para> -Specifies XIM structure address. - </para> - </listitem> - </varlistentry> -</variablelist> - -<para> -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: -</para> - -<funcsynopsis> -<funcprototype> - <funcdef>Bool <function> _XimConnect</function></funcdef> - <paramdef>XIM<parameter> im</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>im</emphasis> - </term> - <listitem> - <para> -Specifies XIM structure address. - </para> - </listitem> - </varlistentry> -</variablelist> -</sect2> - -<sect2 id="Closing_connection"> -<title>Closing connection</title> -<!-- .XS --> -<!-- (SN Closing connection --> -<!-- .XE --> -<para> -<!-- .LP --> -When <function>XCloseIM</function> is called, the following function is called to -disconnect the connection with the IM Server. The Alternative Entry -for this function is: -</para> - -<funcsynopsis> -<funcprototype> - <funcdef>Bool <function> (*shutdown)</function></funcdef> - <paramdef>XIM<parameter> im</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>im</emphasis> - </term> - <listitem> - <para> -Specifies XIM structure address. - </para> - </listitem> - </varlistentry> -</variablelist> - -<para> -<!-- .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: -</para> - -<funcsynopsis> -<funcprototype> - <funcdef>Bool <function>_XimShutdown</function></funcdef> - <paramdef>XIM<parameter> im</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>im</emphasis> - </term> - <listitem> - <para> -Specifies XIM structure address. - </para> - </listitem> - </varlistentry> -</variablelist> - -</sect2> - -<sect2 id="Writing_data"> -<title>Writing data</title> -<para> -The following function is called, when Xlib needs to write data to the -IM Server. -</para> - -<funcsynopsis> -<funcprototype> - <funcdef>Bool <function> _XimWrite</function></funcdef> - <paramdef>XIM<parameter> im</parameter></paramdef> - <paramdef>INT16<parameter> len</parameter></paramdef> - <paramdef>XPointer<parameter> data</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>im</emphasis> - </term> - <listitem> - <para> -Specifies XIM structure address. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>len</emphasis> - </term> - <listitem> - <para> -Specifies the length of writing data. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>data</emphasis> - </term> - <listitem> - <para> -Specifies the writing data. - </para> - </listitem> - </varlistentry> -</variablelist> - -<para> -This function writes the <emphasis remap='I'>data</emphasis> to the IM Server, regardless -of the contents. The number of bytes is passed to <emphasis remap='I'>len</emphasis>. The -writing data is passed to <emphasis remap='I'>data</emphasis>. 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: -</para> - -<funcsynopsis> -<funcprototype> - <funcdef>Bool <function>_XimWrite</function></funcdef> - <paramdef>XIM<parameter> im</parameter></paramdef> - <paramdef>INT16<parameter> len</parameter></paramdef> - <paramdef>XPointer<parameter> data</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>im</emphasis> - </term> - <listitem> - <para> -Specifies XIM structure address. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>len</emphasis> - </term> - <listitem> - <para> -Specifies the length of writing data. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>data</emphasis> - </term> - <listitem> - <para> -Specifies the writing data. - </para> - </listitem> - </varlistentry> -</variablelist> - -</sect2> -<sect2 id="Reading_data"> -<title>Reading data</title> -<para> -The following function is called when Xlib waits for response from IM -server synchronously. -</para> - -<funcsynopsis> -<funcprototype> - <funcdef>Bool <function> _XimRead</function></funcdef> - <paramdef>XIM<parameter> im</parameter></paramdef> - <paramdef>XPointer<parameter> read_buf</parameter></paramdef> - <paramdef>int<parameter> buf_len</parameter></paramdef> - <paramdef>int<parameter> *ret_len</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>im</emphasis> - </term> - <listitem> - <para> -Specifies XIM structure address. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>read_buf</emphasis> - </term> - <listitem> - <para> -Specifies the buffer to store data. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>buf_len</emphasis> - </term> - <listitem> - <para> -Specifies the size of the <emphasis remap='I'>buffer</emphasis> - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>ret_len</emphasis> - </term> - <listitem> - <para> -Specifies the length of stored data. - </para> - </listitem> - </varlistentry> -</variablelist> - -<para> -This function stores the read data in <emphasis remap='I'>read_buf</emphasis>, which size is -specified as <emphasis remap='I'>buf_len</emphasis>. The size of data is set to <emphasis remap='I'>ret_len</emphasis>. -This function return True, if the data is read normally or reading -data is completed. -</para> -<para> -The Alternative Entry for this function is: -</para> - -<funcsynopsis> -<funcprototype> - <funcdef>Bool <function> _XimRead</function></funcdef> - <paramdef>XIM<parameter> im</parameter></paramdef> - <paramdef>INT16<parameter> *ret_len</parameter></paramdef> - <paramdef>XPointer<parameter> buf</parameter></paramdef> - <paramdef>int<parameter> buf_len</parameter></paramdef> - <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef> - <paramdef>XPointer<parameter> predicate_arg</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>im</emphasis> - </term> - <listitem> - <para> -Specifies XIM structure address. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>ret_len</emphasis> - </term> - <listitem> - <para> -Specifies the size of the <emphasis remap='I'>data</emphasis> buffer. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>buf</emphasis> - </term> - <listitem> - <para> -Specifies the buffer to store data. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>buf_len</emphasis> - </term> - <listitem> - <para> -Specifies the length of <emphasis remap='I'>buffer</emphasis>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>predicate</emphasis> - </term> - <listitem> - <para> -Specifies the predicate for the XIM data. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>predicate_arg</emphasis> - </term> - <listitem> - <para> -Specifies the predicate specific data. -<!-- .sp 6p --> - </para> - </listitem> - </varlistentry> -</variablelist> - -<para> -The predicate procedure indicates whether the <emphasis remap='I'>data</emphasis> is for the -XIM or not. <emphasis remap='I'>len</emphasis> -This function stores the read data in <emphasis remap='I'>buf</emphasis>, which size -is specified as <emphasis remap='I'>buf_len</emphasis>. The size of data is set to -<emphasis remap='I'>ret_len</emphasis>. If <emphasis remap='I'>preedicate()</emphasis> -returns True, this function returns True. If not, it calls the registered callback function. -</para> - -<para> -The procedure and its arguments are: -</para> - - -<funcsynopsis> -<funcprototype> - <funcdef>void <function>(*predicate)</function></funcdef> - <paramdef>XIM<parameter> im</parameter></paramdef> - <paramdef>INT16<parameter> len</parameter></paramdef> - <paramdef>XPointer<parameter> data</parameter></paramdef> - <paramdef>XPointer<parameter> predicate_arg</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>im</emphasis> - </term> - <listitem> - <para> -Specifies XIM structure address. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>len</emphasis> - </term> - <listitem> - <para> -Specifies the size of the <emphasis remap='I'>data</emphasis> buffer. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>data</emphasis> - </term> - <listitem> - <para> -Specifies the buffer to store data. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>predicate_arg</emphasis> - </term> - <listitem> - <para> -Specifies the predicate specific data. - </para> - </listitem> - </varlistentry> -</variablelist> - -</sect2> -<sect2 id="Flushing_buffer"> -<title>Flushing buffer</title> -<para> -The following function is called when Xlib needs to flush the data. -</para> - -<funcsynopsis> -<funcprototype> - <funcdef>void <function>(*flush)</function></funcdef> - <paramdef>XIM<parameter> im</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>im</emphasis> - </term> - <listitem> - <para> -Specifies XIM structure address. - </para> - </listitem> - </varlistentry> -</variablelist> - -<para> -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: -</para> - -<funcsynopsis> -<funcprototype> - <funcdef>void <function> _XimFlush</function></funcdef> - <paramdef>XIM<parameter> im</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>im</emphasis> - </term> - <listitem> - <para> -Specifies XIM structure address. - </para> - </listitem> - </varlistentry> -</variablelist> - -</sect2> -<sect2 id="Registering_asynchronous_data_handler"> -<title>Registering asynchronous data handler</title> -<para> -Xlib needs to handle asynchronous response from IM Server. This is -because some of the XIM data occur asynchronously to X events. -</para> - -<para> -Those data will be handled in the <emphasis remap='I'>Filter</emphasis>, -and the <emphasis remap='I'>Filter</emphasis> -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 -<function>_XimCallDispatcher</function>. -</para> - -<para> -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: -</para> - -<funcsynopsis> -<funcprototype> - <funcdef>Bool <function>(*register_dispatcher)</function></funcdef> - <paramdef>XIM<parameter> im</parameter></paramdef> - <paramdef>Bool<parameter> (*dispatcher)()</parameter></paramdef> - <paramdef>XPointer<parameter> call_data</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>im</emphasis> - </term> - <listitem> - <para> -Specifies XIM structure address. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>dispatcher</emphasis> - </term> - <listitem> - <para> -Specifies the dispatcher function to register. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>call_data</emphasis> - </term> - <listitem> - <para> -Specifies a parameter for the <emphasis remap='I'>dispatcher</emphasis>. - </para> - </listitem> - </varlistentry> -</variablelist> - -<para> -The dispatcher is a function of the following type: -</para> - -<funcsynopsis> -<funcprototype> - <funcdef>Bool <function>(*dispatcher)</function></funcdef> - <paramdef>XIM<parameter> im</parameter></paramdef> - <paramdef>INT16<parameter> len</parameter></paramdef> - <paramdef>XPointer<parameter> data</parameter></paramdef> - <paramdef>XPointer<parameter> call_data</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>im</emphasis> - </term> - <listitem> - <para> -Specifies XIM structure address. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>len</emphasis> - </term> - <listitem> - <para> -Specifies the size of the <emphasis remap='I'>data</emphasis> buffer. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>data</emphasis> - </term> - <listitem> - <para> -Specifies the buffer to store data. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>call_data</emphasis> - </term> - <listitem> - <para> -Specifies a parameter passed to the register_dispatcher. - </para> - </listitem> - </varlistentry> -</variablelist> - -<para> -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. -</para> - -<para> -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: -</para> - -<funcsynopsis> -<funcprototype> - <funcdef>Bool <function> _XimRegisterDispatcher</function></funcdef> - <paramdef>XIM<parameter> im</parameter></paramdef> - <paramdef>Bool<parameter> (*dispatcher)()</parameter></paramdef> - <paramdef>XPointer<parameter> call_data</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>im</emphasis> - </term> - <listitem> - <para> -Specifies XIM structure address. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>dispatcher</emphasis> - </term> - <listitem> - <para> -Specifies the dispatcher function to register. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>call_data</emphasis> - </term> - <listitem> - <para> -Specifies a parameter for the <emphasis remap='I'>dispatcher</emphasis>. - </para> - </listitem> - </varlistentry> -</variablelist> - -</sect2> -<sect2 id="Calling_dispatcher"> -<title>Calling dispatcher</title> -<para> -The following function is used to call the registered dispatcher -function, when the asynchronous response from IM Server has arrived. -</para> - -<funcsynopsis> -<funcprototype> - <funcdef>Bool <function>(*call_dispatcher)</function></funcdef> - <paramdef>XIM<parameter> im</parameter></paramdef> - <paramdef>INT16<parameter> len</parameter></paramdef> - <paramdef>XPointer<parameter> data</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>im</emphasis> - </term> - <listitem> - <para> -Specifies XIM structure address. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>len</emphasis> - </term> - <listitem> - <para> -Specifies the size of <emphasis remap='I'>data</emphasis> buffer. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>data</emphasis> - </term> - <listitem> - <para> -Specifies the buffer to store data. - </para> - </listitem> - </varlistentry> -</variablelist> - -<para> -The call_dispatcher must call the dispatcher function, in order of -their registration. <emphasis remap='I'>len</emphasis> and <emphasis remap='I'>data</emphasis> are the data passed to -register_dispatcher. -</para> - -<para> -The return values are checked at each invocation, and if it finds -True, it immediately return with true for its return value. -</para> - -<para> -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: -</para> - -<funcsynopsis> -<funcprototype> - <funcdef>Bool <function> _XimCallDispatcher</function></funcdef> - <paramdef>XIM<parameter> im</parameter></paramdef> - <paramdef>INT16<parameter> len</parameter></paramdef> - <paramdef>XPointer<parameter> call_data</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -</sect2> -</sect1> -<sect1 id="Sample_implementations_for_the_Transport_Layer"> -<title>Sample implementations for the Transport Layer</title> -<para> -Sample implementations for the transporter using the X connection is -described here. -</para> - -<sect2 id="X_Transport"> -<title>X Transport</title> -<para> -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". -</para> - -<sect3 id="Connection"> -<title>Connection</title> -<para> -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. -</para> - -<para> -<!-- .LP --> -Refer to "The Input Method Protocol" for the XIM_SERVER atom. -</para> - -<table frame="none" id="transport_layer_functions"> - <title>The ClientMessage sent to the IMS window.</title> - <tgroup cols="3"> - <colspec colname="col1" colwidth="1*" colsep="0"/> - <colspec colname="col2" colwidth="1*" colsep="1"/> - <colspec colname="col3" colwidth="3.5*" colsep="0"/> - <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> - <thead> - <row> - <entry align="left" spanname="span-horiz">Structure Member</entry> - <entry align="left">Contents</entry> - </row> - </thead> - <tbody> - <row rowsep="0"> - <entry>int</entry> - <entry>type</entry> - <entry>ClientMessage</entry> - </row> - <row rowsep="0"> - <entry>u_long</entry> - <entry>serial</entry> - <entry>Set by the X Window System</entry> - </row> - <row rowsep="0"> - <entry>Bool</entry> - <entry>send_event</entry> - <entry>Set by the X Window System</entry> - </row> - <row rowsep="0"> - <entry>Display</entry> - <entry>*display</entry> - <entry>The display to which connects</entry> - </row> - <row rowsep="0"> - <entry>Window</entry> - <entry>window</entry> - <entry>IMS Window ID</entry> - </row> - <row rowsep="0"> - <entry>Atom</entry> - <entry>message_type</entry> - <entry>XInternAtom(display, "_XIM_CONNECT", false)</entry> - </row> - <row rowsep="0"> - <entry>int</entry> - <entry>format</entry> - <entry>32</entry> - </row> - <row rowsep="0"> - <entry>long</entry> - <entry>data.1[0]</entry> - <entry>client communication window ID</entry> - </row> - <row rowsep="0"> - <entry>long</entry> - <entry>data.1[1]</entry> - <entry>client-major-transport-version(*1)</entry> - </row> - <row rowsep="0"> - <entry>long</entry> - <entry>data.1[2]</entry> - <entry>client-major-transport-version(*1)</entry> - </row> - </tbody> - </tgroup> -</table> - -<para> -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. -</para> - -<table frame="none" id="clientmessage_sent_by_im_server"> - <title>The ClientMessage sent by IM Server.</title> - <tgroup cols="3"> - <colspec colname="col1" colwidth="1*" colsep="0"/> - <colspec colname="col2" colwidth="1*" colsep="1"/> - <colspec colname="col3" colwidth="3.5*" colsep="0"/> - <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> - <thead> - <row> - <entry align="left" spanname="span-horiz">Structure Member</entry> - <entry align="left">Contents</entry> - </row> - </thead> - <tbody> - <row rowsep="0"> - <entry>int</entry> - <entry>type</entry> - <entry>ClientMessage</entry> - </row> - <row rowsep="0"> - <entry>u_long</entry> - <entry>serial</entry> - <entry>Set by the X Window System</entry> - </row> - <row rowsep="0"> - <entry>Bool</entry> - <entry>send_event</entry> - <entry>Set by the X Window System</entry> - </row> - <row rowsep="0"> - <entry>Display</entry> - <entry>*display</entry> - <entry>The display to which connects</entry> - </row> - <row rowsep="0"> - <entry>Window</entry> - <entry>window</entry> - <entry>IMS Window ID</entry> - </row> - <row rowsep="0"> - <entry>Atom</entry> - <entry>message_type</entry> - <entry>XInternAtom(display, "_XIM_CONNECT", false)</entry> - </row> - <row rowsep="0"> - <entry>int</entry> - <entry>format</entry> - <entry>32</entry> - </row> - <row rowsep="0"> - <entry>long</entry> - <entry>data.1[0]</entry> - <entry>client communication window ID</entry> - </row> - <row rowsep="0"> - <entry>long</entry> - <entry>data.1[1]</entry> - <entry>client-major-transport-version(*1)</entry> - </row> - <row rowsep="0"> - <entry>long</entry> - <entry>data.1[2]</entry> - <entry>client-major-transport-version(*1)</entry> - </row> - <row rowsep="0"> - <entry>long</entry> - <entry>data.1[3]</entry> - <entry>dividing size between ClientMessage and Property(*2)</entry> - </row> - </tbody> - </tgroup> -</table> - -<para> -(*1) major/minor-transport-version -</para> - -<para> -The read/write method is decided by the combination of -major/minor-transport-version, as follows: -</para> - -<table frame="all" id="readwrite_method_and_the_majorminor_transport_version"> -<title>The read/write method and the major/minor-transport-version</title> - <tgroup cols="3"> - <colspec colname="col1" colwidth="1*" colsep="1"/> - <colspec colname="col2" colwidth="1*" colsep="1"/> - <colspec colname="col3" colwidth="3*" colsep="1"/> - <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/> - <thead> - <row> - <entry spanname="span-horiz">Transport-version</entry> - <entry>read/write</entry> - </row> - <row> - <entry>major</entry> - <entry>minor</entry> - <entry></entry> - </row> - </thead> - <tbody> - <row rowsep="0"> - <entry morerows="2">0</entry> - <entry>0</entry> - <entry>only-CM & Property-with-CM</entry> - </row> - <row rowsep="0"> - <entry>1</entry> - <entry>only-CM & multi-CM</entry> - </row> - <row rowsep="1"> - <entry>2</entry> - <entry>only-CM & multi-CM & Property-with-CM</entry> - </row> - <row rowsep="1"> - <entry>1</entry> - <entry>0</entry> - <entry>PropertyNotify</entry> - </row> - <row rowsep="0"> - <entry morerows="1">2</entry> - <entry>0</entry> - <entry>only-CM & PropertyNotify</entry> - </row> - <row> - <entry>1</entry> - <entry>only-CM & multi-CM & PropertyNotify</entry> - </row> - </tbody> - </tgroup> -</table> - -<literallayout class="monospaced"> -only-CM : data is sent via a ClientMessage -multi-CM : data is sent via multiple ClientMessages -Property-with-CM : data is written in Property, and its Atom - is send via ClientMessage -PropertyNotify : data is written in Property, and its Atom - is send via PropertyNotify - -</literallayout> - - -<para> -The method to decide major/minor-transport-version is as follows: -</para> - -<itemizedlist> - <listitem> - <para> -The client sends 0 as major/minor-transport-version to the IM Server. -The client must support all methods in Table 4-3. <!-- xref --> -The client may send another number as major/minor-transport-version to -use other method than the above in the future. - </para> - </listitem> - <listitem> - <para> -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. - </para> - </listitem> - <listitem> - <para> -If major/minor-transport-version number is not available, it is regarded -as 0. - </para> - </listitem> -</itemizedlist> - -<para> -(*2) dividing size between ClientMessage and Property -</para> - -<para> -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. -</para> - -</sect3> - -<sect3 id="read_write_"> -<title>read/write </title> -<para> -The data is transferred via either ClientMessage or Window Property in -the X Window System. -</para> - -<sect4 id="Format_for_the_data_from_the_Client_to_the_IM_Server"> -<title>Format for the data from the Client to the IM Server</title> -<para> -<emphasis role="bold">ClientMessage</emphasis> -</para> - -<para> -If data is sent via ClientMessage event, the format is as follows: -</para> - -<table frame="none" id="clientmessage_events_format_first_or_middle"> - <title>The ClientMessage event's format (first or middle)</title> - <tgroup cols="3"> - <colspec colname="col1" colwidth="1*" colsep="0"/> - <colspec colname="col2" colwidth="1*" colsep="1"/> - <colspec colname="col3" colwidth="3.5*" colsep="0"/> - <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> - <thead> - <row> - <entry align="left" spanname="span-horiz">Structure Member</entry> - <entry align="left">Contents</entry> - </row> - </thead> - <tbody> - <row rowsep="0"> - <entry>int</entry> - <entry>type</entry> - <entry>ClientMessage</entry> - </row> - <row rowsep="0"> - <entry>u_long</entry> - <entry>serial</entry> - <entry>Set by the X Window System</entry> - </row> - <row rowsep="0"> - <entry>Bool</entry> - <entry>send_event</entry> - <entry>Set by the X Window System</entry> - </row> - <row rowsep="0"> - <entry>Display</entry> - <entry>*display</entry> - <entry>The display to which connects</entry> - </row> - <row rowsep="0"> - <entry>Window</entry> - <entry>window</entry> - <entry>IMS Window ID</entry> - </row> - <row rowsep="0"> - <entry>Atom</entry> - <entry>message_type</entry> - <entry>XInternAtom(display, "_XIM_MOREDATA", False)</entry> - </row> - <row rowsep="0"> - <entry>int</entry> - <entry>format</entry> - <entry>8</entry> - </row> - <row rowsep="0"> - <entry>char</entry> - <entry>data.b[20]</entry> - <entry>(read/write DATA : 20 byte)</entry> - </row> - </tbody> - </tgroup> -</table> - - - -<table frame="none" id="clientmessage_events_format_only_or_last"> - <title>The ClientMessage event's format (only or last)</title> - <tgroup cols="3"> - <colspec colname="col1" colwidth="1*" colsep="0"/> - <colspec colname="col2" colwidth="1*" colsep="1"/> - <colspec colname="col3" colwidth="3.5*" colsep="0"/> - <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> - <thead> - <row> - <entry align="left" spanname="span-horiz">Structure Member</entry> - <entry align="left">Contents</entry> - </row> - </thead> - <tbody> - <row rowsep="0"> - <entry>int</entry> - <entry>type</entry> - <entry>ClientMessage</entry> - </row> - <row rowsep="0"> - <entry>u_long</entry> - <entry>serial</entry> - <entry>Set by the X Window System</entry> - </row> - <row rowsep="0"> - <entry>Bool</entry> - <entry>send_event</entry> - <entry>Set by the X Window System</entry> - </row> - <row rowsep="0"> - <entry>Display</entry> - <entry>*display</entry> - <entry>The display to which connects</entry> - </row> - <row rowsep="0"> - <entry>Window</entry> - <entry>window</entry> - <entry>IMS Window ID</entry> - </row> - <row rowsep="0"> - <entry>Atom</entry> - <entry>message_type</entry> - <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry> - </row> - <row rowsep="0"> - <entry>int</entry> - <entry>format</entry> - <entry>8</entry> - </row> - <row rowsep="0"> - <entry>char</entry> - <entry>data.b[20]</entry> - <entry>(read/write DATA : MAX 20 byte) -<footnote><para>If the data is smaller -than 20 bytes, all data other than available data must be 0. -</para></footnote> - </entry> - </row> - </tbody> - </tgroup> -</table> - -<para> -<emphasis role="bold">Property</emphasis> -</para> - -<para> -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. -</para> - -<itemizedlist> - <listitem> - <para> -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. - </para> - </listitem> - <listitem> - <para> -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. - </para> - </listitem> -</itemizedlist> - -<para> -The arguments of the XChangeProperty are as follows: -</para> - - -<table frame="none" id="xchangeproperty_events_format"> - <title>The XChangeProperty event's format</title> - <tgroup cols="3"> - <colspec colname="col1" colwidth="1*" colsep="0"/> - <colspec colname="col2" colwidth="1*" colsep="1"/> - <colspec colname="col3" colwidth="3.5*" colsep="0"/> - <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> - <thead> - <row> - <entry align="left" spanname="span-horiz">Argument</entry> - <entry align="left">Contents</entry> - </row> - </thead> - <tbody> - <row rowsep="0"> - <entry>Display</entry> - <entry>*display</entry> - <entry>The display to which connects</entry> - </row> - <row rowsep="0"> - <entry>Window</entry> - <entry>window</entry> - <entry>IMS communication window ID</entry> - </row> - <row rowsep="0"> - <entry>Atom</entry> - <entry>property</entry> - <entry>read/write property Atom (*1)</entry> - </row> - <row rowsep="0"> - <entry>int</entry> - <entry>format</entry> - <entry>8</entry> - </row> - <row rowsep="0"> - <entry>int</entry> - <entry>mode</entry> - <entry>PropModeAppend</entry> - </row> - <row rowsep="0"> - <entry>u_char</entry> - <entry>*data</entry> - <entry>read/write DATA</entry> - </row> - <row rowsep="0"> - <entry>int</entry> - <entry>nelements</entry> - <entry>length of DATA</entry> - </row> - </tbody> - </tgroup> -</table> - -<para> -(*1) The read/write property ATOM allocates the following strings by -<function>XInternAtom</function>. -"_clientXXX" -</para> - -<para> -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). -</para> - -<para> -If Atom is notified via ClientMessage event, the format of the ClientMessage -is as follows: -</para> - -<table frame="none" id="clientmessage_events_format_to_send_atom_of_property"> - <title>The ClientMessage event's format to send Atom of property</title> - <tgroup cols="3"> - <colspec colname="col1" colwidth="1*" colsep="0"/> - <colspec colname="col2" colwidth="1*" colsep="1"/> - <colspec colname="col3" colwidth="3.5*" colsep="0"/> - <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> - <thead> - <row> - <entry align="left" spanname="span-horiz">Structure Member</entry> - <entry align="left">Contents</entry> - </row> - </thead> - <tbody> - <row rowsep="0"> - <entry>int</entry> - <entry>type</entry> - <entry>ClientMessage</entry> - </row> - <row rowsep="0"> - <entry>u_long</entry> - <entry>serial</entry> - <entry>Set by the X Window System</entry> - </row> - <row rowsep="0"> - <entry>Bool</entry> - <entry>send_event</entry> - <entry>Set by the X Window System</entry> - </row> - <row rowsep="0"> - <entry>Display</entry> - <entry>*display</entry> - <entry>The display to which connects</entry> - </row> - <row rowsep="0"> - <entry>Window</entry> - <entry>window</entry> - <entry>IMS Window ID</entry> - </row> - <row rowsep="0"> - <entry>Atom</entry> - <entry>message_type</entry> - <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry> - </row> - <row rowsep="0"> - <entry>int</entry> - <entry>format</entry> - <entry>8</entry> - </row> - <row rowsep="0"> - <entry>long</entry> - <entry>data.1[0]</entry> - <entry>length of read/write property Atom</entry> - </row> - <row rowsep="0"> - <entry>long</entry> - <entry>data.1[1]</entry> - <entry>read/write property Atom</entry> - </row> - </tbody> - </tgroup> -</table> -</sect4> - -<sect4 id="Format_for_the_data_from_the_IM_Server_to_the_Client"> -<title>Format for the data from the IM Server to the Client</title> -<para> -<emphasis role="bold">ClientMessage</emphasis> -</para> - -<para> -The format of the ClientMessage is as follows: -</para> - -<table frame="none" id="clientmessage_events_format_first_or_middle_2"> - <title>The ClientMessage event's format (first or middle)</title> - <tgroup cols="3"> - <colspec colname="col1" colwidth="1*" colsep="0"/> - <colspec colname="col2" colwidth="1*" colsep="1"/> - <colspec colname="col3" colwidth="3.5*" colsep="0"/> - <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> - <thead> - <row> - <entry align="left" spanname="span-horiz">Structure Member</entry> - <entry align="left">Contents</entry> - </row> - </thead> - <tbody> - <row rowsep="0"> - <entry>int</entry> - <entry>type</entry> - <entry>ClientMessage</entry> - </row> - <row rowsep="0"> - <entry>u_long</entry> - <entry>serial</entry> - <entry>Set by the X Window System</entry> - </row> - <row rowsep="0"> - <entry>Bool</entry> - <entry>send_event</entry> - <entry>Set by the X Window System</entry> - </row> - <row rowsep="0"> - <entry>Display</entry> - <entry>*display</entry> - <entry>The display to which connects</entry> - </row> - <row rowsep="0"> - <entry>Window</entry> - <entry>window</entry> - <entry>IMS Window ID</entry> - </row> - <row rowsep="0"> - <entry>Atom</entry> - <entry>message_type</entry> - <entry>XInternAtom(display, "_XIM_MOREDATA", False)</entry> - </row> - <row rowsep="0"> - <entry>int</entry> - <entry>format</entry> - <entry>8</entry> - </row> - <row rowsep="0"> - <entry>char</entry> - <entry>data.b[20]</entry> - <entry>(read/write DATA : 20 byte)</entry> - </row> - </tbody> - </tgroup> -</table> - - - - - -<table frame="none" id="clientmessage_events_format_only_or_last_2"> - <title>The ClientMessage event's format (only or last)</title> - <tgroup cols="3"> - <colspec colname="col1" colwidth="1*" colsep="0"/> - <colspec colname="col2" colwidth="1*" colsep="1"/> - <colspec colname="col3" colwidth="3.5*" colsep="0"/> - <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> - <thead> - <row> - <entry align="left" spanname="span-horiz">Structure Member</entry> - <entry align="left">Contents</entry> - </row> - </thead> - <tbody> - <row rowsep="0"> - <entry>int</entry> - <entry>type</entry> - <entry>ClientMessage</entry> - </row> - <row rowsep="0"> - <entry>u_long</entry> - <entry>serial</entry> - <entry>Set by the X Window System</entry> - </row> - <row rowsep="0"> - <entry>Bool</entry> - <entry>send_event</entry> - <entry>Set by the X Window System</entry> - </row> - <row rowsep="0"> - <entry>Display</entry> - <entry>*display</entry> - <entry>The display to which connects</entry> - </row> - <row rowsep="0"> - <entry>Window</entry> - <entry>window</entry> - <entry>IMS Window ID</entry> - </row> - <row rowsep="0"> - <entry>Atom</entry> - <entry>message_type</entry> - <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry> - </row> - <row rowsep="0"> - <entry>int</entry> - <entry>format</entry> - <entry>8</entry> - </row> - <row rowsep="0"> - <entry>char</entry> - <entry>data.b[20]</entry> - <entry>(read/write DATA : MAX 20 byte) (*1)</entry> - </row> - </tbody> - </tgroup> -</table> - -<para> -(*1) If the data size is smaller than 20 bytes, all data other than available -data must be 0. -</para> - -<para> -<emphasis role="bold">Property</emphasis> -</para> - -<para> -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. -</para> - -<itemizedlist> - <listitem> - <para> -The XChangeProperty function is used to store data in the IMS -communication window, and Atom of the property is sent via the -ClientMessage event. - </para> - </listitem> - <listitem> - <para> -The XChangeProperty function is used to store data in the IMS -communication window, and Atom of the property is sent via -PropertyNotify event. - </para> - </listitem> -</itemizedlist> - -<para> -The arguments of the XChangeProperty are as follows: -</para> - -<table frame="none" id="xchangeproperty_events_format_b"> - <title>The XChangeProperty event's format</title> - <tgroup cols="3"> - <colspec colname="col1" colwidth="1*" colsep="0"/> - <colspec colname="col2" colwidth="1*" colsep="1"/> - <colspec colname="col3" colwidth="3.5*" colsep="0"/> - <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> - <thead> - <row> - <entry align="left" spanname="span-horiz">Argument</entry> - <entry align="left">Contents</entry> - </row> - </thead> - <tbody> - <row rowsep="0"> - <entry>Display</entry> - <entry>*display</entry> - <entry>The display to which connects</entry> - </row> - <row rowsep="0"> - <entry>Window</entry> - <entry>window</entry> - <entry>IMS communication window ID</entry> - </row> - <row rowsep="0"> - <entry>Atom</entry> - <entry>property</entry> - <entry>read/write property Atom (*1)</entry> - </row> - <row rowsep="0"> - <entry>int</entry> - <entry>format</entry> - <entry>8</entry> - </row> - <row rowsep="0"> - <entry>int</entry> - <entry>mode</entry> - <entry>PropModeAppend</entry> - </row> - <row rowsep="0"> - <entry>u_char</entry> - <entry>*data</entry> - <entry>read/write DATA</entry> - </row> - <row rowsep="0"> - <entry>int</entry> - <entry>nelements</entry> - <entry>length of DATA</entry> - </row> - </tbody> - </tgroup> -</table> - -<para> -(*1) The read/write property ATOM allocates some strings, which are not -allocated by the client, by <function>XInternAtom</function>. -</para> - -<para> -The IM Server changes the property with the mode of PropModeAppend and -the client reads it with the delete mode, i.e. (delete = True). -</para> - -<para> -If Atom is notified via ClientMessage event, the format of the ClientMessage -is as follows: -</para> - -<table frame="none" id="clientmessage_events_format_to_send_atom_of_property_2"> - <title>The ClientMessage event's format to send Atom of property</title> - <tgroup cols="3"> - <colspec colname="col1" colwidth="1*" colsep="0"/> - <colspec colname="col2" colwidth="1*" colsep="1"/> - <colspec colname="col3" colwidth="3.5*" colsep="0"/> - <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/> - <thead> - <row> - <entry align="left" spanname="span-horiz">Structure Member</entry> - <entry align="left">Contents</entry> - </row> - </thead> - <tbody> - <row rowsep="0"> - <entry>int</entry> - <entry>type</entry> - <entry>ClientMessage</entry> - </row> - <row rowsep="0"> - <entry>u_long</entry> - <entry>serial</entry> - <entry>Set by the X Window System</entry> - </row> - <row rowsep="0"> - <entry>Bool</entry> - <entry>send_event</entry> - <entry>Set by the X Window System</entry> - </row> - <row rowsep="0"> - <entry>Display</entry> - <entry>*display</entry> - <entry>The display to which connects</entry> - </row> - <row rowsep="0"> - <entry>Window</entry> - <entry>window</entry> - <entry>IMS Window ID</entry> - </row> - <row rowsep="0"> - <entry>Atom</entry> - <entry>message_type</entry> - <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry> - </row> - <row rowsep="0"> - <entry>int</entry> - <entry>format</entry> - <entry>8</entry> - </row> - <row rowsep="0"> - <entry>long</entry> - <entry>data.1[0]</entry> - <entry>length of read/write property Atom</entry> - </row> - <row rowsep="0"> - <entry>long</entry> - <entry>data.1[1]</entry> - <entry>read/write property Atom</entry> - </row> - </tbody> - </tgroup> -</table> - -</sect4> -</sect3> -<sect3 id="Closing_Connection"> -<title>Closing Connection</title> - -<para> -If the client disconnect with the IM Server, shutdown function should -free the communication window properties and etc.. -</para> - -</sect3> -</sect2> -</sect1> - -<sect1 id="References"> -<title>References</title> -<para> -[1] Masahiko Narita and Hideki Hiura, <emphasis remap='I'>"The Input Method Protocol"</emphasis> -</para> -</sect1> - -</chapter> -</book> +<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<book id="trans">
+
+<bookinfo>
+ <title>The XIM Transport Specification</title>
+ <subtitle>Revision 0.1</subtitle>
+ <releaseinfo>X Version 11, Release 7</releaseinfo>
+ <authorgroup>
+ <author>
+ <firstname>Takashi</firstname><surname>Fujiwara</surname>
+ <affiliation><orgname>FUJITSU LIMITED</orgname></affiliation>
+ </author>
+ </authorgroup>
+ <copyright><year>1994</year><holder>FUJITSU LIMITED</holder></copyright>
+ <copyright><year>1994</year><holder>X Consortium</holder></copyright>
+
+ <productnumber>Revision 0.1</productnumber>
+
+
+<abstract>
+<para>
+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.
+</para>
+</abstract>
+
+<legalnotice>
+
+<para>
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files
+(the “Software”), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following
+conditions:
+</para>
+
+<para>
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+</para>
+
+<para>
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+</para>
+
+<para>
+Except as contained in this notice, the name of The 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 X Consortium.
+</para>
+
+<para>X Window System is a trademark of The Open Group.</para>
+
+</legalnotice>
+</bookinfo>
+
+<chapter id="xim_transport_specification">
+<title>X Transport Specification</title>
+
+<sect1 id="Introduction">
+<title>Introduction</title>
+<!-- .XS -->
+<!-- (SN Introduction -->
+<!-- .XE -->
+<para>
+<!-- .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 -->
+</para>
+<variablelist>
+ <varlistentry>
+ <term><emphasis>The protocol layer</emphasis></term>
+ <listitem>
+ <para>
+implements overall function of XIM and calls the interface layer
+functions when it needs to communicate to IM Server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>The interface layer</emphasis></term>
+ <listitem>
+ <para>
+separates the implementation of the transport layer from the protocol
+layer, in other words, it provides implementation independent hook for
+the transport layer functions.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis>The transport layer</emphasis></term>
+ <listitem>
+ <para>
+handles actual data communication with IM Server. It is done by a set
+of several functions named transporters.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+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. <!-- xref -->
+</para>
+</sect1>
+
+<sect1 id="Initialization">
+<title>Initialization</title>
+
+<sect2 id="Registering_structure_to_initialize">
+<title>Registering structure to initialize</title>
+
+<para>
+The structure typed as TransportSW contains the list of the transport
+layer the specific implementations supports.
+</para>
+
+<literallayout class="monospaced">
+typedef struct {
+ char *transport_name;
+ Bool (*config);
+} TransportSW;
+</literallayout>
+
+<informaltable frame="none">
+ <tgroup cols="2">
+ <colspec colname="col1" colwidth="1*" colsep="0"/>
+ <colspec colname="col2" colwidth="1*" colsep="0"/>
+ <tbody>
+ <row rowsep="0">
+ <entry><emphasis>transport_name</emphasis></entry>
+ <entry>name of transport<footnote><para>Refer to "The Input Method Protocol: Appendix B</para></footnote></entry>
+ </row>
+ <row rowsep="0">
+ <entry><emphasis>config</emphasis></entry>
+ <entry>initial configuration function</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+A sample entry for the Xlib supporting transporters is shown below:
+</para>
+
+<literallayout class="monospaced">
+TransportSW _XimTransportRec[] = {
+/* char <emphasis remap='I'>*</emphasis>:
+ * transport_name, Bool <emphasis remap='I'>(*config)()</emphasis>
+ */
+ "X", _XimXConf,
+ "tcp", _XimTransConf,
+ "local", _XimTransConf,
+ "decnet", _XimTransConf,
+ "streams", _XimTransConf,
+ (char *)NULL, (Bool (*)())NULL,
+};
+</literallayout>
+
+</sect2>
+<sect2 id="Initialization_function">
+<title>Initialization function</title>
+<!-- .XS -->
+<!-- (SN Initialization function -->
+<!-- .XE -->
+<para>
+The following function will be called once when Xlib configures the
+transporter functions.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function>(*config)</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>char<parameter> *transport_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>transport_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the data specific to the transporter, in IM Server address.<footnote><para>Refer to "The Input Method Protocol: Appendix B</para></footnote>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This function must setup the transporter function pointers.
+</para>
+
+<para>
+<!-- .LP -->
+The actual <emphasis remap='I'>config</emphasis> function will be chosen by IM Server at the
+pre-connection time, matching by the <emphasis remap='I'>transport_name</emphasis> specified
+in the <function>_XimTransportRec</function> array; The specific members of XimProto
+structure listed below must be initialized so that point they
+appropriate transporter functions.
+</para>
+
+<para>
+If the specified transporter has been configured successfully, this
+function returns True. There is no Alternative Entry for config
+function itself.
+</para>
+
+<para>
+The structure XimProto contains the following function pointers:
+</para>
+
+<literallayout class="monospaced">
+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 */
+</literallayout>
+
+<para>
+These functions are called when Xlib needs to communicate the
+IM Server. These functions must process the appropriate procedure
+described below.
+</para>
+
+</sect2>
+</sect1>
+<sect1 id="The_interface_transport_layer_functions">
+<title>The interface/transport layer functions</title>
+<para>
+Following functions are used for the transport interface.
+</para>
+
+<table frame="all" id="transport_layer_functions_2">
+ <title>The Transport Layer Functions</title>
+ <tgroup cols="3">
+ <colspec colname="col1" colwidth="3*" colsep="1"/>
+ <colspec colname="col2" colwidth="3*" colsep="1"/>
+ <colspec colname="col3" colwidth="1*" colsep="1"/>
+ <thead>
+ <row>
+ <entry align="center">Alternate Entry (Interface Layer)</entry>
+ <entry align="center">XimProto member (Transport Layer)</entry>
+ <entry align="center">Section</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>_XimConnect</entry>
+ <entry>connect</entry>
+ <entry>3.1</entry>
+ </row>
+ <row>
+ <entry>_XimShutdown</entry>
+ <entry>shutdown</entry>
+ <entry>3.2</entry>
+ </row>
+ <row>
+ <entry>_XimWrite</entry>
+ <entry>write</entry>
+ <entry>3.3</entry>
+ </row>
+ <row>
+ <entry>_XimRead</entry>
+ <entry>read</entry>
+ <entry>3.4</entry>
+ </row>
+ <row>
+ <entry>_XimFlush</entry>
+ <entry>flush</entry>
+ <entry>3.5</entry>
+ </row>
+ <row>
+ <entry>_XimRegisterDispatcher</entry>
+ <entry>register_dispatcher</entry>
+ <entry>3.6</entry>
+ </row>
+ <row>
+ <entry>_XimCallDispatcher</entry>
+ <entry>call_dispatcher</entry>
+ <entry>3.7</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+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.
+</para>
+
+<sect2 id="Opening_connection">
+<title>Opening connection</title>
+<para>
+<!-- .LP -->
+When <function>XOpenIM</function> is called, the following function is called to connect
+with the IM Server.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function>(*connect)</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+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:
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function> _XimConnect</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</sect2>
+
+<sect2 id="Closing_connection">
+<title>Closing connection</title>
+<!-- .XS -->
+<!-- (SN Closing connection -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+When <function>XCloseIM</function> is called, the following function is called to
+disconnect the connection with the IM Server. The Alternative Entry
+for this function is:
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function> (*shutdown)</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .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:
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function>_XimShutdown</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2 id="Writing_data">
+<title>Writing data</title>
+<para>
+The following function is called, when Xlib needs to write data to the
+IM Server.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function> _XimWrite</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>INT16<parameter> len</parameter></paramdef>
+ <paramdef>XPointer<parameter> data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>len</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the length of writing data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the writing data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This function writes the <emphasis remap='I'>data</emphasis> to the IM Server, regardless
+of the contents. The number of bytes is passed to <emphasis remap='I'>len</emphasis>. The
+writing data is passed to <emphasis remap='I'>data</emphasis>. 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:
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function>_XimWrite</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>INT16<parameter> len</parameter></paramdef>
+ <paramdef>XPointer<parameter> data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>len</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the length of writing data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the writing data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</sect2>
+<sect2 id="Reading_data">
+<title>Reading data</title>
+<para>
+The following function is called when Xlib waits for response from IM
+server synchronously.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function> _XimRead</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>XPointer<parameter> read_buf</parameter></paramdef>
+ <paramdef>int<parameter> buf_len</parameter></paramdef>
+ <paramdef>int<parameter> *ret_len</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>read_buf</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer to store data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>buf_len</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of the <emphasis remap='I'>buffer</emphasis>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ret_len</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the length of stored data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+This function stores the read data in <emphasis remap='I'>read_buf</emphasis>, which size is
+specified as <emphasis remap='I'>buf_len</emphasis>. The size of data is set to <emphasis remap='I'>ret_len</emphasis>.
+This function return True, if the data is read normally or reading
+data is completed.
+</para>
+<para>
+The Alternative Entry for this function is:
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function> _XimRead</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>INT16<parameter> *ret_len</parameter></paramdef>
+ <paramdef>XPointer<parameter> buf</parameter></paramdef>
+ <paramdef>int<parameter> buf_len</parameter></paramdef>
+ <paramdef>Bool<parameter> (*predicate)()</parameter></paramdef>
+ <paramdef>XPointer<parameter> predicate_arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>ret_len</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of the <emphasis remap='I'>data</emphasis> buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>buf</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer to store data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>buf_len</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the length of <emphasis remap='I'>buffer</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>predicate</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the predicate for the XIM data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>predicate_arg</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the predicate specific data.
+<!-- .sp 6p -->
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The predicate procedure indicates whether the <emphasis remap='I'>data</emphasis> is for the
+XIM or not. <emphasis remap='I'>len</emphasis>
+This function stores the read data in <emphasis remap='I'>buf</emphasis>, which size
+is specified as <emphasis remap='I'>buf_len</emphasis>. The size of data is set to
+<emphasis remap='I'>ret_len</emphasis>. If <emphasis remap='I'>preedicate()</emphasis>
+returns True, this function returns True. If not, it calls the registered callback function.
+</para>
+
+<para>
+The procedure and its arguments are:
+</para>
+
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function>(*predicate)</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>INT16<parameter> len</parameter></paramdef>
+ <paramdef>XPointer<parameter> data</parameter></paramdef>
+ <paramdef>XPointer<parameter> predicate_arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>len</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of the <emphasis remap='I'>data</emphasis> buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer to store data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>predicate_arg</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the predicate specific data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</sect2>
+<sect2 id="Flushing_buffer">
+<title>Flushing buffer</title>
+<para>
+The following function is called when Xlib needs to flush the data.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function>(*flush)</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+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:
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function> _XimFlush</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</sect2>
+<sect2 id="Registering_asynchronous_data_handler">
+<title>Registering asynchronous data handler</title>
+<para>
+Xlib needs to handle asynchronous response from IM Server. This is
+because some of the XIM data occur asynchronously to X events.
+</para>
+
+<para>
+Those data will be handled in the <emphasis remap='I'>Filter</emphasis>,
+and the <emphasis remap='I'>Filter</emphasis>
+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
+<function>_XimCallDispatcher</function>.
+</para>
+
+<para>
+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:
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function>(*register_dispatcher)</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>Bool<parameter> (*dispatcher)()</parameter></paramdef>
+ <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dispatcher</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the dispatcher function to register.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a parameter for the <emphasis remap='I'>dispatcher</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The dispatcher is a function of the following type:
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function>(*dispatcher)</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>INT16<parameter> len</parameter></paramdef>
+ <paramdef>XPointer<parameter> data</parameter></paramdef>
+ <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>len</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of the <emphasis remap='I'>data</emphasis> buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer to store data.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a parameter passed to the register_dispatcher.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+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.
+</para>
+
+<para>
+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:
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function> _XimRegisterDispatcher</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>Bool<parameter> (*dispatcher)()</parameter></paramdef>
+ <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>dispatcher</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the dispatcher function to register.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>call_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a parameter for the <emphasis remap='I'>dispatcher</emphasis>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</sect2>
+<sect2 id="Calling_dispatcher">
+<title>Calling dispatcher</title>
+<para>
+The following function is used to call the registered dispatcher
+function, when the asynchronous response from IM Server has arrived.
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function>(*call_dispatcher)</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>INT16<parameter> len</parameter></paramdef>
+ <paramdef>XPointer<parameter> data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>im</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies XIM structure address.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>len</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size of <emphasis remap='I'>data</emphasis> buffer.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the buffer to store data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+The call_dispatcher must call the dispatcher function, in order of
+their registration. <emphasis remap='I'>len</emphasis> and <emphasis remap='I'>data</emphasis> are the data passed to
+register_dispatcher.
+</para>
+
+<para>
+The return values are checked at each invocation, and if it finds
+True, it immediately return with true for its return value.
+</para>
+
+<para>
+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:
+</para>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function> _XimCallDispatcher</function></funcdef>
+ <paramdef>XIM<parameter> im</parameter></paramdef>
+ <paramdef>INT16<parameter> len</parameter></paramdef>
+ <paramdef>XPointer<parameter> call_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+</sect2>
+</sect1>
+<sect1 id="Sample_implementations_for_the_Transport_Layer">
+<title>Sample implementations for the Transport Layer</title>
+<para>
+Sample implementations for the transporter using the X connection is
+described here.
+</para>
+
+<sect2 id="X_Transport">
+<title>X Transport</title>
+<para>
+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".
+</para>
+
+<sect3 id="Connection">
+<title>Connection</title>
+<para>
+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.
+</para>
+
+<para>
+<!-- .LP -->
+Refer to "The Input Method Protocol" for the XIM_SERVER atom.
+</para>
+
+<table frame="none" id="transport_layer_functions">
+ <title>The ClientMessage sent to the IMS window.</title>
+ <tgroup cols="3">
+ <colspec colname="col1" colwidth="1*" colsep="0"/>
+ <colspec colname="col2" colwidth="1*" colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*" colsep="0"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
+ <thead>
+ <row>
+ <entry align="left" spanname="span-horiz">Structure Member</entry>
+ <entry align="left">Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row rowsep="0">
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS Window ID</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_CONNECT", false)</entry>
+ </row>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>32</entry>
+ </row>
+ <row rowsep="0">
+ <entry>long</entry>
+ <entry>data.1[0]</entry>
+ <entry>client communication window ID</entry>
+ </row>
+ <row rowsep="0">
+ <entry>long</entry>
+ <entry>data.1[1]</entry>
+ <entry>client-major-transport-version(*1)</entry>
+ </row>
+ <row rowsep="0">
+ <entry>long</entry>
+ <entry>data.1[2]</entry>
+ <entry>client-major-transport-version(*1)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+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.
+</para>
+
+<table frame="none" id="clientmessage_sent_by_im_server">
+ <title>The ClientMessage sent by IM Server.</title>
+ <tgroup cols="3">
+ <colspec colname="col1" colwidth="1*" colsep="0"/>
+ <colspec colname="col2" colwidth="1*" colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*" colsep="0"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
+ <thead>
+ <row>
+ <entry align="left" spanname="span-horiz">Structure Member</entry>
+ <entry align="left">Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row rowsep="0">
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS Window ID</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_CONNECT", false)</entry>
+ </row>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>32</entry>
+ </row>
+ <row rowsep="0">
+ <entry>long</entry>
+ <entry>data.1[0]</entry>
+ <entry>client communication window ID</entry>
+ </row>
+ <row rowsep="0">
+ <entry>long</entry>
+ <entry>data.1[1]</entry>
+ <entry>client-major-transport-version(*1)</entry>
+ </row>
+ <row rowsep="0">
+ <entry>long</entry>
+ <entry>data.1[2]</entry>
+ <entry>client-major-transport-version(*1)</entry>
+ </row>
+ <row rowsep="0">
+ <entry>long</entry>
+ <entry>data.1[3]</entry>
+ <entry>dividing size between ClientMessage and Property(*2)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+(*1) major/minor-transport-version
+</para>
+
+<para>
+The read/write method is decided by the combination of
+major/minor-transport-version, as follows:
+</para>
+
+<table frame="all" id="readwrite_method_and_the_majorminor_transport_version">
+<title>The read/write method and the major/minor-transport-version</title>
+ <tgroup cols="3">
+ <colspec colname="col1" colwidth="1*" colsep="1"/>
+ <colspec colname="col2" colwidth="1*" colsep="1"/>
+ <colspec colname="col3" colwidth="3*" colsep="1"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="center"/>
+ <thead>
+ <row>
+ <entry spanname="span-horiz">Transport-version</entry>
+ <entry>read/write</entry>
+ </row>
+ <row>
+ <entry>major</entry>
+ <entry>minor</entry>
+ <entry></entry>
+ </row>
+ </thead>
+ <tbody>
+ <row rowsep="0">
+ <entry morerows="2">0</entry>
+ <entry>0</entry>
+ <entry>only-CM & Property-with-CM</entry>
+ </row>
+ <row rowsep="0">
+ <entry>1</entry>
+ <entry>only-CM & multi-CM</entry>
+ </row>
+ <row rowsep="1">
+ <entry>2</entry>
+ <entry>only-CM & multi-CM & Property-with-CM</entry>
+ </row>
+ <row rowsep="1">
+ <entry>1</entry>
+ <entry>0</entry>
+ <entry>PropertyNotify</entry>
+ </row>
+ <row rowsep="0">
+ <entry morerows="1">2</entry>
+ <entry>0</entry>
+ <entry>only-CM & PropertyNotify</entry>
+ </row>
+ <row>
+ <entry>1</entry>
+ <entry>only-CM & multi-CM & PropertyNotify</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<literallayout class="monospaced">
+only-CM : data is sent via a ClientMessage
+multi-CM : data is sent via multiple ClientMessages
+Property-with-CM : data is written in Property, and its Atom
+ is send via ClientMessage
+PropertyNotify : data is written in Property, and its Atom
+ is send via PropertyNotify
+
+</literallayout>
+
+
+<para>
+The method to decide major/minor-transport-version is as follows:
+</para>
+
+<itemizedlist>
+ <listitem>
+ <para>
+The client sends 0 as major/minor-transport-version to the IM Server.
+The client must support all methods in Table 4-3. <!-- xref -->
+The client may send another number as major/minor-transport-version to
+use other method than the above in the future.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If major/minor-transport-version number is not available, it is regarded
+as 0.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+(*2) dividing size between ClientMessage and Property
+</para>
+
+<para>
+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.
+</para>
+
+</sect3>
+
+<sect3 id="read_write_">
+<title>read/write </title>
+<para>
+The data is transferred via either ClientMessage or Window Property in
+the X Window System.
+</para>
+
+<sect4 id="Format_for_the_data_from_the_Client_to_the_IM_Server">
+<title>Format for the data from the Client to the IM Server</title>
+<para>
+<emphasis role="bold">ClientMessage</emphasis>
+</para>
+
+<para>
+If data is sent via ClientMessage event, the format is as follows:
+</para>
+
+<table frame="none" id="clientmessage_events_format_first_or_middle">
+ <title>The ClientMessage event's format (first or middle)</title>
+ <tgroup cols="3">
+ <colspec colname="col1" colwidth="1*" colsep="0"/>
+ <colspec colname="col2" colwidth="1*" colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*" colsep="0"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
+ <thead>
+ <row>
+ <entry align="left" spanname="span-horiz">Structure Member</entry>
+ <entry align="left">Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row rowsep="0">
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS Window ID</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_MOREDATA", False)</entry>
+ </row>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row rowsep="0">
+ <entry>char</entry>
+ <entry>data.b[20]</entry>
+ <entry>(read/write DATA : 20 byte)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+
+
+<table frame="none" id="clientmessage_events_format_only_or_last">
+ <title>The ClientMessage event's format (only or last)</title>
+ <tgroup cols="3">
+ <colspec colname="col1" colwidth="1*" colsep="0"/>
+ <colspec colname="col2" colwidth="1*" colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*" colsep="0"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
+ <thead>
+ <row>
+ <entry align="left" spanname="span-horiz">Structure Member</entry>
+ <entry align="left">Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row rowsep="0">
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS Window ID</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
+ </row>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row rowsep="0">
+ <entry>char</entry>
+ <entry>data.b[20]</entry>
+ <entry>(read/write DATA : MAX 20 byte)
+<footnote><para>If the data is smaller
+than 20 bytes, all data other than available data must be 0.
+</para></footnote>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+<emphasis role="bold">Property</emphasis>
+</para>
+
+<para>
+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.
+</para>
+
+<itemizedlist>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+The arguments of the XChangeProperty are as follows:
+</para>
+
+
+<table frame="none" id="xchangeproperty_events_format">
+ <title>The XChangeProperty event's format</title>
+ <tgroup cols="3">
+ <colspec colname="col1" colwidth="1*" colsep="0"/>
+ <colspec colname="col2" colwidth="1*" colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*" colsep="0"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
+ <thead>
+ <row>
+ <entry align="left" spanname="span-horiz">Argument</entry>
+ <entry align="left">Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row rowsep="0">
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS communication window ID</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Atom</entry>
+ <entry>property</entry>
+ <entry>read/write property Atom (*1)</entry>
+ </row>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>mode</entry>
+ <entry>PropModeAppend</entry>
+ </row>
+ <row rowsep="0">
+ <entry>u_char</entry>
+ <entry>*data</entry>
+ <entry>read/write DATA</entry>
+ </row>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>nelements</entry>
+ <entry>length of DATA</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+(*1) The read/write property ATOM allocates the following strings by
+<function>XInternAtom</function>.
+"_clientXXX"
+</para>
+
+<para>
+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).
+</para>
+
+<para>
+If Atom is notified via ClientMessage event, the format of the ClientMessage
+is as follows:
+</para>
+
+<table frame="none" id="clientmessage_events_format_to_send_atom_of_property">
+ <title>The ClientMessage event's format to send Atom of property</title>
+ <tgroup cols="3">
+ <colspec colname="col1" colwidth="1*" colsep="0"/>
+ <colspec colname="col2" colwidth="1*" colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*" colsep="0"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
+ <thead>
+ <row>
+ <entry align="left" spanname="span-horiz">Structure Member</entry>
+ <entry align="left">Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row rowsep="0">
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS Window ID</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
+ </row>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row rowsep="0">
+ <entry>long</entry>
+ <entry>data.1[0]</entry>
+ <entry>length of read/write property Atom</entry>
+ </row>
+ <row rowsep="0">
+ <entry>long</entry>
+ <entry>data.1[1]</entry>
+ <entry>read/write property Atom</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+</sect4>
+
+<sect4 id="Format_for_the_data_from_the_IM_Server_to_the_Client">
+<title>Format for the data from the IM Server to the Client</title>
+<para>
+<emphasis role="bold">ClientMessage</emphasis>
+</para>
+
+<para>
+The format of the ClientMessage is as follows:
+</para>
+
+<table frame="none" id="clientmessage_events_format_first_or_middle_2">
+ <title>The ClientMessage event's format (first or middle)</title>
+ <tgroup cols="3">
+ <colspec colname="col1" colwidth="1*" colsep="0"/>
+ <colspec colname="col2" colwidth="1*" colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*" colsep="0"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
+ <thead>
+ <row>
+ <entry align="left" spanname="span-horiz">Structure Member</entry>
+ <entry align="left">Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row rowsep="0">
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS Window ID</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_MOREDATA", False)</entry>
+ </row>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row rowsep="0">
+ <entry>char</entry>
+ <entry>data.b[20]</entry>
+ <entry>(read/write DATA : 20 byte)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+
+
+
+
+<table frame="none" id="clientmessage_events_format_only_or_last_2">
+ <title>The ClientMessage event's format (only or last)</title>
+ <tgroup cols="3">
+ <colspec colname="col1" colwidth="1*" colsep="0"/>
+ <colspec colname="col2" colwidth="1*" colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*" colsep="0"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
+ <thead>
+ <row>
+ <entry align="left" spanname="span-horiz">Structure Member</entry>
+ <entry align="left">Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row rowsep="0">
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS Window ID</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
+ </row>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row rowsep="0">
+ <entry>char</entry>
+ <entry>data.b[20]</entry>
+ <entry>(read/write DATA : MAX 20 byte) (*1)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+(*1) If the data size is smaller than 20 bytes, all data other than available
+data must be 0.
+</para>
+
+<para>
+<emphasis role="bold">Property</emphasis>
+</para>
+
+<para>
+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.
+</para>
+
+<itemizedlist>
+ <listitem>
+ <para>
+The XChangeProperty function is used to store data in the IMS
+communication window, and Atom of the property is sent via the
+ClientMessage event.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The XChangeProperty function is used to store data in the IMS
+communication window, and Atom of the property is sent via
+PropertyNotify event.
+ </para>
+ </listitem>
+</itemizedlist>
+
+<para>
+The arguments of the XChangeProperty are as follows:
+</para>
+
+<table frame="none" id="xchangeproperty_events_format_b">
+ <title>The XChangeProperty event's format</title>
+ <tgroup cols="3">
+ <colspec colname="col1" colwidth="1*" colsep="0"/>
+ <colspec colname="col2" colwidth="1*" colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*" colsep="0"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
+ <thead>
+ <row>
+ <entry align="left" spanname="span-horiz">Argument</entry>
+ <entry align="left">Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row rowsep="0">
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS communication window ID</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Atom</entry>
+ <entry>property</entry>
+ <entry>read/write property Atom (*1)</entry>
+ </row>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>mode</entry>
+ <entry>PropModeAppend</entry>
+ </row>
+ <row rowsep="0">
+ <entry>u_char</entry>
+ <entry>*data</entry>
+ <entry>read/write DATA</entry>
+ </row>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>nelements</entry>
+ <entry>length of DATA</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+(*1) The read/write property ATOM allocates some strings, which are not
+allocated by the client, by <function>XInternAtom</function>.
+</para>
+
+<para>
+The IM Server changes the property with the mode of PropModeAppend and
+the client reads it with the delete mode, i.e. (delete = True).
+</para>
+
+<para>
+If Atom is notified via ClientMessage event, the format of the ClientMessage
+is as follows:
+</para>
+
+<table frame="none" id="clientmessage_events_format_to_send_atom_of_property_2">
+ <title>The ClientMessage event's format to send Atom of property</title>
+ <tgroup cols="3">
+ <colspec colname="col1" colwidth="1*" colsep="0"/>
+ <colspec colname="col2" colwidth="1*" colsep="1"/>
+ <colspec colname="col3" colwidth="3.5*" colsep="0"/>
+ <spanspec namest="col1" nameend="col2" spanname="span-horiz" align="left"/>
+ <thead>
+ <row>
+ <entry align="left" spanname="span-horiz">Structure Member</entry>
+ <entry align="left">Contents</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>type</entry>
+ <entry>ClientMessage</entry>
+ </row>
+ <row rowsep="0">
+ <entry>u_long</entry>
+ <entry>serial</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Bool</entry>
+ <entry>send_event</entry>
+ <entry>Set by the X Window System</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Display</entry>
+ <entry>*display</entry>
+ <entry>The display to which connects</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Window</entry>
+ <entry>window</entry>
+ <entry>IMS Window ID</entry>
+ </row>
+ <row rowsep="0">
+ <entry>Atom</entry>
+ <entry>message_type</entry>
+ <entry>XInternAtom(display, "_XIM_PROTOCOL", False)</entry>
+ </row>
+ <row rowsep="0">
+ <entry>int</entry>
+ <entry>format</entry>
+ <entry>8</entry>
+ </row>
+ <row rowsep="0">
+ <entry>long</entry>
+ <entry>data.1[0]</entry>
+ <entry>length of read/write property Atom</entry>
+ </row>
+ <row rowsep="0">
+ <entry>long</entry>
+ <entry>data.1[1]</entry>
+ <entry>read/write property Atom</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+</sect4>
+</sect3>
+<sect3 id="Closing_Connection">
+<title>Closing Connection</title>
+
+<para>
+If the client disconnect with the IM Server, shutdown function should
+free the communication window properties and etc..
+</para>
+
+</sect3>
+</sect2>
+</sect1>
+
+<sect1 id="References">
+<title>References</title>
+<para>
+[1] Masahiko Narita and Hideki Hiura, <emphasis remap='I'>"The Input Method Protocol"</emphasis>
+</para>
+</sect1>
+
+</chapter>
+</book>
diff --git a/libX11/specs/libX11/CH02.xml b/libX11/specs/libX11/CH02.xml index f4ef1bcd8..4912f71ed 100644 --- a/libX11/specs/libX11/CH02.xml +++ b/libX11/specs/libX11/CH02.xml @@ -1,3489 +1,3489 @@ -<?xml version="1.0" encoding="UTF-8" ?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" - "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> -<chapter id="display_functions"> -<title>Display Functions</title> -<para> -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: -</para> -<itemizedlist> - <listitem> - <para> -Open (connect to) the display - </para> - </listitem> - <listitem> - <para> -Obtain information about the display, image formats, or screens - </para> - </listitem> - <listitem> - <para> -Generate a -<systemitem>NoOperation</systemitem> -protocol request - </para> - </listitem> - <listitem> - <para> -Free client-created data - </para> - </listitem> - <listitem> - <para> -Close (disconnect from) a display - </para> - </listitem> - <listitem> - <para> -Use X Server connection close operations - </para> - </listitem> - <listitem> - <para> -Use Xlib with threads - </para> - </listitem> - <listitem> - <para> -Use internal connections - </para> - </listitem> -</itemizedlist> -<sect1 id="Opening_the_Display"> -<title>Opening the Display</title> -<!-- .XS --> -<!-- (SN Opening the Display --> -<!-- .XE --> -<para> -<!-- .LP --> -To open a connection to the X server that controls a display, use -<function>XOpenDisplay</function>. -<indexterm significance="preferred"><primary>XOpenDisplay</primary></indexterm> -</para> -<funcsynopsis> -<funcprototype> - <funcdef>Display *<function>XOpenDisplay</function></funcdef> - <paramdef>char *<parameter>display_name</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display_name</emphasis> - </term> - <listitem> - <para> -Specifies the hardware display name, which determines the display -and communications domain to be used. -On a <acronym>POSIX</acronym>-conformant system, if the display_name is NULL, -it defaults to the value of the DISPLAY environment variable. -<indexterm><primary>Environment</primary><secondary>DISPLAY</secondary></indexterm> - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .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 <acronym>POSIX</acronym>-conformant systems, -the display name or DISPLAY environment variable can be a string in the format: -</para> -<!-- .LP --> -<!-- .sM --> -<literallayout class="monospaced"> -<!-- .TA 1i --> -<!-- .ta 1i --> - <emphasis remap='I'>protocol</emphasis>/<emphasis remap='I'>hostname</emphasis>:<emphasis remap='I'>number</emphasis>.<emphasis remap='I'>screen_number</emphasis> -</literallayout> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>protocol</emphasis> - </term> - <listitem> - <para> -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. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>hostname</emphasis> - </term> - <listitem> - <para> -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 (::). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>number</emphasis> - </term> - <listitem> - <para> -Specifies the number of the display server on that host machine. -You may optionally follow this display number with a period (.). -A single <acronym>CPU</acronym> can have more than one display. -Multiple displays are usually numbered starting with zero. -<indexterm><primary>Screen</primary></indexterm> - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>screen_number</emphasis> - </term> - <listitem> - <para> -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 -<function>DefaultScreen</function> -macro or the -<function>XDefaultScreen</function> -function if you are using languages other than C (see section 2.2.1). - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -For example, the following would specify screen 1 of display 0 on the -machine named ``dual-headed'': -</para> -<para> -<!-- .LP --> -<literallayout class="monospaced"> -dual-headed:0.1 -</literallayout> -</para> -<para> -<!-- .LP --> -The -<function>XOpenDisplay</function> -function returns a -<type>Display</type> -structure that serves as the -connection to the X server and that contains all the information -about that X server. -<function>XOpenDisplay</function> -connects your application to the X server through <acronym>TCP</acronym> -or DECnet communications protocols, -or through some local inter-process communication protocol. -<indexterm><primary>Protocol</primary><secondary><acronym>TCP</acronym></secondary></indexterm> -<indexterm><primary>Protocol</primary><secondary>DECnet</secondary></indexterm> -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, -<function>XOpenDisplay</function> -connects using <acronym>TCP</acronym> streams. (If the protocol is specified as "inet", <acronym>TCP</acronym> over -IPv4 is used. If the protocol is specified as "inet6", <acronym>TCP</acronym> over IPv6 is used. -Otherwise, the implementation determines which <acronym>IP</acronym> 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, -<function>XOpenDisplay</function> -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. -</para> -<para> -<!-- .LP --> -<indexterm><primary>Display</primary></indexterm> -If successful, -<function>XOpenDisplay</function> -returns a pointer to a -<type>Display</type> -structure, -which is defined in -<filename class="headerfile"><X11/Xlib.h></filename>. -<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm> -<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm> -<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm> -If -<function>XOpenDisplay</function> -does not succeed, it returns NULL. -After a successful call to -<function>XOpenDisplay</function>, -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 -<function>DefaultScreen</function> -macro (or the -<function>XDefaultScreen</function> -function). -You can access elements of the -<type>Display</type> -and -<type>Screen</type> -structures only by using the information macros or functions. -For information about using macros and functions to obtain information from -the -<type>Display</type> -structure, -see section 2.2.1. -</para> -<para> -<!-- .LP --> -X servers may implement various types of access control mechanisms -(see section 9.8). -</para> -</sect1> -<sect1 id="Obtaining_Information_about_the_Display_Image_Formats_or_Screens"> -<title>Obtaining Information about the Display, Image Formats, or Screens</title> -<!-- .XS --> -<!-- (SN Obtaining Information about the Display, Image Formats, or Screens --> -<!-- .XE --> -<para> -<!-- .LP --> -The Xlib library provides a number of useful macros -and corresponding functions that return data from the -<type>Display</type> -structure. -The macros are used for C programming, -and their corresponding function equivalents are for other language bindings. -This section discusses the: -</para> -<itemizedlist> - <listitem> - <para> -Display macros - </para> - </listitem> - <listitem> - <para> -Image format functions and macros - </para> - </listitem> - <listitem> - <para> -Screen information macros - </para> - </listitem> -</itemizedlist> -<para> -<!-- .LP --> -<indexterm ><primary>Display</primary><secondary>data structure</secondary></indexterm> -All other members of the -<type>Display</type> -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 -<type>Display</type> -structure. -<!-- .NT Note --> -The -<function>XDisplayWidth</function>, -<function>XDisplayHeight</function>, -<function>XDisplayCells</function>, -<function>XDisplayPlanes</function>, -<function>XDisplayWidthMM</function>, -and -<function>XDisplayHeightMM</function> -functions in the next sections are misnamed. -These functions really should be named Screen<emphasis remap='I'>whatever</emphasis> -and XScreen<emphasis remap='I'>whatever</emphasis>, not Display<emphasis remap='I'>whatever</emphasis> or XDisplay<emphasis remap='I'>whatever</emphasis>. -Our apologies for the resulting confusion. -<!-- .NE --> -</para> -<sect2 id="Display_Macros_"> -<title>Display Macros </title> -<!-- .XS --> -<!-- (SN Display Macros --> -<!-- .XE --> -<para> -<!-- .LP --> -Applications should not directly modify any part of the -<type>Display</type> -and -<type>Screen</type> -structures. -The members should be considered read-only, -although they may change as the result of other operations on the display. -</para> -<para> -<!-- .LP --> -The following lists the C language macros, -their corresponding function equivalents that are for other language bindings, -and what data both can return. -</para> -<para>AllPlanes()</para> -<para>XAllPlanes()</para> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>AllPlanes</primary></indexterm> -<indexterm significance="preferred"><primary>XAllPlanes</primary></indexterm> -Both return a value with all bits set to 1 suitable for use in a plane argument to -a procedure. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -Both -<function>BlackPixel</function> -and -<function>WhitePixel</function> -can be used in implementing a monochrome application. -These pixel values are for permanently allocated entries in the default -colormap. -The actual <acronym>RGB</acronym> (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 --> -</para> -<para> -BlackPixel(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>unsigned long <function>XBlackPixel</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>int<parameter> screen_number</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>screen_number</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate screen number on the host server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>BlackPixel</primary></indexterm> -<indexterm significance="preferred"><primary>XBlackPixel</primary></indexterm> -Both return the black pixel value for the specified screen. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -WhitePixel(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>unsigned long <function>XWhitePixel</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>int<parameter> screen_number</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>screen_number</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate screen number on the host server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>WhitePixel</primary></indexterm> -<indexterm significance="preferred"><primary>XWhitePixel</primary></indexterm> -Both return the white pixel value for the specified screen. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -ConnectionNumber(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XConnectionNumber</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> - -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>ConnectionNumber</primary></indexterm> -<indexterm significance="preferred"><primary>XConnectionNumber</primary></indexterm> -Both return a connection number for the specified display. -On a <acronym>POSIX</acronym>-conformant system, -this is the file descriptor of the connection. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DefaultColormap(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>Colormap <function>XDefaultColormap</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>int<parameter> screen_number</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>screen_number</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate screen number on the host server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DefaultColormap</primary></indexterm> -<indexterm significance="preferred"><primary>XDefaultColormap</primary></indexterm> -Both return the default colormap ID for allocation on the specified screen. -Most routine allocations of color should be made out of this colormap. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DefaultDepth(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XDefaultDepth</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>int<parameter> screen_number</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>screen_number</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate screen number on the host server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DefaultDepth</primary></indexterm> -<indexterm significance="preferred"><primary>XDefaultDepth</primary></indexterm> -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 -<function>XMatchVisualInfo</function>). -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<indexterm significance="preferred"><primary>XListDepths</primary></indexterm> -To determine the number of depths that are available on a given screen, use -<function>XListDepths</function>. -<!-- .sM --> -</para> -<para> -DefaultGC(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>GC <function>XDefaultGC</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>int<parameter> screen_number</parameter></paramdef> - <paramdef>int<parameter> *count_return</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>screen_number</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate screen number on the host server. -<!-- .ds Cn depths --> - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>count_return</emphasis> - </term> - <listitem> - <para> -Returns the number of (Cn. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -The -<function>XListDepths</function> -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, -<function>XListDepths</function> -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 -<function>XFree</function>. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DefaultGC(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>GC <function>XDefaultGC</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>int<parameter> screen_number</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>screen_number</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate screen number on the host server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DefaultGC</primary></indexterm> -<indexterm significance="preferred"><primary>XDefaultGC</primary></indexterm> -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. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DefaultRootWindow(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>Window <function>XDefaultRootWindow</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DefaultRootWindow</primary></indexterm> -<indexterm significance="preferred"><primary>XDefaultRootWindow</primary></indexterm> -Both return the root window for the default screen. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DefaultScreenOfDisplay(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>Screen *<function>XDefaultScreenOfDisplay</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DefaultScreenOfDisplay</primary></indexterm> -<indexterm significance="preferred"><primary>XDefaultScreenOfDisplay</primary></indexterm> -Both return a pointer to the default screen. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -ScreenOfDisplay(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>Screen *<function>XScreenOfDisplay</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>int<parameter> screen_number</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>screen_number</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate screen number on the host server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>ScreenOfDisplay</primary></indexterm> -<indexterm significance="preferred"><primary>XScreenOfDisplay</primary></indexterm> -Both return a pointer to the indicated screen. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DefaultScreen(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XDefaultScreen</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DefaultScreen</primary></indexterm> -<indexterm significance="preferred"><primary>XDefaultScreen</primary></indexterm> -Both return the default screen number referenced by the -<function>XOpenDisplay</function> -function. -This macro or function should be used to retrieve the screen number -in applications that will use only a single screen. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DefaultVisual(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>Visual *<function>XDefaultVisual</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>int<parameter> screen_number</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>screen_number</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate screen number on the host server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DefaultVisual</primary></indexterm> -<indexterm significance="preferred"><primary>XDefaultVisual</primary></indexterm> -Both return the default visual type for the specified screen. -For further information about visual types, -see section 3.1. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DisplayCells(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XDisplayCells</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>int<parameter> screen_number</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>screen_number</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate screen number on the host server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DisplayCells</primary></indexterm> -<indexterm significance="preferred"><primary>XDisplayCells</primary></indexterm> -Both return the number of entries in the default colormap. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DisplayPlanes(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XDisplayPlanes</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>int<parameter> screen_number</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>screen_number</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate screen number on the host server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DisplayPlanes</primary></indexterm> -<indexterm significance="preferred"><primary>XDisplayPlanes</primary></indexterm> -Both return the depth of the root window of the specified screen. -For an explanation of depth, -see the glossary. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DisplayString(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>char *<function>XDisplayString</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DisplayString</primary></indexterm> -<indexterm significance="preferred"><primary>XDisplayString</primary></indexterm> -Both return the string that was passed to -<function>XOpenDisplay</function> -when the current display was opened. -On <acronym>POSIX</acronym>-conformant systems, -if the passed string was NULL, these return the value of -the DISPLAY environment variable when the current display was opened. -<indexterm><primary><acronym>POSIX</acronym> System Call</primary><secondary>fork</secondary></indexterm> -These are useful to applications that invoke the -<function>fork</function> -system call and want to open a new connection to the same display from the -child process as well as for printing error messages. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -LastKnownRequestProcessed(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>unsigned long <function>XLastKnownRequestProcessed</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>XExtendedMaxRequestSize</primary></indexterm> -The -<function>XExtendedMaxRequestSize</function> -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 -<function>XDrawLines</function>, -<function>XDrawArcs</function>, -<function>XFillPolygon</function>, -<function>XChangeProperty</function>, -<function>XSetClipRectangles</function>, -and -<function>XSetRegion</function> -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, -<function>XDrawPoints</function>, -<function>XDrawRectangles</function>, -<function>XDrawSegments</function>, -<function>XFillArcs</function>, -<function>XFillRectangles</function>, -<function>XPutImage</function>) -is permitted but not required; an Xlib implementation may choose to -split the data across multiple smaller requests instead. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -LastKnownRequestProcessed(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>unsigned long <function>XLastKnownRequestProcessed</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>XMaxRequestSize</primary></indexterm> -The -<function>XMaxRequestSize</function> -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: -<function>XDrawPoints</function>, -<function>XDrawRectangles</function>, -<function>XDrawSegments</function>, -<function>XFillArcs</function>, -<function>XFillRectangles</function>, -and -<function>XPutImage</function>. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -LastKnownRequestProcessed(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>unsigned long <function>XLastKnownRequestProcessed</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>LastKnownRequestProcessed</primary></indexterm> -<indexterm significance="preferred"><primary>XLastKnownRequestProcessed</primary></indexterm> -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. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -NextRequest(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>unsigned long <function>XNextRequest</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>NextRequest</primary></indexterm> -<indexterm significance="preferred"><primary>XNextRequest</primary></indexterm> -Both extract the full serial number that is to be used for the next -request. -Serial numbers are maintained separately for each display connection. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -ProtocolVersion(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XProtocolVersion</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>ProtocolVersion</primary></indexterm> -<indexterm significance="preferred"><primary>XProtocolVersion</primary></indexterm> -Both return the major version number (11) of the X protocol associated with -the connected display. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -ProtocolRevision(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XProtocolRevision</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>ProtocolRevision</primary></indexterm> -<indexterm significance="preferred"><primary>XProtocolRevision</primary></indexterm> -Both return the minor protocol revision number of the X server. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -QLength(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XQLength</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>QLength</primary></indexterm> -<indexterm significance="preferred"><primary>XQLength</primary></indexterm> -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 -<function>XEventsQueued</function>). -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -RootWindow(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>Window <function>XRootWindow</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>int<parameter> screen_number</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>screen_number</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate screen number on the host server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm><primary>Window</primary><secondary>RootWindow</secondary></indexterm> -<indexterm significance="preferred"><primary>RootWindow</primary></indexterm> -<indexterm><primary>Window</primary><secondary>XRootWindow</secondary></indexterm> -<indexterm significance="preferred"><primary>XRootWindow</primary></indexterm> -Both return the root window. -These are useful with functions that need a drawable of a particular screen -and for creating top-level windows. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -ScreenCount(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XScreenCount</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>ScreenCount</primary></indexterm> -<indexterm significance="preferred"><primary>XScreenCount</primary></indexterm> -Both return the number of available screens. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -ServerVendor(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>char *<function>XServerVendor</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>ServerVendor</primary></indexterm> -<indexterm significance="preferred"><primary>XServerVendor</primary></indexterm> -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. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -VendorRelease(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XVendorRelease</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>VendorRelease</primary></indexterm> -<indexterm significance="preferred"><primary>XVendorRelease</primary></indexterm> -Both return a number related to a vendor's release of the X server. -</para> -</sect2> -<sect2 id="Image_Format_Functions_and_Macros"> -<title>Image Format Functions and Macros</title> -<!-- .XS --> -<!-- (SN Image Format Functions and Macros --> -<!-- .XE --> -<para> -<!-- .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). -</para> -<para> -<!-- .LP --> -The -<structname>XPixmapFormatValues</structname> -structure provides an interface to the pixmap format information -that is returned at the time of a connection setup. -It contains: -</para> -<para> -<!-- .LP --> -<!-- .sM --> -<literallayout class="monospaced"> -<!-- .TA .5i 3i --> -<!-- .ta .5i 3i --> -typedef struct { - int depth; - int bits_per_pixel; - int scanline_pad; -} XPixmapFormatValues; -</literallayout> -</para> -<para> -<!-- .LP --> -<!-- .eM --> -<!-- .sp --> -To obtain the pixmap format information for a given display, use -<function>XListPixmapFormats</function>. -<indexterm significance="preferred"><primary>XListPixmapFormats</primary></indexterm> -<!-- .sM --> -</para> -<para> -ImageByteOrder(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XImageByteOrder</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>int<parameter> *count_return</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. -<!-- .ds Cn pixmap formats that are supported by the display --> - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>count_return</emphasis> - </term> - <listitem> - <para> -Returns the number of (Cn. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -The -<function>XListPixmapFormats</function> -function returns an array of -<structname>XPixmapFormatValues</structname> -structures that describe the types of Z format images supported -by the specified display. -If insufficient memory is available, -<function>XListPixmapFormats</function> -returns NULL. -To free the allocated storage for the -<structname>XPixmapFormatValues</structname> -structures, use -<function>XFree</function>. -</para> -<para> -<!-- .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. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -ImageByteOrder(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XImageByteOrder</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>ImageByteOrder</primary></indexterm> -<indexterm significance="preferred"><primary>XImageByteOrder</primary></indexterm> -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 -<symbol>LSBFirst</symbol> -or -<symbol>MSBFirst</symbol>. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -BitmapUnit(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XBitmapUnit</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>BitmapUnit</primary></indexterm> -<indexterm significance="preferred"><primary>XBitmapUnit</primary></indexterm> -Both return the size of a bitmap's scanline unit in bits. -The scanline is calculated in multiples of this value. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -BitmapBitOrder(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XBitmapBitOrder</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>BitmapBitOrder</primary></indexterm> -<indexterm significance="preferred"><primary>XBitmapBitOrder</primary></indexterm> -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 -<symbol>LSBFirst</symbol> -or -<symbol>MSBFirst</symbol>. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -BitmapPad(<emphasis remap='I'>display</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XBitmapPad</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>BitmapPad</primary></indexterm> -<indexterm significance="preferred"><primary>XBitmapPad</primary></indexterm> -Each scanline must be padded to a multiple of bits returned -by this macro or function. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DisplayHeight(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XDisplayHeight</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>int<parameter> screen_number</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>screen_number</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate screen number on the host server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DisplayHeight</primary></indexterm> -<indexterm significance="preferred"><primary>XDisplayHeight</primary></indexterm> -Both return an integer that describes the height of the screen -in pixels. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DisplayHeightMM(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XDisplayHeightMM</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>int<parameter> screen_number</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>screen_number</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate screen number on the host server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DisplayHeightMM</primary></indexterm> -<indexterm significance="preferred"><primary>XDisplayHeightMM</primary></indexterm> -Both return the height of the specified screen in millimeters. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DisplayWidth(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XDisplayWidth</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>int<parameter> screen_number</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>screen_number</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate screen number on the host server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DisplayWidth</primary></indexterm> -<indexterm significance="preferred"><primary>XDisplayWidth</primary></indexterm> -Both return the width of the screen in pixels. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DisplayWidthMM(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XDisplayWidthMM</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>int<parameter> screen_number</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>screen_number</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate screen number on the host server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DisplayWidthMM</primary></indexterm> -<indexterm significance="preferred"><primary>XDisplayWidthMM</primary></indexterm> -Both return the width of the specified screen in millimeters. -</para> -</sect2> -<sect2 id="Screen_Information_Macros"> -<title>Screen Information Macros</title> -<!-- .XS --> -<!-- (SN Screen Information Macros --> -<!-- .XE --> -<para> -<!-- .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. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -BlackPixelOfScreen(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>unsigned long <function>XBlackPixelOfScreen</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>BlackPixelOfScreen</primary></indexterm> -<indexterm significance="preferred"><primary>XBlackPixelOfScreen</primary></indexterm> -Both return the black pixel value of the specified screen. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -WhitePixelOfScreen(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>unsigned long <function>XWhitePixelOfScreen</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>WhitePixelOfScreen</primary></indexterm> -<indexterm significance="preferred"><primary>XWhitePixelOfScreen</primary></indexterm> -Both return the white pixel value of the specified screen. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -CellsOfScreen(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XCellsOfScreen</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>CellsOfScreen</primary></indexterm> -<indexterm significance="preferred"><primary>XCellsOfScreen</primary></indexterm> -Both return the number of colormap cells in the default colormap -of the specified screen. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DefaultColormapOfScreen(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>Colormap <function>XDefaultColormapOfScreen</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DefaultColormapOfScreen</primary></indexterm> -<indexterm significance="preferred"><primary>XDefaultColormapOfScreen</primary></indexterm> -Both return the default colormap of the specified screen. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DefaultDepthOfScreen(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XDefaultDepthOfScreen</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DefaultDepthOfScreen</primary></indexterm> -<indexterm significance="preferred"><primary>XDefaultDepthOfScreen</primary></indexterm> -Both return the depth of the root window. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DefaultGCOfScreen(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>GC <function>XDefaultGCOfScreen</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DefaultGCOfScreen</primary></indexterm> -<indexterm significance="preferred"><primary>XDefaultGCOfScreen</primary></indexterm> -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. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DefaultVisualOfScreen(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>Visual *<function>XDefaultVisualOfScreen</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DefaultVisualOfScreen</primary></indexterm> -<indexterm significance="preferred"><primary>XDefaultVisualOfScreen</primary></indexterm> -Both return the default visual of the specified screen. -For information on visual types, -see section 3.1. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DoesBackingStore(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XDoesBackingStore</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DoesBackingStore</primary></indexterm> -<indexterm significance="preferred"><primary>XDoesBackingStore</primary></indexterm> -Both return a value indicating whether the screen supports backing -stores. -The value returned can be one of -<symbol>WhenMapped</symbol>, -<symbol>NotUseful</symbol>, -or -<symbol>Always</symbol> -(see section 3.2.4). -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DoesSaveUnders(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>Bool <function>XDoesSaveUnders</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DoesSaveUnders</primary></indexterm> -<indexterm significance="preferred"><primary>XDoesSaveUnders</primary></indexterm> -Both return a Boolean value indicating whether the -screen supports save unders. -If -<symbol>True</symbol>, -the screen supports save unders. -If -<symbol>False</symbol>, -the screen does not support save unders (see section 3.2.5). -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -DisplayOfScreen(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>Display *<function>XDisplayOfScreen</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>DisplayOfScreen</primary></indexterm> -<indexterm significance="preferred"><primary>XDisplayOfScreen</primary></indexterm> -Both return the display of the specified screen. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -<indexterm significance="preferred"><primary>XScreenNumberOfScreen</primary></indexterm> -</para> -<para> -EventMaskOfScreen(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>long <function>XEventMaskOfScreen</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -The -<function>XScreenNumberOfScreen</function> -function returns the screen index number of the specified screen. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -EventMaskOfScreen(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>long <function>XEventMaskOfScreen</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>EventMaskOfScreen</primary></indexterm> -<indexterm significance="preferred"><primary>XEventMaskOfScreen</primary></indexterm> -Both return the event mask of the root window for the specified screen -at connection setup time. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -WidthOfScreen(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XWidthOfScreen</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>WidthOfScreen</primary></indexterm> -<indexterm significance="preferred"><primary>XWidthOfScreen</primary></indexterm> -Both return the width of the specified screen in pixels. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -HeightOfScreen(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XHeightOfScreen</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>HeightOfScreen</primary></indexterm> -<indexterm significance="preferred"><primary>XHeightOfScreen</primary></indexterm> -Both return the height of the specified screen in pixels. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -WidthMMOfScreen(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XWidthMMOfScreen</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>WidthMMOfScreen</primary></indexterm> -<indexterm significance="preferred"><primary>XWidthMMOfScreen</primary></indexterm> -Both return the width of the specified screen in millimeters. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -HeightMMOfScreen(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XHeightMMOfScreen</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>HeightMMOfScreen</primary></indexterm> -<indexterm significance="preferred"><primary>XHeightMMOfScreen</primary></indexterm> -Both return the height of the specified screen in millimeters. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -MaxCmapsOfScreen(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XMaxCmapsOfScreen</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>MaxCmapsOfScreen</primary></indexterm> -<indexterm significance="preferred"><primary>XMaxCmapsOfScreen</primary></indexterm> -Both return the maximum number of installed colormaps supported -by the specified screen (see section 9.3). -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -MinCmapsOfScreen(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XMinCmapsOfScreen</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>MinCmapsOfScreen</primary></indexterm> -<indexterm significance="preferred"><primary>XMinCmapsOfScreen</primary></indexterm> -Both return the minimum number of installed colormaps supported -by the specified screen (see section 9.3). -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -PlanesOfScreen(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>int <function>XPlanesOfScreen</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>PlanesOfScreen</primary></indexterm> -<indexterm significance="preferred"><primary>XPlanesOfScreen</primary></indexterm> -Both return the depth of the root window. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -<!-- .sM --> -</para> -<para> -RootWindowOfScreen(<emphasis remap='I'>screen</emphasis>) -</para> -<funcsynopsis> -<funcprototype> - <funcdef>Window <function>XRootWindowOfScreen</function></funcdef> - <paramdef>Screen<parameter> *screen</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>screen</emphasis> - </term> - <listitem> - <para> -Specifies the appropriate -<type>Screen</type> -structure. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -<indexterm significance="preferred"><primary>RootWindowOfScreen</primary></indexterm> -<indexterm significance="preferred"><primary>XRootWindowOfScreen</primary></indexterm> -Both return the root window of the specified screen. -</para> -</sect2> -</sect1> -<sect1 id="Generating_a_NoOperation_Protocol_Request"> -<title>Generating a NoOperation Protocol Request</title> -<!-- .XS --> -<!-- (SN Generating a NoOperation Protocol Request --> -<!-- .XE --> -<para> -<!-- .LP --> -To execute a -<systemitem>NoOperation</systemitem> -protocol request, use -<function>XNoOp</function>. -<indexterm significance="preferred"><primary>XNoOp</primary></indexterm> -<!-- .sM --> -</para> -<funcsynopsis> -<funcprototype> - <funcdef><function>XNoOp</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<variablelist> - <varlistentry> - <term><emphasis remap='I'>display</emphasis></term> - <listitem> - <para>Specifies the connection to the X server.</para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -The -<function>XNoOp</function> -function sends a -<systemitem>NoOperation</systemitem> -protocol request to the X server, -thereby exercising the connection. -</para> -</sect1> -<sect1 id="Freeing_Client_Created_Data"> -<title>Freeing Client-Created Data</title> -<!-- .XS --> -<!-- (SN Freeing Client-Created Data --> -<!-- .XE --> -<para> -<!-- .LP --> -To free in-memory data that was created by an Xlib function, use -<function>XFree</function>. -<indexterm significance="preferred"><primary>XFree</primary></indexterm> -<!-- .sM --> -</para> -<funcsynopsis> -<funcprototype> - <funcdef>XFree</funcdef> - <paramdef>void<parameter> *data</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>data</emphasis> - </term> - <listitem> - <para> -Specifies the data that is to be freed. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -The -<function>XFree</function> -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. -</para> -</sect1> -<sect1 id="Closing_the_Display"> -<title>Closing the Display</title> -<!-- .XS --> -<!-- (SN Closing the Display --> -<!-- .XE --> -<para> -<!-- .LP --> -To close a display or disconnect from the X server, use -<function>XCloseDisplay</function>. -<indexterm significance="preferred"><primary>XCloseDisplay</primary></indexterm> -</para> -<para> -<!-- .LP --> -<!-- .sM --> -</para> -<funcsynopsis> -<funcprototype> - <funcdef>XCloseDisplay</funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -The -<function>XCloseDisplay</function> -function closes the connection to the X server for the display specified in the -<type>Display</type> -structure and destroys all windows, resource IDs -(<type>Window</type>, -<type>Font</type>, -<type>Pixmap</type>, -<type>Colormap</type>, -<type>Cursor</type>, -and -<type>GContext</type>), -or other resources that the client has created -on this display, unless the close-down mode of the resource has been changed -(see -<function>XSetCloseDownMode</function>). -Therefore, these windows, resource IDs, and other resources should never be -referenced again or an error will be generated. -Before exiting, you should call -<function>XCloseDisplay</function> -explicitly so that any pending errors are reported as -<function>XCloseDisplay</function> -performs a final -<function>XSync</function> -operation. -<indexterm><primary>Resource IDs</primary></indexterm> -<indexterm><primary>XCloseDisplay</primary></indexterm> -</para> -<para> -<!-- .LP --> -<function>XCloseDisplay</function> -can generate a -<errorname>BadGC</errorname> -error. -<!-- .sp --> -</para> -<para> -<!-- .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 -<function>XSetCloseDownMode</function>. -<indexterm significance="preferred"><primary>XSetCloseDownMode</primary></indexterm> -<!-- .sM --> -</para> -<funcsynopsis> -<funcprototype> - <funcdef>XSetCloseDownMode</funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>int<parameter> close_mode</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>close_mode</emphasis> - </term> - <listitem> - <para> -Specifies the client close-down mode. -You can pass -<symbol>DestroyAll</symbol>, -<symbol>RetainPermanent</symbol>, -or -<symbol>RetainTemporary</symbol>. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -The -<function>XSetCloseDownMode</function> -defines what will happen to the client's resources at connection close. -A connection starts in -<symbol>DestroyAll</symbol> -mode. -For information on what happens to the client's resources when the -close_mode argument is -<symbol>RetainPermanent</symbol> -or -<symbol>RetainTemporary</symbol>, -see section 2.6. -</para> -<para> -<!-- .LP --> -<function>XSetCloseDownMode</function> -can generate a -<errorname>BadValue</errorname> -error. -</para> -</sect1> -<sect1 id="Using_X_Server_Connection_Close_Operations_"> -<title>Using X Server Connection Close Operations </title> -<!-- .XS --> -<!-- (SN Using X Server Connection Close Operations --> -<!-- .XE --> -<para> -<!-- .LP --> -When the X server's connection to a client is closed -either by an explicit call to -<function>XCloseDisplay</function> -or by a process that exits, the X server performs the following -automatic operations: -</para> -<itemizedlist> - <listitem> - <para> -It disowns all selections owned by the client -(see -<function>XSetSelectionOwner</function>). - </para> - </listitem> - <listitem> - <para> -It performs an -<function>XUngrabPointer</function> -and -<function>XUngrabKeyboard</function> -if the client has actively grabbed the pointer -or the keyboard. - </para> - </listitem> - <listitem> - <para> -It performs an -<function>XUngrabServer</function> -if the client has grabbed the server. - </para> - </listitem> - <listitem> - <para> -It releases all passive grabs made by the client. - </para> - </listitem> - <listitem> - <para> -It marks all resources (including colormap entries) allocated -by the client either as permanent or temporary, -depending on whether the close-down mode is -<symbol>RetainPermanent</symbol> -or -<symbol>RetainTemporary</symbol>. -However, this does not prevent other client applications from explicitly -destroying the resources (see -<function>XSetCloseDownMode</function>). - </para> - </listitem> -</itemizedlist> -<para> -<!-- .LP --> -When the close-down mode is -<symbol>DestroyAll</symbol>, -the X server destroys all of a client's resources as follows: -</para> -<itemizedlist> - <listitem> - <para> -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. - </para> - </listitem> - <listitem> - <para> -It performs a -<systemitem>MapWindow</systemitem> -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. - </para> - </listitem> - <listitem> - <para> -It destroys all windows created by the client. - </para> - </listitem> - <listitem> - <para> -It performs the appropriate free request on each nonwindow resource created by -the client in the server (for example, -<type>Font</type>, -<type>Pixmap</type>, -<type>Cursor</type>, -<type>Colormap</type>, -and -<type>GContext</type>). - </para> - </listitem> - <listitem> - <para> -It frees all colors and colormap entries allocated by a client application. - </para> - </listitem> -</itemizedlist> -<para> -<!-- .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 -<symbol>DestroyAll</symbol>, -the X server does the following: -</para> -<itemizedlist> - <listitem> - <para> -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 -<symbol>RetainPermanent</symbol> -or -<symbol>RetainTemporary</symbol> -mode. - </para> - </listitem> - <listitem> - <para> -It deletes all but the predefined atom identifiers. - </para> - </listitem> - <listitem> - <para> -It deletes all properties on all root windows (see section 4.3). - </para> - </listitem> - <listitem> - <para> -It resets all device maps and attributes -(for example, key click, bell volume, and acceleration) -as well as the access control list. - </para> - </listitem> - <listitem> - <para> -It restores the standard root tiles and cursors. - </para> - </listitem> - <listitem> - <para> -It restores the default font path. - </para> - </listitem> - <listitem> - <para> -It restores the input focus to state -<symbol>PointerRoot</symbol>. - </para> - </listitem> -</itemizedlist> -<para> -<!-- .LP --> -However, the X server does not reset if you close a connection with a close-down -mode set to -<symbol>RetainPermanent</symbol> -or -<symbol>RetainTemporary</symbol>. -</para> -</sect1> -<sect1 id="Using_Xlib_with_Threads"> -<title>Using Xlib with Threads</title> -<!-- .XS --> -<!-- (SN Using Xlib with Threads --> -<!-- .XE --> -<para> -<!-- .LP --> -On systems that have threads, support may be provided to permit -multiple threads to use Xlib concurrently. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -To initialize support for concurrent threads, use -<function>XInitThreads</function>. -<indexterm significance="preferred"><primary>XInitThreads</primary></indexterm> -<!-- .sM --> -</para> -<para>Status XInitThreads();</para> -<!-- .FN --> -<para> -<!-- .LP --> -<!-- .eM --> -The -<function>XInitThreads</function> -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. -</para> -<para> -<!-- .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. - -</para> -<para> -<!-- .LP --> -<!-- .sp --> -To lock a display across several Xlib calls, use -<function>XLockDisplay</function>. -<indexterm significance="preferred"><primary>XLockDisplay</primary></indexterm> -<!-- .sM --> -</para> -<funcsynopsis> -<funcprototype> - <funcdef>XLockDisplay</funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -The -<function>XLockDisplay</function> -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 -<function>XLockDisplay</function> -work correctly; the display will not actually be unlocked until -<function>XUnlockDisplay</function> -has been called the same number of times as -<function>XLockDisplay</function>. -This function has no effect unless Xlib was successfully initialized -for threads using -<function>XInitThreads</function>. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -To unlock a display, use -<function>XUnlockDisplay</function>. -<indexterm significance="preferred"><primary>XUnlockDisplay</primary></indexterm> -<!-- .sM --> -</para> -<funcsynopsis> -<funcprototype> - <funcdef>XUnlockDisplay</funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -The -<function>XUnlockDisplay</function> -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 -<function>XLockDisplay</function> -has been called multiple times by a thread, then -<function>XUnlockDisplay</function> -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 -<function>XInitThreads</function>. -</para> -</sect1> -<sect1 id="Using_Internal_Connections"> -<title>Using Internal Connections</title> -<!-- .XS --> -<!-- (SN Using Internal Connections --> -<!-- .XE --> -<para> -<!-- .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. -</para> -<para> -<!-- .LP --> -To track internal connections for a display, use -<function>XAddConnectionWatch</function>. -</para> -<funcsynopsis> -<funcprototype> - <funcdef>type void XConnectionWatchProc</funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>XPointer<parameter> client_data</parameter></paramdef> - <paramdef>int<parameter> fd</parameter></paramdef> - <paramdef>Bool<parameter> opening</parameter></paramdef> - <paramdef>XPointer<parameter> *watch_data</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<funcsynopsis> -<funcprototype> - <funcdef>Status XAddConnectionWatch</funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>XWatchProc<parameter> procedure</parameter></paramdef> - <paramdef>XPointer<parameter> client_data</parameter></paramdef> -</funcprototype> -</funcsynopsis> - -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>procedure</emphasis> - </term> - <listitem> - <para> -Specifies the procedure to be called. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>client_data</emphasis> - </term> - <listitem> - <para> -Specifies the additional client data. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -The -<function>XAddConnectionWatch</function> -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 -<symbol>True</symbol>, -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 -<symbol>False</symbol>, -the location pointed to by watch_data will hold this same private data pointer. -</para> -<para> -<!-- .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 -<function>XAddConnectionWatch</function> -returns. -<function>XAddConnectionWatch</function> -returns a nonzero status if the procedure is successfully registered; -otherwise, it returns zero. -</para> -<para> -<!-- .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 -<function>XLockDisplay</function>. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -To stop tracking internal connections for a display, use -<function>XRemoveConnectionWatch</function>. -<indexterm significance="preferred"><primary>XRemoveConnectionWatch</primary></indexterm> -<!-- .sM --> -</para> -<para> -() -</para> -<funcsynopsis> -<funcprototype> - <funcdef>Status <function>XRemoveConnectionWatch</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>XWatchProc<parameter> procedure</parameter></paramdef> - <paramdef>XPointer<parameter> client_data</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>procedure</emphasis> - </term> - <listitem> - <para> -Specifies the procedure to be called. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>client_data</emphasis> - </term> - <listitem> - <para> -Specifies the additional client data. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -The -<function>XRemoveConnectionWatch</function> -function removes a previously registered connection watch procedure. -The client_data must match the client_data used when the procedure -was initially registered. - -</para> -<para> -<!-- .LP --> -<!-- .sp --> -To process input on an internal connection, use -<function>XProcessInternalConnection</function>. -<indexterm significance="preferred"><primary>XProcessInternalConnection</primary></indexterm> -<!-- .sM --> -</para> -<para> -() -</para> -<funcsynopsis> -<funcprototype> - <funcdef>void <function>XProcessInternalConnection</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>int<parameter> fd</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>fd</emphasis> - </term> - <listitem> - <para> -Specifies the file descriptor. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -The -<function>XProcessInternalConnection</function> -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, -<function>select</function> -or -<function>poll</function>) -has indicated that input is available; otherwise, -the effect is not defined. -</para> -<para> -<!-- .LP --> -<!-- .sp --> -To obtain all of the current internal connections for a display, use -<function>XInternalConnectionNumbers</function>. -<indexterm significance="preferred"><primary>XInternalConnectionNumbers</primary></indexterm> -<!-- .sM --> -</para> -<para> -() -</para> -<funcsynopsis> -<funcprototype> - <funcdef>Status <function>XInternalConnectionNumbers</function></funcdef> - <paramdef>Display<parameter> *display</parameter></paramdef> - <paramdef>int **<parameter> fd</parameter></paramdef> - <paramdef>int *<parameter> count_return</parameter></paramdef> -</funcprototype> -</funcsynopsis> -<!-- .FN --> -<variablelist> - <varlistentry> - <term> - <emphasis remap='I'>display</emphasis> - </term> - <listitem> - <para> -Specifies the connection to the X server. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>fd_return</emphasis> - </term> - <listitem> - <para> -Returns the file descriptors. -<!-- .ds Cn file descriptors --> - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <emphasis remap='I'>count_return</emphasis> - </term> - <listitem> - <para> -Returns the number of (Cn. - </para> - </listitem> - </varlistentry> -</variablelist> -<para> -<!-- .LP --> -<!-- .eM --> -The -<function>XInternalConnectionNumbers</function> -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 -<function>XFree</function>. -This functions returns a nonzero status if the list is successfully allocated; -otherwise, it returns zero. -</para> -</sect1> -</chapter> +<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<chapter id="display_functions">
+<title>Display Functions</title>
+<para>
+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:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Open (connect to) the display
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Obtain information about the display, image formats, or screens
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Generate a
+<systemitem>NoOperation</systemitem>
+protocol request
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Free client-created data
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Close (disconnect from) a display
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Use X Server connection close operations
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Use Xlib with threads
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Use internal connections
+ </para>
+ </listitem>
+</itemizedlist>
+<sect1 id="Opening_the_Display">
+<title>Opening the Display</title>
+<!-- .XS -->
+<!-- (SN Opening the Display -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To open a connection to the X server that controls a display, use
+<function>XOpenDisplay</function>.
+<indexterm significance="preferred"><primary>XOpenDisplay</primary></indexterm>
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Display *<function>XOpenDisplay</function></funcdef>
+ <paramdef>char *<parameter>display_name</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the hardware display name, which determines the display
+and communications domain to be used.
+On a <acronym>POSIX</acronym>-conformant system, if the display_name is NULL,
+it defaults to the value of the DISPLAY environment variable.
+<indexterm><primary>Environment</primary><secondary>DISPLAY</secondary></indexterm>
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .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 <acronym>POSIX</acronym>-conformant systems,
+the display name or DISPLAY environment variable can be a string in the format:
+</para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA 1i -->
+<!-- .ta 1i -->
+ <emphasis remap='I'>protocol</emphasis>/<emphasis remap='I'>hostname</emphasis>:<emphasis remap='I'>number</emphasis>.<emphasis remap='I'>screen_number</emphasis>
+</literallayout>
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>protocol</emphasis>
+ </term>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hostname</emphasis>
+ </term>
+ <listitem>
+ <para>
+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 (::).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of the display server on that host machine.
+You may optionally follow this display number with a period (.).
+A single <acronym>CPU</acronym> can have more than one display.
+Multiple displays are usually numbered starting with zero.
+<indexterm><primary>Screen</primary></indexterm>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+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
+<function>DefaultScreen</function>
+macro or the
+<function>XDefaultScreen</function>
+function if you are using languages other than C (see section 2.2.1).
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+For example, the following would specify screen 1 of display 0 on the
+machine named ``dual-headed'':
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+dual-headed:0.1
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XOpenDisplay</function>
+function returns a
+<type>Display</type>
+structure that serves as the
+connection to the X server and that contains all the information
+about that X server.
+<function>XOpenDisplay</function>
+connects your application to the X server through <acronym>TCP</acronym>
+or DECnet communications protocols,
+or through some local inter-process communication protocol.
+<indexterm><primary>Protocol</primary><secondary><acronym>TCP</acronym></secondary></indexterm>
+<indexterm><primary>Protocol</primary><secondary>DECnet</secondary></indexterm>
+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,
+<function>XOpenDisplay</function>
+connects using <acronym>TCP</acronym> streams. (If the protocol is specified as "inet", <acronym>TCP</acronym> over
+IPv4 is used. If the protocol is specified as "inet6", <acronym>TCP</acronym> over IPv6 is used.
+Otherwise, the implementation determines which <acronym>IP</acronym> 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,
+<function>XOpenDisplay</function>
+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.
+</para>
+<para>
+<!-- .LP -->
+<indexterm><primary>Display</primary></indexterm>
+If successful,
+<function>XOpenDisplay</function>
+returns a pointer to a
+<type>Display</type>
+structure,
+which is defined in
+<filename class="headerfile"><X11/Xlib.h></filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm>
+If
+<function>XOpenDisplay</function>
+does not succeed, it returns NULL.
+After a successful call to
+<function>XOpenDisplay</function>,
+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
+<function>DefaultScreen</function>
+macro (or the
+<function>XDefaultScreen</function>
+function).
+You can access elements of the
+<type>Display</type>
+and
+<type>Screen</type>
+structures only by using the information macros or functions.
+For information about using macros and functions to obtain information from
+the
+<type>Display</type>
+structure,
+see section 2.2.1.
+</para>
+<para>
+<!-- .LP -->
+X servers may implement various types of access control mechanisms
+(see section 9.8).
+</para>
+</sect1>
+<sect1 id="Obtaining_Information_about_the_Display_Image_Formats_or_Screens">
+<title>Obtaining Information about the Display, Image Formats, or Screens</title>
+<!-- .XS -->
+<!-- (SN Obtaining Information about the Display, Image Formats, or Screens -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The Xlib library provides a number of useful macros
+and corresponding functions that return data from the
+<type>Display</type>
+structure.
+The macros are used for C programming,
+and their corresponding function equivalents are for other language bindings.
+This section discusses the:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Display macros
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Image format functions and macros
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Screen information macros
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<indexterm ><primary>Display</primary><secondary>data structure</secondary></indexterm>
+All other members of the
+<type>Display</type>
+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
+<type>Display</type>
+structure.
+<!-- .NT Note -->
+The
+<function>XDisplayWidth</function>,
+<function>XDisplayHeight</function>,
+<function>XDisplayCells</function>,
+<function>XDisplayPlanes</function>,
+<function>XDisplayWidthMM</function>,
+and
+<function>XDisplayHeightMM</function>
+functions in the next sections are misnamed.
+These functions really should be named Screen<emphasis remap='I'>whatever</emphasis>
+and XScreen<emphasis remap='I'>whatever</emphasis>, not Display<emphasis remap='I'>whatever</emphasis> or XDisplay<emphasis remap='I'>whatever</emphasis>.
+Our apologies for the resulting confusion.
+<!-- .NE -->
+</para>
+<sect2 id="Display_Macros_">
+<title>Display Macros </title>
+<!-- .XS -->
+<!-- (SN Display Macros -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Applications should not directly modify any part of the
+<type>Display</type>
+and
+<type>Screen</type>
+structures.
+The members should be considered read-only,
+although they may change as the result of other operations on the display.
+</para>
+<para>
+<!-- .LP -->
+The following lists the C language macros,
+their corresponding function equivalents that are for other language bindings,
+and what data both can return.
+</para>
+<para>AllPlanes()</para>
+<para>XAllPlanes()</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>AllPlanes</primary></indexterm>
+<indexterm significance="preferred"><primary>XAllPlanes</primary></indexterm>
+Both return a value with all bits set to 1 suitable for use in a plane argument to
+a procedure.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+Both
+<function>BlackPixel</function>
+and
+<function>WhitePixel</function>
+can be used in implementing a monochrome application.
+These pixel values are for permanently allocated entries in the default
+colormap.
+The actual <acronym>RGB</acronym> (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 -->
+</para>
+<para>
+BlackPixel(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned long <function>XBlackPixel</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>BlackPixel</primary></indexterm>
+<indexterm significance="preferred"><primary>XBlackPixel</primary></indexterm>
+Both return the black pixel value for the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+WhitePixel(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned long <function>XWhitePixel</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>WhitePixel</primary></indexterm>
+<indexterm significance="preferred"><primary>XWhitePixel</primary></indexterm>
+Both return the white pixel value for the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+ConnectionNumber(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XConnectionNumber</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ConnectionNumber</primary></indexterm>
+<indexterm significance="preferred"><primary>XConnectionNumber</primary></indexterm>
+Both return a connection number for the specified display.
+On a <acronym>POSIX</acronym>-conformant system,
+this is the file descriptor of the connection.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultColormap(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Colormap <function>XDefaultColormap</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultColormap</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultColormap</primary></indexterm>
+Both return the default colormap ID for allocation on the specified screen.
+Most routine allocations of color should be made out of this colormap.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultDepth(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XDefaultDepth</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultDepth</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultDepth</primary></indexterm>
+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
+<function>XMatchVisualInfo</function>).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XListDepths</primary></indexterm>
+To determine the number of depths that are available on a given screen, use
+<function>XListDepths</function>.
+<!-- .sM -->
+</para>
+<para>
+DefaultGC(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>GC <function>XDefaultGC</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+ <paramdef>int<parameter> *count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+<!-- .ds Cn depths -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XListDepths</function>
+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,
+<function>XListDepths</function>
+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
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultGC(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>GC <function>XDefaultGC</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultGC</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultGC</primary></indexterm>
+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.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultRootWindow(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Window <function>XDefaultRootWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultRootWindow</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultRootWindow</primary></indexterm>
+Both return the root window for the default screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultScreenOfDisplay(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Screen *<function>XDefaultScreenOfDisplay</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultScreenOfDisplay</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultScreenOfDisplay</primary></indexterm>
+Both return a pointer to the default screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+ScreenOfDisplay(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Screen *<function>XScreenOfDisplay</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ScreenOfDisplay</primary></indexterm>
+<indexterm significance="preferred"><primary>XScreenOfDisplay</primary></indexterm>
+Both return a pointer to the indicated screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultScreen(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XDefaultScreen</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultScreen</primary></indexterm>
+Both return the default screen number referenced by the
+<function>XOpenDisplay</function>
+function.
+This macro or function should be used to retrieve the screen number
+in applications that will use only a single screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultVisual(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Visual *<function>XDefaultVisual</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultVisual</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultVisual</primary></indexterm>
+Both return the default visual type for the specified screen.
+For further information about visual types,
+see section 3.1.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DisplayCells(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XDisplayCells</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DisplayCells</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayCells</primary></indexterm>
+Both return the number of entries in the default colormap.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DisplayPlanes(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XDisplayPlanes</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DisplayPlanes</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayPlanes</primary></indexterm>
+Both return the depth of the root window of the specified screen.
+For an explanation of depth,
+see the glossary.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DisplayString(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char *<function>XDisplayString</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DisplayString</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayString</primary></indexterm>
+Both return the string that was passed to
+<function>XOpenDisplay</function>
+when the current display was opened.
+On <acronym>POSIX</acronym>-conformant systems,
+if the passed string was NULL, these return the value of
+the DISPLAY environment variable when the current display was opened.
+<indexterm><primary><acronym>POSIX</acronym> System Call</primary><secondary>fork</secondary></indexterm>
+These are useful to applications that invoke the
+<function>fork</function>
+system call and want to open a new connection to the same display from the
+child process as well as for printing error messages.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+LastKnownRequestProcessed(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned long <function>XLastKnownRequestProcessed</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XExtendedMaxRequestSize</primary></indexterm>
+The
+<function>XExtendedMaxRequestSize</function>
+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
+<function>XDrawLines</function>,
+<function>XDrawArcs</function>,
+<function>XFillPolygon</function>,
+<function>XChangeProperty</function>,
+<function>XSetClipRectangles</function>,
+and
+<function>XSetRegion</function>
+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,
+<function>XDrawPoints</function>,
+<function>XDrawRectangles</function>,
+<function>XDrawSegments</function>,
+<function>XFillArcs</function>,
+<function>XFillRectangles</function>,
+<function>XPutImage</function>)
+is permitted but not required; an Xlib implementation may choose to
+split the data across multiple smaller requests instead.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+LastKnownRequestProcessed(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned long <function>XLastKnownRequestProcessed</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>XMaxRequestSize</primary></indexterm>
+The
+<function>XMaxRequestSize</function>
+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:
+<function>XDrawPoints</function>,
+<function>XDrawRectangles</function>,
+<function>XDrawSegments</function>,
+<function>XFillArcs</function>,
+<function>XFillRectangles</function>,
+and
+<function>XPutImage</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+LastKnownRequestProcessed(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned long <function>XLastKnownRequestProcessed</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>LastKnownRequestProcessed</primary></indexterm>
+<indexterm significance="preferred"><primary>XLastKnownRequestProcessed</primary></indexterm>
+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.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+NextRequest(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned long <function>XNextRequest</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>NextRequest</primary></indexterm>
+<indexterm significance="preferred"><primary>XNextRequest</primary></indexterm>
+Both extract the full serial number that is to be used for the next
+request.
+Serial numbers are maintained separately for each display connection.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+ProtocolVersion(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XProtocolVersion</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ProtocolVersion</primary></indexterm>
+<indexterm significance="preferred"><primary>XProtocolVersion</primary></indexterm>
+Both return the major version number (11) of the X protocol associated with
+the connected display.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+ProtocolRevision(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XProtocolRevision</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ProtocolRevision</primary></indexterm>
+<indexterm significance="preferred"><primary>XProtocolRevision</primary></indexterm>
+Both return the minor protocol revision number of the X server.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+QLength(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XQLength</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>QLength</primary></indexterm>
+<indexterm significance="preferred"><primary>XQLength</primary></indexterm>
+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
+<function>XEventsQueued</function>).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+RootWindow(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Window <function>XRootWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm><primary>Window</primary><secondary>RootWindow</secondary></indexterm>
+<indexterm significance="preferred"><primary>RootWindow</primary></indexterm>
+<indexterm><primary>Window</primary><secondary>XRootWindow</secondary></indexterm>
+<indexterm significance="preferred"><primary>XRootWindow</primary></indexterm>
+Both return the root window.
+These are useful with functions that need a drawable of a particular screen
+and for creating top-level windows.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+ScreenCount(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XScreenCount</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ScreenCount</primary></indexterm>
+<indexterm significance="preferred"><primary>XScreenCount</primary></indexterm>
+Both return the number of available screens.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+ServerVendor(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>char *<function>XServerVendor</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ServerVendor</primary></indexterm>
+<indexterm significance="preferred"><primary>XServerVendor</primary></indexterm>
+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.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+VendorRelease(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XVendorRelease</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>VendorRelease</primary></indexterm>
+<indexterm significance="preferred"><primary>XVendorRelease</primary></indexterm>
+Both return a number related to a vendor's release of the X server.
+</para>
+</sect2>
+<sect2 id="Image_Format_Functions_and_Macros">
+<title>Image Format Functions and Macros</title>
+<!-- .XS -->
+<!-- (SN Image Format Functions and Macros -->
+<!-- .XE -->
+<para>
+<!-- .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).
+</para>
+<para>
+<!-- .LP -->
+The
+<structname>XPixmapFormatValues</structname>
+structure provides an interface to the pixmap format information
+that is returned at the time of a connection setup.
+It contains:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ int depth;
+ int bits_per_pixel;
+ int scanline_pad;
+} XPixmapFormatValues;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To obtain the pixmap format information for a given display, use
+<function>XListPixmapFormats</function>.
+<indexterm significance="preferred"><primary>XListPixmapFormats</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>
+ImageByteOrder(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XImageByteOrder</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> *count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+<!-- .ds Cn pixmap formats that are supported by the display -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XListPixmapFormats</function>
+function returns an array of
+<structname>XPixmapFormatValues</structname>
+structures that describe the types of Z format images supported
+by the specified display.
+If insufficient memory is available,
+<function>XListPixmapFormats</function>
+returns NULL.
+To free the allocated storage for the
+<structname>XPixmapFormatValues</structname>
+structures, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .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.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+ImageByteOrder(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XImageByteOrder</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>ImageByteOrder</primary></indexterm>
+<indexterm significance="preferred"><primary>XImageByteOrder</primary></indexterm>
+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
+<symbol>LSBFirst</symbol>
+or
+<symbol>MSBFirst</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+BitmapUnit(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XBitmapUnit</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>BitmapUnit</primary></indexterm>
+<indexterm significance="preferred"><primary>XBitmapUnit</primary></indexterm>
+Both return the size of a bitmap's scanline unit in bits.
+The scanline is calculated in multiples of this value.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+BitmapBitOrder(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XBitmapBitOrder</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>BitmapBitOrder</primary></indexterm>
+<indexterm significance="preferred"><primary>XBitmapBitOrder</primary></indexterm>
+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
+<symbol>LSBFirst</symbol>
+or
+<symbol>MSBFirst</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+BitmapPad(<emphasis remap='I'>display</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XBitmapPad</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>BitmapPad</primary></indexterm>
+<indexterm significance="preferred"><primary>XBitmapPad</primary></indexterm>
+Each scanline must be padded to a multiple of bits returned
+by this macro or function.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DisplayHeight(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XDisplayHeight</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DisplayHeight</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayHeight</primary></indexterm>
+Both return an integer that describes the height of the screen
+in pixels.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DisplayHeightMM(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XDisplayHeightMM</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DisplayHeightMM</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayHeightMM</primary></indexterm>
+Both return the height of the specified screen in millimeters.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DisplayWidth(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XDisplayWidth</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DisplayWidth</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayWidth</primary></indexterm>
+Both return the width of the screen in pixels.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DisplayWidthMM(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XDisplayWidthMM</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DisplayWidthMM</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayWidthMM</primary></indexterm>
+Both return the width of the specified screen in millimeters.
+</para>
+</sect2>
+<sect2 id="Screen_Information_Macros">
+<title>Screen Information Macros</title>
+<!-- .XS -->
+<!-- (SN Screen Information Macros -->
+<!-- .XE -->
+<para>
+<!-- .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.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+BlackPixelOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned long <function>XBlackPixelOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>BlackPixelOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XBlackPixelOfScreen</primary></indexterm>
+Both return the black pixel value of the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+WhitePixelOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>unsigned long <function>XWhitePixelOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>WhitePixelOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XWhitePixelOfScreen</primary></indexterm>
+Both return the white pixel value of the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+CellsOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XCellsOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>CellsOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XCellsOfScreen</primary></indexterm>
+Both return the number of colormap cells in the default colormap
+of the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultColormapOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Colormap <function>XDefaultColormapOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultColormapOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultColormapOfScreen</primary></indexterm>
+Both return the default colormap of the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultDepthOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XDefaultDepthOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultDepthOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultDepthOfScreen</primary></indexterm>
+Both return the depth of the root window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultGCOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>GC <function>XDefaultGCOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultGCOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultGCOfScreen</primary></indexterm>
+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.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DefaultVisualOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Visual *<function>XDefaultVisualOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DefaultVisualOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XDefaultVisualOfScreen</primary></indexterm>
+Both return the default visual of the specified screen.
+For information on visual types,
+see section 3.1.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DoesBackingStore(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XDoesBackingStore</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DoesBackingStore</primary></indexterm>
+<indexterm significance="preferred"><primary>XDoesBackingStore</primary></indexterm>
+Both return a value indicating whether the screen supports backing
+stores.
+The value returned can be one of
+<symbol>WhenMapped</symbol>,
+<symbol>NotUseful</symbol>,
+or
+<symbol>Always</symbol>
+(see section 3.2.4).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DoesSaveUnders(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Bool <function>XDoesSaveUnders</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DoesSaveUnders</primary></indexterm>
+<indexterm significance="preferred"><primary>XDoesSaveUnders</primary></indexterm>
+Both return a Boolean value indicating whether the
+screen supports save unders.
+If
+<symbol>True</symbol>,
+the screen supports save unders.
+If
+<symbol>False</symbol>,
+the screen does not support save unders (see section 3.2.5).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+DisplayOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Display *<function>XDisplayOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>DisplayOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XDisplayOfScreen</primary></indexterm>
+Both return the display of the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+<indexterm significance="preferred"><primary>XScreenNumberOfScreen</primary></indexterm>
+</para>
+<para>
+EventMaskOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>long <function>XEventMaskOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XScreenNumberOfScreen</function>
+function returns the screen index number of the specified screen.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+EventMaskOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>long <function>XEventMaskOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>EventMaskOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XEventMaskOfScreen</primary></indexterm>
+Both return the event mask of the root window for the specified screen
+at connection setup time.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+WidthOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XWidthOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>WidthOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XWidthOfScreen</primary></indexterm>
+Both return the width of the specified screen in pixels.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+HeightOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XHeightOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>HeightOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XHeightOfScreen</primary></indexterm>
+Both return the height of the specified screen in pixels.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+WidthMMOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XWidthMMOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>WidthMMOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XWidthMMOfScreen</primary></indexterm>
+Both return the width of the specified screen in millimeters.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+HeightMMOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XHeightMMOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>HeightMMOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XHeightMMOfScreen</primary></indexterm>
+Both return the height of the specified screen in millimeters.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+MaxCmapsOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XMaxCmapsOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>MaxCmapsOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XMaxCmapsOfScreen</primary></indexterm>
+Both return the maximum number of installed colormaps supported
+by the specified screen (see section 9.3).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+MinCmapsOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XMinCmapsOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>MinCmapsOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XMinCmapsOfScreen</primary></indexterm>
+Both return the minimum number of installed colormaps supported
+by the specified screen (see section 9.3).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+PlanesOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int <function>XPlanesOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>PlanesOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XPlanesOfScreen</primary></indexterm>
+Both return the depth of the root window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .sM -->
+</para>
+<para>
+RootWindowOfScreen(<emphasis remap='I'>screen</emphasis>)
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Window <function>XRootWindowOfScreen</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate
+<type>Screen</type>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<indexterm significance="preferred"><primary>RootWindowOfScreen</primary></indexterm>
+<indexterm significance="preferred"><primary>XRootWindowOfScreen</primary></indexterm>
+Both return the root window of the specified screen.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Generating_a_NoOperation_Protocol_Request">
+<title>Generating a NoOperation Protocol Request</title>
+<!-- .XS -->
+<!-- (SN Generating a NoOperation Protocol Request -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To execute a
+<systemitem>NoOperation</systemitem>
+protocol request, use
+<function>XNoOp</function>.
+<indexterm significance="preferred"><primary>XNoOp</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function>XNoOp</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term><emphasis remap='I'>display</emphasis></term>
+ <listitem>
+ <para>Specifies the connection to the X server.</para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XNoOp</function>
+function sends a
+<systemitem>NoOperation</systemitem>
+protocol request to the X server,
+thereby exercising the connection.
+</para>
+</sect1>
+<sect1 id="Freeing_Client_Created_Data">
+<title>Freeing Client-Created Data</title>
+<!-- .XS -->
+<!-- (SN Freeing Client-Created Data -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To free in-memory data that was created by an Xlib function, use
+<function>XFree</function>.
+<indexterm significance="preferred"><primary>XFree</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XFree</funcdef>
+ <paramdef>void<parameter> *data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the data that is to be freed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFree</function>
+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.
+</para>
+</sect1>
+<sect1 id="Closing_the_Display">
+<title>Closing the Display</title>
+<!-- .XS -->
+<!-- (SN Closing the Display -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To close a display or disconnect from the X server, use
+<function>XCloseDisplay</function>.
+<indexterm significance="preferred"><primary>XCloseDisplay</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XCloseDisplay</funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XCloseDisplay</function>
+function closes the connection to the X server for the display specified in the
+<type>Display</type>
+structure and destroys all windows, resource IDs
+(<type>Window</type>,
+<type>Font</type>,
+<type>Pixmap</type>,
+<type>Colormap</type>,
+<type>Cursor</type>,
+and
+<type>GContext</type>),
+or other resources that the client has created
+on this display, unless the close-down mode of the resource has been changed
+(see
+<function>XSetCloseDownMode</function>).
+Therefore, these windows, resource IDs, and other resources should never be
+referenced again or an error will be generated.
+Before exiting, you should call
+<function>XCloseDisplay</function>
+explicitly so that any pending errors are reported as
+<function>XCloseDisplay</function>
+performs a final
+<function>XSync</function>
+operation.
+<indexterm><primary>Resource IDs</primary></indexterm>
+<indexterm><primary>XCloseDisplay</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<function>XCloseDisplay</function>
+can generate a
+<errorname>BadGC</errorname>
+error.
+<!-- .sp -->
+</para>
+<para>
+<!-- .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
+<function>XSetCloseDownMode</function>.
+<indexterm significance="preferred"><primary>XSetCloseDownMode</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XSetCloseDownMode</funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> close_mode</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>close_mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the client close-down mode.
+You can pass
+<symbol>DestroyAll</symbol>,
+<symbol>RetainPermanent</symbol>,
+or
+<symbol>RetainTemporary</symbol>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetCloseDownMode</function>
+defines what will happen to the client's resources at connection close.
+A connection starts in
+<symbol>DestroyAll</symbol>
+mode.
+For information on what happens to the client's resources when the
+close_mode argument is
+<symbol>RetainPermanent</symbol>
+or
+<symbol>RetainTemporary</symbol>,
+see section 2.6.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetCloseDownMode</function>
+can generate a
+<errorname>BadValue</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Using_X_Server_Connection_Close_Operations_">
+<title>Using X Server Connection Close Operations </title>
+<!-- .XS -->
+<!-- (SN Using X Server Connection Close Operations -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+When the X server's connection to a client is closed
+either by an explicit call to
+<function>XCloseDisplay</function>
+or by a process that exits, the X server performs the following
+automatic operations:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+It disowns all selections owned by the client
+(see
+<function>XSetSelectionOwner</function>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It performs an
+<function>XUngrabPointer</function>
+and
+<function>XUngrabKeyboard</function>
+if the client has actively grabbed the pointer
+or the keyboard.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It performs an
+<function>XUngrabServer</function>
+if the client has grabbed the server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It releases all passive grabs made by the client.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It marks all resources (including colormap entries) allocated
+by the client either as permanent or temporary,
+depending on whether the close-down mode is
+<symbol>RetainPermanent</symbol>
+or
+<symbol>RetainTemporary</symbol>.
+However, this does not prevent other client applications from explicitly
+destroying the resources (see
+<function>XSetCloseDownMode</function>).
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+When the close-down mode is
+<symbol>DestroyAll</symbol>,
+the X server destroys all of a client's resources as follows:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It performs a
+<systemitem>MapWindow</systemitem>
+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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It destroys all windows created by the client.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It performs the appropriate free request on each nonwindow resource created by
+the client in the server (for example,
+<type>Font</type>,
+<type>Pixmap</type>,
+<type>Cursor</type>,
+<type>Colormap</type>,
+and
+<type>GContext</type>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It frees all colors and colormap entries allocated by a client application.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .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
+<symbol>DestroyAll</symbol>,
+the X server does the following:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+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
+<symbol>RetainPermanent</symbol>
+or
+<symbol>RetainTemporary</symbol>
+mode.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It deletes all but the predefined atom identifiers.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It deletes all properties on all root windows (see section 4.3).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It resets all device maps and attributes
+(for example, key click, bell volume, and acceleration)
+as well as the access control list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It restores the standard root tiles and cursors.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It restores the default font path.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+It restores the input focus to state
+<symbol>PointerRoot</symbol>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+However, the X server does not reset if you close a connection with a close-down
+mode set to
+<symbol>RetainPermanent</symbol>
+or
+<symbol>RetainTemporary</symbol>.
+</para>
+</sect1>
+<sect1 id="Using_Xlib_with_Threads">
+<title>Using Xlib with Threads</title>
+<!-- .XS -->
+<!-- (SN Using Xlib with Threads -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+On systems that have threads, support may be provided to permit
+multiple threads to use Xlib concurrently.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To initialize support for concurrent threads, use
+<function>XInitThreads</function>.
+<indexterm significance="preferred"><primary>XInitThreads</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>Status XInitThreads();</para>
+<!-- .FN -->
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XInitThreads</function>
+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.
+</para>
+<para>
+<!-- .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.
+
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To lock a display across several Xlib calls, use
+<function>XLockDisplay</function>.
+<indexterm significance="preferred"><primary>XLockDisplay</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XLockDisplay</funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XLockDisplay</function>
+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
+<function>XLockDisplay</function>
+work correctly; the display will not actually be unlocked until
+<function>XUnlockDisplay</function>
+has been called the same number of times as
+<function>XLockDisplay</function>.
+This function has no effect unless Xlib was successfully initialized
+for threads using
+<function>XInitThreads</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To unlock a display, use
+<function>XUnlockDisplay</function>.
+<indexterm significance="preferred"><primary>XUnlockDisplay</primary></indexterm>
+<!-- .sM -->
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XUnlockDisplay</funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XUnlockDisplay</function>
+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
+<function>XLockDisplay</function>
+has been called multiple times by a thread, then
+<function>XUnlockDisplay</function>
+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
+<function>XInitThreads</function>.
+</para>
+</sect1>
+<sect1 id="Using_Internal_Connections">
+<title>Using Internal Connections</title>
+<!-- .XS -->
+<!-- (SN Using Internal Connections -->
+<!-- .XE -->
+<para>
+<!-- .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.
+</para>
+<para>
+<!-- .LP -->
+To track internal connections for a display, use
+<function>XAddConnectionWatch</function>.
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>type void XConnectionWatchProc</funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+ <paramdef>int<parameter> fd</parameter></paramdef>
+ <paramdef>Bool<parameter> opening</parameter></paramdef>
+ <paramdef>XPointer<parameter> *watch_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status XAddConnectionWatch</funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XWatchProc<parameter> procedure</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>procedure</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAddConnectionWatch</function>
+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
+<symbol>True</symbol>,
+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
+<symbol>False</symbol>,
+the location pointed to by watch_data will hold this same private data pointer.
+</para>
+<para>
+<!-- .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
+<function>XAddConnectionWatch</function>
+returns.
+<function>XAddConnectionWatch</function>
+returns a nonzero status if the procedure is successfully registered;
+otherwise, it returns zero.
+</para>
+<para>
+<!-- .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
+<function>XLockDisplay</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To stop tracking internal connections for a display, use
+<function>XRemoveConnectionWatch</function>.
+<indexterm significance="preferred"><primary>XRemoveConnectionWatch</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>
+()
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XRemoveConnectionWatch</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XWatchProc<parameter> procedure</parameter></paramdef>
+ <paramdef>XPointer<parameter> client_data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>procedure</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure to be called.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>client_data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the additional client data.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRemoveConnectionWatch</function>
+function removes a previously registered connection watch procedure.
+The client_data must match the client_data used when the procedure
+was initially registered.
+
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To process input on an internal connection, use
+<function>XProcessInternalConnection</function>.
+<indexterm significance="preferred"><primary>XProcessInternalConnection</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>
+()
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void <function>XProcessInternalConnection</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int<parameter> fd</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fd</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the file descriptor.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XProcessInternalConnection</function>
+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,
+<function>select</function>
+or
+<function>poll</function>)
+has indicated that input is available; otherwise,
+the effect is not defined.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain all of the current internal connections for a display, use
+<function>XInternalConnectionNumbers</function>.
+<indexterm significance="preferred"><primary>XInternalConnectionNumbers</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>
+()
+</para>
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status <function>XInternalConnectionNumbers</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>int **<parameter> fd</parameter></paramdef>
+ <paramdef>int *<parameter> count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>fd_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the file descriptors.
+<!-- .ds Cn file descriptors -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XInternalConnectionNumbers</function>
+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
+<function>XFree</function>.
+This functions returns a nonzero status if the list is successfully allocated;
+otherwise, it returns zero.
+</para>
+</sect1>
+</chapter>
diff --git a/libX11/specs/libX11/Makefile.am b/libX11/specs/libX11/Makefile.am index b87e568cd..f91320c09 100644 --- a/libX11/specs/libX11/Makefile.am +++ b/libX11/specs/libX11/Makefile.am @@ -1,38 +1,38 @@ - -if ENABLE_SPECS - -# Main DocBook/XML files (DOCTYPE book) -docbook = libX11.xml - -# Included chapters, appendix, images -chapters = \ - AppA.xml \ - AppB.xml \ - AppC.xml \ - AppD.xml \ - CH01.xml \ - CH02.xml \ - CH03.xml \ - CH04.xml \ - CH05.xml \ - CH06.xml \ - CH07.xml \ - CH08.xml \ - CH09.xml \ - CH10.xml \ - CH11.xml \ - CH12.xml \ - CH13.xml \ - CH14.xml \ - CH15.xml \ - CH16.xml \ - credits.xml \ - glossary.xml - -# The location where the DocBook/XML files and their generated formats are installed -shelfdir = $(docdir)/libX11 - -# Generate DocBook/XML output formats with or without stylesheets -include $(top_srcdir)/docbook.am - -endif ENABLE_SPECS +
+if ENABLE_SPECS
+
+# Main DocBook/XML files (DOCTYPE book)
+docbook = libX11.xml
+
+# Included chapters, appendix, images
+chapters = \
+ AppA.xml \
+ AppB.xml \
+ AppC.xml \
+ AppD.xml \
+ CH01.xml \
+ CH02.xml \
+ CH03.xml \
+ CH04.xml \
+ CH05.xml \
+ CH06.xml \
+ CH07.xml \
+ CH08.xml \
+ CH09.xml \
+ CH10.xml \
+ CH11.xml \
+ CH12.xml \
+ CH13.xml \
+ CH14.xml \
+ CH15.xml \
+ CH16.xml \
+ credits.xml \
+ glossary.xml
+
+# The location where the DocBook/XML files and their generated formats are installed
+shelfdir = $(docdir)/libX11
+
+# Generate DocBook/XML output formats with or without stylesheets
+include $(top_srcdir)/docbook.am
+
+endif ENABLE_SPECS
|