diff options
Diffstat (limited to 'libX11/specs/libX11/CH02')
| -rw-r--r-- | libX11/specs/libX11/CH02 | 2052 |
1 files changed, 2052 insertions, 0 deletions
diff --git a/libX11/specs/libX11/CH02 b/libX11/specs/libX11/CH02 new file mode 100644 index 000000000..61554b898 --- /dev/null +++ b/libX11/specs/libX11/CH02 @@ -0,0 +1,2052 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996, 2000 The Open Group +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of The Open Group shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from The Open Group. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +.\" $XFree86$ +\& +.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 formats, or screens +.IP \(bu 5 +Generate a +.PN NoOperation +protocol request +.IP \(bu 5 +Free client-created data +.IP \(bu 5 +Close (disconnect from) a display +.IP \(bu 5 +Use X Server connection close operations +.IP \(bu 5 +Use Xlib with threads +.IP \(bu 5 +Use internal connections +.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 +.sM +.FD 0 +Display *XOpenDisplay\^(\^\fIdisplay_name\fP\^) +.br + char *\fIdisplay_name\fP\^; +.FN +.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" +.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 POSIX-conformant systems, +the display name or DISPLAY environment variable can be a string in the format: +.LP +.sM +.Ds 0 +.TA 1i +.ta 1i + \fIprotocol\fP\^/\^\fIhostname\fP\^:\^\fInumber\fP\^.\^\fIscreen_number\fP +.De +.IP \fIprotocol\fP 1i +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. +.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). +.LP +.eM +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 +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 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, +.PN XOpenDisplay +connects using TCP streams. (If the protocol is specified as "inet", TCP over +IPv4 is used. If the protocol is specified as "inet6", TCP over IPv6 is used. +Otherwise, the implementation determines which IP 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, +.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 +.hN 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 functions and macros +.IP \(bu 5 +Screen information 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 both can return. +.LP +.sp +.sM +.FD 0 +AllPlanes +.sp +unsigned long XAllPlanes(\^) +.FN +.LP +.eM +.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. +.sM +.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 +.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. +.LP +.eM +.IN "BlackPixel" "" "@DEF@" +.IN "XBlackPixel" "" "@DEF@" +Both return the black pixel value for the specified screen. +.LP +.sp +.sM +.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 +.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. +.LP +.eM +.IN "WhitePixel" "" "@DEF@" +.IN "XWhitePixel" "" "@DEF@" +Both return the white pixel value for the specified screen. +.LP +.sp +.sM +.FD 0 +ConnectionNumber\^(\^\fIdisplay\fP\^) +.sp +int XConnectionNumber\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.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 +.sM +.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 +.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. +.LP +.eM +.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 +.sM +.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 +.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. +.LP +.eM +.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 . +.sM +.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 +.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. +.LP +.eM +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 +.sM +.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 +.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. +.LP +.eM +.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 +.sM +.FD 0 +DefaultRootWindow\^(\^\fIdisplay\fP\^) +.sp +Window XDefaultRootWindow\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "DefaultRootWindow" "" "@DEF@" +.IN "XDefaultRootWindow" "" "@DEF@" +Both return the root window for the default screen. +.LP +.sp +.sM +.FD 0 +DefaultScreenOfDisplay\^(\^\fIdisplay\fP\^) +.sp +Screen *XDefaultScreenOfDisplay\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "DefaultScreenOfDisplay" "" "@DEF@" +.IN "XDefaultScreenOfDisplay" "" "@DEF@" +Both return a pointer to the default screen. +.LP +.sp +.sM +.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 +.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. +.LP +.eM +.IN "ScreenOfDisplay" "" "@DEF@" +.IN "XScreenOfDisplay" "" "@DEF@" +Both return a pointer to the indicated screen. +.LP +.sp +.sM +.FD 0 +DefaultScreen\^(\^\fIdisplay\fP\^) +.sp +int XDefaultScreen\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.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 +.sM +.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 +.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. +.LP +.eM +.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 +.sM +.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 +.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. +.LP +.eM +.IN "DisplayCells" "" "@DEF@" +.IN "XDisplayCells" "" "@DEF@" +Both return the number of entries in the default colormap. +.LP +.sp +.sM +.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 +.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. +.LP +.eM +.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 +.sM +.FD 0 +DisplayString\^(\^\fIdisplay\fP\^) +.sp +char *XDisplayString\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.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 +.sM +.FD 0 +long XExtendedMaxRequestSize(\^\fIdisplay\fP\^) + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "XExtendedMaxRequestSize" "" "@DEF@" +The +.PN XExtendedMaxRequestSize +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 +.PN XDrawLines , +.PN XDrawArcs , +.PN XFillPolygon , +.PN XChangeProperty , +.PN XSetClipRectangles , +and +.PN XSetRegion +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, +.PN XDrawPoints , +.PN XDrawRectangles , +.PN XDrawSegments , +.PN XFillArcs , +.PN XFillRectangles , +.PN XPutImage ) +is permitted but not required; an Xlib implementation may choose to +split the data across multiple smaller requests instead. +.LP +.sp +.sM +.FD 0 +long XMaxRequestSize(\^\fIdisplay\fP\^) + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "XMaxRequestSize" "" "@DEF@" +The +.PN XMaxRequestSize +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: +.PN XDrawPoints , +.PN XDrawRectangles , +.PN XDrawSegments , +.PN XFillArcs , +.PN XFillRectangles , +and +.PN XPutImage . +.LP +.sp +.sM +.FD 0 +LastKnownRequestProcessed\^(\^\fIdisplay\fP\^) +.sp +unsigned long XLastKnownRequestProcessed\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.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. +Xlib automatically sets this number when replies, events, and errors +are received. +.LP +.sp +.sM +.FD 0 +NextRequest\^(\^\fIdisplay\fP\^) +.sp +unsigned long XNextRequest\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.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 +.sM +.FD 0 +ProtocolVersion\^(\^\fIdisplay\fP\^) +.sp +int XProtocolVersion\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "ProtocolVersion" "" "@DEF@" +.IN "XProtocolVersion" "" "@DEF@" +Both return the major version number (11) of the X protocol associated with +the connected display. +.LP +.sp +.sM +.FD 0 +ProtocolRevision\^(\^\fIdisplay\fP\^) +.sp +int XProtocolRevision\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "ProtocolRevision" "" "@DEF@" +.IN "XProtocolRevision" "" "@DEF@" +Both return the minor protocol revision number of the X server. +.LP +.sp +.sM +.FD 0 +QLength\^(\^\fIdisplay\fP\^) +.sp +int XQLength\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.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 +.sM +.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 +.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. +.LP +.eM +.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 +.sM +.FD 0 +ScreenCount\^(\^\fIdisplay\fP\^) +.sp +int XScreenCount\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "ScreenCount" "" "@DEF@" +.IN "XScreenCount" "" "@DEF@" +Both return the number of available screens. +.LP +.sp +.sM +.FD 0 +ServerVendor\^(\^\fIdisplay\fP\^) +.sp +char *XServerVendor\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.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 +.sM +.FD 0 +VendorRelease\^(\^\fIdisplay\fP\^) +.sp +int XVendorRelease\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.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 +.sM +.Ds 0 +.TA .5i 3i +.ta .5i 3i +typedef struct { + int depth; + int bits_per_pixel; + int scanline_pad; +} XPixmapFormatValues; +.De +.LP +.eM +.sp +To obtain the pixmap format information for a given display, use +.PN XListPixmapFormats . +.IN "XListPixmapFormats" "" "@DEF@" +.sM +.FD 0 +XPixmapFormatValues *XListPixmapFormats\^(\^\fIdisplay\fP, \fIcount_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int *\fIcount_return\fP\^; +.FN +.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. +.LP +.eM +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 +.sM +.FD 0 +ImageByteOrder\^(\^\fIdisplay\fP\^) +.sp +int XImageByteOrder\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.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 +.sM +.FD 0 +BitmapUnit\^(\^\fIdisplay\fP\^) +.sp +int XBitmapUnit\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.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 +.sM +.FD 0 +BitmapBitOrder\^(\^\fIdisplay\fP\^) +.sp +int XBitmapBitOrder\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.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 +.sM +.FD 0 +BitmapPad\^(\^\fIdisplay\fP\^) +.sp +int XBitmapPad\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +.IN "BitmapPad" "" "@DEF@" +.IN "XBitmapPad" "" "@DEF@" +Each scanline must be padded to a multiple of bits returned +by this macro or function. +.LP +.sp +.sM +.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 +.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. +.LP +.eM +.IN "DisplayHeight" "" "@DEF@" +.IN "XDisplayHeight" "" "@DEF@" +Both return an integer that describes the height of the screen +in pixels. +.LP +.sp +.sM +.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 +.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. +.LP +.eM +.IN "DisplayHeightMM" "" "@DEF@" +.IN "XDisplayHeightMM" "" "@DEF@" +Both return the height of the specified screen in millimeters. +.LP +.sp +.sM +.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 +.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. +.LP +.eM +.IN "DisplayWidth" "" "@DEF@" +.IN "XDisplayWidth" "" "@DEF@" +Both return the width of the screen in pixels. +.LP +.sp +.sM +.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 +.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. +.LP +.eM +.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 +.sM +.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. +.LP +.eM +.IN "BlackPixelOfScreen" "" "@DEF@" +.IN "XBlackPixelOfScreen" "" "@DEF@" +Both return the black pixel value of the specified screen. +.LP +.sp +.sM +.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. +.LP +.eM +.IN "WhitePixelOfScreen" "" "@DEF@" +.IN "XWhitePixelOfScreen" "" "@DEF@" +Both return the white pixel value of the specified screen. +.LP +.sp +.sM +.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. +.LP +.eM +.IN "CellsOfScreen" "" "@DEF@" +.IN "XCellsOfScreen" "" "@DEF@" +Both return the number of colormap cells in the default colormap +of the specified screen. +.LP +.sp +.sM +.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. +.LP +.eM +.IN "DefaultColormapOfScreen" "" "@DEF@" +.IN "XDefaultColormapOfScreen" "" "@DEF@" +Both return the default colormap of the specified screen. +.LP +.sp +.sM +.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. +.LP +.eM +.IN "DefaultDepthOfScreen" "" "@DEF@" +.IN "XDefaultDepthOfScreen" "" "@DEF@" +Both return the depth of the root window. +.LP +.sp +.sM +.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. +.LP +.eM +.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 +.sM +.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. +.LP +.eM +.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 +.sM +.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. +.LP +.eM +.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 +.sM +.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. +.LP +.eM +.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 +.sM +.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. +.LP +.eM +.IN "DisplayOfScreen" "" "@DEF@" +.IN "XDisplayOfScreen" "" "@DEF@" +Both return the display of the specified screen. +.LP +.sp +.sM +.IN "XScreenNumberOfScreen" "" "@DEF@" +.FD 0 +int XScreenNumberOfScreen\^(\^\fIscreen\fP\^) +.br + Screen *\fIscreen\fP\^; +.FN +.IP \fIscreen\fP 1i +Specifies the appropriate +.PN Screen +structure. +.LP +.eM +The +.PN XScreenNumberOfScreen +function returns the screen index number of the specified screen. +.LP +.sp +.sM +.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. +.LP +.eM +.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 +.sM +.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. +.LP +.eM +.IN "WidthOfScreen" "" "@DEF@" +.IN "XWidthOfScreen" "" "@DEF@" +Both return the width of the specified screen in pixels. +.LP +.sp +.sM +.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. +.LP +.eM +.IN "HeightOfScreen" "" "@DEF@" +.IN "XHeightOfScreen" "" "@DEF@" +Both return the height of the specified screen in pixels. +.LP +.sp +.sM +.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. +.LP +.eM +.IN "WidthMMOfScreen" "" "@DEF@" +.IN "XWidthMMOfScreen" "" "@DEF@" +Both return the width of the specified screen in millimeters. +.LP +.sp +.sM +.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. +.LP +.eM +.IN "HeightMMOfScreen" "" "@DEF@" +.IN "XHeightMMOfScreen" "" "@DEF@" +Both return the height of the specified screen in millimeters. +.LP +.sp +.sM +.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. +.LP +.eM +.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 +.sM +.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. +.LP +.eM +.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 +.sM +.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. +.LP +.eM +.IN "PlanesOfScreen" "" "@DEF@" +.IN "XPlanesOfScreen" "" "@DEF@" +Both return the depth of the root window. +.LP +.sp +.sM +.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. +.LP +.eM +.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@" +.sM +.FD 0 +XNoOp\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +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@" +.sM +.FD 0 +XFree\^(\^\fIdata\fP\^) +.br + void *\fIdata\fP\^; +.FN +.IP \fIdata\fP 1i +Specifies the data that is to be freed. +.LP +.eM +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. +A NULL pointer cannot be passed to this function. +.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 +.sM +.FD 0 +XCloseDisplay\^(\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +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@" +.sM +.FD 0 +XSetCloseDownMode\^(\^\fIdisplay\fP, \fIclose_mode\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIclose_mode\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIclose_mode\fP 1i +Specifies the client close-down mode. +You can pass +.PN DestroyAll , +.PN RetainPermanent , +or +.PN RetainTemporary . +.LP +.eM +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 +Using X Server Connection Close Operations +.XS +\*(SN Using 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 +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. +.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 . +.NH 2 +Using Xlib with Threads +.XS +\*(SN Using Xlib with Threads +.XE +.LP +On systems that have threads, support may be provided to permit +multiple threads to use Xlib concurrently. +.LP +.sp +To initialize support for concurrent threads, use +.PN XInitThreads . +.IN "XInitThreads" "" "@DEF@" +.sM +.FD 0 +Status XInitThreads\^(\|); +.FN +.LP +.eM +The +.PN XInitThreads +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. +.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. + +.LP +.sp +To lock a display across several Xlib calls, use +.PN XLockDisplay . +.IN "XLockDisplay" "" "@DEF@" +.sM +.FD 0 +void XLockDisplay\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XLockDisplay +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 +.PN XLockDisplay +work correctly; the display will not actually be unlocked until +.PN XUnlockDisplay +has been called the same number of times as +.PN XLockDisplay . +This function has no effect unless Xlib was successfully initialized +for threads using +.PN XInitThreads . +.LP +.sp +To unlock a display, use +.PN XUnlockDisplay . +.IN "XUnlockDisplay" "" "@DEF@" +.sM +.FD 0 +void XUnlockDisplay\^(\^\fIdisplay\fP\^) +.br + Display *\fIdisplay\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.LP +.eM +The +.PN XUnlockDisplay +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 +.PN XLockDisplay +has been called multiple times by a thread, then +.PN XUnlockDisplay +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 +.PN XInitThreads . +.NH 2 +Using Internal Connections +.XS +\*(SN Using Internal Connections +.XE +.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. +.LP +To track internal connections for a display, use +.PN XAddConnectionWatch . +.LP +.IN "XWatchProc" "" "@DEF@" +.IN "XAddConnectionWatch" "" "@DEF@" +.sM +.FD 0 +typedef void (*XConnectionWatchProc)\^(\^\fIdisplay\fP, \fIclient_data\fP, \fIfd\fP, \fIopening\fP, \fIwatch_data\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XPointer \fIclient_data\fP\^; +.br + int \fIfd\fP\^; +.br + Bool \fIopening\fP\^; +.br + XPointer *\fIwatch_data\fP\^; +.sp +Status XAddConnectionWatch\^(\^\fIdisplay\fP, \fIprocedure\fP\^, \fIclient_data\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XWatchProc \fIprocedure\fP\^; +.br + XPointer \fIclient_data\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIprocedure\fP 1i +Specifies the procedure to be called. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.LP +.eM +The +.PN XAddConnectionWatch +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 +.PN True , +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 +.PN False , +the location pointed to by watch_data will hold this same private data pointer. +.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 +.PN XAddConnectionWatch +returns. +.PN XAddConnectionWatch +returns a nonzero status if the procedure is successfully registered; +otherwise, it returns zero. +.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 +.PN XLockDisplay . +.LP +.sp +To stop tracking internal connections for a display, use +.PN XRemoveConnectionWatch . +.IN "XRemoveConnectionWatch" "" "@DEF@" +.sM +.FD 0 +Status XRemoveConnectionWatch\^(\^\fIdisplay\fP, \fIprocedure\fP\^, \fIclient_data\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XWatchProc \fIprocedure\fP\^; +.br + XPointer \fIclient_data\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIprocedure\fP 1i +Specifies the procedure to be called. +.IP \fIclient_data\fP 1i +Specifies the additional client data. +.LP +.eM +The +.PN XRemoveConnectionWatch +function removes a previously registered connection watch procedure. +The client_data must match the client_data used when the procedure +was initially registered. + +.LP +.sp +To process input on an internal connection, use +.PN XProcessInternalConnection . +.IN "XProcessInternalConnection" "" "@DEF@" +.sM +.FD 0 +void XProcessInternalConnection\^(\^\fIdisplay\fP, \fIfd\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int \fIfd\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIfd\fP 1i +Specifies the file descriptor. +.LP +.eM +The +.PN XProcessInternalConnection +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, +.PN select +or +.PN poll ) +has indicated that input is available; otherwise, +the effect is not defined. +.LP +.sp +To obtain all of the current internal connections for a display, use +.PN XInternalConnectionNumbers . +.IN "XInternalConnectionNumbers" "" "@DEF@" +.sM +.FD 0 +Status XInternalConnectionNumbers\^(\^\fIdisplay\fP, \fIfd_return\fP\^, \fIcount_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + int **\fIfd_return\fP\^; +.br + int *\fIcount_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIfd_return\fP 1i +Returns the file descriptors. +.ds Cn file descriptors +.IP \fIcount_return\fP 1i +Returns the number of \*(Cn. +.LP +.eM +The +.PN XInternalConnectionNumbers +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 +.PN XFree . +This functions returns a nonzero status if the list is successfully allocated; +otherwise, it returns zero. +.LP +.bp |