MirBSD manpage: Xnest(1)


XNEST(1)            UNIX Programmer's Manual             XNEST(1)

NAME

     Xnest - a nested X server

SYNOPSIS

     Xnest [-options]

DESCRIPTION

     Xnest is a client and a server.  Xnest is a client of the
     real server which manages windows and graphics requests on
     its behalf. Xnest is a server to its own clients.  Xnest
     manages windows and graphics requests on their behalf.  To
     these clients Xnest appears to be a conventional server.

OPTIONS

     Xnest supports all standard options of the sample server
     implementation.  For more details, please see the manual
     page on your system for Xserver.  The following additional
     arguments are supported as well.

     -display string
         This option specifies the display name of the real
         server that Xnest should try to connect with.  If it is
         not provided on the command line Xnest will read the
         DISPLAY environment variable in order to find out the
         same information.

     -sync
         This option tells Xnest to synchronize its window and
         graphics operations with the real server.  This is a
         useful option for debugging, but it will slow down the
         performance considerably.  It should not be used unless
         absolutely necessary.

     -full
         This option tells Xnest to utilize full regeneration of
         real server objects and reopen a new connection to the
         real server each time the nested server regenerates.
         The sample server implementation regenerates all objects
         in the server when the last client of this server ter-
         minates.  When this happens, Xnest by default maintains
         the same top level window and the same real server con-
         nection in each new generation.  If the user selects
         full regeneration, even the top level window and the
         connection to the real server will be regenerated for
         each server generation.

     -class string
         This option specifies the default visual class of the
         nested server. It is similar to the -cc option from the
         set of standard options except that it will accept a
         string rather than a number for the visual class specif-
         ication.  The string must be one of the following six

XFree86                   Version 4.5.0                         1

XNEST(1)            UNIX Programmer's Manual             XNEST(1)

         values: StaticGray, GrayScale, StaticColor, PseudoColor,
         TrueColor, or DirectColor.  If both, -class and -cc
         options are specified, the last instance of either
         option assumes precedence.  The class of the default
         visual of the nested server need not be the same as the
         class of the default visual of the real server;
         although, it has to be supported by the real server.
         See xdpyinfo for a list of supported visual classes on
         the real server before starting Xnest.  If the user
         chooses a static class, all the colors in the default
         colormap will be preallocated.  If the user chooses a
         dynamic class, colors in the default colormap will be
         available to individual clients for allocation.

     -depth int
         This option specifies the default visual depth of the
         nested server. The depth of the default visual of the
         nested server need not be the same as the depth of the
         default visual of the real server; although, it has to
         be supported by the real server.  See xdpyinfo for a
         list of supported visual depths on the real server
         before starting Xnest.

     -sss
         This option tells Xnest to use the software screen
         saver.  By default Xnest will use the screen saver that
         corresponds to the hardware screen saver in the real
         server.  Of course, even this screen saver is software
         generated since Xnest does not control any actual
         hardware.  However, it is treated as a hardware screen
         saver within the sample server code.

     -geometry WxH+X+Y
         This option specifies geometry parameters for the top
         level Xnest windows.  These windows corresponds to the
         root windows of the nested server.  The width and height
         specified with this option will be the maximum width and
         height of each top level Xnest window.  Xnest will allow
         the user to make any top level window smaller, but it
         will not actually change the size of the nested server
         root window.  As of yet, there is no mechanism within
         the sample server implementation to change the size of
         the root window after screen initialization.  In order
         to do so, one would probably need to extend the X proto-
         col.  Therefore, it is not likely that this will be
         available any time soon.  If this option is not speci-
         fied Xnest will choose width and height to be 3/4 of the
         dimensions of the root window of the real server.

     -bw int
         This option specifies the border width of the top level
         Xnest window.  The integer parameter must be a positive

XFree86                   Version 4.5.0                         2

XNEST(1)            UNIX Programmer's Manual             XNEST(1)

         number.  The default border width is 1.

     -name string
         This option specifies the name of the top level Xnest
         window. The default value is the program name.

     -scrns int
         This option specifies the number of screens to create in
         the nested server.  For each screen, Xnest will create a
         separate top level window.  Each screen is referenced by
         the number after the dot in the client display name
         specification.  For example, xterm -display :1.1 will
         open an xterm client in the nested server with the
         display number :1 on the second screen.  The number of
         screens is limited by the hard coded constant in the
         server sample code which is usually 3.

     -install
         This option tells Xnest to do its own colormap installa-
         tion by bypassing the real window manager.  For it to
         work properly the user will probably have to temporarily
         quit the real window manager.  By default Xnest will
         keep the nested client window whose colormap should be
         installed in the real server in the WM_COLORMAP_WINDOWS
         property of the top level Xnest window.  If this color-
         map is of the same visual type as the root window of the
         nested server, Xnest will associate this colormap with
         the top level Xnest window as well.  Since this does not
         have to be the case, window managers should look pri-
         marily at the WM_COLORMAP_WINDOWS property rather than
         the colormap associated with the top level Xnest window.
         Unfortunately, window managers are not very good at
         doing that yet so this option might come in handy.

     -parent window_id
         This option tells Xnest to use the window_id as the root
         window instead of creating a window. This option is used
         by the xrx xnestplugin.

USAGE

     Starting up Xnest is as simple as starting up xclock from a
     terminal emulator.  If a user wishes to run Xnest on the
     same workstation as the real server, it is important that
     the nested server is given its own listening socket address.
     Therefore, if there is a server already running on the
     user's workstation, Xnest will have to be started up with a
     new display number.  Since there is usually no more than one
     server running on a workstation, specifying Xnest :1 on the
     command line will be sufficient for most users. For each
     server running on the workstation the display number needs
     to be incremented by one.  Thus, if you wish to start
     another Xnest, you will need to type Xnest :2 on the command

XFree86                   Version 4.5.0                         3

XNEST(1)            UNIX Programmer's Manual             XNEST(1)

     line.

     On some operating environments, you need to add authorisa-
     tion cookies to your xauth list before. You might find the
     following script useful:
#!/bin/sh
dispnr=${1:-1}
hostname=$(hostname)
COOKIE=$(/usr/sbin/openssl rand -hex 16)

xauth add $hostname/unix:$dispnr . $COOKIE
xauth add localhost/unix:$dispnr . $COOKIE
Xnest :$dispnr
rv=$?
xauth remove $hostname/unix:$dispnr localhost/unix:$dispnr
exit $rv

     To run clients in the nested server each client needs to be
     given the same display number as the nested server.  For
     example, xterm -display :1 will start up an xterm in the
     first nested server and xterm -display :2 will start an
     xterm in the second nested server from the example above.
     Additional clients can be started from these xterms in each
     nested server.

XNEST AS A CLIENT

     Xnest behaves and looks to the real server and other real
     clients as another real client.  It is a rather demanding
     client, however, since almost any window or graphics request
     from a nested client will result in a window or graphics
     request from Xnest to the real server.  Therefore, it is
     desirable that Xnest and the real server are on a local net-
     work, or even better, on the same machine.  As of now, Xnest
     assumes that the real server supports the shape extension.
     There is no way to turn off this assumption dynamically.
     Xnest can be compiled without the shape extension built in,
     and in that case the real server need not support it.  The
     dynamic shape extension selection support should be con-
     sidered in further development of Xnest.

     Since Xnest need not use the same default visual as the the
     real server, the top level window of the Xnest client always
     has its own colormap.  This implies that other windows'
     colors will not be displayed properly while the keyboard or
     pointer focus is in the Xnest window, unless the real server
     has support for more than one installed colormap at any
     time.  The colormap associated with the top window of the
     Xnest client need not be the appropriate colormap that the
     nested server wants installed in the real server. In the
     case that a nested client attempts to install a colormap of
     a different visual from the default visual of the nested
     server, Xnest will put the top window of this nested client

XFree86                   Version 4.5.0                         4

XNEST(1)            UNIX Programmer's Manual             XNEST(1)

     and all other top windows of the nested clients that use the
     same colormap into the WM_COLORMAP_WINDOWS property of the
     top level Xnest window on the real server.  Thus, it is
     important that the real window manager that manages the
     Xnest top level window looks at the WM_COLORMAP_WINDOWS pro-
     perty rather than the colormap associated with the top level
     Xnest window.  Since most window managers appear to not
     implement this convention properly as of yet, Xnest can
     optionally do direct installation of colormaps into the real
     server bypassing the real window manager.  If the user
     chooses this option, it is usually necessary to temporarily
     disable the real window manager since it will interfere with
     the Xnest scheme of colormap installation.

     Keyboard and pointer control procedures of the nested server
     change the keyboard and pointer control parameters of the
     real server. Therefore, after Xnest is started up, it will
     change the keyboard and pointer controls of the real server
     to its own internal defaults.  Perhaps there should be a
     command line option to tell Xnest to inherit the keyboard
     and pointer control parameters from the real server rather
     than imposing its own.  This is a future consideration.

XNEST AS A SERVER

     Xnest as a server looks exactly like a real server to its
     own clients.  For the clients there is no way of telling if
     they are running on a real or a nested server.

     As already mentioned, Xnest is a very user friendly server
     when it comes to customization.  Xnest will pick up a number
     of command line arguments that can configure its default
     visual class and depth, number of screens, etc.  In the
     future, Xnest should read a customization input file to pro-
     vide even greater freedom and simplicity in selecting the
     desired layout.  Unfortunately, there is no support for
     backing store and save under as of yet, but this should also
     be considered in the future development of Xnest.

     The only apparent intricacy from the users' perspective
     about using Xnest as a server is the selection of fonts.
     Xnest manages fonts by loading them locally and then passing
     the font name to the real server and asking it to load that
     font remotely.  This approach avoids the overload of sending
     the glyph bits across the network for every text operation,
     although it is really a bug.  The proper implementation of
     fonts should be moved into the os layer. The consequence of
     this approach is that the user will have to worry about two
     different font paths - a local one for the nested server and
     a remote one for the real server - since Xnest does not pro-
     pagate its font path to the real server.  The reason for
     this is because real and nested servers need not run on the
     same file system which makes the two font paths mutually

XFree86                   Version 4.5.0                         5

XNEST(1)            UNIX Programmer's Manual             XNEST(1)

     incompatible.  Thus, if there is a font in the local font
     path of the nested server, there is no guarantee that this
     font exists in the remote font path of the real server.
     Xlsfonts client, if run on the nested server will list fonts
     in the local font path and if run on the real server will
     list fonts in the remote font path.  Before a font can be
     successfully opened by the nested server it has to exist in
     local and remote font paths.  It is the users' responsibil-
     ity to make sure that this is the case.

BUGS

     Won't run well on servers supporting different visual
     depths. Still crashes randomly.  Probably has some memory
     leaks.

AUTHOR

     Davor Matic, MIT X Consortium

XFree86                   Version 4.5.0                         6

Generated on 2021-12-07 11:07:08 by $MirOS: src/scripts/roff2htm,v 1.103 2021/01/23 20:24:35 tg Exp $ — This product includes material provided by mirabilos.

These manual pages and other documentation are copyrighted by their respective writers; their sources are available at the project’s CVSweb, AnonCVS and other mirrors. The rest is Copyright © 2002–2021 MirBSD.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report — diffs preferred.