diff options
Diffstat (limited to 'libX11/specs/libX11/CH09')
| -rw-r--r-- | libX11/specs/libX11/CH09 | 1290 |
1 files changed, 0 insertions, 1290 deletions
diff --git a/libX11/specs/libX11/CH09 b/libX11/specs/libX11/CH09 deleted file mode 100644 index 2b79d3880..000000000 --- a/libX11/specs/libX11/CH09 +++ /dev/null @@ -1,1290 +0,0 @@ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996, 2002 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. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 9\fP\s-1 - -\s+1\fBWindow and Session Manager Functions\fP\s-1 -.sp 2 -.nr H1 9 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.na -.LP -.XS -Chapter 9: Window and Session Manager Functions -.XE -Although it is difficult to categorize functions as exclusively -for an application, a window manager, or a session manager, -the functions in this chapter are most often used by window managers -and session managers. -It is not expected that these functions will be used by most -application programs. -Xlib provides management functions to: -.IP \(bu 5 -Change the parent of a window -.IP \(bu 5 -Control the lifetime of a window -.IP \(bu 5 -Manage installed colormaps -.IP \(bu 5 -Set and retrieve the font search path -.IP \(bu 5 -Grab the server -.IP \(bu 5 -Kill a client -.IP \(bu 5 -Control the screen saver -.IP \(bu 5 -Control host access -.NH 2 -Changing the Parent of a Window -.XS -\*(SN Changing the Parent of a Window -.XE -.LP -To change a window's parent to another window on the same screen, use -.PN XReparentWindow . -There is no way to move a window between screens. -.IN "XReparentWindow" "" "@DEF@" -.sM -.FD 0 -XReparentWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIparent\fP\^, \fIx\fP\^, \fIy\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - Window \fIparent\fP\^; -.br - int \fIx\fP\^, \fIy\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIw\fP 1i -Specifies the window. -.IP \fIparent\fP 1i -Specifies the parent window. -.ds Xy \ of the position in the new parent window -.IP \fIx\fP 1i -.br -.ns -.IP \fIy\fP 1i -Specify the x and y coordinates\*(Xy. -.LP -.eM -If the specified window is mapped, -.PN XReparentWindow -automatically performs an -.PN UnmapWindow -request on it, removes it from its current position in the hierarchy, -and inserts it as the child of the specified parent. -The window is placed in the stacking order on top with respect to -sibling windows. -.LP -After reparenting the specified window, -.PN XReparentWindow -causes the X server to generate a -.PN ReparentNotify -event. -The override_redirect member returned in this event is -set to the window's corresponding attribute. -Window manager clients usually should ignore this window if this member -is set to -.PN True . -Finally, if the specified window was originally mapped, -the X server automatically performs a -.PN MapWindow -request on it. -.LP -The X server performs normal exposure processing on formerly obscured -windows. -The X server might not generate -.PN Expose -events for regions from the initial -.PN UnmapWindow -request that are immediately obscured by the final -.PN MapWindow -request. -A -.PN BadMatch -error results if: -.IP \(bu 5 -The new parent window is not on the same screen as -the old parent window. -.IP \(bu 5 -The new parent window is the specified window or an inferior of the -specified window. -.IP \(bu 5 -The new parent is -.PN InputOnly , -and the window is not. -.IP \(bu 5 -The specified window has a -.PN ParentRelative -background, and the new parent window is not the same depth as the -specified window. -.LP -.PN XReparentWindow -can generate -.PN BadMatch -and -.PN BadWindow -errors. -.NH 2 -Controlling the Lifetime of a Window -.XS -\*(SN Controlling the Lifetime of a Window -.XE -.LP -The save-set of a client is a list of other clients' windows that, -if they are inferiors of one of the client's windows at connection close, -should not be destroyed and should be remapped if they are unmapped. -For further information about close-connection processing, -see section 2.6. -To allow an application's window to survive when a window manager that -has reparented a window fails, -Xlib provides the save-set functions that you can -use to control the longevity of subwindows -that are normally destroyed when the parent is destroyed. -For example, a window manager that wants to add decoration -to a window by adding a frame might reparent an application's -window. -When the frame is destroyed, -the application's window should not be destroyed -but be returned to its previous place in the window hierarchy. -.LP -The X server automatically removes windows from the save-set -when they are destroyed. -.LP -.sp -To add or remove a window from the client's save-set, use -.PN XChangeSaveSet . -.IN "XChangeSaveSet" "" "@DEF@" -.sM -.FD 0 -XChangeSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^, \fIchange_mode\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - int \fIchange_mode\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi that you want to add to or delete from the client's save-set -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.IP \fIchange_mode\fP 1i -Specifies the mode. -You can pass -.PN SetModeInsert -or -.PN SetModeDelete . -.LP -.eM -Depending on the specified mode, -.PN XChangeSaveSet -either inserts or deletes the specified window from the client's save-set. -The specified window must have been created by some other client, -or a -.PN BadMatch -error results. -.LP -.PN XChangeSaveSet -can generate -.PN BadMatch , -.PN BadValue , -and -.PN BadWindow -errors. -.LP -.sp -To add a window to the client's save-set, use -.PN XAddToSaveSet . -.IN "XAddToSaveSet" "" "@DEF@" -.sM -.FD 0 -XAddToSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi that you want to add to the client's save-set -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.LP -.eM -The -.PN XAddToSaveSet -function adds the specified window to the client's save-set. -The specified window must have been created by some other client, -or a -.PN BadMatch -error results. -.LP -.PN XAddToSaveSet -can generate -.PN BadMatch -and -.PN BadWindow -errors. -.LP -.sp -To remove a window from the client's save-set, use -.PN XRemoveFromSaveSet . -.IN "XRemoveFromSaveSet" "" "@DEF@" -.sM -.FD 0 -XRemoveFromSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi that you want to delete from the client's save-set -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.LP -.eM -The -.PN XRemoveFromSaveSet -function removes the specified window from the client's save-set. -The specified window must have been created by some other client, -or a -.PN BadMatch -error results. -.LP -.PN XRemoveFromSaveSet -can generate -.PN BadMatch -and -.PN BadWindow -errors. -.NH 2 -Managing Installed Colormaps -.XS -\*(SN Managing Installed Colormaps -.XE -.LP -The X server maintains a list of installed colormaps. -Windows using these colormaps are guaranteed to display with -correct colors; windows using other colormaps may or may not display -with correct colors. -Xlib provides functions that you can use to install a colormap, -uninstall a colormap, and obtain a list of installed colormaps. -.LP -At any time, -there is a subset of the installed maps that is viewed as an ordered list -and is called the required list. -The length of the required list is at most M, -where M is the minimum number of installed colormaps specified for the screen -in the connection setup. -The required list is maintained as follows. -When a colormap is specified to -.PN XInstallColormap , -it is added to the head of the list; -the list is truncated at the tail, if necessary, to keep its length to -at most M. -When a colormap is specified to -.PN XUninstallColormap -and it is in the required list, -it is removed from the list. -A colormap is not added to the required list when it is implicitly installed -by the X server, -and the X server cannot implicitly uninstall a colormap that is in the -required list. -.LP -.sp -To install a colormap, use -.PN XInstallColormap . -.IN "XInstallColormap" "" "@DEF@" -.sM -.FD 0 -XInstallColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.LP -.eM -The -.PN XInstallColormap -function installs the specified colormap for its associated screen. -All windows associated with this colormap immediately display with -true colors. -You associated the windows with this colormap when you created them by calling -.PN XCreateWindow , -.PN XCreateSimpleWindow , -.PN XChangeWindowAttributes , -or -.PN XSetWindowColormap . -.LP -If the specified colormap is not already an installed colormap, -the X server generates a -.PN ColormapNotify -event on each window that has that colormap. -In addition, for every other colormap that is installed as -a result of a call to -.PN XInstallColormap , -the X server generates a -.PN ColormapNotify -event on each window that has that colormap. -.LP -.PN XInstallColormap -can generate a -.PN BadColor -error. -.LP -.sp -To uninstall a colormap, use -.PN XUninstallColormap . -.IN "XUninstallColormap" "" "@DEF@" -.sM -.FD 0 -XUninstallColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Colormap \fIcolormap\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIcolormap\fP 1i -Specifies the colormap. -.LP -.eM -The -.PN XUninstallColormap -function removes the specified colormap from the required -list for its screen. -As a result, -the specified colormap might be uninstalled, -and the X server might implicitly install or uninstall additional colormaps. -Which colormaps get installed or uninstalled is server dependent -except that the required list must remain installed. -.LP -If the specified colormap becomes uninstalled, -the X server generates a -.PN ColormapNotify -event on each window that has that colormap. -In addition, for every other colormap that is installed or uninstalled as a -result of a call to -.PN XUninstallColormap , -the X server generates a -.PN ColormapNotify -event on each window that has that colormap. -.LP -.PN XUninstallColormap -can generate a -.PN BadColor -error. -.LP -.sp -To obtain a list of the currently installed colormaps for a given screen, use -.PN XListInstalledColormaps . -.IN "XListInstalledColormaps" "" "@DEF@" -.sM -.FD 0 -Colormap *XListInstalledColormaps\^(\^\fIdisplay\fP, \fIw\fP, \fInum_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - Window \fIw\fP\^; -.br - int *\fInum_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Wi that determines the screen -.IP \fIw\fP 1i -Specifies the window \*(Wi. -.IP \fInum_return\fP 1i -Returns the number of currently installed colormaps. -.LP -.eM -The -.PN XListInstalledColormaps -function returns a list of the currently installed colormaps for the screen -of the specified window. -The order of the colormaps in the list is not significant -and is no explicit indication of the required list. -When the allocated list is no longer needed, -free it by using -.PN XFree . -.LP -.PN XListInstalledColormaps -can generate a -.PN BadWindow -error. -.NH 2 -Setting and Retrieving the Font Search Path -.XS -\*(SN Setting and Retrieving the Font Search Path -.XE -.LP -The set of fonts available from a server depends on a font -search path. Xlib provides functions to set and retrieve the -search path for a server. -.LP -.sp -To set the font search path, use -.PN XSetFontPath . -.IN "XSetFontPath" "" "@DEF@" -.sM -.FD 0 -XSetFontPath\^(\^\fIdisplay\fP, \fIdirectories\fP\^, \fIndirs\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - char **\fIdirectories\fP\^; -.br - int \fIndirs\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIdirectories\fP 1i -Specifies the directory path used to look for a font. -Setting the path to the empty list restores the default path defined -for the X server. -.IP \fIndirs\fP 1i -Specifies the number of directories in the path. -.LP -.eM -The -.PN XSetFontPath -function defines the directory search path for font lookup. -There is only one search path per X server, not one per client. -The encoding and interpretation of the strings are implementation-dependent, -but typically they specify directories or font servers to be searched -in the order listed. -An X server is permitted to cache font information internally; -for example, it might cache an entire font from a file and not -check on subsequent opens of that font to see if the underlying -font file has changed. -However, -when the font path is changed, -the X server is guaranteed to flush all cached information about fonts -for which there currently are no explicit resource IDs allocated. -The meaning of an error from this request is implementation-dependent. -.LP -.PN XSetFontPath -can generate a -.PN BadValue -error. -.LP -.sp -To get the current font search path, use -.PN XGetFontPath . -.IN "XGetFontPath" "" "@DEF@" -.sM -.FD 0 -char **XGetFontPath\^(\^\fIdisplay\fP, \fInpaths_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int *\fInpaths_return\fP\^; - -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fInpaths_return\fP 1i -Returns the number of strings in the font path array. -.LP -.eM -The -.PN XGetFontPath -function allocates and returns an array of strings containing the search path. -The contents of these strings are implementation-dependent -and are not intended to be interpreted by client applications. -When it is no longer needed, -the data in the font path should be freed by using -.PN XFreeFontPath . -.LP -.sp -To free data returned by -.PN XGetFontPath , -use -.PN XFreeFontPath . -.IN "XFreeFontPath" "" "@DEF@" -.sM -.FD 0 -XFreeFontPath\^(\^\fIlist\fP\^) -.br - char **\fIlist\fP\^; - -.FN -.IP \fIlist\fP 1i -Specifies the array of strings you want to free. -.LP -.eM -The -.PN XFreeFontPath -function -frees the data allocated by -.PN XGetFontPath . -.NH 2 -Grabbing the Server -.XS -\*(SN Grabbing the Server -.XE -.LP -Xlib provides functions that you can use to grab and ungrab the server. -These functions can be used to control processing of output on other -connections by the window system server. -While the server is grabbed, -no processing of requests or close downs on any other connection will occur. -A client closing its connection automatically ungrabs the server. -.IN "Menus" -.IN "Window" "managers" -Although grabbing the server is highly discouraged, it is sometimes necessary. -.LP -.sp -To grab the server, use -.PN XGrabServer . -.IN "Server" "grabbing" -.IN "Grabbing" "server" -.IN "XGrabServer" "" "@DEF@" -.sM -.FD 0 -XGrabServer\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XGrabServer -function disables processing of requests and close downs on all other -connections than the one this request arrived on. -You should not grab the X server any more than is absolutely necessary. -.LP -.sp -To ungrab the server, use -.PN XUngrabServer . -.IN "XUngrabServer" "" "@DEF@" -.sM -.FD 0 -XUngrabServer\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XUngrabServer -function restarts processing of requests and close downs on other connections. -You should avoid grabbing the X server as much as possible. -.NH 2 -Killing Clients -.XS -\*(SN Killing Clients -.XE -.LP -Xlib provides a function to cause the connection to -a client to be closed and its resources to be destroyed. -To destroy a client, use -.PN XKillClient . -.IN "XKillClient" "" "@DEF@" -.sM -.FD 0 -XKillClient\^(\^\fIdisplay\fP, \fIresource\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XID \fIresource\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fIresource\fP 1i -Specifies any resource associated with the client that you want to destroy or -.PN AllTemporary . -.LP -.eM -The -.PN XKillClient -function -forces a close down of the client -that created the resource -if a valid resource is specified. -If the client has already terminated in -either -.PN RetainPermanent -or -.PN RetainTemporary -mode, all of the client's -resources are destroyed. -If -.PN AllTemporary -is specified, the resources of all clients that have terminated in -.PN RetainTemporary -are destroyed (see section 2.5). -This permits implementation of window manager facilities that aid debugging. -A client can set its close-down mode to -.PN RetainTemporary . -If the client then crashes, -its windows would not be destroyed. -The programmer can then inspect the application's window tree -and use the window manager to destroy the zombie windows. -.LP -.PN XKillClient -can generate a -.PN BadValue -error. -.NH 2 -Controlling the Screen Saver -.XS -\*(SN Controlling the Screen Saver -.XE -.LP -Xlib provides functions that you can use to set or reset the mode -of the screen saver, to force or activate the screen saver, -or to obtain the current screen saver values. -.LP -.sp -To set the screen saver mode, use -.PN XSetScreenSaver . -.IN "XSetScreenSaver" "" "@DEF@" -.sM -.FD 0 -XSetScreenSaver\^(\^\fIdisplay\fP, \fItimeout\fP\^, \fIinterval\fP\^, \fIprefer_blanking\fP\^, \fIallow_exposures\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fItimeout\fP\^, \fIinterval\fP\^; -.br - int \fIprefer_blanking\fP\^; -.br - int \fIallow_exposures\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fItimeout\fP 1i -Specifies the timeout, in seconds, until the screen saver turns on. -.IP \fIinterval\fP 1i -Specifies the interval, in seconds, between screen saver alterations. -.IP \fIprefer_blanking\fP 1i -Specifies how to enable screen blanking. -You can pass -.PN DontPreferBlanking , -.PN PreferBlanking , -or -.PN DefaultBlanking . -.IP \fIallow_exposures\fP 1i -Specifies the screen save control values. -You can pass -.PN DontAllowExposures , -.PN AllowExposures , -or -.PN DefaultExposures . -.LP -.eM -Timeout and interval are specified in seconds. -A timeout of 0 disables the screen saver -(but an activated screen saver is not deactivated), -and a timeout of \-1 restores the default. -Other negative values generate a -.PN BadValue -error. -If the timeout value is nonzero, -.PN XSetScreenSaver -enables the screen saver. -An interval of 0 disables the random-pattern motion. -If no input from devices (keyboard, mouse, and so on) is generated -for the specified number of timeout seconds once the screen saver is enabled, -the screen saver is activated. -.LP -For each screen, -if blanking is preferred and the hardware supports video blanking, -the screen simply goes blank. -Otherwise, if either exposures are allowed or the screen can be regenerated -without sending -.PN Expose -events to clients, -the screen is tiled with the root window background tile randomly -re-origined each interval seconds. -Otherwise, the screens' state do not change, -and the screen saver is not activated. -The screen saver is deactivated, -and all screen states are restored at the next -keyboard or pointer input or at the next call to -.PN XForceScreenSaver -with mode -.PN ScreenSaverReset . -.LP -If the server-dependent screen saver method supports periodic change, -the interval argument serves as a hint about how long the change period -should be, and zero hints that no periodic change should be made. -Examples of ways to change the screen include scrambling the colormap -periodically, moving an icon image around the screen periodically, or tiling -the screen with the root window background tile, randomly re-origined -periodically. -.LP -.PN XSetScreenSaver -can generate a -.PN BadValue -error. -.LP -.sp -To force the screen saver on or off, use -.PN XForceScreenSaver . -.IN "XForceScreenSaver" "" "@DEF@" -.sM -.FD 0 -XForceScreenSaver\^(\^\fIdisplay\fP\^, \fImode\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fImode\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fImode\fP 1i -Specifies the mode that is to be applied. -You can pass -.PN ScreenSaverActive -or -.PN ScreenSaverReset . -.LP -.eM -If the specified mode is -.PN ScreenSaverActive -and the screen saver currently is deactivated, -.PN XForceScreenSaver -activates the screen saver even if the screen saver had been disabled -with a timeout of zero. -If the specified mode is -.PN ScreenSaverReset -and the screen saver currently is enabled, -.PN XForceScreenSaver -deactivates the screen saver if it was activated, -and the activation timer is reset to its initial state -(as if device input had been received). -.LP -.PN XForceScreenSaver -can generate a -.PN BadValue -error. -.LP -.sp -To activate the screen saver, use -.PN XActivateScreenSaver . -.IN "XActivateScreenSaver" "" "@DEF@" -.sM -.FD 0 -XActivateScreenSaver\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.sp -To reset the screen saver, use -.PN XResetScreenSaver . -.IN "XResetScreenSaver" "" "@DEF@" -.sM -.FD 0 -XResetScreenSaver\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -.sp -To get the current screen saver values, use -.PN XGetScreenSaver . -.IN "XGetScreenSaver" "" "@DEF@" -.sM -.FD 0 -XGetScreenSaver\^(\^\fIdisplay\fP, \fItimeout_return\fP\^, \fIinterval_return\fP\^, \fIprefer_blanking_return\fP\^, -.br - \fIallow_exposures_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int *\fItimeout_return\fP\^, *\fIinterval_return\fP\^; -.br - int *\fIprefer_blanking_return\fP\^; -.br - int *\fIallow_exposures_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fItimeout_return\fP 1i -Returns the timeout, in seconds, until the screen saver turns on. -.IP \fIinterval_return\fP 1i -Returns the interval between screen saver invocations. -.IP \fIprefer_blanking_return\fP 1i -Returns the current screen blanking preference -.Pn ( DontPreferBlanking , -.PN PreferBlanking , -or -.PN DefaultBlanking ). -.IP \fIallow_exposures_return\fP 1i -Returns the current screen save control value -.Pn ( DontAllowExposures , -.PN AllowExposures , -or -.PN DefaultExposures ). -.LP -.eM -.NH 2 -Controlling Host Access -.XS -\*(SN Controlling Host Access -.XE -.LP -This section discusses how to: -.IP \(bu 5 -Add, get, or remove hosts from the access control list -.IP \(bu 5 -Change, enable, or disable access -.LP -.IN "Access control list" -.IN "Authentication" -X does not provide any protection on a per-window basis. -If you find out the resource ID of a resource, you can manipulate it. -To provide some minimal level of protection, however, -connections are permitted only from machines you trust. -This is adequate on single-user workstations but obviously -breaks down on timesharing machines. -Although provisions exist in the X protocol for proper connection -authentication, the lack of a standard authentication server -leaves host-level access control as the only common mechanism. -.LP -.IN "Default Protection" -The initial set of hosts allowed to open connections typically consists of: -.IP \(bu 5 -The host the window system is running on. -.IP \(bu 5 -On POSIX-conformant systems, each host listed in the -.PN /etc/X?.hosts -file. -The ? indicates the number of the -display. -.IN "Files" "/etc/X?.hosts" -This file should consist of host names separated by newlines. -DECnet nodes must terminate in :: to distinguish them from Internet hosts. -.LP -If a host is not in the access control list when the access control -mechanism is enabled and if the host attempts to establish a connection, -the server refuses the connection. -To change the access list, -the client must reside on the same host as the server and/or must -have been granted permission in the initial authorization at connection -setup. -.LP -Servers also can implement other access control policies in addition to -or in place of this host access facility. -For further information about other access control implementations, -see ``X Window System Protocol.'' -.NH 3 -Adding, Getting, or Removing Hosts -.XS -\*(SN Adding, Getting, or Removing Hosts -.XE -.LP -Xlib provides functions that you can use to add, get, or remove hosts -from the access control list. -All the host access control functions use the -.PN XHostAddress -structure, which contains: -.LP -.IN "XHostAddress" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int family; /* for example FamilyInternet */ - int length; /* length of address, in bytes */ - char *address; /* pointer to where to find the address */ -} XHostAddress; -.De -.LP -.eM -The family member specifies which protocol address family to use -(for example, TCP/IP or DECnet) and can be -.PN FamilyInternet , -.PN FamilyInternet6 , -.PN FamilyServerInterpreted , -.PN FamilyDECnet , -or -.PN FamilyChaos . -The length member specifies the length of the address in bytes. -The address member specifies a pointer to the address. -.LP -For TCP/IP, the address should be in network byte order. -For IP version 4 addresses, the family should be FamilyInternet -and the length should be 4 bytes. For IP version 6 addresses, the -family should be FamilyInternet6 and the length should be 16 bytes. -.LP -For the DECnet family, -the server performs no automatic swapping on the address bytes. -A Phase IV address is 2 bytes long. -The first byte contains the least significant 8 bits of the node number. -The second byte contains the most significant 2 bits of the -node number in the least significant 2 bits of the byte -and the area in the most significant 6 bits of the byte. -.LP -For the ServerInterpreted family, the length is ignored and the address -member is a pointer to a -.PN XServerInterpretedAddress -structure, which contains: -.LP -.IN "XServerInterpretedAddress" "" "@DEF@" -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - int typelength; /* length of type string, in bytes */ - int valuelength;/* length of value string, in bytes */ - char *type; /* pointer to where to find the type string */ - char *value; /* pointer to where to find the address */ -} XServerInterpretedAddress; -.De -.LP -.eM -The type and value members point to strings representing the type and value of -the server interpreted entry. These strings may not be NULL-terminated so care -should be used when accessing them. The typelength and valuelength members -specify the length in byte of the type and value strings. -.LP -.sp -To add a single host, use -.PN XAddHost . -.IN "XAddHost" "" "@DEF@" -.sM -.FD 0 -XAddHost\^(\^\fIdisplay\fP, \fIhost\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XHostAddress *\fIhost\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Ho added -.IP \fIhost\fP 1i -Specifies the host that is to be \*(Ho. -.LP -.eM -The -.PN XAddHost -function adds the specified host to the access control list for that display. -The server must be on the same host as the client issuing the command, or a -.PN BadAccess -error results. -.LP -.PN XAddHost -can generate -.PN BadAccess -and -.PN BadValue -errors. -.LP -.sp -To add multiple hosts at one time, use -.PN XAddHosts . -.IN "XAddHosts" "" "@DEF@" -.sM -.FD 0 -XAddHosts\^(\^\fIdisplay\fP, \fIhosts\fP, \fInum_hosts\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XHostAddress *\fIhosts\fP\^; -.br - int \fInum_hosts\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Ho added -.IP \fIhosts\fP 1i -Specifies each host that is to be \*(Ho. -.IP \fInum_hosts\fP 1i -Specifies the number of hosts. -.LP -.eM -The -.PN XAddHosts -function adds each specified host to the access control list for that display. -The server must be on the same host as the client issuing the command, or a -.PN BadAccess -error results. -.LP -.PN XAddHosts -can generate -.PN BadAccess -and -.PN BadValue -errors. -.LP -.sp -To obtain a host list, use -.PN XListHosts . -.IN "XListHosts" "" "@DEF@" -.sM -.FD 0 -XHostAddress *XListHosts\^(\^\fIdisplay\fP, \fInhosts_return\fP, \fIstate_return\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int *\fInhosts_return\fP\^; -.br - Bool *\fIstate_return\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fInhosts_return\fP 1i -Returns the number of hosts currently in the access control list. -.IP \fIstate_return\fP 1i -Returns the state of the access control. -.LP -.eM -The -.PN XListHosts -function returns the current access control list as well as whether the use -of the list at connection setup was enabled or disabled. -.PN XListHosts -allows a program to find out what machines can make connections. -It also returns a pointer to a list of host structures that -were allocated by the function. -When no longer needed, -this memory should be freed by calling -.PN XFree . -.LP -.sp -To remove a single host, use -.PN XRemoveHost . -.IN "XRemoveHost" "" "@DEF@" -.sM -.FD 0 -XRemoveHost\^(\^\fIdisplay\fP, \fIhost\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XHostAddress *\fIhost\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Ho removed -.IP \fIhost\fP 1i -Specifies the host that is to be \*(Ho. -.LP -.eM -The -.PN XRemoveHost -function removes the specified host from the access control list -for that display. -The server must be on the same host as the client process, or a -.PN BadAccess -error results. -If you remove your machine from the access list, -you can no longer connect to that server, -and this operation cannot be reversed unless you reset the server. -.LP -.PN XRemoveHost -can generate -.PN BadAccess -and -.PN BadValue -errors. -.LP -.sp -To remove multiple hosts at one time, use -.PN XRemoveHosts . -.IN "XRemoveHosts" "" "@DEF@" -.sM -.FD 0 -XRemoveHosts\^(\^\fIdisplay\fP, \fIhosts\fP, \fInum_hosts\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - XHostAddress *\fIhosts\fP\^; -.br - int \fInum_hosts\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.ds Ho removed -.IP \fIhosts\fP 1i -Specifies each host that is to be \*(Ho. -.IP \fInum_hosts\fP 1i -Specifies the number of hosts. -.LP -.eM -The -.PN XRemoveHosts -function removes each specified host from the access control list for that -display. -The X server must be on the same host as the client process, or a -.PN BadAccess -error results. -If you remove your machine from the access list, -you can no longer connect to that server, -and this operation cannot be reversed unless you reset the server. -.LP -.PN XRemoveHosts -can generate -.PN BadAccess -and -.PN BadValue -errors. -.NH 3 -Changing, Enabling, or Disabling Access Control -.XS -\*(SN Changing, Enabling, or Disabling Access Control -.XE -.LP -Xlib provides functions that you can use to enable, disable, -or change access control. -.LP -For these functions to execute successfully, -the client application must reside on the same host as the X server -and/or have been given permission in the initial authorization -at connection setup. -.LP -.sp -To change access control, use -.PN XSetAccessControl . -.IN "XSetAccessControl" "" "@DEF@" -.sM -.FD 0 -XSetAccessControl\^(\^\fIdisplay\fP, \fImode\fP\^) -.br - Display *\fIdisplay\fP\^; -.br - int \fImode\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.IP \fImode\fP 1i -Specifies the mode. -You can pass -.PN EnableAccess -or -.PN DisableAccess . -.LP -.eM -The -.PN XSetAccessControl -function either enables or disables the use of the access control list -at each connection setup. -.LP -.PN XSetAccessControl -can generate -.PN BadAccess -and -.PN BadValue -errors. -.LP -.sp -To enable access control, use -.PN XEnableAccessControl . -.IN "XEnableAccessControl" "" "@DEF@" -.sM -.FD 0 -XEnableAccessControl\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XEnableAccessControl -function enables the use of the access control list at each connection setup. -.LP -.PN XEnableAccessControl -can generate a -.PN BadAccess -error. -.LP -.sp -To disable access control, use -.PN XDisableAccessControl . -.IN "XDisableAccessControl" "" "@DEF@" -.sM -.FD 0 -XDisableAccessControl\^(\^\fIdisplay\fP\^) -.br - Display *\fIdisplay\fP\^; -.FN -.IP \fIdisplay\fP 1i -Specifies the connection to the X server. -.LP -.eM -The -.PN XDisableAccessControl -function disables the use of the access control list at each connection setup. -.LP -.PN XDisableAccessControl -can generate a -.PN BadAccess -error. -.bp |