diff options
Diffstat (limited to 'libX11/specs/libX11/CH09.xml')
| -rw-r--r-- | libX11/specs/libX11/CH09.xml | 4032 |
1 files changed, 2016 insertions, 2016 deletions
diff --git a/libX11/specs/libX11/CH09.xml b/libX11/specs/libX11/CH09.xml index 7d0f779f1..eff97c39c 100644 --- a/libX11/specs/libX11/CH09.xml +++ b/libX11/specs/libX11/CH09.xml @@ -1,2016 +1,2016 @@ -<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
-<chapter id="window_and_session_manager_functions">
-<title>Window and Session Manager Functions</title>
-
-<para>
-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:
-</para>
-
-<itemizedlist>
- <listitem><para>Change the parent of a window</para></listitem>
- <listitem><para>Control the lifetime of a window</para></listitem>
- <listitem><para>Manage installed colormaps</para></listitem>
- <listitem><para>Set and retrieve the font search path</para></listitem>
- <listitem><para>Grab the server</para></listitem>
- <listitem><para>Kill a client</para></listitem>
- <listitem><para>Control the screen saver</para></listitem>
- <listitem><para>Control host access</para></listitem>
-</itemizedlist>
-
-<sect1 id="Changing_the_Parent_of_a_Window">
-<title>Changing the Parent of a Window</title>
-<!-- .XS -->
-<!-- (SN Changing the Parent of a Window -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-To change a window's parent to another window on the same screen, use
-<function>XReparentWindow</function>.
-There is no way to move a window between screens.
-<indexterm significance="preferred"><primary>XReparentWindow</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XReparentWindow</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Window<parameter> w</parameter></paramdef>
- <paramdef>Window<parameter> parent</parameter></paramdef>
- <paramdef>intx,<parameter> y</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>w</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the window.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>parent</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the parent window.
-<!-- .ds Xy \ of the position in the new parent window -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>x</emphasis>
- </term>
- <listitem>
- <para>
-<!-- .br -->
-<!-- .ns -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>y</emphasis>
- </term>
- <listitem>
- <para>
-Specify the x and y coordinates(Xy.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-If the specified window is mapped,
-<function>XReparentWindow</function>
-automatically performs an
-<systemitem>UnmapWindow</systemitem>
-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.
-</para>
-<para>
-<!-- .LP -->
-After reparenting the specified window,
-<function>XReparentWindow</function>
-causes the X server to generate a
-<symbol>ReparentNotify</symbol>
-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
-<symbol>True</symbol>.
-Finally, if the specified window was originally mapped,
-the X server automatically performs a
-<systemitem>MapWindow</systemitem>
-request on it.
-</para>
-<para>
-<!-- .LP -->
-The X server performs normal exposure processing on formerly obscured
-windows.
-The X server might not generate
-<symbol>Expose</symbol>
-events for regions from the initial
-<systemitem>UnmapWindow</systemitem>
-request that are immediately obscured by the final
-<systemitem>MapWindow</systemitem>
-request.
-A
-<errorname>BadMatch</errorname>
-error results if:
-</para>
-<itemizedlist>
- <listitem>
- <para>
-The new parent window is not on the same screen as
-the old parent window.
- </para>
- </listitem>
- <listitem>
- <para>
-The new parent window is the specified window or an inferior of the
-specified window.
- </para>
- </listitem>
- <listitem>
- <para>
-The new parent is
-<symbol>InputOnly</symbol>,
-and the window is not.
- </para>
- </listitem>
- <listitem>
- <para>
-The specified window has a
-<symbol>ParentRelative</symbol>
-background, and the new parent window is not the same depth as the
-specified window.
- </para>
- </listitem>
-</itemizedlist>
-<para>
-<!-- .LP -->
-<function>XReparentWindow</function>
-can generate
-<errorname>BadMatch</errorname>
-and
-<errorname>BadWindow</errorname>
-errors.
-</para>
-</sect1>
-<sect1 id="Controlling_the_Lifetime_of_a_Window">
-<title>Controlling the Lifetime of a Window</title>
-<!-- .XS -->
-<!-- (SN Controlling the Lifetime of a Window -->
-<!-- .XE -->
-<para>
-<!-- .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.
-</para>
-<para>
-<!-- .LP -->
-The X server automatically removes windows from the save-set
-when they are destroyed.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To add or remove a window from the client's save-set, use
-<function>XChangeSaveSet</function>.
-<indexterm significance="preferred"><primary>XChangeSaveSet</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XChangeSaveSet</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Window<parameter> w</parameter></paramdef>
- <paramdef>int<parameter> change_mode</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
-<!-- .ds Wi that you want to add to or delete from the client's save-set -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>w</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the window (Wi.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>change_mode</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the mode.
-You can pass
-<symbol>SetModeInsert</symbol>
-or
-<symbol>SetModeDelete</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-Depending on the specified mode,
-<function>XChangeSaveSet</function>
-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
-<errorname>BadMatch</errorname>
-error results.
-</para>
-<para>
-<!-- .LP -->
-<function>XChangeSaveSet</function>
-can generate
-<errorname>BadMatch</errorname>,
-<errorname>BadValue</errorname>,
-and
-<errorname>BadWindow</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To add a window to the client's save-set, use
-<function>XAddToSaveSet</function>.
-<indexterm significance="preferred"><primary>XAddToSaveSet</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XAddToSaveSet</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Window<parameter> w</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
-<!-- .ds Wi that you want to add to the client's save-set -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>w</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the window (Wi.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XAddToSaveSet</function>
-function adds the specified window to the client's save-set.
-The specified window must have been created by some other client,
-or a
-<errorname>BadMatch</errorname>
-error results.
-</para>
-<para>
-<!-- .LP -->
-<function>XAddToSaveSet</function>
-can generate
-<errorname>BadMatch</errorname>
-and
-<errorname>BadWindow</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To remove a window from the client's save-set, use
-<function>XRemoveFromSaveSet</function>.
-<indexterm significance="preferred"><primary>XRemoveFromSaveSet</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XRemoveFromSaveSet</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Window<parameter> w</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
-<!-- .ds Wi that you want to delete from the client's save-set -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>w</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the window (Wi.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XRemoveFromSaveSet</function>
-function removes the specified window from the client's save-set.
-The specified window must have been created by some other client,
-or a
-<errorname>BadMatch</errorname>
-error results.
-</para>
-<para>
-<!-- .LP -->
-<function>XRemoveFromSaveSet</function>
-can generate
-<errorname>BadMatch</errorname>
-and
-<errorname>BadWindow</errorname>
-errors.
-</para>
-</sect1>
-<sect1 id="Managing_Installed_Colormaps">
-<title>Managing Installed Colormaps</title>
-<!-- .XS -->
-<!-- (SN Managing Installed Colormaps -->
-<!-- .XE -->
-<para>
-<!-- .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.
-</para>
-<para>
-<!-- .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
-<function>XInstallColormap</function>,
-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
-<function>XUninstallColormap</function>
-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.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To install a colormap, use
-<function>XInstallColormap</function>.
-<indexterm significance="preferred"><primary>XInstallColormap</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XInstallColormap</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Colormap<parameter> colormap</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>colormap</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the colormap.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XInstallColormap</function>
-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
-<function>XCreateWindow</function>,
-<function>XCreateSimpleWindow</function>,
-<function>XChangeWindowAttributes</function>,
-or
-<function>XSetWindowColormap</function>.
-</para>
-<para>
-<!-- .LP -->
-If the specified colormap is not already an installed colormap,
-the X server generates a
-<symbol>ColormapNotify</symbol>
-event on each window that has that colormap.
-In addition, for every other colormap that is installed as
-a result of a call to
-<function>XInstallColormap</function>,
-the X server generates a
-<symbol>ColormapNotify</symbol>
-event on each window that has that colormap.
-</para>
-<para>
-<!-- .LP -->
-<function>XInstallColormap</function>
-can generate a
-<errorname>BadColor</errorname>
-error.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To uninstall a colormap, use
-<function>XUninstallColormap</function>.
-<indexterm significance="preferred"><primary>XUninstallColormap</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XUninstallColormap</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Colormap<parameter> colormap</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>colormap</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the colormap.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XUninstallColormap</function>
-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.
-</para>
-<para>
-<!-- .LP -->
-If the specified colormap becomes uninstalled,
-the X server generates a
-<symbol>ColormapNotify</symbol>
-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
-<function>XUninstallColormap</function>,
-the X server generates a
-<symbol>ColormapNotify</symbol>
-event on each window that has that colormap.
-</para>
-<para>
-<!-- .LP -->
-<function>XUninstallColormap</function>
-can generate a
-<errorname>BadColor</errorname>
-error.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To obtain a list of the currently installed colormaps for a given screen, use
-<function>XListInstalledColormaps</function>.
-<indexterm significance="preferred"><primary>XListInstalledColormaps</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>Colormap *<function>XListInstalledColormaps</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>Window<parameter> w</parameter></paramdef>
- <paramdef>int<parameter> *num_return</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
-<!-- .ds Wi that determines the screen -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>w</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the window (Wi.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>num_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the number of currently installed colormaps.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XListInstalledColormaps</function>
-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
-<function>XFree</function>.
-</para>
-<para>
-<!-- .LP -->
-<function>XListInstalledColormaps</function>
-can generate a
-<errorname>BadWindow</errorname>
-error.
-</para>
-</sect1>
-<sect1 id="Setting_and_Retrieving_the_Font_Search_Path">
-<title>Setting and Retrieving the Font Search Path</title>
-<!-- .XS -->
-<!-- (SN Setting and Retrieving the Font Search Path -->
-<!-- .XE -->
-<para>
-<!-- .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.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To set the font search path, use
-<function>XSetFontPath</function>.
-<indexterm significance="preferred"><primary>XSetFontPath</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetFontPath</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>char<parameter> **directories</parameter></paramdef>
- <paramdef>int<parameter> ndirs</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>directories</emphasis>
- </term>
- <listitem>
- <para>
-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.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>ndirs</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of directories in the path.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XSetFontPath</function>
-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.
-</para>
-<para>
-<!-- .LP -->
-<function>XSetFontPath</function>
-can generate a
-<errorname>BadValue</errorname>
-error.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To get the current font search path, use
-<function>XGetFontPath</function>.
-<indexterm significance="preferred"><primary>XGetFontPath</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>char **<function>XGetFontPath</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>int<parameter> *npaths_return</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>npaths_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the number of strings in the font path array.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XGetFontPath</function>
-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
-<function>XFreeFontPath</function>.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To free data returned by
-<function>XGetFontPath</function>,
-use
-<function>XFreeFontPath</function>.
-<indexterm significance="preferred"><primary>XFreeFontPath</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XFreeFontPath</function></funcdef>
- <paramdef>char<parameter> **list</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>list</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the array of strings you want to free.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XFreeFontPath</function>
-function
-frees the data allocated by
-<function>XGetFontPath</function>.
-</para>
-</sect1>
-<sect1 id="Grabbing_the_Server_">
-<title>Grabbing the Server </title>
-<!-- .XS -->
-<!-- (SN Grabbing the Server -->
-<!-- .XE -->
-<para>
-<!-- .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.
-<indexterm><primary>Menus</primary></indexterm>
-<indexterm><primary>Window</primary><secondary>managers</secondary></indexterm>
-Although grabbing the server is highly discouraged, it is sometimes necessary.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To grab the server, use
-<function>XGrabServer</function>.
-<indexterm><primary>Server</primary><secondary>grabbing</secondary></indexterm>
-<indexterm><primary>Grabbing</primary><secondary>server</secondary></indexterm>
-<indexterm significance="preferred"><primary>XGrabServer</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XGrabServer</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XGrabServer</function>
-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.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To ungrab the server, use
-<function>XUngrabServer</function>.
-<indexterm significance="preferred"><primary>XUngrabServer</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XUngrabServer</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XUngrabServer</function>
-function restarts processing of requests and close downs on other connections.
-You should avoid grabbing the X server as much as possible.
-</para>
-</sect1>
-<sect1 id="Killing_Clients">
-<title>Killing Clients</title>
-<!-- .XS -->
-<!-- (SN Killing Clients -->
-<!-- .XE -->
-<para>
-<!-- .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
-<function>XKillClient</function>.
-<indexterm significance="preferred"><primary>XKillClient</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XKillClient</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>XID<parameter> resource</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>resource</emphasis>
- </term>
- <listitem>
- <para>
-Specifies any resource associated with the client that you want to destroy or
-<symbol>AllTemporary</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XKillClient</function>
-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
-<symbol>RetainPermanent</symbol>
-or
-<symbol>RetainTemporary</symbol>
-mode, all of the client's
-resources are destroyed.
-If
-<symbol>AllTemporary</symbol>
-is specified, the resources of all clients that have terminated in
-<symbol>RetainTemporary</symbol>
-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
-<symbol>RetainTemporary</symbol>.
-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.
-</para>
-<para>
-<!-- .LP -->
-<function>XKillClient</function>
-can generate a
-<errorname>BadValue</errorname>
-error.
-</para>
-</sect1>
-<sect1 id="Controlling_the_Screen_Saver_">
-<title>Controlling the Screen Saver </title>
-<!-- .XS -->
-<!-- (SN Controlling the Screen Saver -->
-<!-- .XE -->
-<para>
-<!-- .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.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To set the screen saver mode, use
-<function>XSetScreenSaver</function>.
-<indexterm significance="preferred"><primary>XSetScreenSaver</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetScreenSaver</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>inttimeout,<parameter> interval</parameter></paramdef>
- <paramdef>int<parameter> prefer_blanking</parameter></paramdef>
- <paramdef>int<parameter> allow_exposures</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>timeout</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the timeout, in seconds, until the screen saver turns on.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>interval</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the interval, in seconds, between screen saver alterations.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>prefer_blanking</emphasis>
- </term>
- <listitem>
- <para>
-Specifies how to enable screen blanking.
-You can pass
-<symbol>DontPreferBlanking</symbol>,
-<symbol>PreferBlanking</symbol>,
-or
-<symbol>DefaultBlanking</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>allow_exposures</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the screen save control values.
-You can pass
-<symbol>DontAllowExposures</symbol>,
-<symbol>AllowExposures</symbol>,
-or
-<symbol>DefaultExposures</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .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
-<errorname>BadValue</errorname>
-error.
-If the timeout value is nonzero,
-<function>XSetScreenSaver</function>
-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.
-</para>
-<para>
-<!-- .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
-<symbol>Expose</symbol>
-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
-<function>XForceScreenSaver</function>
-with mode
-<symbol>ScreenSaverReset</symbol>.
-</para>
-<para>
-<!-- .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.
-</para>
-<para>
-<!-- .LP -->
-<function>XSetScreenSaver</function>
-can generate a
-<errorname>BadValue</errorname>
-error.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To force the screen saver on or off, use
-<function>XForceScreenSaver</function>.
-<indexterm significance="preferred"><primary>XForceScreenSaver</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XForceScreenSaver</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>int<parameter> mode</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>mode</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the mode that is to be applied.
-You can pass
-<symbol>ScreenSaverActive</symbol>
-or
-<symbol>ScreenSaverReset</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-If the specified mode is
-<symbol>ScreenSaverActive</symbol>
-and the screen saver currently is deactivated,
-<function>XForceScreenSaver</function>
-activates the screen saver even if the screen saver had been disabled
-with a timeout of zero.
-If the specified mode is
-<symbol>ScreenSaverReset</symbol>
-and the screen saver currently is enabled,
-<function>XForceScreenSaver</function>
-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).
-</para>
-<para>
-<!-- .LP -->
-<function>XForceScreenSaver</function>
-can generate a
-<errorname>BadValue</errorname>
-error.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To activate the screen saver, use
-<function>XActivateScreenSaver</function>.
-<indexterm significance="preferred"><primary>XActivateScreenSaver</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XActivateScreenSaver</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-To reset the screen saver, use
-<function>XResetScreenSaver</function>.
-<indexterm significance="preferred"><primary>XResetScreenSaver</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XResetScreenSaver</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-To get the current screen saver values, use
-<function>XGetScreenSaver</function>.
-<indexterm significance="preferred"><primary>XGetScreenSaver</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XGetScreenSaver</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>int*timeout_return,<parameter> *interval_return</parameter></paramdef>
- <paramdef>int<parameter> *prefer_blanking_return</parameter></paramdef>
- <paramdef>int<parameter> *allow_exposures_return</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>timeout_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the timeout, in seconds, until the screen saver turns on.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>interval_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the interval between screen saver invocations.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>prefer_blanking_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the current screen blanking preference
-(<symbol>DontPreferBlanking</symbol>,
-<symbol>PreferBlanking</symbol>,
-or
-<symbol>DefaultBlanking</symbol>).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>allow_exposures_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the current screen save control value
-(<symbol>DontAllowExposures</symbol>,
-<symbol>AllowExposures</symbol>,
-or
-<symbol>DefaultExposures</symbol>).
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-</para>
-</sect1>
-<sect1 id="Controlling_Host_Access">
-<title>Controlling Host Access</title>
-<!-- .XS -->
-<!-- (SN Controlling Host Access -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-This section discusses how to:
-</para>
-<itemizedlist>
- <listitem>
- <para>
-Add, get, or remove hosts from the access control list
- </para>
- </listitem>
- <listitem>
- <para>
-Change, enable, or disable access
- </para>
- </listitem>
-</itemizedlist>
-<para>
-<!-- .LP -->
-<indexterm><primary>Access control list</primary></indexterm>
-<indexterm><primary>Authentication</primary></indexterm>
-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.
-</para>
-<para>
-<!-- .LP -->
-<indexterm><primary>Default Protection</primary></indexterm>
-The initial set of hosts allowed to open connections typically consists of:
-</para>
-<itemizedlist>
- <listitem>
- <para>
-The host the window system is running on.
- </para>
- </listitem>
- <listitem>
- <para>
-On <acronym>POSIX</acronym>-conformant systems, each host listed in the
-<filename>/etc/X<replaceable>?</replaceable>.hosts</filename>
-file.
-The ? indicates the number of the
-display.
-<indexterm><primary>Files</primary><secondary><filename>/etc/X<replaceable>?</replaceable>.hosts</filename></secondary></indexterm>
-This file should consist of host names separated by newlines.
-DECnet nodes must terminate in :: to distinguish them from Internet hosts.
- </para>
- </listitem>
-</itemizedlist>
-<para>
-<!-- .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.
-</para>
-<para>
-<!-- .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.''
-</para>
-<sect2 id="Adding_Getting_or_Removing_Hosts">
-<title>Adding, Getting, or Removing Hosts</title>
-<!-- .XS -->
-<!-- (SN Adding, Getting, or Removing Hosts -->
-<!-- .XE -->
-<para>
-<!-- .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
-<structname>XHostAddress</structname>
-structure, which contains:
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XHostAddress</primary></indexterm>
-<!-- .sM -->
-<literallayout class="monospaced">
-<!-- .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;
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The family member specifies which protocol address family to use
-(for example, <acronym>TCP</acronym>/<acronym>IP</acronym> or DECnet) and can be
-<symbol>FamilyInternet</symbol>,
-<symbol>FamilyInternet6</symbol>,
-<symbol>FamilyServerInterpreted</symbol>,
-<symbol>FamilyDECnet</symbol>,
-or
-<symbol>FamilyChaos</symbol>.
-The length member specifies the length of the address in bytes.
-The address member specifies a pointer to the address.
-</para>
-<para>
-<!-- .LP -->
-For <acronym>TCP</acronym>/<acronym>IP</acronym>, the address should be in network byte order.
-For <acronym>IP</acronym> version 4 addresses, the family should be FamilyInternet
-and the length should be 4 bytes. For <acronym>IP</acronym> version 6 addresses, the
-family should be FamilyInternet6 and the length should be 16 bytes.
-</para>
-<para>
-<!-- .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.
-</para>
-<para>
-<!-- .LP -->
-For the ServerInterpreted family, the length is ignored and the address
-member is a pointer to a
-<structname>XServerInterpretedAddress</structname>
-structure, which contains:
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XServerInterpretedAddress</primary></indexterm>
-<!-- .sM -->
-<literallayout class="monospaced">
-<!-- .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;
-</literallayout>
-</para>
-<para>
-<!-- .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.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To add a single host, use
-<function>XAddHost</function>.
-<indexterm significance="preferred"><primary>XAddHost</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XAddHost</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>XHostAddress<parameter> *host</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
-<!-- .ds Ho added -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>host</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the host that is to be (Ho.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XAddHost</function>
-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
-<errorname>BadAccess</errorname>
-error results.
-</para>
-<para>
-<!-- .LP -->
-<function>XAddHost</function>
-can generate
-<errorname>BadAccess</errorname>
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To add multiple hosts at one time, use
-<function>XAddHosts</function>.
-<indexterm significance="preferred"><primary>XAddHosts</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XAddHosts</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>XHostAddress<parameter> *hosts</parameter></paramdef>
- <paramdef>int<parameter> num_hosts</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
-<!-- .ds Ho added -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hosts</emphasis>
- </term>
- <listitem>
- <para>
-Specifies each host that is to be (Ho.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>num_hosts</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of hosts.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XAddHosts</function>
-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
-<errorname>BadAccess</errorname>
-error results.
-</para>
-<para>
-<!-- .LP -->
-<function>XAddHosts</function>
-can generate
-<errorname>BadAccess</errorname>
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To obtain a host list, use
-<function>XListHosts</function>.
-<indexterm significance="preferred"><primary>XListHosts</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>XHostAddress *<function>XListHosts</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>int<parameter> *nhosts_return</parameter></paramdef>
- <paramdef>Bool<parameter> *state_return</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>nhosts_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the number of hosts currently in the access control list.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>state_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the state of the access control.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XListHosts</function>
-function returns the current access control list as well as whether the use
-of the list at connection setup was enabled or disabled.
-<function>XListHosts</function>
-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
-<function>XFree</function>.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To remove a single host, use
-<function>XRemoveHost</function>.
-<indexterm significance="preferred"><primary>XRemoveHost</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XRemoveHost</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>XHostAddress<parameter> *host</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
-<!-- .ds Ho removed -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>host</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the host that is to be (Ho.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XRemoveHost</function>
-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
-<errorname>BadAccess</errorname>
-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.
-</para>
-<para>
-<!-- .LP -->
-<function>XRemoveHost</function>
-can generate
-<errorname>BadAccess</errorname>
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To remove multiple hosts at one time, use
-<function>XRemoveHosts</function>.
-<indexterm significance="preferred"><primary>XRemoveHosts</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XRemoveHosts</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>XHostAddress<parameter> *hosts</parameter></paramdef>
- <paramdef>int<parameter> num_hosts</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
-<!-- .ds Ho removed -->
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>hosts</emphasis>
- </term>
- <listitem>
- <para>
-Specifies each host that is to be (Ho.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>num_hosts</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of hosts.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XRemoveHosts</function>
-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
-<errorname>BadAccess</errorname>
-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.
-</para>
-<para>
-<!-- .LP -->
-<function>XRemoveHosts</function>
-can generate
-<errorname>BadAccess</errorname>
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-</sect2>
-<sect2 id="Changing_Enabling_or_Disabling_Access_Control">
-<title>Changing, Enabling, or Disabling Access Control</title>
-<!-- .XS -->
-<!-- (SN Changing, Enabling, or Disabling Access Control -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-Xlib provides functions that you can use to enable, disable,
-or change access control.
-</para>
-<para>
-<!-- .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.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To change access control, use
-<function>XSetAccessControl</function>.
-<indexterm significance="preferred"><primary>XSetAccessControl</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XSetAccessControl</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>int<parameter> mode</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>mode</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the mode.
-You can pass
-<symbol>EnableAccess</symbol>
-or
-<symbol>DisableAccess</symbol>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XSetAccessControl</function>
-function either enables or disables the use of the access control list
-at each connection setup.
-</para>
-<para>
-<!-- .LP -->
-<function>XSetAccessControl</function>
-can generate
-<errorname>BadAccess</errorname>
-and
-<errorname>BadValue</errorname>
-errors.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To enable access control, use
-<function>XEnableAccessControl</function>.
-<indexterm significance="preferred"><primary>XEnableAccessControl</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XEnableAccessControl</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XEnableAccessControl</function>
-function enables the use of the access control list at each connection setup.
-</para>
-<para>
-<!-- .LP -->
-<function>XEnableAccessControl</function>
-can generate a
-<errorname>BadAccess</errorname>
-error.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To disable access control, use
-<function>XDisableAccessControl</function>.
-<indexterm significance="preferred"><primary>XDisableAccessControl</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XDisableAccessControl</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XDisableAccessControl</function>
-function disables the use of the access control list at each connection setup.
-</para>
-<para>
-<!-- .LP -->
-<function>XDisableAccessControl</function>
-can generate a
-<errorname>BadAccess</errorname>
-error.
-<!-- .bp -->
-
-</para>
-</sect2>
-</sect1>
-</chapter>
+<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> +<chapter id="window_and_session_manager_functions"> +<title>Window and Session Manager Functions</title> + +<para> +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: +</para> + +<itemizedlist> + <listitem><para>Change the parent of a window</para></listitem> + <listitem><para>Control the lifetime of a window</para></listitem> + <listitem><para>Manage installed colormaps</para></listitem> + <listitem><para>Set and retrieve the font search path</para></listitem> + <listitem><para>Grab the server</para></listitem> + <listitem><para>Kill a client</para></listitem> + <listitem><para>Control the screen saver</para></listitem> + <listitem><para>Control host access</para></listitem> +</itemizedlist> + +<sect1 id="Changing_the_Parent_of_a_Window"> +<title>Changing the Parent of a Window</title> +<!-- .XS --> +<!-- (SN Changing the Parent of a Window --> +<!-- .XE --> +<para> +<!-- .LP --> +To change a window's parent to another window on the same screen, use +<function>XReparentWindow</function>. +There is no way to move a window between screens. +<indexterm significance="preferred"><primary>XReparentWindow</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xreparentwindow'> +<funcprototype> + <funcdef><function>XReparentWindow</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> w</parameter></paramdef> + <paramdef>Window<parameter> parent</parameter></paramdef> + <paramdef>intx,<parameter> y</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the window. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>parent</emphasis> + </term> + <listitem> + <para> +Specifies the parent window. +<!-- .ds Xy \ of the position in the new parent window --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para> +<!-- .br --> +<!-- .ns --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specify the x and y coordinates(Xy. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +If the specified window is mapped, +<function>XReparentWindow</function> +automatically performs an +<systemitem>UnmapWindow</systemitem> +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. +</para> +<para> +<!-- .LP --> +After reparenting the specified window, +<function>XReparentWindow</function> +causes the X server to generate a +<symbol>ReparentNotify</symbol> +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 +<symbol>True</symbol>. +Finally, if the specified window was originally mapped, +the X server automatically performs a +<systemitem>MapWindow</systemitem> +request on it. +</para> +<para> +<!-- .LP --> +The X server performs normal exposure processing on formerly obscured +windows. +The X server might not generate +<symbol>Expose</symbol> +events for regions from the initial +<systemitem>UnmapWindow</systemitem> +request that are immediately obscured by the final +<systemitem>MapWindow</systemitem> +request. +A +<errorname>BadMatch</errorname> +error results if: +</para> +<itemizedlist> + <listitem> + <para> +The new parent window is not on the same screen as +the old parent window. + </para> + </listitem> + <listitem> + <para> +The new parent window is the specified window or an inferior of the +specified window. + </para> + </listitem> + <listitem> + <para> +The new parent is +<symbol>InputOnly</symbol>, +and the window is not. + </para> + </listitem> + <listitem> + <para> +The specified window has a +<symbol>ParentRelative</symbol> +background, and the new parent window is not the same depth as the +specified window. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<function>XReparentWindow</function> +can generate +<errorname>BadMatch</errorname> +and +<errorname>BadWindow</errorname> +errors. +</para> +</sect1> +<sect1 id="Controlling_the_Lifetime_of_a_Window"> +<title>Controlling the Lifetime of a Window</title> +<!-- .XS --> +<!-- (SN Controlling the Lifetime of a Window --> +<!-- .XE --> +<para> +<!-- .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. +</para> +<para> +<!-- .LP --> +The X server automatically removes windows from the save-set +when they are destroyed. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To add or remove a window from the client's save-set, use +<function>XChangeSaveSet</function>. +<indexterm significance="preferred"><primary>XChangeSaveSet</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xchangesaveset'> +<funcprototype> + <funcdef><function>XChangeSaveSet</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> w</parameter></paramdef> + <paramdef>int<parameter> change_mode</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. +<!-- .ds Wi that you want to add to or delete from the client's save-set --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the window (Wi. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>change_mode</emphasis> + </term> + <listitem> + <para> +Specifies the mode. +You can pass +<symbol>SetModeInsert</symbol> +or +<symbol>SetModeDelete</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +Depending on the specified mode, +<function>XChangeSaveSet</function> +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 +<errorname>BadMatch</errorname> +error results. +</para> +<para> +<!-- .LP --> +<function>XChangeSaveSet</function> +can generate +<errorname>BadMatch</errorname>, +<errorname>BadValue</errorname>, +and +<errorname>BadWindow</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To add a window to the client's save-set, use +<function>XAddToSaveSet</function>. +<indexterm significance="preferred"><primary>XAddToSaveSet</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xaddtosaveset'> +<funcprototype> + <funcdef><function>XAddToSaveSet</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. +<!-- .ds Wi that you want to add to the client's save-set --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the window (Wi. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XAddToSaveSet</function> +function adds the specified window to the client's save-set. +The specified window must have been created by some other client, +or a +<errorname>BadMatch</errorname> +error results. +</para> +<para> +<!-- .LP --> +<function>XAddToSaveSet</function> +can generate +<errorname>BadMatch</errorname> +and +<errorname>BadWindow</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To remove a window from the client's save-set, use +<function>XRemoveFromSaveSet</function>. +<indexterm significance="preferred"><primary>XRemoveFromSaveSet</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xremovefromsaveset'> +<funcprototype> + <funcdef><function>XRemoveFromSaveSet</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> w</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. +<!-- .ds Wi that you want to delete from the client's save-set --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the window (Wi. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XRemoveFromSaveSet</function> +function removes the specified window from the client's save-set. +The specified window must have been created by some other client, +or a +<errorname>BadMatch</errorname> +error results. +</para> +<para> +<!-- .LP --> +<function>XRemoveFromSaveSet</function> +can generate +<errorname>BadMatch</errorname> +and +<errorname>BadWindow</errorname> +errors. +</para> +</sect1> +<sect1 id="Managing_Installed_Colormaps"> +<title>Managing Installed Colormaps</title> +<!-- .XS --> +<!-- (SN Managing Installed Colormaps --> +<!-- .XE --> +<para> +<!-- .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. +</para> +<para> +<!-- .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 +<function>XInstallColormap</function>, +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 +<function>XUninstallColormap</function> +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. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To install a colormap, use +<function>XInstallColormap</function>. +<indexterm significance="preferred"><primary>XInstallColormap</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xinstallcolormap'> +<funcprototype> + <funcdef><function>XInstallColormap</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Colormap<parameter> colormap</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>colormap</emphasis> + </term> + <listitem> + <para> +Specifies the colormap. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XInstallColormap</function> +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 +<function>XCreateWindow</function>, +<function>XCreateSimpleWindow</function>, +<function>XChangeWindowAttributes</function>, +or +<function>XSetWindowColormap</function>. +</para> +<para> +<!-- .LP --> +If the specified colormap is not already an installed colormap, +the X server generates a +<symbol>ColormapNotify</symbol> +event on each window that has that colormap. +In addition, for every other colormap that is installed as +a result of a call to +<function>XInstallColormap</function>, +the X server generates a +<symbol>ColormapNotify</symbol> +event on each window that has that colormap. +</para> +<para> +<!-- .LP --> +<function>XInstallColormap</function> +can generate a +<errorname>BadColor</errorname> +error. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To uninstall a colormap, use +<function>XUninstallColormap</function>. +<indexterm significance="preferred"><primary>XUninstallColormap</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xuninstallcolormap'> +<funcprototype> + <funcdef><function>XUninstallColormap</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Colormap<parameter> colormap</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>colormap</emphasis> + </term> + <listitem> + <para> +Specifies the colormap. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XUninstallColormap</function> +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. +</para> +<para> +<!-- .LP --> +If the specified colormap becomes uninstalled, +the X server generates a +<symbol>ColormapNotify</symbol> +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 +<function>XUninstallColormap</function>, +the X server generates a +<symbol>ColormapNotify</symbol> +event on each window that has that colormap. +</para> +<para> +<!-- .LP --> +<function>XUninstallColormap</function> +can generate a +<errorname>BadColor</errorname> +error. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To obtain a list of the currently installed colormaps for a given screen, use +<function>XListInstalledColormaps</function>. +<indexterm significance="preferred"><primary>XListInstalledColormaps</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xlistinstalledcolormaps'> +<funcprototype> + <funcdef>Colormap *<function>XListInstalledColormaps</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> w</parameter></paramdef> + <paramdef>int<parameter> *num_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. +<!-- .ds Wi that determines the screen --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the window (Wi. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_return</emphasis> + </term> + <listitem> + <para> +Returns the number of currently installed colormaps. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XListInstalledColormaps</function> +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 +<function>XFree</function>. +</para> +<para> +<!-- .LP --> +<function>XListInstalledColormaps</function> +can generate a +<errorname>BadWindow</errorname> +error. +</para> +</sect1> +<sect1 id="Setting_and_Retrieving_the_Font_Search_Path"> +<title>Setting and Retrieving the Font Search Path</title> +<!-- .XS --> +<!-- (SN Setting and Retrieving the Font Search Path --> +<!-- .XE --> +<para> +<!-- .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. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set the font search path, use +<function>XSetFontPath</function>. +<indexterm significance="preferred"><primary>XSetFontPath</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetfontpath'> +<funcprototype> + <funcdef><function>XSetFontPath</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>char<parameter> **directories</parameter></paramdef> + <paramdef>int<parameter> ndirs</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>directories</emphasis> + </term> + <listitem> + <para> +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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>ndirs</emphasis> + </term> + <listitem> + <para> +Specifies the number of directories in the path. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XSetFontPath</function> +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. +</para> +<para> +<!-- .LP --> +<function>XSetFontPath</function> +can generate a +<errorname>BadValue</errorname> +error. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To get the current font search path, use +<function>XGetFontPath</function>. +<indexterm significance="preferred"><primary>XGetFontPath</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xgetfontpath'> +<funcprototype> + <funcdef>char **<function>XGetFontPath</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>int<parameter> *npaths_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>npaths_return</emphasis> + </term> + <listitem> + <para> +Returns the number of strings in the font path array. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XGetFontPath</function> +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 +<function>XFreeFontPath</function>. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To free data returned by +<function>XGetFontPath</function>, +use +<function>XFreeFontPath</function>. +<indexterm significance="preferred"><primary>XFreeFontPath</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xfreefontpath'> +<funcprototype> + <funcdef><function>XFreeFontPath</function></funcdef> + <paramdef>char<parameter> **list</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>list</emphasis> + </term> + <listitem> + <para> +Specifies the array of strings you want to free. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XFreeFontPath</function> +function +frees the data allocated by +<function>XGetFontPath</function>. +</para> +</sect1> +<sect1 id="Grabbing_the_Server_"> +<title>Grabbing the Server </title> +<!-- .XS --> +<!-- (SN Grabbing the Server --> +<!-- .XE --> +<para> +<!-- .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. +<indexterm><primary>Menus</primary></indexterm> +<indexterm><primary>Window</primary><secondary>managers</secondary></indexterm> +Although grabbing the server is highly discouraged, it is sometimes necessary. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To grab the server, use +<function>XGrabServer</function>. +<indexterm><primary>Server</primary><secondary>grabbing</secondary></indexterm> +<indexterm><primary>Grabbing</primary><secondary>server</secondary></indexterm> +<indexterm significance="preferred"><primary>XGrabServer</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xgrabserver'> +<funcprototype> + <funcdef><function>XGrabServer</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XGrabServer</function> +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. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To ungrab the server, use +<function>XUngrabServer</function>. +<indexterm significance="preferred"><primary>XUngrabServer</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xungrabserver'> +<funcprototype> + <funcdef><function>XUngrabServer</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XUngrabServer</function> +function restarts processing of requests and close downs on other connections. +You should avoid grabbing the X server as much as possible. +</para> +</sect1> +<sect1 id="Killing_Clients"> +<title>Killing Clients</title> +<!-- .XS --> +<!-- (SN Killing Clients --> +<!-- .XE --> +<para> +<!-- .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 +<function>XKillClient</function>. +<indexterm significance="preferred"><primary>XKillClient</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xkillclient'> +<funcprototype> + <funcdef><function>XKillClient</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XID<parameter> resource</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>resource</emphasis> + </term> + <listitem> + <para> +Specifies any resource associated with the client that you want to destroy or +<symbol>AllTemporary</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XKillClient</function> +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 +<symbol>RetainPermanent</symbol> +or +<symbol>RetainTemporary</symbol> +mode, all of the client's +resources are destroyed. +If +<symbol>AllTemporary</symbol> +is specified, the resources of all clients that have terminated in +<symbol>RetainTemporary</symbol> +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 +<symbol>RetainTemporary</symbol>. +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. +</para> +<para> +<!-- .LP --> +<function>XKillClient</function> +can generate a +<errorname>BadValue</errorname> +error. +</para> +</sect1> +<sect1 id="Controlling_the_Screen_Saver_"> +<title>Controlling the Screen Saver </title> +<!-- .XS --> +<!-- (SN Controlling the Screen Saver --> +<!-- .XE --> +<para> +<!-- .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. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To set the screen saver mode, use +<function>XSetScreenSaver</function>. +<indexterm significance="preferred"><primary>XSetScreenSaver</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetscreensaver'> +<funcprototype> + <funcdef><function>XSetScreenSaver</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>inttimeout,<parameter> interval</parameter></paramdef> + <paramdef>int<parameter> prefer_blanking</parameter></paramdef> + <paramdef>int<parameter> allow_exposures</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>timeout</emphasis> + </term> + <listitem> + <para> +Specifies the timeout, in seconds, until the screen saver turns on. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>interval</emphasis> + </term> + <listitem> + <para> +Specifies the interval, in seconds, between screen saver alterations. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>prefer_blanking</emphasis> + </term> + <listitem> + <para> +Specifies how to enable screen blanking. +You can pass +<symbol>DontPreferBlanking</symbol>, +<symbol>PreferBlanking</symbol>, +or +<symbol>DefaultBlanking</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>allow_exposures</emphasis> + </term> + <listitem> + <para> +Specifies the screen save control values. +You can pass +<symbol>DontAllowExposures</symbol>, +<symbol>AllowExposures</symbol>, +or +<symbol>DefaultExposures</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .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 +<errorname>BadValue</errorname> +error. +If the timeout value is nonzero, +<function>XSetScreenSaver</function> +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. +</para> +<para> +<!-- .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 +<symbol>Expose</symbol> +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 +<function>XForceScreenSaver</function> +with mode +<symbol>ScreenSaverReset</symbol>. +</para> +<para> +<!-- .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. +</para> +<para> +<!-- .LP --> +<function>XSetScreenSaver</function> +can generate a +<errorname>BadValue</errorname> +error. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To force the screen saver on or off, use +<function>XForceScreenSaver</function>. +<indexterm significance="preferred"><primary>XForceScreenSaver</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xforcescreensaver'> +<funcprototype> + <funcdef><function>XForceScreenSaver</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>int<parameter> mode</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>mode</emphasis> + </term> + <listitem> + <para> +Specifies the mode that is to be applied. +You can pass +<symbol>ScreenSaverActive</symbol> +or +<symbol>ScreenSaverReset</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +If the specified mode is +<symbol>ScreenSaverActive</symbol> +and the screen saver currently is deactivated, +<function>XForceScreenSaver</function> +activates the screen saver even if the screen saver had been disabled +with a timeout of zero. +If the specified mode is +<symbol>ScreenSaverReset</symbol> +and the screen saver currently is enabled, +<function>XForceScreenSaver</function> +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). +</para> +<para> +<!-- .LP --> +<function>XForceScreenSaver</function> +can generate a +<errorname>BadValue</errorname> +error. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To activate the screen saver, use +<function>XActivateScreenSaver</function>. +<indexterm significance="preferred"><primary>XActivateScreenSaver</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xactivatescreensaver'> +<funcprototype> + <funcdef><function>XActivateScreenSaver</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<!-- .sp --> +To reset the screen saver, use +<function>XResetScreenSaver</function>. +<indexterm significance="preferred"><primary>XResetScreenSaver</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xresetscreensaver'> +<funcprototype> + <funcdef><function>XResetScreenSaver</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<!-- .sp --> +To get the current screen saver values, use +<function>XGetScreenSaver</function>. +<indexterm significance="preferred"><primary>XGetScreenSaver</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xgetscreensaver'> +<funcprototype> + <funcdef><function>XGetScreenSaver</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>int*timeout_return,<parameter> *interval_return</parameter></paramdef> + <paramdef>int<parameter> *prefer_blanking_return</parameter></paramdef> + <paramdef>int<parameter> *allow_exposures_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>timeout_return</emphasis> + </term> + <listitem> + <para> +Returns the timeout, in seconds, until the screen saver turns on. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>interval_return</emphasis> + </term> + <listitem> + <para> +Returns the interval between screen saver invocations. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>prefer_blanking_return</emphasis> + </term> + <listitem> + <para> +Returns the current screen blanking preference +(<symbol>DontPreferBlanking</symbol>, +<symbol>PreferBlanking</symbol>, +or +<symbol>DefaultBlanking</symbol>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>allow_exposures_return</emphasis> + </term> + <listitem> + <para> +Returns the current screen save control value +(<symbol>DontAllowExposures</symbol>, +<symbol>AllowExposures</symbol>, +or +<symbol>DefaultExposures</symbol>). + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +</para> +</sect1> +<sect1 id="Controlling_Host_Access"> +<title>Controlling Host Access</title> +<!-- .XS --> +<!-- (SN Controlling Host Access --> +<!-- .XE --> +<para> +<!-- .LP --> +This section discusses how to: +</para> +<itemizedlist> + <listitem> + <para> +Add, get, or remove hosts from the access control list + </para> + </listitem> + <listitem> + <para> +Change, enable, or disable access + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<indexterm><primary>Access control list</primary></indexterm> +<indexterm><primary>Authentication</primary></indexterm> +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. +</para> +<para> +<!-- .LP --> +<indexterm><primary>Default Protection</primary></indexterm> +The initial set of hosts allowed to open connections typically consists of: +</para> +<itemizedlist> + <listitem> + <para> +The host the window system is running on. + </para> + </listitem> + <listitem> + <para> +On <acronym>POSIX</acronym>-conformant systems, each host listed in the +<filename>/etc/X<replaceable>?</replaceable>.hosts</filename> +file. +The ? indicates the number of the +display. +<indexterm><primary>Files</primary><secondary><filename>/etc/X<replaceable>?</replaceable>.hosts</filename></secondary></indexterm> +This file should consist of host names separated by newlines. +DECnet nodes must terminate in :: to distinguish them from Internet hosts. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .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. +</para> +<para> +<!-- .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.'' +</para> +<sect2 id="Adding_Getting_or_Removing_Hosts"> +<title>Adding, Getting, or Removing Hosts</title> +<!-- .XS --> +<!-- (SN Adding, Getting, or Removing Hosts --> +<!-- .XE --> +<para> +<!-- .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 +<structname>XHostAddress</structname> +structure, which contains: +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XHostAddress</primary></indexterm> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .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; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The family member specifies which protocol address family to use +(for example, <acronym>TCP</acronym>/<acronym>IP</acronym> or DECnet) and can be +<symbol>FamilyInternet</symbol>, +<symbol>FamilyInternet6</symbol>, +<symbol>FamilyServerInterpreted</symbol>, +<symbol>FamilyDECnet</symbol>, +or +<symbol>FamilyChaos</symbol>. +The length member specifies the length of the address in bytes. +The address member specifies a pointer to the address. +</para> +<para> +<!-- .LP --> +For <acronym>TCP</acronym>/<acronym>IP</acronym>, the address should be in network byte order. +For <acronym>IP</acronym> version 4 addresses, the family should be FamilyInternet +and the length should be 4 bytes. For <acronym>IP</acronym> version 6 addresses, the +family should be FamilyInternet6 and the length should be 16 bytes. +</para> +<para> +<!-- .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. +</para> +<para> +<!-- .LP --> +For the ServerInterpreted family, the length is ignored and the address +member is a pointer to a +<structname>XServerInterpretedAddress</structname> +structure, which contains: +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XServerInterpretedAddress</primary></indexterm> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .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; +</literallayout> +</para> +<para> +<!-- .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. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To add a single host, use +<function>XAddHost</function>. +<indexterm significance="preferred"><primary>XAddHost</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xaddhost'> +<funcprototype> + <funcdef><function>XAddHost</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XHostAddress<parameter> *host</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. +<!-- .ds Ho added --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>host</emphasis> + </term> + <listitem> + <para> +Specifies the host that is to be (Ho. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XAddHost</function> +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 +<errorname>BadAccess</errorname> +error results. +</para> +<para> +<!-- .LP --> +<function>XAddHost</function> +can generate +<errorname>BadAccess</errorname> +and +<errorname>BadValue</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To add multiple hosts at one time, use +<function>XAddHosts</function>. +<indexterm significance="preferred"><primary>XAddHosts</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xaddhosts'> +<funcprototype> + <funcdef><function>XAddHosts</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XHostAddress<parameter> *hosts</parameter></paramdef> + <paramdef>int<parameter> num_hosts</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. +<!-- .ds Ho added --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hosts</emphasis> + </term> + <listitem> + <para> +Specifies each host that is to be (Ho. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_hosts</emphasis> + </term> + <listitem> + <para> +Specifies the number of hosts. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XAddHosts</function> +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 +<errorname>BadAccess</errorname> +error results. +</para> +<para> +<!-- .LP --> +<function>XAddHosts</function> +can generate +<errorname>BadAccess</errorname> +and +<errorname>BadValue</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To obtain a host list, use +<function>XListHosts</function>. +<indexterm significance="preferred"><primary>XListHosts</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xlisthosts'> +<funcprototype> + <funcdef>XHostAddress *<function>XListHosts</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>int<parameter> *nhosts_return</parameter></paramdef> + <paramdef>Bool<parameter> *state_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>nhosts_return</emphasis> + </term> + <listitem> + <para> +Returns the number of hosts currently in the access control list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>state_return</emphasis> + </term> + <listitem> + <para> +Returns the state of the access control. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XListHosts</function> +function returns the current access control list as well as whether the use +of the list at connection setup was enabled or disabled. +<function>XListHosts</function> +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 +<function>XFree</function>. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To remove a single host, use +<function>XRemoveHost</function>. +<indexterm significance="preferred"><primary>XRemoveHost</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xremovehost'> +<funcprototype> + <funcdef><function>XRemoveHost</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XHostAddress<parameter> *host</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. +<!-- .ds Ho removed --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>host</emphasis> + </term> + <listitem> + <para> +Specifies the host that is to be (Ho. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XRemoveHost</function> +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 +<errorname>BadAccess</errorname> +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. +</para> +<para> +<!-- .LP --> +<function>XRemoveHost</function> +can generate +<errorname>BadAccess</errorname> +and +<errorname>BadValue</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To remove multiple hosts at one time, use +<function>XRemoveHosts</function>. +<indexterm significance="preferred"><primary>XRemoveHosts</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xremovehosts'> +<funcprototype> + <funcdef><function>XRemoveHosts</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XHostAddress<parameter> *hosts</parameter></paramdef> + <paramdef>int<parameter> num_hosts</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. +<!-- .ds Ho removed --> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>hosts</emphasis> + </term> + <listitem> + <para> +Specifies each host that is to be (Ho. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_hosts</emphasis> + </term> + <listitem> + <para> +Specifies the number of hosts. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XRemoveHosts</function> +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 +<errorname>BadAccess</errorname> +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. +</para> +<para> +<!-- .LP --> +<function>XRemoveHosts</function> +can generate +<errorname>BadAccess</errorname> +and +<errorname>BadValue</errorname> +errors. +</para> +</sect2> +<sect2 id="Changing_Enabling_or_Disabling_Access_Control"> +<title>Changing, Enabling, or Disabling Access Control</title> +<!-- .XS --> +<!-- (SN Changing, Enabling, or Disabling Access Control --> +<!-- .XE --> +<para> +<!-- .LP --> +Xlib provides functions that you can use to enable, disable, +or change access control. +</para> +<para> +<!-- .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. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To change access control, use +<function>XSetAccessControl</function>. +<indexterm significance="preferred"><primary>XSetAccessControl</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xsetaccesscontrol'> +<funcprototype> + <funcdef><function>XSetAccessControl</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>int<parameter> mode</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>mode</emphasis> + </term> + <listitem> + <para> +Specifies the mode. +You can pass +<symbol>EnableAccess</symbol> +or +<symbol>DisableAccess</symbol>. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XSetAccessControl</function> +function either enables or disables the use of the access control list +at each connection setup. +</para> +<para> +<!-- .LP --> +<function>XSetAccessControl</function> +can generate +<errorname>BadAccess</errorname> +and +<errorname>BadValue</errorname> +errors. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To enable access control, use +<function>XEnableAccessControl</function>. +<indexterm significance="preferred"><primary>XEnableAccessControl</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xenableaccesscontrol'> +<funcprototype> + <funcdef><function>XEnableAccessControl</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XEnableAccessControl</function> +function enables the use of the access control list at each connection setup. +</para> +<para> +<!-- .LP --> +<function>XEnableAccessControl</function> +can generate a +<errorname>BadAccess</errorname> +error. +</para> +<para> +<!-- .LP --> +<!-- .sp --> +To disable access control, use +<function>XDisableAccessControl</function>. +<indexterm significance="preferred"><primary>XDisableAccessControl</primary></indexterm> +<!-- .sM --> +<funcsynopsis id='xdisableaccesscontrol'> +<funcprototype> + <funcdef><function>XDisableAccessControl</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XDisableAccessControl</function> +function disables the use of the access control list at each connection setup. +</para> +<para> +<!-- .LP --> +<function>XDisableAccessControl</function> +can generate a +<errorname>BadAccess</errorname> +error. +<!-- .bp --> + +</para> +</sect2> +</sect1> +</chapter> |