1Xnest(1)                    General Commands Manual                   Xnest(1)
2
3
4

NAME

6       Xnest - a nested X server
7

SYNOPSIS

9       Xnest [ options ]
10

DESCRIPTION

12       Xnest  is  both  an X client and an X server.  Xnest is a client of the
13       real server which manages windows and graphics requests on its  behalf.
14       Xnest is a server to its own clients.  Xnest manages windows and graph‐
15       ics requests on their behalf.  To these clients, Xnest appears to be  a
16       conventional server.
17

OPTIONS

19       Xnest  supports  all  standard options of the sample server implementa‐
20       tion.  For more details, please see Xserver(1).   The  following  addi‐
21       tional arguments are supported as well.
22
23       -display string
24              This  option  specifies the display name of the real server that
25              Xnest should try to connect to.  If it is not  provided  on  the
26              command  line,  Xnest will read the DISPLAY environment variable
27              in order to find out this information.
28
29       -sync  This option tells Xnest to synchronize its window  and  graphics
30              operations  with  the  real server.  This is a useful option for
31              debugging, but it will slow down Xnest's  performance  consider‐
32              ably.  It should not be used unless absolutely necessary.
33
34       -full  This  option  tells  Xnest  to utilize full regeneration of real
35              server objects and reopen a new connection to  the  real  server
36              each  time the nested server regenerates.  The sample server im‐
37              plementation regenerates all objects in the server when the last
38              client  of  this server terminates.  When this happens, Xnest by
39              default maintains the same top-level window and  the  same  real
40              server  connection  in each new generation.  If the user selects
41              full regeneration, even the top-level window and the  connection
42              to  the  real server will be regenerated for each server genera‐
43              tion.
44
45       -class string
46              This option specifies the default visual  class  of  the  nested
47              server.   It  is similar to the -cc option from the set of stan‐
48              dard options except that it will accept a string rather  than  a
49              number  for  the visual class specification.  The string must be
50              one of the following six values: StaticGray, GrayScale,  Static‐
51              Color,  PseudoColor,  TrueColor,  or  DirectColor.   If both the
52              -class and -cc options are specified, the last instance  of  ei‐
53              ther  option  takes precedence.  The class of the default visual
54              of the nested server need not be the same as the  class  of  the
55              default  visual  of the real server, but it must be supported by
56              the real server.  Use xdpyinfo(1) to obtain a list of  supported
57              visual classes on the real server before starting Xnest.  If the
58              user chooses a static class, all the colors in the default color
59              map  will be preallocated.  If the user chooses a dynamic class,
60              colors in the default color map will be available to  individual
61              clients for allocation.
62
63       -depth int
64              This  option  specifies  the  default visual depth of the nested
65              server.  The depth of the default visual of  the  nested  server
66              need  not  be the same as the depth of the default visual of the
67              real server, but it must be supported by the real  server.   Use
68              xdpyinfo(1)  to  obtain a list of supported visual depths on the
69              real server before starting Xnest.
70
71       -sss   This option tells Xnest to use the software  screen  saver.   By
72              default, Xnest will use the screen saver that corresponds to the
73              hardware screen saver in the real server.  Of course, even  this
74              screen  saver is software-generated since Xnest does not control
75              any actual hardware.  However,  it  is  treated  as  a  hardware
76              screen saver within the sample server code.
77
78       -geometry WxH+X+Y
79              This  option specifies the geometry parameters for the top-level
80              Xnest window.  See “GEOMETRY SPECIFICATIONS” in X(7) for a  dis‐
81              cusson  of this option's syntax.  This window corresponds to the
82              root window of the nested server.  The  width  W  and  height  H
83              specified  with this option will be the maximum width and height
84              of each top-level Xnest window.  Xnest will allow  the  user  to
85              make  any  top-level  window  smaller,  but it will not actually
86              change the size of the nested server root  window.   Xnest  does
87              not  yet support the RANDR extension for resizing, rotation, and
88              reflection of the root window.  If this option is not specified,
89              Xnest  will  choose  W  and H to be 3/4ths the dimensions of the
90              root window of the real server.
91
92       -bw int
93              This option specifies the border width of  the  top-level  Xnest
94              window.   The  integer  parameter int must be positive.  The de‐
95              fault border width is 1.
96
97       -name string
98              This option specifies the name of the top-level Xnest window  as
99              string.  The default value is the program name.
100
101       -scrns int
102              This  option  specifies  the  number of screens to create in the
103              nested server.  For each screen, Xnest will  create  a  separate
104              top-level window.  Each screen is referenced by the number after
105              the dot in the client display name specification.  For  example,
106              xterm  -display  :1.1 will open an xterm(1) client in the nested
107              server with the display number :1 on  the  second  screen.   The
108              number  of  screens is limited by the hard-coded constant in the
109              server sample code, which is usually 3.
110
111       -install
112              This option tells Xnest to do its own color map installation  by
113              bypassing the real window manager.  For it to work properly, the
114              user will probably have to temporarily quit the real window man‐
115              ager.   By  default,  Xnest  will  keep the nested client window
116              whose color map should be installed in the real  server  in  the
117              WM_COLORMAP_WINDOWS  property of the top-level Xnest window.  If
118              this color map is of the same visual type as the root window  of
119              the  nested server, Xnest will associate this color map with the
120              top-level Xnest window as well.  Since this does not have to  be
121              the  case,  window managers should look primarily at the WM_COL‐
122              ORMAP_WINDOWS property rather than the color map associated with
123              the  top-level Xnest window.  Unfortunately, window managers are
124              not very good at doing that yet so this  option  might  come  in
125              handy.
126
127       -parent window_id
128              This  option tells Xnest to use window_id as the root window in‐
129              stead of creating a window.
130

EXTENDED DESCRIPTION

132       Starting up Xnest is just as simple as starting  up  xclock(1)  from  a
133       terminal  emulator.  If a user wishes to run Xnest on the same worksta‐
134       tion as the real server, it is important  that  the  nested  server  is
135       given  its  own  listening  socket  address.   Therefore, if there is a
136       server already running on the user's workstation, Xnest will have to be
137       started  up  with a new display number.  Since there is usually no more
138       than one server running on a workstation, specifying ‘Xnest :1’ on  the
139       command  line  will be sufficient for most users.  For each server run‐
140       ning on the workstation, the display number needs to be incremented  by
141       one.   Thus,  if you wish to start another Xnest, you will need to type
142Xnest :2’ on the command line.
143
144       To run clients in the nested server, each client needs to be given  the
145       same display number as the nested server.  For example, ‘xterm -display
146       :1’ will start up an xterm process  in  the  first  nested  server  and
147xterm  -display  :2’  will  start an xterm in the second nested server
148       from the example above.  Additional clients can be started  from  these
149       xterms in each nested server.
150
151   Xnest as a client
152       Xnest  behaves  and  looks to the real server and other real clients as
153       another real client.  It is a rather demanding client,  however,  since
154       almost  any window or graphics request from a nested client will result
155       in a window or graphics request from Xnest to the real server.   There‐
156       fore,  it  is  desirable  that Xnest and the real server are on a local
157       network, or even better, on the same machine.  Xnest assumes  that  the
158       real  server supports the SHAPE extension.  There is no way to turn off
159       this assumption dynamically.  Xnest can be compiled without  the  SHAPE
160       extension  built in, in which case the real server need not support it.
161       Dynamic SHAPE extension selection support may be considered in  further
162       development of Xnest.
163
164       Since  Xnest  need  not  use  the  same  default visual as the the real
165       server, the top-level window of the Xnest client  always  has  its  own
166       color  map.   This  implies that other windows' colors will not be dis‐
167       played properly while the keyboard or pointer focus  is  in  the  Xnest
168       window,  unless the real server has support for more than one installed
169       color map at any time.  The color map associated with the top window of
170       the  Xnest client need not be the appropriate color map that the nested
171       server wants installed in the real server.  In the case that  a  nested
172       client  attempts  to install a color map of a different visual from the
173       default visual of the nested server, Xnest will put the top  window  of
174       this nested client and all other top windows of the nested clients that
175       use the same color map into the  WM_COLORMAP_WINDOWS  property  of  the
176       top-level  Xnest window on the real server.  Thus, it is important that
177       the real window manager that manages the Xnest top-level  window  looks
178       at  the  WM_COLORMAP_WINDOWS property rather than the color map associ‐
179       ated with the top-level Xnest window.  Since most window managers don't
180       yet  appear to implement this convention properly, Xnest can optionally
181       do direct installation of color maps into the real server bypassing the
182       real  window  manager.   If the user chooses this option, it is usually
183       necessary to temporarily disable the real window manager since it  will
184       interfere with the Xnest scheme of color map installation.
185
186       Keyboard and pointer control procedures of the nested server change the
187       keyboard and pointer control parameters of the real server.  Therefore,
188       after Xnest is started up, it will change the keyboard and pointer con‐
189       trols of the real server to its own internal defaults.
190
191   Xnest as a server
192       Xnest as a server looks exactly like a real server to its own  clients.
193       For  the  clients,  there is no way of telling if they are running on a
194       real or a nested server.
195
196       As already mentioned, Xnest is a  very  user-friendly  server  when  it
197       comes  to  customization.   Xnest will pick up a number of command-line
198       arguments that can configure its default visual class and depth, number
199       of screens, etc.
200
201       The  only  apparent  intricacy  from the users' perspective about using
202       Xnest as a server is the selection of fonts.  Xnest  manages  fonts  by
203       loading  them locally and then passing the font name to the real server
204       and asking it to load that font remotely.   This  approach  avoids  the
205       overload  of  sending  the glyph bits across the network for every text
206       operation, although it is really a bug.  The consequence  of  this  ap‐
207       proach  is  that  the  user will have to worry about two different font
208       paths — a local one for the nested server and a remote one for the real
209       server  —  since  Xnest  does  not  propagate its font path to the real
210       server.  The reason for this is because real and  nested  servers  need
211       not run on the same file system which makes the two font paths mutually
212       incompatible.  Thus, if there is a font in the local font path  of  the
213       nested  server,  there is no guarantee that this font exists in the re‐
214       mote font path of the real server.  The xlsfonts(1) client, if  run  on
215       the  nested  server, will list fonts in the local font path and, if run
216       on the real server, will list fonts in the remote font path.  Before  a
217       font  can  be successfully opened by the nested server, it has to exist
218       in local and remote font paths.  It is  the  users'  responsibility  to
219       make sure that this is the case.
220

FUTURE DIRECTIONS

222       Make  dynamic  the  requirement  for  the  SHAPE  extension in the real
223       server, rather than having to recompile Xnest to turn this  requirement
224       on and off.
225
226       Perhaps  there should be a command-line option to tell Xnest to inherit
227       the keyboard and pointer control parameters from the real server rather
228       than imposing its own.
229
230       Xnest  should  read  a customization input file to provide even greater
231       freedom and simplicity in selecting the desired layout.
232
233       There is no support for backing store and save unders, but this  should
234       also be considered.
235
236       The proper implementation of fonts should be moved into the os layer.
237

BUGS

239       Doesn't run well on servers supporting different visual depths.
240
241       Still crashes randomly.
242
243       Probably has some memory leaks.
244

AUTHOR

246       Davor Matic, MIT X Consortium
247

SEE ALSO

249       Xserver(1), xdpyinfo(1), X(7)
250
251
252
253X Version 11                  xorg-server 1.20.14                     Xnest(1)
Impressum