Next: , Previous: , Up: Displays   [Contents][Index]

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

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.


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).


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.


Type display.

Function: open-default-display &optional 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.

Next: , Previous: , Up: Displays   [Contents][Index]