XOpenDisplay()XOpenDisplay()NameXOpenDisplay – connect a client program to an X server.
Synopsis
Display *XOpenDisplay(display_name)
char *display_name;
Arguments
display_name Specifies the display name, which determines the server
to connect to and the communications domain to be used.
See Description below.
Returns
The display structure.
Description
The XOpenDisplay() routine connects the client to the server control‐
ling the hardware display through TCP or DECnet communication proto‐
cols, or through some local inter-process communication protocol.
On a POSIX-conformant system, if display_name is NULL, the value
defaults to the contents of the DISPLAY environment variable on POSIX-
based systems. On non-UNIX-based systems, see that operating system's
Xlib manual for the default display_name. The encoding and interpreta‐
tion of the display name is implementation-dependent. Strings in the
Host Portable Character Encoding are supported; support for other char‐
acters is implementation-dependent. The display_name or DISPLAY envi‐
ronment variable is a string that has the format hostname:server or
hostname:server.screen. For example, frog:0.2 would specify screen 2
of server 0 on the machine frog.
hostname Specifies the name of the host machine on which the display
is physically connected. You follow the hostname with
either a single colon (:) or a double colon (::), which
determines the communications domain to use. Any or all of
the communication protocols can be used simultaneously on a
server built to support them (but only one per client).
· If hostname is a host machine name and a single colon
(:) separates the hostname and display number, XOpenDis‐
play() connects to the server using TCP streams. If the
hostname is not specified, Xlib uses what it believes is
the fastest transport.
· If hostname is a host machine name and a double colon
(::) separates the hostname and display number,
XOpenDisplay() connects with the server using DECnet
streams. To use DECnet, however, you must build all
software for DECnet. A single X server can accept both
TCP and DECnet connections if it has been built for DEC‐
net.
· Note that support for use of the string "unix" in a dis‐
play name is no longer part of the Xlib specification as
of Release 4.
server Specifies the number of the server on its host machine.
This display number may be followed by a period (.). A
single CPU can have more than one display; the displays are
numbered starting from 0.
screen Specifies the number of the default screen on server. Mul‐
tiple screens can be connected to (controlled by) a single
X server, but they are used as a single display by a single
user. screen merely sets an internal variable that is
returned by the DefaultScreen() macro. If screen is omit‐
ted, it defaults to 0.
If successful, XOpenDisplay() returns a pointer to a Display. This
structure provides many of the specifications of the server and its
screens. If XOpenDisplay() does not succeed, it returns NULL.
After a successful call to XOpenDisplay(), all of the screens on the
server may be used by the application. The screen number specified in
the display_name argument serves only to specify the value that will be
returned by the DefaultScreen() macro. After opening the display, you
can use the ScreenCount() macro to determine how many screens are
available. Then you can reference each screen with integer values
between 0 and the value returned by (ScreenCount() -1). You can access
elements of the Display and Screen structures only using the informa‐
tion macros and functions listed in Appendix C, Macros.
For more information, see Volume One, Chapter 2, X Concepts, and Chap‐
ter 3, Basic Window Program.
See AlsoXDefaultScreen(), XCloseDisplay(), XFree(), XNoOp().
Xlib - HouseKeeping XOpenDisplay()
