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
         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 W+H+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
         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
     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.   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
     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
     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



















































Man(1) output converted with man2html