Xnest



XNEST(1)                                                              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 implementa-
       tion.  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  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, Pseudo-
           Color, TrueColor, or DirectColor.  If both, -class and -cc  options
           are  specified,  the  last instance of either option assumes prece-
           dence.  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  win-
           dow.   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 protocol.  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 win-
           dow.  The integer parameter must be a positive 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  dis-
           play number :1 on the second screen.  The number of screens is lim-
           ited by the hard coded constant in the server sample code which  is
           usually 3.

       -install
           This  option  tells  Xnest  to  do its own colormap installation by
           bypassing the real window manager.  For it  to  work  properly  the
           user  will  probably  have to temporarily quit the real window man-
           ager.  By default Xnest will keep the nested  client  window  whose
           colormap  should  be  installed  in  the real server in the WM_COL-
           ORMAP_WINDOWS property of the top level Xnest window.  If this col-
           ormap  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 primarily at the WM_COLORMAP_WINDOWS  property
           rather  than  the colormap associated with the top level Xnest win-
           dow.  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 xnest-
           plugin.


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 run-
       ning 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  worksta-
       tion  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 com-
       mand 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 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.  There-
       fore, it is desirable that Xnest and the real server  are  on  a  local
       network, 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
       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
       colormap.  This implies that other windows’ colors  will  not  be  dis-
       played  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 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 property 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 con-
       trols  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 impos-
       ing 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 provide 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 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.  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’ responsibility 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




                                                                      XNEST(1)

Man(1) output converted with man2html