3.1 Opening the Display

The open-display and open-default-display functions are used to open a connection to an X server. open-default-display is an extension that is not present in the MIT CLX tree, but is preferred where available as it uses the same rules for display defaulting as the C Xlib bindings, and tends to get authorization right more often than open-display (particularly on ssh-forwarded connections)

Function: open-display host &key :display :protocol

host

Specifies the name of the host machine on which the server executes. A string must be acceptable as a host, but otherwise the possible types are not constrained and will likely be very system dependent.

:display

An integer that specifies which display device on the host should be used for this connection. This is needed since multiple displays can be controlled by a single X server. The default is display 0 (zero).

:protocol

A keyword argument that specifies which network protocol should be used for connecting to the server (for example, :tcp, :dna, or :chaos). The set of possible values and the default value are implementation specific.

Returns a display that serves as the connection to the X server and contains all the information about that X server.

Authorization, if any, is assumed to come from the environment. After a successful call to open-display, all screens on the display can be used by the client application.

display

Type display.

Function: open-default-display &optional display-name

display-name

The display to connect to. Display names have the format

  [protocol/] [hostname] : [:] displaynumber [.screennumber]

There are two special cases in parsing, to match that done in the Xlib C language bindings

• If the hostname is unix or the empty string, any supplied protocol is ignored and a connection is made using the local transport.
• If a double colon separates hostname from displaynumber, the protocol is assumed to be decnet.

If display-name is not supplied, a default will be provided appropriate for the local environment: on a POSIX system - the only kind this CLX port runs on - the default display is taken from the environment variable DISPLAY. See also the section “DISPLAY NAMES” in X(7)

Open a connection to display-name or to the appropriate default display.

open-display-name always attempts to do display authorization, following complicated rules that closely match the ones that the C Xlib bindings use. Briefly: the hostname is resolved to an address, then authorization data for the (protocol, host-address, displaynumber) triple is looked up in the file given by the environment variable AUTHORITY_PATHNAME (typically $HOME/.Xauthority). If the protocol is :local, or if the hostname resolves to the local host, authority data for the local machine’s actual hostname - as returned by gethostname(3) - is used instead.