aboutsummaryrefslogtreecommitdiff
path: root/libX11/specs
diff options
context:
space:
mode:
Diffstat (limited to 'libX11/specs')
-rw-r--r--libX11/specs/libX11/CH02.xml6983
1 files changed, 3489 insertions, 3494 deletions
diff --git a/libX11/specs/libX11/CH02.xml b/libX11/specs/libX11/CH02.xml
index a00b7c283..f4ef1bcd8 100644
--- a/libX11/specs/libX11/CH02.xml
+++ b/libX11/specs/libX11/CH02.xml
@@ -1,3494 +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>
-<para>
-<!-- .LP -->
-<!-- .sM -->
-</para>
-<para>
-AllPlanes()
-</para>
-<para>
-XAllPlanes
-</para>
-
-<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">&lt;X11/Xlib.h&gt;</filename>.
-<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xlib.h&gt;</filename></secondary></indexterm>
-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xlib.h&gt;</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">&lt;X11/Xlib.h&gt;</filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xlib.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xlib.h&gt;</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>