<?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"><X11/Xlib.h></filename>.
<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm>
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm>
If
<function>XOpenDisplay</function>
does not succeed, it returns NULL.
After a successful call to
<function>XOpenDisplay</function>,
all of the screens in the display can be used by the client.
The screen number specified in the display_name argument is returned
by the
<function>DefaultScreen</function>
macro (or the
<function>XDefaultScreen</function>
function).
You can access elements of the
<type>Display</type>
and
<type>Screen</type>
structures only by using the information macros or functions.
For information about using macros and functions to obtain information from
the
<type>Display</type>
structure,
see section 2.2.1.
</para>
<para>
<!-- .LP -->
X servers may implement various types of access control mechanisms
(see section 9.8).
</para>
</sect1>
<sect1 id="Obtaining_Information_about_the_Display_Image_Formats_or_Screens">
<title>Obtaining Information about the Display, Image Formats, or Screens</title>
<!-- .XS -->
<!-- (SN Obtaining Information about the Display, Image Formats, or Screens -->
<!-- .XE -->
<para>
<!-- .LP -->
The Xlib library provides a number of useful macros
and corresponding functions that return data from the
<type>Display</type>
structure.
The macros are used for C programming,
and their corresponding function equivalents are for other language bindings.
This section discusses the:
</para>
<itemizedlist>
<listitem>
<para>
Display macros
</para>
</listitem>
<listitem>
<para>
Image format functions and macros
</para>
</listitem>
<listitem>
<para>
Screen information macros
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
<indexterm ><primary>Display</primary><secondary>data structure</secondary></indexterm>
All other members of the
<type>Display</type>
structure (that is, those for which no macros are defined) are private to Xlib
and must not be used.
Applications must never directly modify or inspect these private members of the
<type>Display</type>
structure.
<!-- .NT Note -->
The
<function>XDisplayWidth</function>,
<function>XDisplayHeight</function>,
<function>XDisplayCells</function>,
<function>XDisplayPlanes</function>,
<function>XDisplayWidthMM</function>,
and
<function>XDisplayHeightMM</function>
functions in the next sections are misnamed.
These functions really should be named Screen<emphasis remap='I'>whatever</emphasis>
and XScreen<emphasis remap='I'>whatever</emphasis>, not Display<emphasis remap='I'>whatever</emphasis> or XDisplay<emphasis remap='I'>whatever</emphasis>.
Our apologies for the resulting confusion.
<!-- .NE -->
</para>
<sect2 id="Display_Macros_">
<title>Display Macros </title>
<!-- .XS -->
<!-- (SN Display Macros -->
<!-- .XE -->
<para>
<!-- .LP -->
Applications should not directly modify any part of the
<type>Display</type>
and
<type>Screen</type>
structures.
The members should be considered read-only,
although they may change as the result of other operations on the display.
</para>
<para>
<!-- .LP -->
The following lists the C language macros,
their corresponding function equivalents that are for other language bindings,
and what data both can return.
</para>
<para>AllPlanes()</para>
<para>XAllPlanes()</para>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>AllPlanes</primary></indexterm>
<indexterm significance="preferred"><primary>XAllPlanes</primary></indexterm>
Both return a value with all bits set to 1 suitable for use in a plane argument to
a procedure.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
Both
<function>BlackPixel</function>
and
<function>WhitePixel</function>
can be used in implementing a monochrome application.
These pixel values are for permanently allocated entries in the default
colormap.
The actual <acronym>RGB</acronym> (red, green, and blue) values are settable on some screens
and, in any case, may not actually be black or white.
The names are intended to convey the expected relative intensity of the colors.
<!-- .sM -->
</para>
<para>
BlackPixel(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>unsigned long <function>XBlackPixel</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>int<parameter> screen_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>screen_number</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate screen number on the host server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>BlackPixel</primary></indexterm>
<indexterm significance="preferred"><primary>XBlackPixel</primary></indexterm>
Both return the black pixel value for the specified screen.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
WhitePixel(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>unsigned long <function>XWhitePixel</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>int<parameter> screen_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>screen_number</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate screen number on the host server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>WhitePixel</primary></indexterm>
<indexterm significance="preferred"><primary>XWhitePixel</primary></indexterm>
Both return the white pixel value for the specified screen.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
ConnectionNumber(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XConnectionNumber</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>ConnectionNumber</primary></indexterm>
<indexterm significance="preferred"><primary>XConnectionNumber</primary></indexterm>
Both return a connection number for the specified display.
On a <acronym>POSIX</acronym>-conformant system,
this is the file descriptor of the connection.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DefaultColormap(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>Colormap <function>XDefaultColormap</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>int<parameter> screen_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>screen_number</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate screen number on the host server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DefaultColormap</primary></indexterm>
<indexterm significance="preferred"><primary>XDefaultColormap</primary></indexterm>
Both return the default colormap ID for allocation on the specified screen.
Most routine allocations of color should be made out of this colormap.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DefaultDepth(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XDefaultDepth</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>int<parameter> screen_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>screen_number</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate screen number on the host server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DefaultDepth</primary></indexterm>
<indexterm significance="preferred"><primary>XDefaultDepth</primary></indexterm>
Both return the depth (number of planes) of the default root window for the
specified screen.
Other depths may also be supported on this screen (see
<function>XMatchVisualInfo</function>).
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<indexterm significance="preferred"><primary>XListDepths</primary></indexterm>
To determine the number of depths that are available on a given screen, use
<function>XListDepths</function>.
<!-- .sM -->
</para>
<para>
DefaultGC(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>GC <function>XDefaultGC</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>int<parameter> screen_number</parameter></paramdef>
<paramdef>int<parameter> *count_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>screen_number</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate screen number on the host server.
<!-- .ds Cn depths -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>count_return</emphasis>
</term>
<listitem>
<para>
Returns the number of (Cn.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XListDepths</function>
function returns the array of depths
that are available on the specified screen.
If the specified screen_number is valid and sufficient memory for the array
can be allocated,
<function>XListDepths</function>
sets count_return to the number of available depths.
Otherwise, it does not set count_return and returns NULL.
To release the memory allocated for the array of depths, use
<function>XFree</function>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DefaultGC(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>GC <function>XDefaultGC</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>int<parameter> screen_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>screen_number</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate screen number on the host server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DefaultGC</primary></indexterm>
<indexterm significance="preferred"><primary>XDefaultGC</primary></indexterm>
Both return the default graphics context for the root window of the
specified screen.
This GC is created for the convenience of simple applications
and contains the default GC components with the foreground and
background pixel values initialized to the black and white
pixels for the screen, respectively.
You can modify its contents freely because it is not used in any Xlib
function.
This GC should never be freed.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DefaultRootWindow(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>Window <function>XDefaultRootWindow</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DefaultRootWindow</primary></indexterm>
<indexterm significance="preferred"><primary>XDefaultRootWindow</primary></indexterm>
Both return the root window for the default screen.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DefaultScreenOfDisplay(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>Screen *<function>XDefaultScreenOfDisplay</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DefaultScreenOfDisplay</primary></indexterm>
<indexterm significance="preferred"><primary>XDefaultScreenOfDisplay</primary></indexterm>
Both return a pointer to the default screen.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
ScreenOfDisplay(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>Screen *<function>XScreenOfDisplay</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>int<parameter> screen_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>screen_number</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate screen number on the host server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>ScreenOfDisplay</primary></indexterm>
<indexterm significance="preferred"><primary>XScreenOfDisplay</primary></indexterm>
Both return a pointer to the indicated screen.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DefaultScreen(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XDefaultScreen</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DefaultScreen</primary></indexterm>
<indexterm significance="preferred"><primary>XDefaultScreen</primary></indexterm>
Both return the default screen number referenced by the
<function>XOpenDisplay</function>
function.
This macro or function should be used to retrieve the screen number
in applications that will use only a single screen.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DefaultVisual(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>Visual *<function>XDefaultVisual</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>int<parameter> screen_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>screen_number</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate screen number on the host server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DefaultVisual</primary></indexterm>
<indexterm significance="preferred"><primary>XDefaultVisual</primary></indexterm>
Both return the default visual type for the specified screen.
For further information about visual types,
see section 3.1.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DisplayCells(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XDisplayCells</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>int<parameter> screen_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>screen_number</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate screen number on the host server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DisplayCells</primary></indexterm>
<indexterm significance="preferred"><primary>XDisplayCells</primary></indexterm>
Both return the number of entries in the default colormap.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DisplayPlanes(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XDisplayPlanes</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>int<parameter> screen_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>screen_number</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate screen number on the host server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DisplayPlanes</primary></indexterm>
<indexterm significance="preferred"><primary>XDisplayPlanes</primary></indexterm>
Both return the depth of the root window of the specified screen.
For an explanation of depth,
see the glossary.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DisplayString(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XDisplayString</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DisplayString</primary></indexterm>
<indexterm significance="preferred"><primary>XDisplayString</primary></indexterm>
Both return the string that was passed to
<function>XOpenDisplay</function>
when the current display was opened.
On <acronym>POSIX</acronym>-conformant systems,
if the passed string was NULL, these return the value of
the DISPLAY environment variable when the current display was opened.
<indexterm><primary><acronym>POSIX</acronym> System Call</primary><secondary>fork</secondary></indexterm>
These are useful to applications that invoke the
<function>fork</function>
system call and want to open a new connection to the same display from the
child process as well as for printing error messages.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
LastKnownRequestProcessed(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>unsigned long <function>XLastKnownRequestProcessed</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>XExtendedMaxRequestSize</primary></indexterm>
The
<function>XExtendedMaxRequestSize</function>
function returns zero if the specified display does not support an
extended-length protocol encoding; otherwise,
it returns the maximum request size (in 4-byte units) supported
by the server using the extended-length encoding.
The Xlib functions
<function>XDrawLines</function>,
<function>XDrawArcs</function>,
<function>XFillPolygon</function>,
<function>XChangeProperty</function>,
<function>XSetClipRectangles</function>,
and
<function>XSetRegion</function>
will use the extended-length encoding as necessary, if supported
by the server. Use of the extended-length encoding in other Xlib
functions (for example,
<function>XDrawPoints</function>,
<function>XDrawRectangles</function>,
<function>XDrawSegments</function>,
<function>XFillArcs</function>,
<function>XFillRectangles</function>,
<function>XPutImage</function>)
is permitted but not required; an Xlib implementation may choose to
split the data across multiple smaller requests instead.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
LastKnownRequestProcessed(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>unsigned long <function>XLastKnownRequestProcessed</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>XMaxRequestSize</primary></indexterm>
The
<function>XMaxRequestSize</function>
function returns the maximum request size (in 4-byte units) supported
by the server without using an extended-length protocol encoding.
Single protocol requests to the server can be no larger than this size
unless an extended-length protocol encoding is supported by the server.
The protocol guarantees the size to be no smaller than 4096 units
(16384 bytes).
Xlib automatically breaks data up into multiple protocol requests
as necessary for the following functions:
<function>XDrawPoints</function>,
<function>XDrawRectangles</function>,
<function>XDrawSegments</function>,
<function>XFillArcs</function>,
<function>XFillRectangles</function>,
and
<function>XPutImage</function>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
LastKnownRequestProcessed(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>unsigned long <function>XLastKnownRequestProcessed</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>LastKnownRequestProcessed</primary></indexterm>
<indexterm significance="preferred"><primary>XLastKnownRequestProcessed</primary></indexterm>
Both extract the full serial number of the last request known by Xlib
to have been processed by the X server.
Xlib automatically sets this number when replies, events, and errors
are received.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
NextRequest(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>unsigned long <function>XNextRequest</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>NextRequest</primary></indexterm>
<indexterm significance="preferred"><primary>XNextRequest</primary></indexterm>
Both extract the full serial number that is to be used for the next
request.
Serial numbers are maintained separately for each display connection.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
ProtocolVersion(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XProtocolVersion</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>ProtocolVersion</primary></indexterm>
<indexterm significance="preferred"><primary>XProtocolVersion</primary></indexterm>
Both return the major version number (11) of the X protocol associated with
the connected display.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
ProtocolRevision(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XProtocolRevision</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>ProtocolRevision</primary></indexterm>
<indexterm significance="preferred"><primary>XProtocolRevision</primary></indexterm>
Both return the minor protocol revision number of the X server.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
QLength(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XQLength</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>QLength</primary></indexterm>
<indexterm significance="preferred"><primary>XQLength</primary></indexterm>
Both return the length of the event queue for the connected display.
Note that there may be more events that have not been read into
the queue yet (see
<function>XEventsQueued</function>).
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
RootWindow(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>Window <function>XRootWindow</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>int<parameter> screen_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>screen_number</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate screen number on the host server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm><primary>Window</primary><secondary>RootWindow</secondary></indexterm>
<indexterm significance="preferred"><primary>RootWindow</primary></indexterm>
<indexterm><primary>Window</primary><secondary>XRootWindow</secondary></indexterm>
<indexterm significance="preferred"><primary>XRootWindow</primary></indexterm>
Both return the root window.
These are useful with functions that need a drawable of a particular screen
and for creating top-level windows.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
ScreenCount(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XScreenCount</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>ScreenCount</primary></indexterm>
<indexterm significance="preferred"><primary>XScreenCount</primary></indexterm>
Both return the number of available screens.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
ServerVendor(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>XServerVendor</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>ServerVendor</primary></indexterm>
<indexterm significance="preferred"><primary>XServerVendor</primary></indexterm>
Both return a pointer to a null-terminated string that provides
some identification of the owner of the X server implementation.
If the data returned by the server is in the Latin Portable Character Encoding,
then the string is in the Host Portable Character Encoding.
Otherwise, the contents of the string are implementation-dependent.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
VendorRelease(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XVendorRelease</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>VendorRelease</primary></indexterm>
<indexterm significance="preferred"><primary>XVendorRelease</primary></indexterm>
Both return a number related to a vendor's release of the X server.
</para>
</sect2>
<sect2 id="Image_Format_Functions_and_Macros">
<title>Image Format Functions and Macros</title>
<!-- .XS -->
<!-- (SN Image Format Functions and Macros -->
<!-- .XE -->
<para>
<!-- .LP -->
Applications are required to present data to the X server
in a format that the server demands.
To help simplify applications,
most of the work required to convert the data is provided by Xlib
(see sections 8.7 and 16.8).
</para>
<para>
<!-- .LP -->
The
<structname>XPixmapFormatValues</structname>
structure provides an interface to the pixmap format information
that is returned at the time of a connection setup.
It contains:
</para>
<para>
<!-- .LP -->
<!-- .sM -->
<literallayout class="monospaced">
<!-- .TA .5i 3i -->
<!-- .ta .5i 3i -->
typedef struct {
int depth;
int bits_per_pixel;
int scanline_pad;
} XPixmapFormatValues;
</literallayout>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
<!-- .sp -->
To obtain the pixmap format information for a given display, use
<function>XListPixmapFormats</function>.
<indexterm significance="preferred"><primary>XListPixmapFormats</primary></indexterm>
<!-- .sM -->
</para>
<para>
ImageByteOrder(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XImageByteOrder</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>int<parameter> *count_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
<!-- .ds Cn pixmap formats that are supported by the display -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>count_return</emphasis>
</term>
<listitem>
<para>
Returns the number of (Cn.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XListPixmapFormats</function>
function returns an array of
<structname>XPixmapFormatValues</structname>
structures that describe the types of Z format images supported
by the specified display.
If insufficient memory is available,
<function>XListPixmapFormats</function>
returns NULL.
To free the allocated storage for the
<structname>XPixmapFormatValues</structname>
structures, use
<function>XFree</function>.
</para>
<para>
<!-- .LP -->
The following lists the C language macros,
their corresponding function equivalents that are for other language bindings,
and what data they both return for the specified server and screen.
These are often used by toolkits as well as by simple applications.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
ImageByteOrder(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XImageByteOrder</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>ImageByteOrder</primary></indexterm>
<indexterm significance="preferred"><primary>XImageByteOrder</primary></indexterm>
Both specify the required byte order for images for each scanline unit in
XY format (bitmap) or for each pixel value in
Z format.
The macro or function can return either
<symbol>LSBFirst</symbol>
or
<symbol>MSBFirst</symbol>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
BitmapUnit(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XBitmapUnit</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>BitmapUnit</primary></indexterm>
<indexterm significance="preferred"><primary>XBitmapUnit</primary></indexterm>
Both return the size of a bitmap's scanline unit in bits.
The scanline is calculated in multiples of this value.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
BitmapBitOrder(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XBitmapBitOrder</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>BitmapBitOrder</primary></indexterm>
<indexterm significance="preferred"><primary>XBitmapBitOrder</primary></indexterm>
Within each bitmap unit, the left-most bit in the bitmap as displayed
on the screen is either the least significant or most significant bit in the
unit.
This macro or function can return
<symbol>LSBFirst</symbol>
or
<symbol>MSBFirst</symbol>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
BitmapPad(<emphasis remap='I'>display</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XBitmapPad</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>BitmapPad</primary></indexterm>
<indexterm significance="preferred"><primary>XBitmapPad</primary></indexterm>
Each scanline must be padded to a multiple of bits returned
by this macro or function.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DisplayHeight(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XDisplayHeight</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>int<parameter> screen_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>screen_number</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate screen number on the host server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DisplayHeight</primary></indexterm>
<indexterm significance="preferred"><primary>XDisplayHeight</primary></indexterm>
Both return an integer that describes the height of the screen
in pixels.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DisplayHeightMM(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XDisplayHeightMM</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>int<parameter> screen_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>screen_number</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate screen number on the host server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DisplayHeightMM</primary></indexterm>
<indexterm significance="preferred"><primary>XDisplayHeightMM</primary></indexterm>
Both return the height of the specified screen in millimeters.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DisplayWidth(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XDisplayWidth</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>int<parameter> screen_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>screen_number</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate screen number on the host server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DisplayWidth</primary></indexterm>
<indexterm significance="preferred"><primary>XDisplayWidth</primary></indexterm>
Both return the width of the screen in pixels.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DisplayWidthMM(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XDisplayWidthMM</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>int<parameter> screen_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>screen_number</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate screen number on the host server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DisplayWidthMM</primary></indexterm>
<indexterm significance="preferred"><primary>XDisplayWidthMM</primary></indexterm>
Both return the width of the specified screen in millimeters.
</para>
</sect2>
<sect2 id="Screen_Information_Macros">
<title>Screen Information Macros</title>
<!-- .XS -->
<!-- (SN Screen Information Macros -->
<!-- .XE -->
<para>
<!-- .LP -->
The following lists the C language macros,
their corresponding function equivalents that are for other language bindings,
and what data they both can return.
These macros or functions all take a pointer to the appropriate screen
structure.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
BlackPixelOfScreen(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>unsigned long <function>XBlackPixelOfScreen</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>BlackPixelOfScreen</primary></indexterm>
<indexterm significance="preferred"><primary>XBlackPixelOfScreen</primary></indexterm>
Both return the black pixel value of the specified screen.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
WhitePixelOfScreen(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>unsigned long <function>XWhitePixelOfScreen</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>WhitePixelOfScreen</primary></indexterm>
<indexterm significance="preferred"><primary>XWhitePixelOfScreen</primary></indexterm>
Both return the white pixel value of the specified screen.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
CellsOfScreen(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XCellsOfScreen</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>CellsOfScreen</primary></indexterm>
<indexterm significance="preferred"><primary>XCellsOfScreen</primary></indexterm>
Both return the number of colormap cells in the default colormap
of the specified screen.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DefaultColormapOfScreen(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>Colormap <function>XDefaultColormapOfScreen</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DefaultColormapOfScreen</primary></indexterm>
<indexterm significance="preferred"><primary>XDefaultColormapOfScreen</primary></indexterm>
Both return the default colormap of the specified screen.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DefaultDepthOfScreen(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XDefaultDepthOfScreen</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DefaultDepthOfScreen</primary></indexterm>
<indexterm significance="preferred"><primary>XDefaultDepthOfScreen</primary></indexterm>
Both return the depth of the root window.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DefaultGCOfScreen(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>GC <function>XDefaultGCOfScreen</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DefaultGCOfScreen</primary></indexterm>
<indexterm significance="preferred"><primary>XDefaultGCOfScreen</primary></indexterm>
Both return a default graphics context (GC) of the specified screen,
which has the same depth as the root window of the screen.
The GC must never be freed.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DefaultVisualOfScreen(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>Visual *<function>XDefaultVisualOfScreen</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DefaultVisualOfScreen</primary></indexterm>
<indexterm significance="preferred"><primary>XDefaultVisualOfScreen</primary></indexterm>
Both return the default visual of the specified screen.
For information on visual types,
see section 3.1.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DoesBackingStore(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XDoesBackingStore</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DoesBackingStore</primary></indexterm>
<indexterm significance="preferred"><primary>XDoesBackingStore</primary></indexterm>
Both return a value indicating whether the screen supports backing
stores.
The value returned can be one of
<symbol>WhenMapped</symbol>,
<symbol>NotUseful</symbol>,
or
<symbol>Always</symbol>
(see section 3.2.4).
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DoesSaveUnders(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>Bool <function>XDoesSaveUnders</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DoesSaveUnders</primary></indexterm>
<indexterm significance="preferred"><primary>XDoesSaveUnders</primary></indexterm>
Both return a Boolean value indicating whether the
screen supports save unders.
If
<symbol>True</symbol>,
the screen supports save unders.
If
<symbol>False</symbol>,
the screen does not support save unders (see section 3.2.5).
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
DisplayOfScreen(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>Display *<function>XDisplayOfScreen</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>DisplayOfScreen</primary></indexterm>
<indexterm significance="preferred"><primary>XDisplayOfScreen</primary></indexterm>
Both return the display of the specified screen.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
<indexterm significance="preferred"><primary>XScreenNumberOfScreen</primary></indexterm>
</para>
<para>
EventMaskOfScreen(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>long <function>XEventMaskOfScreen</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XScreenNumberOfScreen</function>
function returns the screen index number of the specified screen.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
EventMaskOfScreen(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>long <function>XEventMaskOfScreen</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>EventMaskOfScreen</primary></indexterm>
<indexterm significance="preferred"><primary>XEventMaskOfScreen</primary></indexterm>
Both return the event mask of the root window for the specified screen
at connection setup time.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
WidthOfScreen(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XWidthOfScreen</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>WidthOfScreen</primary></indexterm>
<indexterm significance="preferred"><primary>XWidthOfScreen</primary></indexterm>
Both return the width of the specified screen in pixels.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
HeightOfScreen(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XHeightOfScreen</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>HeightOfScreen</primary></indexterm>
<indexterm significance="preferred"><primary>XHeightOfScreen</primary></indexterm>
Both return the height of the specified screen in pixels.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
WidthMMOfScreen(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XWidthMMOfScreen</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>WidthMMOfScreen</primary></indexterm>
<indexterm significance="preferred"><primary>XWidthMMOfScreen</primary></indexterm>
Both return the width of the specified screen in millimeters.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
HeightMMOfScreen(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XHeightMMOfScreen</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>HeightMMOfScreen</primary></indexterm>
<indexterm significance="preferred"><primary>XHeightMMOfScreen</primary></indexterm>
Both return the height of the specified screen in millimeters.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
MaxCmapsOfScreen(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XMaxCmapsOfScreen</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>MaxCmapsOfScreen</primary></indexterm>
<indexterm significance="preferred"><primary>XMaxCmapsOfScreen</primary></indexterm>
Both return the maximum number of installed colormaps supported
by the specified screen (see section 9.3).
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
MinCmapsOfScreen(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XMinCmapsOfScreen</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>MinCmapsOfScreen</primary></indexterm>
<indexterm significance="preferred"><primary>XMinCmapsOfScreen</primary></indexterm>
Both return the minimum number of installed colormaps supported
by the specified screen (see section 9.3).
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
PlanesOfScreen(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>XPlanesOfScreen</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>PlanesOfScreen</primary></indexterm>
<indexterm significance="preferred"><primary>XPlanesOfScreen</primary></indexterm>
Both return the depth of the root window.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
<!-- .sM -->
</para>
<para>
RootWindowOfScreen(<emphasis remap='I'>screen</emphasis>)
</para>
<funcsynopsis>
<funcprototype>
<funcdef>Window <function>XRootWindowOfScreen</function></funcdef>
<paramdef>Screen<parameter> *screen</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>screen</emphasis>
</term>
<listitem>
<para>
Specifies the appropriate
<type>Screen</type>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
<indexterm significance="preferred"><primary>RootWindowOfScreen</primary></indexterm>
<indexterm significance="preferred"><primary>XRootWindowOfScreen</primary></indexterm>
Both return the root window of the specified screen.
</para>
</sect2>
</sect1>
<sect1 id="Generating_a_NoOperation_Protocol_Request">
<title>Generating a NoOperation Protocol Request</title>
<!-- .XS -->
<!-- (SN Generating a NoOperation Protocol Request -->
<!-- .XE -->
<para>
<!-- .LP -->
To execute a
<systemitem>NoOperation</systemitem>
protocol request, use
<function>XNoOp</function>.
<indexterm significance="preferred"><primary>XNoOp</primary></indexterm>
<!-- .sM -->
</para>
<funcsynopsis>
<funcprototype>
<funcdef><function>XNoOp</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
<varlistentry>
<term><emphasis remap='I'>display</emphasis></term>
<listitem>
<para>Specifies the connection to the X server.</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XNoOp</function>
function sends a
<systemitem>NoOperation</systemitem>
protocol request to the X server,
thereby exercising the connection.
</para>
</sect1>
<sect1 id="Freeing_Client_Created_Data">
<title>Freeing Client-Created Data</title>
<!-- .XS -->
<!-- (SN Freeing Client-Created Data -->
<!-- .XE -->
<para>
<!-- .LP -->
To free in-memory data that was created by an Xlib function, use
<function>XFree</function>.
<indexterm significance="preferred"><primary>XFree</primary></indexterm>
<!-- .sM -->
</para>
<funcsynopsis>
<funcprototype>
<funcdef>XFree</funcdef>
<paramdef>void<parameter> *data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>data</emphasis>
</term>
<listitem>
<para>
Specifies the data that is to be freed.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XFree</function>
function is a general-purpose Xlib routine that frees the specified data.
You must use it to free any objects that were allocated by Xlib,
unless an alternate function is explicitly specified for the object.
A NULL pointer cannot be passed to this function.
</para>
</sect1>
<sect1 id="Closing_the_Display">
<title>Closing the Display</title>
<!-- .XS -->
<!-- (SN Closing the Display -->
<!-- .XE -->
<para>
<!-- .LP -->
To close a display or disconnect from the X server, use
<function>XCloseDisplay</function>.
<indexterm significance="preferred"><primary>XCloseDisplay</primary></indexterm>
</para>
<para>
<!-- .LP -->
<!-- .sM -->
</para>
<funcsynopsis>
<funcprototype>
<funcdef>XCloseDisplay</funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XCloseDisplay</function>
function closes the connection to the X server for the display specified in the
<type>Display</type>
structure and destroys all windows, resource IDs
(<type>Window</type>,
<type>Font</type>,
<type>Pixmap</type>,
<type>Colormap</type>,
<type>Cursor</type>,
and
<type>GContext</type>),
or other resources that the client has created
on this display, unless the close-down mode of the resource has been changed
(see
<function>XSetCloseDownMode</function>).
Therefore, these windows, resource IDs, and other resources should never be
referenced again or an error will be generated.
Before exiting, you should call
<function>XCloseDisplay</function>
explicitly so that any pending errors are reported as
<function>XCloseDisplay</function>
performs a final
<function>XSync</function>
operation.
<indexterm><primary>Resource IDs</primary></indexterm>
<indexterm><primary>XCloseDisplay</primary></indexterm>
</para>
<para>
<!-- .LP -->
<function>XCloseDisplay</function>
can generate a
<errorname>BadGC</errorname>
error.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
Xlib provides a function to permit the resources owned by a client
to survive after the client's connection is closed.
To change a client's close-down mode, use
<function>XSetCloseDownMode</function>.
<indexterm significance="preferred"><primary>XSetCloseDownMode</primary></indexterm>
<!-- .sM -->
</para>
<funcsynopsis>
<funcprototype>
<funcdef>XSetCloseDownMode</funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>int<parameter> close_mode</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>close_mode</emphasis>
</term>
<listitem>
<para>
Specifies the client close-down mode.
You can pass
<symbol>DestroyAll</symbol>,
<symbol>RetainPermanent</symbol>,
or
<symbol>RetainTemporary</symbol>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XSetCloseDownMode</function>
defines what will happen to the client's resources at connection close.
A connection starts in
<symbol>DestroyAll</symbol>
mode.
For information on what happens to the client's resources when the
close_mode argument is
<symbol>RetainPermanent</symbol>
or
<symbol>RetainTemporary</symbol>,
see section 2.6.
</para>
<para>
<!-- .LP -->
<function>XSetCloseDownMode</function>
can generate a
<errorname>BadValue</errorname>
error.
</para>
</sect1>
<sect1 id="Using_X_Server_Connection_Close_Operations_">
<title>Using X Server Connection Close Operations </title>
<!-- .XS -->
<!-- (SN Using X Server Connection Close Operations -->
<!-- .XE -->
<para>
<!-- .LP -->
When the X server's connection to a client is closed
either by an explicit call to
<function>XCloseDisplay</function>
or by a process that exits, the X server performs the following
automatic operations:
</para>
<itemizedlist>
<listitem>
<para>
It disowns all selections owned by the client
(see
<function>XSetSelectionOwner</function>).
</para>
</listitem>
<listitem>
<para>
It performs an
<function>XUngrabPointer</function>
and
<function>XUngrabKeyboard</function>
if the client has actively grabbed the pointer
or the keyboard.
</para>
</listitem>
<listitem>
<para>
It performs an
<function>XUngrabServer</function>
if the client has grabbed the server.
</para>
</listitem>
<listitem>
<para>
It releases all passive grabs made by the client.
</para>
</listitem>
<listitem>
<para>
It marks all resources (including colormap entries) allocated
by the client either as permanent or temporary,
depending on whether the close-down mode is
<symbol>RetainPermanent</symbol>
or
<symbol>RetainTemporary</symbol>.
However, this does not prevent other client applications from explicitly
destroying the resources (see
<function>XSetCloseDownMode</function>).
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
When the close-down mode is
<symbol>DestroyAll</symbol>,
the X server destroys all of a client's resources as follows:
</para>
<itemizedlist>
<listitem>
<para>
It examines each window in the client's save-set to determine if it is an inferior
(subwindow) of a window created by the client.
(The save-set is a list of other clients' windows
that are referred to as save-set windows.)
If so, the X server reparents the save-set window to the closest ancestor so
that the save-set window is not an inferior of a window created by the client.
The reparenting leaves unchanged the absolute coordinates (with respect to
the root window) of the upper-left outer corner of the save-set
window.
</para>
</listitem>
<listitem>
<para>
It performs a
<systemitem>MapWindow</systemitem>
request on the save-set window if the save-set window is unmapped.
The X server does this even if the save-set window was not an inferior of
a window created by the client.
</para>
</listitem>
<listitem>
<para>
It destroys all windows created by the client.
</para>
</listitem>
<listitem>
<para>
It performs the appropriate free request on each nonwindow resource created by
the client in the server (for example,
<type>Font</type>,
<type>Pixmap</type>,
<type>Cursor</type>,
<type>Colormap</type>,
and
<type>GContext</type>).
</para>
</listitem>
<listitem>
<para>
It frees all colors and colormap entries allocated by a client application.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
Additional processing occurs when the last connection to the X server closes.
An X server goes through a cycle of having no connections and having some
connections.
When the last connection to the X server closes as a result of a connection
closing with the close_mode of
<symbol>DestroyAll</symbol>,
the X server does the following:
</para>
<itemizedlist>
<listitem>
<para>
It resets its state as if it had just been
started.
The X server begins by destroying all lingering resources from
clients that have terminated in
<symbol>RetainPermanent</symbol>
or
<symbol>RetainTemporary</symbol>
mode.
</para>
</listitem>
<listitem>
<para>
It deletes all but the predefined atom identifiers.
</para>
</listitem>
<listitem>
<para>
It deletes all properties on all root windows (see section 4.3).
</para>
</listitem>
<listitem>
<para>
It resets all device maps and attributes
(for example, key click, bell volume, and acceleration)
as well as the access control list.
</para>
</listitem>
<listitem>
<para>
It restores the standard root tiles and cursors.
</para>
</listitem>
<listitem>
<para>
It restores the default font path.
</para>
</listitem>
<listitem>
<para>
It restores the input focus to state
<symbol>PointerRoot</symbol>.
</para>
</listitem>
</itemizedlist>
<para>
<!-- .LP -->
However, the X server does not reset if you close a connection with a close-down
mode set to
<symbol>RetainPermanent</symbol>
or
<symbol>RetainTemporary</symbol>.
</para>
</sect1>
<sect1 id="Using_Xlib_with_Threads">
<title>Using Xlib with Threads</title>
<!-- .XS -->
<!-- (SN Using Xlib with Threads -->
<!-- .XE -->
<para>
<!-- .LP -->
On systems that have threads, support may be provided to permit
multiple threads to use Xlib concurrently.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To initialize support for concurrent threads, use
<function>XInitThreads</function>.
<indexterm significance="preferred"><primary>XInitThreads</primary></indexterm>
<!-- .sM -->
</para>
<para>Status XInitThreads();</para>
<!-- .FN -->
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XInitThreads</function>
function initializes Xlib support for concurrent threads.
This function must be the first Xlib function a
multi-threaded program calls, and it must complete
before any other Xlib call is made.
This function returns a nonzero status if initialization was
successful; otherwise, it returns zero.
On systems that do not support threads, this function always returns zero.
</para>
<para>
<!-- .LP -->
It is only necessary to call this function if multiple threads
might use Xlib concurrently. If all calls to Xlib functions
are protected by some other access mechanism (for example,
a mutual exclusion lock in a toolkit or through explicit client
programming), Xlib thread initialization is not required.
It is recommended that single-threaded programs not call this function.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To lock a display across several Xlib calls, use
<function>XLockDisplay</function>.
<indexterm significance="preferred"><primary>XLockDisplay</primary></indexterm>
<!-- .sM -->
</para>
<funcsynopsis>
<funcprototype>
<funcdef>XLockDisplay</funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XLockDisplay</function>
function locks out all other threads from using the specified display.
Other threads attempting to use the display will block until
the display is unlocked by this thread.
Nested calls to
<function>XLockDisplay</function>
work correctly; the display will not actually be unlocked until
<function>XUnlockDisplay</function>
has been called the same number of times as
<function>XLockDisplay</function>.
This function has no effect unless Xlib was successfully initialized
for threads using
<function>XInitThreads</function>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To unlock a display, use
<function>XUnlockDisplay</function>.
<indexterm significance="preferred"><primary>XUnlockDisplay</primary></indexterm>
<!-- .sM -->
</para>
<funcsynopsis>
<funcprototype>
<funcdef>XUnlockDisplay</funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XUnlockDisplay</function>
function allows other threads to use the specified display again.
Any threads that have blocked on the display are allowed to continue.
Nested locking works correctly; if
<function>XLockDisplay</function>
has been called multiple times by a thread, then
<function>XUnlockDisplay</function>
must be called an equal number of times before the display is
actually unlocked.
This function has no effect unless Xlib was successfully initialized
for threads using
<function>XInitThreads</function>.
</para>
</sect1>
<sect1 id="Using_Internal_Connections">
<title>Using Internal Connections</title>
<!-- .XS -->
<!-- (SN Using Internal Connections -->
<!-- .XE -->
<para>
<!-- .LP -->
In addition to the connection to the X server, an Xlib implementation
may require connections to other kinds of servers (for example, to
input method servers as described in chapter 13). Toolkits and clients
that use multiple displays, or that use displays in combination with
other inputs, need to obtain these additional connections to correctly
block until input is available and need to process that input
when it is available. Simple clients that use a single display and
block for input in an Xlib event function do not need to use these
facilities.
</para>
<para>
<!-- .LP -->
To track internal connections for a display, use
<function>XAddConnectionWatch</function>.
</para>
<funcsynopsis>
<funcprototype>
<funcdef>type void XConnectionWatchProc</funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
<paramdef>int<parameter> fd</parameter></paramdef>
<paramdef>Bool<parameter> opening</parameter></paramdef>
<paramdef>XPointer<parameter> *watch_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>Status XAddConnectionWatch</funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>XWatchProc<parameter> procedure</parameter></paramdef>
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>procedure</emphasis>
</term>
<listitem>
<para>
Specifies the procedure to be called.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>client_data</emphasis>
</term>
<listitem>
<para>
Specifies the additional client data.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XAddConnectionWatch</function>
function registers a procedure to be called each time Xlib opens or closes an
internal connection for the specified display. The procedure is passed the
display, the specified client_data, the file descriptor for the connection,
a Boolean indicating whether the connection is being opened or closed, and a
pointer to a location for private watch data. If opening is
<symbol>True</symbol>,
the procedure can store a pointer to private data in the location pointed
to by watch_data;
when the procedure is later called for this same connection and opening is
<symbol>False</symbol>,
the location pointed to by watch_data will hold this same private data pointer.
</para>
<para>
<!-- .LP -->
This function can be called at any time after a display is opened.
If internal connections already exist, the registered procedure will
immediately be called for each of them, before
<function>XAddConnectionWatch</function>
returns.
<function>XAddConnectionWatch</function>
returns a nonzero status if the procedure is successfully registered;
otherwise, it returns zero.
</para>
<para>
<!-- .LP -->
The registered procedure should not call any Xlib functions.
If the procedure directly or indirectly causes the state of internal
connections or watch procedures to change, the result is not defined.
If Xlib has been initialized for threads, the procedure is called with
the display locked and the result of a call by the procedure to any
Xlib function that locks the display is not defined unless the executing
thread has externally locked the display using
<function>XLockDisplay</function>.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To stop tracking internal connections for a display, use
<function>XRemoveConnectionWatch</function>.
<indexterm significance="preferred"><primary>XRemoveConnectionWatch</primary></indexterm>
<!-- .sM -->
</para>
<para>
()
</para>
<funcsynopsis>
<funcprototype>
<funcdef>Status <function>XRemoveConnectionWatch</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>XWatchProc<parameter> procedure</parameter></paramdef>
<paramdef>XPointer<parameter> client_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>procedure</emphasis>
</term>
<listitem>
<para>
Specifies the procedure to be called.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>client_data</emphasis>
</term>
<listitem>
<para>
Specifies the additional client data.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XRemoveConnectionWatch</function>
function removes a previously registered connection watch procedure.
The client_data must match the client_data used when the procedure
was initially registered.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To process input on an internal connection, use
<function>XProcessInternalConnection</function>.
<indexterm significance="preferred"><primary>XProcessInternalConnection</primary></indexterm>
<!-- .sM -->
</para>
<para>
()
</para>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>XProcessInternalConnection</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>int<parameter> fd</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>fd</emphasis>
</term>
<listitem>
<para>
Specifies the file descriptor.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XProcessInternalConnection</function>
function processes input available on an internal connection.
This function should be called for an internal connection only
after an operating system facility (for example,
<function>select</function>
or
<function>poll</function>)
has indicated that input is available; otherwise,
the effect is not defined.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To obtain all of the current internal connections for a display, use
<function>XInternalConnectionNumbers</function>.
<indexterm significance="preferred"><primary>XInternalConnectionNumbers</primary></indexterm>
<!-- .sM -->
</para>
<para>
()
</para>
<funcsynopsis>
<funcprototype>
<funcdef>Status <function>XInternalConnectionNumbers</function></funcdef>
<paramdef>Display<parameter> *display</parameter></paramdef>
<paramdef>int **<parameter> fd</parameter></paramdef>
<paramdef>int *<parameter> count_return</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<!-- .FN -->
<variablelist>
<varlistentry>
<term>
<emphasis remap='I'>display</emphasis>
</term>
<listitem>
<para>
Specifies the connection to the X server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>fd_return</emphasis>
</term>
<listitem>
<para>
Returns the file descriptors.
<!-- .ds Cn file descriptors -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>count_return</emphasis>
</term>
<listitem>
<para>
Returns the number of (Cn.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XInternalConnectionNumbers</function>
function returns a list of the file descriptors for all internal
connections currently open for the specified display.
When the allocated list is no longer needed,
free it by using
<function>XFree</function>.
This functions returns a nonzero status if the list is successfully allocated;
otherwise, it returns zero.
</para>
</sect1>
</chapter>
