.\".U7
.\".UT "Display Functions" 2
\&
.sp 1
.ce 3
\s+1\fBChapter 2\fP\s-1

\s+1\fBDisplay Functions\fP\s-1
.sp 2
.nr H1 2
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.na
.LP
.XS
Chapter 2: Display Functions
.XE
Before your program can use a display, you must establish a connection
to the X server driving your display.
Once you have established a connection,
you then can use the Xlib macros and functions discussed in this chapter
to return information about the display.
This chapter discusses how to:
.IP \(bu 5
Open (connect) the display
.IP \(bu 5
Obtain information about the display, image formats, or a screen
.IP \(bu 5
Generate a NoOperation protocol request
.IP \(bu 5
Free client-created data
.IP \(bu 5
Close (disconnect) a display
.LP
Finally, the chapter concludes with a section that describes 
the operations that occur when the connection to the X server is closed.
.NH 2
Opening the Display
.XS
\*(SN Opening the Display
.XE
.LP
To open a connection to the X server controlling the specified display, use
.PN XOpenDisplay .
.IN "XOpenDisplay" "" "@DEF@"
.LP
.FD 0
.so ./Xsrc/XOpenDisplay.f
.FN	
.so ./Xsrc/display_name.a
On all non-UNIX systems, see the Xlib manual associated with your
operating system to determine the default for this argument.
.LP
On UNIX-based systems,
the display name or DISPLAY environment variable is a string
that has the format:
.LP
.Ds 0
.TA 1i
.ta 1i
	\fIhostname\fP\^:\^\fInumber\fP\^.\^\fIscreen_number\fP
.De
.IP \fIhostname\fP 1i
Specifies the name of the host machine on which the display is physically
attached.
You follow the hostname with either a single colon (:) or a double colon (::).
Each is discussed in the following paragraph.
.IP \fInumber\fP 1i
Specifies the number of the display server on that host machine.
You may optionally follow this display number with a period (.).
.IN "Screen"
.IP \fIscreen_number\fP 1i
Specifies which screen should be used on that host server.
Multiple screens can be connected to or controlled by a single X server.
The screen_number sets an internal variable that can be accessed by
using the 
.PN DefaultScreen 
macro (or the 
.PN XDefaultScreen
function if you are using other languages).
See Section 2.2.1 for further information. 
.LP
For example, the following would specify screen 2 of display 0 on the 
machine named mit-athena:
.LP
.Ds
mit-athena:0.2
.De
.LP
.so ./Xdescrip/XOpenDisplay.d
If the hostname is a host machine name and a single colon (:)
separates the hostname and display number,
.PN XOpenDisplay
connects using TCP streams.
If the hostname is 
\fIunix\fP
and a single colon (:) separates it from the display number, 
.PN XOpenDisplay
connects using UNIX domain IPC streams.
If the hostname is a host machine name and a double colon (::)
separates the hostname and display number,
.PN XOpenDisplay
connects using DECnet streams.
To use DECnet, however,
the X library implementation must have been built to support it.
A single server can support any or all of these transport mechanisms
simultaneously.
.LP
.IN "Display"
If successful, 
.PN XOpenDisplay 
returns a pointer to a 
.PN Display 
structure that is defined in 
.Pn < X11/Xlib.h >.
See Section 2.2.1,
for information about using macros and functions to obtain information from 
the
.PN Display 
structure.
If 
.PN XOpenDisplay 
does not succeed, it returns a NULL.
After a successful call to
.PN XOpenDisplay ,
all of the screens in the display may be used by the client application.
The screen number specified in the display_name argument will be returned 
by the 
.PN DefaultScreen
macro or the
.PN XDefaultScreen
function.
You can access elements of the
.PN Display
and
.PN Screen
structures by using the information macros or functions.
.LP
X servers may implement various types of access control mechanisms.
See section 7.11 for information about access control.
.NH 2
Obtaining Information About the Display, Image Formats, or Screens
.XS
\*(SN Obtaining Information About the Display, Image Formats, or Screens
.XE
.LP
The Xlib library provides a number of useful macros 
and corresponding functions that return data from the 
.PN Display 
structure.
The macros are to be used for C programming, while
their corresponding function equivalents are for other language bindings.
This section discusses the:
.IP \(bu 5
Display macros
.IP \(bu 5
Image format macros
.IP \(bu 5
Screen macros
.LP
.IN "Display" "data structure" 
All other members of the 
.PN Display 
structure (that is, those for which no macros are defined) are private to Xlib 
and must not be used.
That is,
applications must never directly modify or inspect
these private elements in the 
.PN Display 
structure.
.NT
Some of the functions in the following sections are misnamed
(for example,
.PN XDisplayWidth ).
These functions really should be named Screen\fIwhatever\fP 
and XScreen\fIwhatever\fP,
not Display\fIwhatever\fP or XDisplay\fIwhatever\fP.
Our apologies for the resulting confusion.
.NE
.NH 3
Display Macros 
.XS
\*(SN Display Macros
.XE
.LP
Applications should not directly modify any part of the
.PN Display
and
.PN Screen
structures.
The members should be considered read-only,
although they may change as the result of other operations on the display.
.LP 
The following lists the C language macros,
their corresponding function equivalents that are for other language bindings,
and what data they both can return.
.LP
.sp
.FD 0
AllPlanes(\^) 
.sp
.so ./Xsrc/XAllPlanes.f
.FN
.LP
.IN "AllPlanes" "" "@DEF@"
.IN "XAllPlanes" "" "@DEF@"
Both return a value with all bits set on suitable for use in a plane argument to
a procedure.
.LP
.sp
Both PlackPixel and WhitePixel can be used in implementing a ``monochrome''
application.
These pixel values are for permanently allocated entries in the default
color map.
The actual RGB 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.
.FD 0
BlackPixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
.so ./Xsrc/XBlkPixel.f
.FN
.LP
.IN "BlackPixel" "" "@DEF@"
.IN "XBlackPixel" "" "@DEF@"
Both return the black pixel value for the specified screen.
.LP
.sp
.FD 0
WhitePixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
.so ./Xsrc/XWPixel.f
.FN
.LP
.IN "WhitePixel" "" "@DEF@"
.IN "XWhitePixel" "" "@DEF@"
Both return the white pixel value for the specified screen. 
.LP
.sp
.FD 0
ConnectionNumber\^(\^\fIdisplay\fP\^)
.sp
.so ./Xsrc/Xdpyno.f
.FN
.LP
.IN "ConnectionNumber" "" "@DEF@"
.IN "XConnectionNumber" "" "@DEF@"
Both return a connection number for the specified display.
On a UNIX-based system,
this is the file descriptor of the connection.
.LP
.sp
.FD 0
DefaultColormap\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
.so ./Xsrc/XDefClrmap.f
.FN
.LP
.IN "DefaultColormap" "" "@DEF@"
.IN "XDefaultColormap" "" "@DEF@"
Both return the default Colormap ID for allocation on the specified screen.
Most routine allocations of color should be made out of this color map.
.LP
.sp
.FD 0
DefaultDepth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
.so ./Xsrc/XDefDepth.f
.FN
.LP
.IN "DefaultDepth" "" "@DEF@"
.IN "XDefaultDepth" "" "@DEF@"
Both return the depth (number of planes) of the default root window for the
specified screen.
Other depths may also be supported on this screen.
See
.PN XMatchVisualInfo
in Chapter 10 to find out how to determine what depths may be available.
.LP
.sp
.FD 0
DefaultGC\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
.so ./Xsrc/XDefGC.f
.FN
.LP
.IN "DefaultGC" "" "@DEF@"
.IN "XDefaultGC" "" "@DEF@"
Both return the default graphics context for the root window of the 
specified screen.
This GC is created for the convenience of simple applications
and contains the default GC components with the foreground and
background pixel values initialized to the black and white
pixels, respectively, for the screen.
You can modify its contents freely because it is not used in any Xlib
function.
.LP
.sp
.FD 0
DefaultRootWindow\^(\^\fIdisplay\fP\^)
.sp
.so ./Xsrc/XDefRootWin.f
.FN
.LP
.IN "DefaultRootWindow" "" "@DEF@"
.IN "XDefaultRootWindow" "" "@DEF@"
Both return the root window for the default screen.
.LP
.sp
.FD 0
DefaultScreen\^(\^\fIdisplay\fP\^)
.sp
.so ./Xsrc/XDefScreen.f
.FN
.LP
.IN "DefaultScreen" "" "@DEF@"
.IN "XDefaultScreen" "" "@DEF@"
Both return the default screen number referenced in the 
.PN XOpenDisplay
routine. 
This macro and function should be used to retrieve the screen number in applications
that will use only a single screen.
.LP
.sp
.FD 0
DefaultVisual\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
.so ./Xsrc/XDefVisual.f
.FN
.LP
.IN "DefaultVisual" "" "@DEF@"
.IN "XDefaultVisual" "" "@DEF@"
Both return the default visual type for the specified screen.
See section 3.1 for further information about visual types.
.LP
.sp
.FD 0
DisplayCells\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
.so ./Xsrc/XDispCells.f
.FN
.LP
.IN "DisplayCells" "" "@DEF@"
.IN "XDisplayCells" "" "@DEF@"
Both return the number of entries in the default color map.
.LP
.sp
.FD 0
DisplayPlanes\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
.so ./Xsrc/XDispPlanes.f
.FN
.LP
.IN "DisplayPlanes" "" "@DEF@"
.IN "XDisplayPlanes" "" "@DEF@"
Both return the depth of the root window of the specified screen.
See the glossary for a discussion of depth.
.LP
.sp
.FD 0
DisplayString\^(\^\fIdisplay\fP\^)
.sp
.so ./Xsrc/XDispStrng.f
.FN
.LP
.IN "DisplayString" "" "@DEF@"
.IN "XDisplayString" "" "@DEF@"
Both return the string that was passed to 
.PN XOpenDisplay
when the current display was opened. 
On UNIX-based systems, 
if the passed string was NULL, this macro returns the value of
the DISPLAY environment variable when the current display was opened.
.IN "Unix System Call" "fork"
This macro is useful to applications that invoke the 
.PN fork
system call and want to open a new connection to the same display from the 
child process.
.LP
.sp
.FD 0
ImageByteOrder\^(\^\fIdisplay\fP\^)
.sp
.so ./Xsrc/XByteOrder.f
.FN
.LP
.IN "ImageByteOrder" "" "@DEF@"
.IN "XImageByteOrder" "" "@DEF@"
Both specify the required byte order for images for each scanline unit in 
XYFormat (bitmap) or for each pixel value in 
ZFormat.
The macro and function can return either
.PN LSBFirst 
or 
.PN MSBFirst .
.LP
.sp
.FD 0
LastKnownRequestProcessed\^(\^\fIdisplay\fP\^)
.sp
int XLastKnownRequestProcessed\^(\^\fIdisplay\fP\^)
.br
     Display *\fIdisplay\fP\^;
.FN
.IN "LastKnownRequestProcessed" "" "@DEF@"
.IN "XLastKnownRequestProcessed" "" "@DEF@"
Both extract the full serial number of the last request known by Xlib
to have been processed by the X server.
This number is automatically set by Xlib when replies, events, and errors
are received.
.LP
.sp
.FD 0
NextRequest\^(\^\fIdisplay\fP\^)
.sp
int XNextRequest\^(\^\fIdisplay\fP\^)
.br
     Display *\fIdisplay\fP\^;
.FN
.IN "NextRequest" "" "@DEF@"
.IN "XNextRequest" "" "@DEF@"
Both extract the full serial number that is to be used for the next
request.
Serial numbers are maintained separately for each display connection.
.LP
.sp
.FD 0
ProtocolVersion\^(\^\fIdisplay\fP\^)
.sp
.so ./Xsrc/XProtoVers.f
.FN
.LP
.IN "ProtocolVersion" "" "@DEF@"
.IN "XProtocolVersion" "" "@DEF@"
Both return the major version number (11) of the X protocol associated with 
the connected display.
.LP
.sp
.FD 0
ProtocolRevision\^(\^\fIdisplay\fP\^)
.sp
.so ./Xsrc/XProtoRev.f
.FN
.LP
.IN "ProtocolRevision" "" "@DEF@"
.IN "XProtocolRevision" "" "@DEF@"
Both return the minor protocol revision number of the X server.
.LP
.sp
.FD 0
QLength\^(\^\fIdisplay\fP\^)
.sp
.so ./Xsrc/XQLenth.f
.FN
.LP
.IN "QLength" "" "@DEF@"
.IN "XQLength" "" "@DEF@"
Both return the length of the event queue for the connected display.
Note that there may be more events that have not been read into
the queue yet.
.LP
.sp
.FD 0
RootWindow\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
.so ./Xsrc/XRootWindow.f
.FN
.LP
.IN "Window" "RootWindow"
.IN "RootWindow" "" "@DEF@"
.IN "Window" "XRootWindow"
.IN "XRootWindow" "" "@DEF@"
Both return the root window.
This macro and function are useful with functions that take a
parent window as an argument.
.LP
.sp
.FD 0
ScreenCount\^(\^\fIdisplay\fP\^)
.sp
.so ./Xsrc/XScrnCount.f
.FN
.LP
.IN "ScreenCount" "" "@DEF@"
.IN "XScreenCount" "" "@DEF@"
Both return the number of available screens.
.LP
.sp
.FD 0
ServerVendor\^(\^\fIdisplay\fP\^)
.sp
.so ./Xsrc/XSrvVendor.f
.FN
.LP
.IN "ServerVendor" "" "@DEF@"
.IN "XServerVendor" "" "@DEF@"
Both return a pointer to a null-terminated string that provides
some identification of the owner of the X server implementation.
.LP
.sp
.FD 0
VendorRelease\^(\^\fIdisplay\fP\^)
.sp
.so ./Xsrc/XVenRelease.f
.FN
.LP
.IN "VendorRelease" "" "@DEF@"
.IN "XVendorRelease" "" "@DEF@"
Both return a number related to a vendor's release of the X server.
.NH 3
Image Format Macros
.XS
\*(SN Image Format Macros
.XE
.LP
Applications are required to present data to the display 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 6.7 and 10.9 for further information about these
utility functions.
.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 simple applications.
.LP
.sp
.FD 0
BitmapBitOrder\^(\^\fIdisplay\fP\^)
.sp
.so ./Xsrc/XBitBitOdr.f
.FN
.LP
.IN "BitmapBitOrder" "" "@DEF@"
.IN "XBitmapBitOrder" "" "@DEF@"
Within each bitmap unit, the leftmost bit in the bitmap as displayed
on the screen is either the least or most significant bit in the
unit.
This macro and function can return either
.PN LSBFirst
or 
.PN MSBFirst .
.LP
.sp
.FD 0
BitmapPad\^(\^\fIdisplay\fP\^)
.sp
.so ./Xsrc/XBitmapPad.f
.FN
.LP
.IN "BitmapPad" "" "@DEF@"
.IN "XBitmapPad" "" "@DEF@"
Each scanline must be padded to a multiple of bits returned
by this macro or function.
.LP
.sp
.FD 0
BitmapUnit\^(\^\fIdisplay\fP\^)
.sp
.so ./Xsrc/XBitmapUnit.f
.FN
.LP
.IN "BitmapUnit" "" "@DEF@"
.IN "XBitmapUnit" "" "@DEF@"
Both return the size of a bitmap's scanline unit in bits.
The scanline is calculated in multiples of this value.
It is always less than the bitmap scanline pad.
.\".LP
.\".sp
.\".FD 0
.\"DisplayHeight\^(\^\fIdisplay\fP\^, \^\fIscreen\fP\^)
.\".sp
.\".so ./Xsrc/XDispHeight.f
.\".FN
.\".LP
.\".IN "DisplayHeight" "" "@DEF@"
.\".IN "XDisplayHeight" "" "@DEF@"
.\"Both return an integer that describes the height of the screen
.\"in pixels.
.LP
.sp
.FD 0
DisplayHeightMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
.so ./Xsrc/XDispHeight.f
.FN
.LP
.IN "DisplayHeightMM" "" "@DEF@"
.IN "XDisplayHeight" "" "@DEF@"
Both return the height of the specified screen in millimeters.
.LP
.sp
.FD 0
DisplayWidth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
.so ./Xsrc/XDispWidth.f
.FN
.LP
.IN "DisplayWidth" "" "@DEF@"
.IN "XDisplayWidth" "" "@DEF@"
Both return an integer that describes the width of the screen
in pixels.
.LP
.sp
.FD 0
DisplayWidthMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
.so ./Xsrc/XDWidthMM.f
.FN
.LP
.IN "DisplayWidthMM" "" "@DEF@"
.IN "XDisplayWidthMM" "" "@DEF@"
Both return the width of the specified screen in millimeters.
.NH 3
Screen Information Macros
.XS
\*(SN Screen Information Macros
.XE
.LP
The following lists the C language macros,
their corresponding function equivalents that are for other language bindings,
and what data they both can return.
These macros or functions all take a pointer to the appropriate screen
structure.
.LP
.sp
.FD 0
BlackPixelOfScreen\^(\^\fIscreen\fP\^)
.sp
unsigned long XBlackPixelOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.LP
.IN "BlackPixelOfScreen" "" "@DEF@"
.IN "XBlackPixelOfScreen" "" "@DEF@"
Both return the black pixel value of the specified screen.
.LP
.sp
.FD 0
WhitePixelOfScreen\^(\^\fIscreen\fP\^)
.sp
unsigned long XWhitePixelOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IN "WhitePixelOfScreen" "" "@DEF@"
.IN "XWhitePixelOfScreen" "" "@DEF@"
Both return the white pixel value of the specified screen.
.LP
.sp
.FD 0
CellsOfScreen\^(\^\fIscreen\fP\^)
.sp
int XCellsOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.LP
.IN "CellsOfScreen" "" "@DEF@"
.IN "XCellsOfScreen" "" "@DEF@"
Both return the number of color map cells of the specified screen.
.LP
.sp
.FD 0
DefaultColormapOfScreen\^(\^\fIscreen\fP\^)
.sp
Colormap XDefaultColormapOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.LP
.IN "DefaultColormapOfScreen" "" "@DEF@"
.IN "XDefaultColormapOfScreen" "" "@DEF@"
Both return the default color map of the specified screen.
.LP
.sp
.FD 0
DefaultDepthOfScreen\^(\^\fIscreen\fP\^)
.sp 
int XDefaultDepthOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.LP
.IN "DefaultDepthOfScreen" "" "@DEF@"
.IN "XDefaultDepthOfScreen" "" "@DEF@"
Both return the default depth of the specified screen.
.LP
.sp
.FD 0
DefaultGCOfScreen\^(\^\fIscreen\fP\^)
.sp
GC XDefaultGCOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.LP
.IN "DefaultGCOfScreen" "" "@DEF@"
.IN "XDefaultGCOfScreen" "" "@DEF@"
Both return the default graphics context (GC) of the specified screen.
.LP
.sp
.FD 0
DefaultScreenOfDisplay\^(\^\fIdisplay\fP\^)
.sp
Screen *XDefaultScreenOfDisplay\^(\^\fIdisplay\fP\^)
.br
      Display *\fIdisplay\fP\^;
.FN
.LP
.IN "DefaultScreenOfDisplay" "" "@DEF@"
.IN "XDefaultScreenOfDisplay" "" "@DEF@"
Both return the default screen of the specified display.
.LP
.sp
.FD 0
DefaultVisualOfScreen\^(\^\fIscreen\fP\^)
.sp
Visual *XDefaultVisualOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.LP
.IN "DefaultVisualOfScreen" "" "@DEF@"
.IN "XDefaultVisualOfScreen" "" "@DEF@"
Both return the default visual of the specified screen.
See Section 3.1 for information on visual types.
.LP
.sp
.FD 0
DoesBackingStore\^(\^\fIscreen\fP\^)
.sp
int XDoesBackingStore\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.LP
.IN "DoesBackingStore" "" "@DEF@"
.IN "XDoesBackingStore" "" "@DEF@"
Both return a value indicating whether the screen supports backing
stores.
The value returned can be one of 
.PN WhenMapped ,
.PN NotUseful ,
or
.PN Always .
See section 3.2.4 for a discussion of the backing store.
.LP
.sp
.FD 0
DoesSaveUnders\^(\^\fIscreen\fP\^)
.sp
Bool XDoesSaveUnders\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.LP
.IN "DoesSaveUnders" "" "@DEF@"
.IN "XDoesSaveUnders" "" "@DEF@"
Both return a boolean value indicating whether the
screen supports save unders.
If
.PN True ,
the screen supports save unders.
If
.PN False ,
the screen does not support save unders.
See section 3.2.6 for a discussion of the save under.
.LP
.sp
.FD 0
DisplayOfScreen\^(\^\fIscreen\fP\^)
.sp
Display *XDisplayOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.LP
.IN "DisplayOfScreen" "" "@DEF@"
.IN "XDisplayOfScreen" "" "@DEF@"
Both return the display of the specified screen.
.LP
.sp
.FD 0
EventMaskOfScreen\^(\^\fIscreen\fP\^)
.sp
long XEventMaskOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.LP
.IN "EventMaskOfScreen" "" "@DEF@"
.IN "XEventMaskOfScreen" "" "@DEF@"
Both return the initial root event mask for the specified screen.
.LP
.sp
.FD 0
HeightOfScreen\^(\^\fIscreen\fP\^)
.sp
int XHeightOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.LP
.IN "HeightOfScreen" "" "@DEF@"
.IN "XHeightOfScreen" "" "@DEF@"
Both return the height of the specified screen.
.LP
.sp
.FD 0
HeightMMOfScreen\^(\^\fIscreen\fP\^)
.sp
int XHeightMMOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.LP
.IN "HeightMMOfScreen" "" "@DEF@"
.IN "XHeightMMOfScreen" "" "@DEF@"
Both return the height of the specified screen in millimeters.
.LP
.sp
.FD 0
MaxCmapsOfScreen\^(\^\fIscreen\fP\^)
.sp
int XMaxCmapsOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.LP
.IN "MaxCmapsOfScreen" "" "@DEF@"
.IN "XMaxCmapsOfScreen" "" "@DEF@"
Both return the maximum number of color maps supported by the specified screen.
.LP
.sp
.FD 0
MinCmapsOfScreen\^(\^\fIscreen\fP\^)
.sp
int XMinCmapsOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.LP
.IN "MinCmapsOfScreen" "" "@DEF@"
.IN "XMinCmapsOfScreen" "" "@DEF@"
Both return the minimum number of color maps supported by the specified screen.
.LP
.sp
.FD 0
PlanesOfScreen\^(\^\fIscreen\fP\^)
.sp
int XPlanesOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.LP
.IN "PlanesOfScreen" "" "@DEF@"
.IN "XPlanesOfScreen" "" "@DEF@"
Both return the number of planes in the specified screen.
.LP
.sp
.FD 0
RootWindowOfScreen\^(\^\fIscreen\fP\^)
.sp
Window XRootWindowOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.LP
.IN "RootWindowOfScreen" "" "@DEF@"
.IN "XRootWindowOfScreen" "" "@DEF@"
Both return the root window of the specified screen.
.LP
.sp
.FD 0
ScreenOfDisplay\^(\^\fIdisplay\fP, \fIscreen_number\fP\^)
.sp
Screen *XScreenOfDisplay\^(\^\fIdisplay\fP, \fIscreen_number\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fIscreen_number\fP\^;
.FN
.LP
.IN "ScreenOfDisplay" "" "@DEF@"
.IN "XScreenOfDisplay" "" "@DEF@"
Both return a pointer to the screen of the specified display.
.LP
.sp
.FD 0
WidthOfScreen\^(\^\fIscreen\fP\^)
.sp
int XWidthOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.LP
.IN "WidthOfScreen" "" "@DEF@"
.IN "XWidthOfScreen" "" "@DEF@"
Both return the width of the specified screen.
.LP
.sp
.FD 0
WidthMMOfScreen\^(\^\fIscreen\fP\^)
.sp
int XWidthMMOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.LP
.IN "WidthMMOfScreen" "" "@DEF@"
.IN "XWidthMMOfScreen" "" "@DEF@"
Both return the width of the specified screen in millimeters.
.NH 2
Generating a NoOperation Protocol Request
.XS
\*(SN Generating a NoOperation Protocol Request
.XE
.LP
To execute a 
.PN NoOperation 
protocol request, use
.PN XNoOp .
.IN "XNoOp" "" "@DEF@"
.FD 0
.so ./Xsrc/XNoop.f
.FN
.so ./Xsrc/display.a
.LP
The
.PN XNoOp
function sends a 
.PN NoOperation 
protocol request to the X server,
thereby exercising the connection.
It does not flush the output buffer.
.NH 2
Freeing Client-Created Data
.XS
\*(SN Freeing Client-Created Data
.XE
.LP
To free any in-memory data that was created by an Xlib function, use
.PN XFree .
.IN "XFree" "" "@DEF@"
.FD 0
.so ./Xsrc/XFree.f
.FN
.so ./Xsrc/data_free.a
.LP
.so ./Xdescrip/XFree.d
.NH 2
Closing the Display
.XS
\*(SN Closing the Display
.XE
.LP
To close or disconnect a display from the X server, use
.PN XCloseDisplay .
.IN "XCloseDisplay" "" "@DEF@"
.LP
.FD 0
.so ./Xsrc/XCloseDisp.f
.FN
.so ./Xsrc/display.a
.LP
.so ./Xdescrip/XCloseDisp.d
The 
.PN XCloseDisplay 
function destroys all windows, resource IDs (Window, Font, Pixmap, Colormap, 
Cursor, and GContext), or other resources (GCs) that the 
client application has created on this display, unless the closedown mode
of the resource has been changed (see
.PN XSetCloseDownMode ).
Therefore, these windows, resource IDs, and other resources should never be 
referenced again.
In addition, this function discards
any output requests that have been buffered but have not yet been sent. 
Because these operations automatically (implicitly) occur if a process exits,
you normally do not have to call 
.PN XCloseDisplay 
explicitly.
.IN "Resource IDs"
.IN "XCloseDisplay"
.NH 2
X Server Connection Close Operations 
.XS
\*(SN X Server Connection Close Operations
.XE
.LP
When the X server's connection to a client is closed,
either by an explicit call to
.PN XCloseDisplay
or by a process that exits, the X server performs these
automatic operations:
.IP \(bu 5
All selections (see 
.PN XSetSelectionOwner )
owned by the client are disowned.
.IP \(bu 5
Performs an
.PN XUngrabPointer
and
.PN XUngrabKeyboard 
if the client application
has actively grabbed the pointer or the keyboard. 
These functions are described in Chapter 7.
.IP \(bu 5
Performs an
.PN XUngrabServer 
if the client has grabbed the server.
This function is described in Chapter 7.
.IP \(bu 5
Releases all passive grabs made by the client application.  
.IP \(bu 5
Marks all resources (including color map entries) allocated 
by the client application either as permanent or temporary, 
depending on whether the close_mode argument is either
.PN RetainPermanent
or
.PN RetainTemporary .
However, this does not prevent other client applications from explicitly
destroying the resources.
(See below and
.PN XSetCloseDownMode 
in Chapter 7 for further information.)
.LP
When the mode is
.PN DestroyAll ,
the X server destroys all of a client application's resources as follows:
.IP \(bu 5
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, and windows in this list are
referred to as a save-set window.)
If so, the X server reparents the save-set window to the closest ancestor such
that the save-set window is not an inferior of a window created by the client.
.IP \(bu 5
Performs a
.PN MapWindow
request on the save-set window if the save-set window is unmapped.
The X server does this even if the save-set window was not an inferior of 
a window created by the client.
.IP \(bu 5
Examines each window in the client's save-set,
and destroys all windows created by the client.
.IP \(bu 5
Performs the appropriate free request on each nonwindow resource created by
the client in the server (for example, Font, Pixmap, Cursor, Colormap, 
and GContext).
.IP \(bu 5
Frees all colors and color map entries allocated by a client application.
.LP
Additional processing occurs when the last connection to the X server closes.
An X server goes through a cycle of having no connections and having some
connections.
When the last connection to the X server closes as a result of a connection
closing with the close_mode of
.PN DestroyAll 
(that is, the X server reverts
to the state of having no connections), the X server: 
.IP \(bu 5
Resets its state, as if it had just been
started.  
The X server begins by destroying all lingering resources from
clients that have terminated in 
.PN RetainPermanent
or
.PN RetainTemporary
mode.
.IP \(bu 5
Deletes all but the predefined atom identifiers.
.IP \(bu 5
Deletes all properties on all root windows.
See Chapter 4 for information about properties.
.IP \(bu 5
Resets all device maps and attributes 
(for example, key click, bell volume, and acceleration) 
and the access control list.
.IP \(bu 5
Restores the standard root tiles and cursors.
.IP \(bu 5
Restores the default font path.
.IP \(bu 5
Restores the input focus to state
.PN PointerRoot .
.LP
However, the X server does not reset if you close a connection with a close_down
mode argument set to
.PN RetainPermanent
or
.PN RetainTemporary .
.bp
