⟦03bdfdb5d⟧

TextFile

\&
.sp 1
.ce 3
\s+1\fBChapter 2\fP\s-1

\s+1\fBDisplay Functions\fP\s-1
.sp 2
.nr H1 2
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.na
.LP
.XS
Chapter 2: Display Functions
.XE
Before your program can use a display, you must establish a connection
to the X server.
Once you have established a connection,
you then can use the Xlib macros and functions discussed in this chapter
to return information about the display.
This chapter discusses how to:
.IP \(bu 5
Open (connect to) the display
.IP \(bu 5
Obtain information about the display, image format, and screen
.IP \(bu 5
Free client-created data
.IP \(bu 5
Close (disconnect from) a display
.LP
The chapter concludes with a general discussion of what
occurs 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 that controls a display, use
.PN XOpenDisplay .
.IN "XOpenDisplay" "" "@DEF@"
.LP
.\" Start marker code here
.FD 0
.\" $Header: XOpenDisplay.f,v 1.1 88/02/26 10:01:40 mento Exp $
Display *XOpenDisplay\^(\^\fIdisplay_name\fP\^)
.br
      char *\fIdisplay_name\fP\^;
.FN	
.\" $Header: display_name.a,v 1.2 88/03/30 14:12:53 mento Exp $
.IP \fIdisplay_name\fP 1i
Specifies the hardware display name, which determines the display
and communications domain to be used.
On a POSIX-conformant system, if the display_name is NULL, 
it defaults to the value of the DISPLAY environment variable. 
.IN "Environment" "DISPLAY"
.\" End marker code here
.LP
The encoding and interpretation of the display name is
implementation dependent.
Strings in the Host Portable Character Encoding are supported;
support for other characters is implementation dependent.
On POSIX-conformant systems,
the display name or DISPLAY environment variable can be a string in the format:
.LP
.\" Start marker code here
.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 (::).
.IP \fInumber\fP 1i
Specifies the number of the display server on that host machine.
You may optionally follow this display number with a period (.).
A single CPU can have more than one display.
Multiple displays are usually numbered starting with zero.
.IN "Screen"
.IP \fIscreen_number\fP 1i
Specifies the screen to be used on that server.
Multiple screens can be controlled by a single X server.
The screen_number sets an internal variable that can be accessed by
using the 
.PN DefaultScreen 
macro or the 
.PN XDefaultScreen
function if you are using languages other than C (see section 2.2.1).
.\" End marker code here
.LP
For example, the following would specify screen 1 of display 0 on the 
machine named ``dual-headed'':
.LP
.Ds
dual-headed:0.1
.De
.LP
.\" $Header: XOpenDisplay.d,v 1.6 88/08/16 08:38:55 mento Exp $
The
.PN XOpenDisplay
function returns a 
.PN Display 
structure that serves as the
connection to the X server and that contains all the information
about that X server.
.PN XOpenDisplay
connects your application to the X server through TCP 
or DECnet communications protocols,
or through some local inter-process communication protocol.
.IN "Protocol" "TCP"
.IN "Protocol" "DECnet"
If the 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 not specified,
Xlib uses whatever it believes is the fastest transport.
If the hostname is a host machine name and a double colon (::)
separates the hostname and display number,
.PN XOpenDisplay
connects using DECnet.
A single X server can support any or all of these transport mechanisms
simultaneously.
A particular Xlib implementation can support many more of these transport
mechanisms.
.LP
.IN "Display"
If successful, 
.PN XOpenDisplay 
returns a pointer to a 
.PN Display 
structure,
which is defined in 
.Pn < X11/Xlib.h >.
If 
.PN XOpenDisplay 
does not succeed, it returns NULL.
After a successful call to
.PN XOpenDisplay ,
all of the screens in the display can be used by the client.
The screen number specified in the display_name argument is returned 
by the 
.PN DefaultScreen
macro (or the
.PN XDefaultScreen
function).
You can access elements of the
.PN Display
and
.PN Screen
structures only by using the information macros or functions.
For information about using macros and functions to obtain information from 
the
.PN Display 
structure,
see section 2.2.1.
.LP
X servers may implement various types of access control mechanisms
(see section 9.8).
.NH 2
Obtaining Information about the Display, Image Formats, or Screens
.XS
\*(SN Obtaining Information about the Display, Image Formats, or Screens
.XE
.LP
The Xlib library provides a number of useful macros 
and corresponding functions that return data from the 
.PN Display 
structure.
The macros are used for C programming, 
and their corresponding function equivalents are for other language bindings.
This section discusses the:
.IP \(bu 5
Display macros
.IP \(bu 5
Image format 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.
Applications must never directly modify or inspect these private members of the 
.PN Display 
structure.
.NT Note
The
.PN XDisplayWidth ,
.PN XDisplayHeight ,
.PN XDisplayCells ,
.PN XDisplayPlanes ,
.PN XDisplayWidthMM ,
and
.PN XDisplayHeightMM
functions in the next sections are misnamed.
These functions really should be named Screen\fIwhatever\fP 
and XScreen\fIwhatever\fP, not Display\fIwhatever\fP or XDisplay\fIwhatever\fP.
Our apologies for the resulting confusion.
.NE
.NH 3
Display Macros 
.XS
\*(SN Display Macros
.XE
.LP
Applications should not directly modify any part of the
.PN Display
and
.PN Screen
structures.
The members should be considered read-only,
although they may change as the result of other operations on the display.
.LP 
The following lists the C language macros,
their corresponding function equivalents that are for other language bindings,
and what data they both can return.
.LP
.sp
.\" Start marker code here
.FD 0
AllPlanes
.sp
unsigned long XAllPlanes(\^) 
.FN
.\" End marker code here
.LP
.IN "AllPlanes" "" "@DEF@"
.IN "XAllPlanes" "" "@DEF@"
Both return a value with all bits set to 1 suitable for use in a plane argument to
a procedure.
.LP
.sp
Both 
.PN BlackPixel 
and 
.PN WhitePixel 
can be used in implementing a monochrome application.
These pixel values are for permanently allocated entries in the default
colormap.
The actual RGB (red, green, and blue) values are settable on some screens 
and, in any case, may not actually be black or white.
The names are intended to convey the expected relative intensity of the colors.
.\" Start marker code here
.FD 0
BlackPixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
unsigned long XBlackPixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fIscreen_number\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the appropriate screen number on the host server.
.\" End marker code here
.LP
.IN "BlackPixel" "" "@DEF@"
.IN "XBlackPixel" "" "@DEF@"
Both return the black pixel value for the specified screen.
.LP
.sp
.\" Start marker code here
.FD 0
WhitePixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
unsigned long XWhitePixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fIscreen_number\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the appropriate screen number on the host server.
.\" End marker code here
.LP
.IN "WhitePixel" "" "@DEF@"
.IN "XWhitePixel" "" "@DEF@"
Both return the white pixel value for the specified screen. 
.LP
.sp
.\" Start marker code here
.FD 0
ConnectionNumber\^(\^\fIdisplay\fP\^)
.sp
int XConnectionNumber\^(\^\fIdisplay\fP\^)
.br
      Display *\fIdisplay\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.LP
.IN "ConnectionNumber" "" "@DEF@"
.IN "XConnectionNumber" "" "@DEF@"
Both return a connection number for the specified display.
On a POSIX-conformant system,
this is the file descriptor of the connection.
.LP
.sp
.\" Start marker code here
.FD 0
DefaultColormap\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
Colormap XDefaultColormap\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fIscreen_number\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the appropriate screen number on the host server.
.\" End marker code here
.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 colormap.
.LP
.sp
.\" Start marker code here
.FD 0
DefaultDepth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
int XDefaultDepth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fIscreen_number\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the appropriate screen number on the host server.
.\" End marker code here
.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 ).
.LP
.sp
.IN "XListDepths" "" "@DEF@"
To determine the number of depths that are available on a given screen, use
.PN XListDepths .
.\" Start marker code here
.FD 0
int *XListDepths\^(\^\fIdisplay\fP, \fIscreen_number\fP, \fIcount_return\fP\^)
.br
      Display *\fIdisplay\fP;
.br
      int \fIscreen_number\fP;
.br
      int *\fIcount_return\fP;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the appropriate screen number on the host server.
.ds Cn depths
.IP \fIcount_return\fP 1i
Returns the number of \*(Cn.
.\" End marker code here
.LP
The
.PN XListDepths
function returns the array of depths 
that are available on the specified screen.
If the specified screen_number is valid and sufficient memory for the array
can be allocated,
.PN XListDepths
sets count_return to the number of available depths.
Otherwise, it does not set count_return and returns NULL.
To release the memory allocated for the array of depths, use
.PN XFree .
.LP
.sp
.\" Start marker code here
.FD 0
DefaultGC\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
GC XDefaultGC\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fIscreen_number\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the appropriate screen number on the host server.
.\" End marker code here
.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 for the screen, respectively.
You can modify its contents freely because it is not used in any Xlib
function.
This GC should never be freed.
.LP
.sp
.\" Start marker code here
.FD 0
DefaultRootWindow\^(\^\fIdisplay\fP\^)
.sp
Window XDefaultRootWindow\^(\^\fIdisplay\fP\^)
.br
      Display *\fIdisplay\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.LP
.IN "DefaultRootWindow" "" "@DEF@"
.IN "XDefaultRootWindow" "" "@DEF@"
Both return the root window for the default screen.
.LP
.sp
.\" Start marker code here
.FD 0
DefaultScreenOfDisplay\^(\^\fIdisplay\fP\^)
.sp
Screen *XDefaultScreenOfDisplay\^(\^\fIdisplay\fP\^)
.br
      Display *\fIdisplay\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.LP
.IN "DefaultScreenOfDisplay" "" "@DEF@"
.IN "XDefaultScreenOfDisplay" "" "@DEF@"
Both return a pointer to the default screen.
.LP
.sp
.\" Start marker code here
.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
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the appropriate screen number on the host server.
.\" End marker code here
.LP
.IN "ScreenOfDisplay" "" "@DEF@"
.IN "XScreenOfDisplay" "" "@DEF@"
Both return a pointer to the indicated screen.
.LP
.sp
.\" Start marker code here
.FD 0
DefaultScreen\^(\^\fIdisplay\fP\^)
.sp
int XDefaultScreen\^(\^\fIdisplay\fP\^)
.br
      Display *\fIdisplay\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.LP
.IN "DefaultScreen" "" "@DEF@"
.IN "XDefaultScreen" "" "@DEF@"
Both return the default screen number referenced by the 
.PN XOpenDisplay
function. 
This macro or function should be used to retrieve the screen number 
in applications that will use only a single screen.
.LP
.sp
.\" Start marker code here
.FD 0
DefaultVisual\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
Visual *XDefaultVisual\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fIscreen_number\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the appropriate screen number on the host server.
.\" End marker code here
.LP
.IN "DefaultVisual" "" "@DEF@"
.IN "XDefaultVisual" "" "@DEF@"
Both return the default visual type for the specified screen.
For further information about visual types,
see section 3.1.
.LP
.sp
.\" Start marker code here
.FD 0
DisplayCells\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
int XDisplayCells\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fIscreen_number\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the appropriate screen number on the host server.
.\" End marker code here
.LP
.IN "DisplayCells" "" "@DEF@"
.IN "XDisplayCells" "" "@DEF@"
Both return the number of entries in the default colormap.
.LP
.sp
.\" Start marker code here
.FD 0
DisplayPlanes\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
int XDisplayPlanes\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fIscreen_number\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the appropriate screen number on the host server.
.\" End marker code here
.LP
.IN "DisplayPlanes" "" "@DEF@"
.IN "XDisplayPlanes" "" "@DEF@"
Both return the depth of the root window of the specified screen.
For an explanation of depth,
see the glossary.
.LP
.sp
.\" Start marker code here
.FD 0
DisplayString\^(\^\fIdisplay\fP\^)
.sp
char *XDisplayString\^(\^\fIdisplay\fP\^)
.br
      Display *\fIdisplay\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.LP
.IN "DisplayString" "" "@DEF@"
.IN "XDisplayString" "" "@DEF@"
Both return the string that was passed to 
.PN XOpenDisplay
when the current display was opened. 
On POSIX-conformant systems, 
if the passed string was NULL, these return the value of
the DISPLAY environment variable when the current display was opened.
.IN "POSIX System Call" "fork"
These are useful to applications that invoke the 
.PN fork
system call and want to open a new connection to the same display from the 
child process as well as for printing error messages.
.LP
.sp
.\" Start marker code here
.FD 0
long XMaxRequestSize(\^\fIdisplay\fP\^)
	Display *\fIdisplay\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.IN "XMaxRequestSize" "" "@DEF@"
.LP
.PN XMaxRequestSize
returns the maximum request size (in 4-byte units) supported by the server.
Single protocol requests to the server can be no longer than this size.
The protocol guarantees the size to be no smaller than 4096 units
(16384 bytes).
Xlib automatically breaks data up into multiple protocol requests
as necessary for the following functions:
.PN XDrawPoints ,
.PN XDrawRectangles ,
.PN XDrawSegments ,
.PN XFillArcs ,
.PN XFillRectangles ,
and 
.PN XPutImage .
.LP
.sp
.\" Start marker code here
.FD 0
LastKnownRequestProcessed\^(\^\fIdisplay\fP\^)
.sp
unsigned long XLastKnownRequestProcessed\^(\^\fIdisplay\fP\^)
.br
     Display *\fIdisplay\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.IN "LastKnownRequestProcessed" "" "@DEF@"
.IN "XLastKnownRequestProcessed" "" "@DEF@"
.LP
Both extract the full serial number of the last request known by Xlib
to have been processed by the X server.
Xlib automatically sets this number when replies, events, and errors
are received.
.LP
.sp
.\" Start marker code here
.FD 0
NextRequest\^(\^\fIdisplay\fP\^)
.sp
unsigned long XNextRequest\^(\^\fIdisplay\fP\^)
.br
     Display *\fIdisplay\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.IN "NextRequest" "" "@DEF@"
.IN "XNextRequest" "" "@DEF@"
.LP
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
.\" Start marker code here
.FD 0
ProtocolVersion\^(\^\fIdisplay\fP\^)
.sp
int XProtocolVersion\^(\^\fIdisplay\fP\^)
.br
      Display *\fIdisplay\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.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
.\" Start marker code here
.FD 0
ProtocolRevision\^(\^\fIdisplay\fP\^)
.sp
int XProtocolRevision\^(\^\fIdisplay\fP\^)
.br
      Display *\fIdisplay\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.LP
.IN "ProtocolRevision" "" "@DEF@"
.IN "XProtocolRevision" "" "@DEF@"
Both return the minor protocol revision number of the X server.
.LP
.sp
.\" Start marker code here
.FD 0
QLength\^(\^\fIdisplay\fP\^)
.sp
int XQLength\^(\^\fIdisplay\fP\^)
.br
      Display *\fIdisplay\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.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 (see
.PN XEventsQueued ).
.LP
.sp
.\" Start marker code here
.FD 0
RootWindow\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
Window XRootWindow\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fIscreen_number\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the appropriate screen number on the host server.
.\" End marker code here
.LP
.IN "Window" "RootWindow"
.IN "RootWindow" "" "@DEF@"
.IN "Window" "XRootWindow"
.IN "XRootWindow" "" "@DEF@"
Both return the root window.
These are useful with functions that need a drawable of a particular screen
and for creating top-level windows.
.LP
.sp
.\" Start marker code here
.FD 0
ScreenCount\^(\^\fIdisplay\fP\^)
.sp
int XScreenCount\^(\^\fIdisplay\fP\^)
.br
      Display *\fIdisplay\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.LP
.IN "ScreenCount" "" "@DEF@"
.IN "XScreenCount" "" "@DEF@"
Both return the number of available screens.
.LP
.sp
.\" Start marker code here
.FD 0
ServerVendor\^(\^\fIdisplay\fP\^)
.sp
char *XServerVendor\^(\^\fIdisplay\fP\^)
.br
      Display *\fIdisplay\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.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.
If the data returned by the server is in the Latin Portable Character Encoding,
then the string is in the Host Portable Character Encoding.
Otherwise, the contents of the string are implementation dependent.
.LP
.sp
.\" Start marker code here
.FD 0
VendorRelease\^(\^\fIdisplay\fP\^)
.sp
int XVendorRelease\^(\^\fIdisplay\fP\^)
.br
      Display *\fIdisplay\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.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 Functions and Macros
.XS
\*(SN Image Format Functions and Macros
.XE
.LP
Applications are required to present data to the X server
in a format that the server demands.
To help simplify applications,
most of the work required to convert the data is provided by Xlib
(see sections 8.7 and 16.8).
.LP
The
.PN XPixmapFormatValues
structure provides an interface to the pixmap format information
that is returned at the time of a connection setup.
It contains:
.LP
.\" Start marker code here
.Ds 0
.TA .5i 3i
.ta .5i 3i
typedef struct {
	int depth;
	int bits_per_pixel;
	int scanline_pad;
} XPixmapFormatValues;
.De
.\" End marker code here
.sp
.LP
To obtain the pixmap format information for a given display, use
.PN XListPixmapFormats .
.IN "XListPixmapFormats" "" "@DEF@"
.\" Start marker code here
.FD 0
XPixmapFormatValues *XListPixmapFormats\^(\^\fIdisplay\fP, \fIcount_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int *\fIcount_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.ds Cn pixmap formats that are supported by the display
.IP \fIcount_return\fP 1i
Returns the number of \*(Cn.
.\" End marker code here
.LP
The
.PN XListPixmapFormats
function returns an array of
.PN XPixmapFormatValues
structures that describe the types of Z format images supported
by the specified display.
If insufficient memory is available,
.PN XListPixmapFormats
returns NULL.
To free the allocated storage for the
.PN XPixmapFormatValues
structures, use
.PN XFree .
.LP 
The following lists the C language macros,
their corresponding function equivalents that are for other language bindings,
and what data they both return for the specified server and screen.
These are often used by toolkits as well as by simple applications.
.LP
.sp
.\" Start marker code here
.FD 0
ImageByteOrder\^(\^\fIdisplay\fP\^)
.sp
int XImageByteOrder\^(\^\fIdisplay\fP\^)
.br
      Display *\fIdisplay\fP\^;
.FN
.\" End marker code here
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.LP
.IN "ImageByteOrder" "" "@DEF@"
.IN "XImageByteOrder" "" "@DEF@"
Both specify the required byte order for images for each scanline unit in 
XY format (bitmap) or for each pixel value in 
Z format.
The macro or function can return either
.PN LSBFirst 
or 
.PN MSBFirst .
.LP
.sp
.\" Start marker code here
.FD 0
BitmapUnit\^(\^\fIdisplay\fP\^)
.sp
int XBitmapUnit\^(\^\fIdisplay\fP\^)
.br
      Display *\fIdisplay\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.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.
.LP
.sp
.\" Start marker code here
.FD 0
BitmapBitOrder\^(\^\fIdisplay\fP\^)
.sp
int XBitmapBitOrder\^(\^\fIdisplay\fP\^)
.br
      Display *\fIdisplay\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.LP
.IN "BitmapBitOrder" "" "@DEF@"
.IN "XBitmapBitOrder" "" "@DEF@"
Within each bitmap unit, the left-most bit in the bitmap as displayed
on the screen is either the least-significant or most-significant bit in the
unit.
This macro or function can return 
.PN LSBFirst
or 
.PN MSBFirst .
.LP
.sp
.\" Start marker code here
.FD 0
BitmapPad\^(\^\fIdisplay\fP\^)
.sp
int XBitmapPad\^(\^\fIdisplay\fP\^)
.br
      Display *\fIdisplay\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.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
.\" Start marker code here
.FD 0
DisplayHeight\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
int XDisplayHeight\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fIscreen_number\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the appropriate screen number on the host server.
.\" End marker code here
.LP
.IN "DisplayHeight" "" "@DEF@"
.IN "XDisplayHeight" "" "@DEF@"
Both return an integer that describes the height of the screen
in pixels.
.LP
.sp
.\" Start marker code here
.FD 0
DisplayHeightMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
int XDisplayHeightMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fIscreen_number\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the appropriate screen number on the host server.
.\" End marker code here
.LP
.IN "DisplayHeightMM" "" "@DEF@"
.IN "XDisplayHeightMM" "" "@DEF@"
Both return the height of the specified screen in millimeters.
.LP
.sp
.\" Start marker code here
.FD 0
DisplayWidth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
int XDisplayWidth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fIscreen_number\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the appropriate screen number on the host server.
.\" End marker code here
.LP
.IN "DisplayWidth" "" "@DEF@"
.IN "XDisplayWidth" "" "@DEF@"
Both return the width of the screen in pixels.
.LP
.sp
.\" Start marker code here
.FD 0
DisplayWidthMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.sp
int XDisplayWidthMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fIscreen_number\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen_number\fP 1i
Specifies the appropriate screen number on the host server.
.\" End marker code here
.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
.\" Start marker code here
.FD 0
BlackPixelOfScreen\^(\^\fIscreen\fP\^)
.sp
unsigned long XBlackPixelOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.LP
.IN "BlackPixelOfScreen" "" "@DEF@"
.IN "XBlackPixelOfScreen" "" "@DEF@"
Both return the black pixel value of the specified screen.
.LP
.sp
.\" Start marker code here
.FD 0
WhitePixelOfScreen\^(\^\fIscreen\fP\^)
.sp
unsigned long XWhitePixelOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.IN "WhitePixelOfScreen" "" "@DEF@"
.IN "XWhitePixelOfScreen" "" "@DEF@"
.LP
Both return the white pixel value of the specified screen.
.LP
.sp
.\" Start marker code here
.FD 0
CellsOfScreen\^(\^\fIscreen\fP\^)
.sp
int XCellsOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.LP
.IN "CellsOfScreen" "" "@DEF@"
.IN "XCellsOfScreen" "" "@DEF@"
Both return the number of colormap cells in the default colormap 
of the specified screen.
.LP
.sp
.\" Start marker code here
.FD 0
DefaultColormapOfScreen\^(\^\fIscreen\fP\^)
.sp
Colormap XDefaultColormapOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.LP
.IN "DefaultColormapOfScreen" "" "@DEF@"
.IN "XDefaultColormapOfScreen" "" "@DEF@"
Both return the default colormap of the specified screen.
.LP
.sp
.\" Start marker code here
.FD 0
DefaultDepthOfScreen\^(\^\fIscreen\fP\^)
.sp 
int XDefaultDepthOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.LP
.IN "DefaultDepthOfScreen" "" "@DEF@"
.IN "XDefaultDepthOfScreen" "" "@DEF@"
Both return the depth of the root window.
.LP
.sp
.\" Start marker code here
.FD 0
DefaultGCOfScreen\^(\^\fIscreen\fP\^)
.sp
GC XDefaultGCOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.LP
.IN "DefaultGCOfScreen" "" "@DEF@"
.IN "XDefaultGCOfScreen" "" "@DEF@"
Both return a default graphics context (GC) of the specified screen,
which has the same depth as the root window of the screen.
The GC must never be freed.
.LP
.sp
.\" Start marker code here
.FD 0
DefaultVisualOfScreen\^(\^\fIscreen\fP\^)
.sp
Visual *XDefaultVisualOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.LP
.IN "DefaultVisualOfScreen" "" "@DEF@"
.IN "XDefaultVisualOfScreen" "" "@DEF@"
Both return the default visual of the specified screen.
For information on visual types,
see section 3.1.
.LP
.sp
.\" Start marker code here
.FD 0
DoesBackingStore\^(\^\fIscreen\fP\^)
.sp
int XDoesBackingStore\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.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).
.LP
.sp
.\" Start marker code here
.FD 0
DoesSaveUnders\^(\^\fIscreen\fP\^)
.sp
Bool XDoesSaveUnders\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.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.5).
.LP
.sp
.\" Start marker code here
.FD 0
DisplayOfScreen\^(\^\fIscreen\fP\^)
.sp
Display *XDisplayOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.LP
.IN "DisplayOfScreen" "" "@DEF@"
.IN "XDisplayOfScreen" "" "@DEF@"
Both return the display of the specified screen.
.LP
.sp
.\" Start marker code here
.IN "XScreenNumberOfScreen" "" "@DEF@"
.FD 0
int XScreenNumberOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.LP
The
.PN XScreenNumberOfScreen
function returns the screen index number of the specified screen.
.LP
.sp
.\" Start marker code here
.FD 0
EventMaskOfScreen\^(\^\fIscreen\fP\^)
.sp
long XEventMaskOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.LP
.IN "EventMaskOfScreen" "" "@DEF@"
.IN "XEventMaskOfScreen" "" "@DEF@"
Both return the event mask of the root window for the specified screen
at connection setup time.
.LP
.sp
.\" Start marker code here
.FD 0
WidthOfScreen\^(\^\fIscreen\fP\^)
.sp
int XWidthOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.LP
.IN "WidthOfScreen" "" "@DEF@"
.IN "XWidthOfScreen" "" "@DEF@"
Both return the width of the specified screen in pixels.
.LP
.sp
.\" Start marker code here
.FD 0
HeightOfScreen\^(\^\fIscreen\fP\^)
.sp
int XHeightOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.LP
.IN "HeightOfScreen" "" "@DEF@"
.IN "XHeightOfScreen" "" "@DEF@"
Both return the height of the specified screen in pixels.
.LP
.sp
.\" Start marker code here
.FD 0
WidthMMOfScreen\^(\^\fIscreen\fP\^)
.sp
int XWidthMMOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.LP
.IN "WidthMMOfScreen" "" "@DEF@"
.IN "XWidthMMOfScreen" "" "@DEF@"
Both return the width of the specified screen in millimeters.
.LP
.sp
.\" Start marker code here
.FD 0
HeightMMOfScreen\^(\^\fIscreen\fP\^)
.sp
int XHeightMMOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.LP
.IN "HeightMMOfScreen" "" "@DEF@"
.IN "XHeightMMOfScreen" "" "@DEF@"
Both return the height of the specified screen in millimeters.
.LP
.sp
.\" Start marker code here
.FD 0
MaxCmapsOfScreen\^(\^\fIscreen\fP\^)
.sp
int XMaxCmapsOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.LP
.IN "MaxCmapsOfScreen" "" "@DEF@"
.IN "XMaxCmapsOfScreen" "" "@DEF@"
Both return the maximum number of installed colormaps supported 
by the specified screen (see section 9.3).
.LP
.sp
.\" Start marker code here
.FD 0
MinCmapsOfScreen\^(\^\fIscreen\fP\^)
.sp
int XMinCmapsOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.LP
.IN "MinCmapsOfScreen" "" "@DEF@"
.IN "XMinCmapsOfScreen" "" "@DEF@"
Both return the minimum number of installed colormaps supported 
by the specified screen (see section 9.3).
.LP
.sp
.\" Start marker code here
.FD 0
PlanesOfScreen\^(\^\fIscreen\fP\^)
.sp
int XPlanesOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.LP
.IN "PlanesOfScreen" "" "@DEF@"
.IN "XPlanesOfScreen" "" "@DEF@"
Both return the depth of the root window.
.LP
.sp
.\" Start marker code here
.FD 0
RootWindowOfScreen\^(\^\fIscreen\fP\^)
.sp
Window XRootWindowOfScreen\^(\^\fIscreen\fP\^)
.br
      Screen *\fIscreen\fP\^;
.FN
.IP \fIscreen\fP 1i
Specifies the appropriate 
.PN Screen
structure.
.\" End marker code here
.LP
.IN "RootWindowOfScreen" "" "@DEF@"
.IN "XRootWindowOfScreen" "" "@DEF@"
Both return the root window of the specified screen.
.NH 2
Generating a NoOperation Protocol Request
.XS
\*(SN Generating a NoOperation Protocol Request
.XE
.LP
To execute a 
.PN NoOperation 
protocol request, use
.PN XNoOp .
.IN "XNoOp" "" "@DEF@"
.\" Start marker code here
.FD 0
XNoOp\^(\^\fIdisplay\fP\^)
.br
      Display *\fIdisplay\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.LP
The
.PN XNoOp
function sends a 
.PN NoOperation 
protocol request to the X server,
thereby exercising the connection.
.NH 2
Freeing Client-Created Data
.XS
\*(SN Freeing Client-Created Data
.XE
.LP
To free in-memory data that was created by an Xlib function, use
.PN XFree .
.IN "XFree" "" "@DEF@"
.\" Start marker code here
.FD 0
XFree\^(\^\fIdata\fP\^)
.br
     void *\fIdata\fP\^; 
.FN
.IP \fIdata\fP 1i
Specifies the data that is to be freed.
.\" End marker code here
.LP
The
.PN XFree
function is a general-purpose Xlib routine that frees the specified data.
You must use it to free any objects that were allocated by Xlib,
unless an alternate function is explicitly specified for the object.
.NH 2
Closing the Display
.XS
\*(SN Closing the Display
.XE
.LP
To close a display or disconnect from the X server, use
.PN XCloseDisplay .
.IN "XCloseDisplay" "" "@DEF@"
.LP
.\" Start marker code here
.FD 0
.\" $Header: XCloseDisp.f,v 1.1 88/02/26 09:58:48 mento Exp $
XCloseDisplay\^(\fIdisplay\fP\^)
.br
      Display *\fIdisplay\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.LP
.\" $Header: XCloseDisp.d,v 1.6 88/08/16 09:50:19 mento Exp $
The
.PN XCloseDisplay
function closes the connection to the X server for the display specified in the
.PN Display
structure and destroys all windows, resource IDs
.Pn ( Window ,
.PN Font ,
.PN Pixmap ,
.PN Colormap ,
.PN Cursor ,
and
.PN GContext ),
or other resources that the client has created
on this display, unless the close-down mode of the resource has been changed
(see
.PN XSetCloseDownMode ).
Therefore, these windows, resource IDs, and other resources should never be 
referenced again or an error will be generated.
Before exiting, you should call
.PN XCloseDisplay
explicitly so that any pending errors are reported as
.PN XCloseDisplay
performs a final
.PN XSync
operation.
.IN "Resource IDs"
.IN "XCloseDisplay"
.LP
.PN XCloseDisplay
can generate a
.PN BadGC
error.
.sp
.LP
Xlib provides a function to permit the resources owned by a client
to survive after the client's connection is closed.
To change a client's close-down mode, use
.PN XSetCloseDownMode .
.IN "XSetCloseDownMode" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XChClsDwnMd.f,v 1.1 88/02/26 09:58:30 mento Exp $
XSetCloseDownMode\^(\^\fIdisplay\fP, \fIclose_mode\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fIclose_mode\fP\^;	
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: closemode.a,v 1.4 88/05/14 09:00:07 mento Exp $
.IP \fIclose_mode\fP 1i
Specifies the client close-down mode.
You can pass 
.PN DestroyAll , 
.PN RetainPermanent , 
or
.PN RetainTemporary . 
.\" End marker code here
.LP
.\" $Header: XChClsDwnMd.d,v 1.3 88/08/19 20:35:01 mento Exp $
The
.PN XSetCloseDownMode
defines what will happen to the client's resources at connection close.
A connection starts in
.PN DestroyAll
mode.
For information on what happens to the client's resources when the
close_mode argument is
.PN RetainPermanent
or
.PN RetainTemporary ,
see section 2.6.
.LP
.PN XSetCloseDownMode
can generate a
.PN BadValue 
error.
.NH 2
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 the following
automatic operations:
.IP \(bu 5
It disowns all selections owned by the client
(see 
.PN XSetSelectionOwner ).
.IP \(bu 5
It performs an
.PN XUngrabPointer
and
.PN XUngrabKeyboard 
if the client has actively grabbed the pointer 
or the keyboard.
.IP \(bu 5
It performs an
.PN XUngrabServer 
if the client has grabbed the server.
.IP \(bu 5
It releases all passive grabs made by the client.  
.IP \(bu 5
It marks all resources (including colormap entries) allocated 
by the client either as permanent or temporary, 
depending on whether the close-down mode is 
.PN RetainPermanent
or
.PN RetainTemporary .
However, this does not prevent other client applications from explicitly
destroying the resources (see 
.PN XSetCloseDownMode ).
.LP
When the close-down mode is
.PN DestroyAll ,
the X server destroys all of a client's resources as follows:
.IP \(bu 5
It examines each window in the client's save-set to determine if it is an inferior
(subwindow) of a window created by the client.
(The save-set is a list of other clients' windows, 
which are referred to as save-set windows.)
If so, the X server reparents the save-set window to the closest ancestor so
that the save-set window is not an inferior of a window created by the client.
The reparenting leaves unchanged the absolute coordinates (with respect to
the root window) of the upper-left outer corner of the save-set
window.
.IP \(bu 5
It performs a
.PN MapWindow
request on the save-set window if the save-set window is unmapped.
The X server does this even if the save-set window was not an inferior of 
a window created by the client.
.IP \(bu 5
It destroys all windows created by the client.
.IP \(bu 5
It performs the appropriate free request on each nonwindow resource created by
the client in the server (for example, 
.PN Font , 
.PN Pixmap , 
.PN Cursor , 
.PN Colormap , 
and 
.PN GContext ).
.IP \(bu 5
It frees all colors and colormap entries allocated by a client application.
.LP
Additional processing occurs when the last connection to the X server closes.
An X server goes through a cycle of having no connections and having some
connections.
When the last connection to the X server closes as a result of a connection
closing with the close_mode of
.PN DestroyAll ,
the X server does the following: 
.IP \(bu 5
It resets its state as if it had just been
started.  
The X server begins by destroying all lingering resources from
clients that have terminated in 
.PN RetainPermanent
or
.PN RetainTemporary
mode.
.IP \(bu 5
It deletes all but the predefined atom identifiers.
.IP \(bu 5
It deletes all properties on all root windows (see section 4.3).
.IP \(bu 5
It resets all device maps and attributes 
(for example, key click, bell volume, and acceleration) 
as well as the access control list.
.IP \(bu 5
It restores the standard root tiles and cursors.
.IP \(bu 5
It restores the default font path.
.IP \(bu 5
It restores the input focus to state
.PN PointerRoot .
.LP
However, the X server does not reset if you close a connection with a close-down
mode set to
.PN RetainPermanent
or
.PN RetainTemporary .
.bp
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦03bdfdb5d⟧ TextFile

Derivation

TextFile
