Provided by: xnest_1.11.4-0ubuntu10_amd64 bug

NAME

       Xnest - a nested X server

SYNOPSIS

       Xnest [ options ]

DESCRIPTION

       Xnest  is  both  an  X client and an X 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 Xserver(1).  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 to.  If it is not provided on the command line, Xnest will read the DISPLAY
              environment variable in order to find out this 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  Xnest's
              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  terminates.   When  this  happens,  Xnest  by  default
              maintains the same top-level window and the same real server connection 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 specification.  The string must be
              one of the following six values: StaticGray, GrayScale,  StaticColor,  PseudoColor,
              TrueColor,  or  DirectColor.  If both the -class and -cc options are specified, the
              last instance of either option takes 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, but it must be supported by  the  real  server.   Use  xdpyinfo(1)  to
              obtain 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 color map will be
              preallocated.  If the user chooses a dynamic class, colors in the default color map
              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, but it must be supported  by  the  real  server.
              Use  xdpyinfo(1)  to  obtain  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 the geometry parameters for the top-level Xnest window.   See
              “GEOMETRY  SPECIFICATIONS”  in  X(7) for a discusson of this option's syntax.  This
              window corresponds to the root window of the nested server.  The width W and height
              H 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.  Xnest does
              not yet support the RANDR extension for resizing, rotation, and reflection  of  the
              root  window.   If  this  option  is not specified, Xnest will choose W and H to be
              3/4ths 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 int must be positive.  The default border width is 1.

       -name string
              This  option  specifies  the  name  of  the  top-level Xnest window as string.  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(1) 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 color map installation 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 color map 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 color map with the top-level Xnest window as well.  Since this does
              not  have  to  be  the  case,  window  managers  should  look  primarily   at   the
              WM_COLORMAP_WINDOWS  property  rather  than  the color map 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 window_id as the root window instead of creating a
              window.

EXTENDED DESCRIPTION

       Starting up Xnest is just as simple as starting up xclock(1) 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 line.

       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 process 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 network, or even
       better, on the same machine.  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, in which case  the  real  server  need  not
       support  it.   Dynamic  SHAPE  extension  selection  support  may be considered 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 color map.  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 color map at any
       time.  The color map associated with the top window of the Xnest client need  not  be  the
       appropriate  color  map that the nested server wants installed in the real server.  In the
       case that a nested client attempts to install a color map of a different visual  from  the
       default  visual  of the nested server, Xnest will put the top window of this nested client
       and all other top windows of the nested clients that use  the  same  color  map  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  property rather than the color map associated with the top-level
       Xnest window.  Since most window managers don't yet appear to  implement  this  convention
       properly,  Xnest  can optionally do direct installation of color maps 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 color map 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.

   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.

       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 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 propagate 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 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.  The xlsfonts(1) 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' responsibility
       to make sure that this is the case.

FUTURE DIRECTIONS

       Make dynamic the requirement for the SHAPE extension  in  the  real  server,  rather  than
       having to recompile Xnest to turn this requirement on and off.

       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.

       Xnest should read  a  customization  input  file  to  provide  even  greater  freedom  and
       simplicity in selecting the desired layout.

       There is no support for backing store and save unders, but this should also be considered.

       The proper implementation of fonts should be moved into the os layer.

BUGS

       Doesn't run well on servers supporting different visual depths.

       Still crashes randomly.

       Probably has some memory leaks.

AUTHOR

       Davor Matic, MIT X Consortium

SEE ALSO

       Xserver(1), xdpyinfo(1), X(7)