15.5 Client Termination

The CLX functions affecting client termination are discussed in the following paragraphs.

When a display connection to an X server is closed, whether by an explicit call to close-display or by some external condition, the server automatically performs a sequence of operations to clean up server state information associated with the closed connection. The effect of these operations depends the close-down mode and the save-set that the client has specified for the closed display connection. The close-down mode of a display determines whether server resources allocated by the connection are freed or not. The save-set identifies windows that will remain after the connection is closed.

The display save-set is used primarily by window managers that reparent the top-level windows of other clients. For example, such a window manager can automatically create a frame window that encloses a top-level client window, along with a set of controls used for window management. Ordinarily, termination of the window manager client would then destroy all client windows! However, the window manager can prevent this by adding to its save-set those windows created by other clients that should be preserved.

When a display connection closes, an X server performs the following operations:

1. For each selection owned by a window created on the connection, the selection owner is set to nil.
2. An active or passive grab established for a window created on the connection is released.
3. If the connection has grabbed the server, the server is ungrabbed.
4. Server resources and colormap cells allocated by the connection are freed and destroyed, depending on the close-down mode, as follows:
   • :retain-permanent – All resources are marked permanent, and no resources are destroyed. These resources can later be destroyed by a call to kill-client.
   • :retain-temporary – All resources are marked temporary, and no resources are destroyed. These resources can later be destroyed by a call to kill-client or kill-temporary-clients.
   • :destroy – All resources are destroyed.

When server resources allocated by a display connection are destroyed – whether by closing the connection with close-down mode :destroy or by later calling kill-client or kill-temporary-clients – then an X server performs the following operations on each member of the save-set before actually destroying resources.

1. If the save-set window is a descendant of a window created on the connection, the save-set window is reparented. The new parent is the closest ancestor such that the save-set window is no longer a descendant of any window created on the connection. The position of the reparented window with respect to its parent remains unchanged.
2. If the save-set window is unmapped, then it is mapped.

If the last connection open to an X server is closed with close-down mode :destroy, the server resets its state to restore all initial defaults. The server state after reset is the same as its initial state when first started. When an X server resets, it performs the following operations:

• All permanent and temporary server resources from previously-closed connections are destroyed.
• All but the predefined atoms are deleted.
• All root window properties are deleted.
• All device control attributes and mappings are restored to their original default values.
• The default background and cursor for all root windows are restored.
• The default font path is restored.
• The input focus is set to :pointer-root.
• The access control list is reset.

The following paragraphs describe the CLX functions used to:

• Add or remove a window from a display save-set.
• Return or change the display close-down mode.
• Force a connection to be closed or all its server resources to be destroyed.
• Force a connection to be closed and all temporary resources to be destroyed.

Function: add-to-save-set window

window

A window.

Adds the specified window to the save-set of the window display. The window must have been created by some other display. Windows are removed automatically from the save-set when they are destroyed.

Function: close-down-mode display

display

A display.

Returns and (with setf) sets the close-down mode of the client’s resources at connection close.

mode

One of :destroy, :retain-permanent, or :retain-temporary.

Function: kill-client display resource-id

display

A display.

resource-id

A valid card29 resource ID.

Closes the display connection which created the given resource-id. The resource-id must be valid, but need not belong to the given display.

If the closed connection was previously open, the connection is closed according to its close-down mode. Otherwise, if the connection had been previously terminated with close-down mode :retain-permanent or :retain-temporary, then all its retained server resources – both permanent and temporary – are destroyed.

Function: kill-temporary-clients display

display

A display.

Closes the display connection and destroys all retained temporary server resources for this and all previously-terminated connections.

If the display connection was previously open, the connection is closed according to its close-down mode. Otherwise, if the display connection had been previously terminated with close-down mode :retain-permanent or :retain-temporary, then all its retained server resources – both permanent and temporary – are destroyed.

Function: remove-from-save-set window

window

A window.

Removes the specified window from the save-set of the window display. The window must have been created by some other display. Windows are removed automatically from the save-set when they are destroyed.