Commit | Line | Data |
---|---|---|
a09e091a JB |
1 | .\" $Xorg: Xnest.man,v 1.3 2000/08/17 19:53:28 cpqbld Exp $ |
2 | .\" Copyright (c) 1993, 1994 X Consortium | |
3 | .\" | |
4 | .\" Permission is hereby granted, free of charge, to any person obtaining | |
5 | .\" a copy of this software and associated documentation files (the | |
6 | .\" "Software"), to deal in the Software without restriction, including | |
7 | .\" without limitation the rights to use, copy, modify, merge, publish, | |
8 | .\" distribute, sublicense, and/or sell copies of the Software, and to | |
9 | .\" permit persons to whom the Software is furnished to do so, subject to | |
10 | .\" the following conditions: | |
11 | .\" | |
12 | .\" The above copyright notice and this permission notice shall be included | |
13 | .\" in all copies or substantial portions of the Software. | |
14 | .\" | |
15 | .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS | |
16 | .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF | |
17 | .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. | |
18 | .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR | |
19 | .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, | |
20 | .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR | |
21 | .\" OTHER DEALINGS IN THE SOFTWARE. | |
22 | .\" | |
23 | .\" Except as contained in this notice, the name of the X Consortium shall | |
24 | .\" not be used in advertising or otherwise to promote the sale, use or | |
25 | .\" other dealings in this Software without prior written authorization | |
26 | .\" from the X Consortium. | |
27 | .\" | |
28 | .\" $XFree86: xc/programs/Xserver/hw/xnest/Xnest.man,v 1.6 2001/01/27 18:21:00 dawes Exp $ | |
29 | .\" | |
30 | .TH Xnest __appmansuffix__ __xorgversion__ | |
31 | .SH NAME | |
32 | Xnest \- a nested X server | |
33 | .SH SYNOPSIS | |
34 | .B Xnest | |
35 | [ | |
36 | .I options | |
37 | ] | |
38 | .SH DESCRIPTION | |
39 | .B Xnest | |
40 | is both an X client and an X server. | |
41 | .B Xnest | |
42 | is a client of the real server which manages windows and graphics requests on | |
43 | its behalf. | |
44 | .B Xnest | |
45 | is a server to its own clients. | |
46 | .B Xnest | |
47 | manages windows and graphics requests on their behalf. | |
48 | To these clients, | |
49 | .B Xnest | |
50 | appears to be a conventional server. | |
51 | .SH OPTIONS | |
52 | .B Xnest | |
53 | supports all standard options of the sample server implementation. | |
54 | For more details, please see | |
55 | .BR Xserver (__appmansuffix__). | |
56 | The following additional arguments are supported as well. | |
57 | .TP | |
58 | .BI "\-display " string | |
59 | This option specifies the display name of the real server that | |
60 | .B Xnest | |
61 | should try to connect to. | |
62 | If it is not provided on the command line, | |
63 | .B Xnest | |
64 | will read the | |
65 | .I DISPLAY | |
66 | environment variable in order to find out this information. | |
67 | .TP | |
68 | .B \-sync | |
69 | This option tells | |
70 | .B Xnest | |
71 | to synchronize its window and graphics operations with the real server. | |
72 | This is a useful option for debugging, but it will slow down | |
73 | .BR Xnest 's | |
74 | performance considerably. | |
75 | It should not be used unless absolutely necessary. | |
76 | .TP | |
77 | .B \-full | |
78 | This option tells | |
79 | .B Xnest | |
80 | to utilize full regeneration of real server objects and reopen a new connection | |
81 | to the real server each time the nested server regenerates. | |
82 | The sample server implementation regenerates all objects in the server when the | |
83 | last client of this server terminates. | |
84 | When this happens, | |
85 | .B Xnest | |
86 | by default maintains the same top-level window and the same real server | |
87 | connection in each new generation. | |
88 | If the user selects full regeneration, even the top-level window and the | |
89 | connection to the real server will be regenerated for each server generation. | |
90 | .TP | |
91 | .BI "\-class " string | |
92 | This option specifies the default visual class of the nested server. | |
93 | It is similar to the | |
94 | .B \-cc | |
95 | option from the set of standard options except that it will accept a string | |
96 | rather than a number for the visual class specification. | |
97 | The | |
98 | .I string | |
99 | must be one of the following six values: | |
100 | .BR StaticGray , | |
101 | .BR GrayScale , | |
102 | .BR StaticColor , | |
103 | .BR PseudoColor , | |
104 | .BR TrueColor , | |
105 | or | |
106 | .BR DirectColor . | |
107 | If both the | |
108 | .B \-class | |
109 | and | |
110 | .B \-cc | |
111 | options are specified, the last instance of either option takes precedence. | |
112 | The class of the default visual of the nested server need not be the same as the | |
113 | class of the default visual of the real server, but it must be supported by the | |
114 | real server. | |
115 | Use | |
116 | .BR xdpyinfo (__appmansuffix__) | |
117 | to obtain a list of supported visual classes on the real server before starting | |
118 | .BR Xnest . | |
119 | If the user chooses a static class, all the colors in the default color map will | |
120 | be preallocated. | |
121 | If the user chooses a dynamic class, colors in the default color map will be | |
122 | available to individual clients for allocation. | |
123 | .TP | |
124 | .BI "\-depth " int | |
125 | This option specifies the default visual depth of the nested server. | |
126 | The depth of the default visual of the nested server need not be the same as the | |
127 | depth of the default visual of the real server, but it must be supported by the | |
128 | real server. | |
129 | Use | |
130 | .BR xdpyinfo (__appmansuffix__) | |
131 | to obtain a list of supported visual depths on the real server before starting | |
132 | .BR Xnest . | |
133 | .TP | |
134 | .B \-sss | |
135 | This option tells | |
136 | .B Xnest | |
137 | to use the software screen saver. | |
138 | By default, | |
139 | .B Xnest | |
140 | will use the screen saver that corresponds to the hardware screen saver in the | |
141 | real server. | |
142 | Of course, even this screen saver is software-generated since | |
143 | .B Xnest | |
144 | does not control any actual hardware. | |
145 | However, it is treated as a hardware screen saver within the sample server code. | |
146 | .TP | |
147 | .B \-geometry \fIW\fBx\fIH\fB+\fIX\fB+\fIY\fP | |
148 | This option specifies the geometry parameters for the top-level | |
149 | .B Xnest | |
150 | window. | |
151 | See \(lqGEOMETRY SPECIFICATIONS\(rq in | |
152 | .BR X (__miscmansuffix__) | |
153 | for a discusson of this option's syntax. | |
154 | This window corresponds to the root window of the nested server. | |
155 | The width | |
156 | .I W | |
157 | and height | |
158 | .I H | |
159 | specified with this option will be the maximum width and height of each | |
160 | top-level | |
161 | .B Xnest | |
162 | window. | |
163 | .B Xnest | |
164 | will allow the user to make any top-level window smaller, but it will not | |
165 | actually change the size of the nested server root window. | |
166 | .B Xnest | |
167 | does not yet support the RANDR extension for resizing, rotation, and reflection | |
168 | of the root window. | |
169 | If this option is not specified, | |
170 | .B Xnest | |
171 | will choose | |
172 | .I W | |
173 | and | |
174 | .I H | |
175 | to be 3/4ths the dimensions of the root window of the real server. | |
176 | .TP | |
177 | .BI "\-bw " int | |
178 | This option specifies the border width of the top-level | |
179 | .B Xnest | |
180 | window. | |
181 | The integer parameter | |
182 | .I int | |
183 | must be positive. | |
184 | The default border width is 1. | |
185 | .TP | |
186 | .BI "\-name " string | |
187 | This option specifies the name of the top-level | |
188 | .B Xnest | |
189 | window as | |
190 | .IR string . | |
191 | The default value is the program name. | |
192 | .TP | |
193 | .BI "\-scrns " int | |
194 | This option specifies the number of screens to create in the nested server. | |
195 | For each screen, | |
196 | .B Xnest | |
197 | will create a separate top-level window. | |
198 | Each screen is referenced by the number after the dot in the client display name | |
199 | specification. | |
200 | For example, | |
201 | .B xterm \-display :1.1 | |
202 | will open an | |
203 | .BR xterm (__appmansuffix__) | |
204 | client in the nested server with the display number | |
205 | .B :1 | |
206 | on the second screen. | |
207 | The number of screens is limited by the hard-coded constant in the server sample | |
208 | code, which is usually 3. | |
209 | .TP | |
210 | .B \-install | |
211 | This option tells | |
212 | .B Xnest | |
213 | to do its own color map installation by bypassing the real window manager. | |
214 | For it to work properly, the user will probably have to temporarily quit the | |
215 | real window manager. | |
216 | By default, | |
217 | .B Xnest | |
218 | will keep the nested client window whose color map should be installed in the | |
219 | real server in the | |
220 | .I WM_COLORMAP_WINDOWS | |
221 | property of the top-level | |
222 | .B Xnest | |
223 | window. | |
224 | If this color map is of the same visual type as the root window of the nested | |
225 | server, | |
226 | .B Xnest | |
227 | will associate this color map with the top-level | |
228 | .B Xnest | |
229 | window as well. | |
230 | Since this does not have to be the case, window managers should look primarily | |
231 | at the | |
232 | .I WM_COLORMAP_WINDOWS | |
233 | property rather than the color map associated with the top-level | |
234 | .B Xnest | |
235 | window. | |
236 | .\" Is the following still true? This sentence is several years old. | |
237 | Unfortunately, window managers are not very good at doing that yet so this | |
238 | option might come in handy. | |
239 | .TP | |
240 | .BI "\-parent " window_id | |
241 | This option tells | |
242 | .B Xnest | |
243 | to use | |
244 | .I window_id | |
245 | as the root window instead of creating a window. | |
246 | .\" XRX is dead, dead, dead. | |
247 | .\" This option is used by the xrx xnestplugin. | |
248 | .SH "EXTENDED DESCRIPTION" | |
249 | Starting up | |
250 | .B Xnest | |
251 | is just as simple as starting up | |
252 | .BR xclock (__appmansuffix__) | |
253 | from a terminal emulator. | |
254 | If a user wishes to run | |
255 | .B Xnest | |
256 | on the same | |
257 | workstation as the real server, it is important that the nested server is given | |
258 | its own listening socket address. | |
259 | Therefore, if there is a server already running on the user's workstation, | |
260 | .B Xnest | |
261 | will have to be started up with a new display number. | |
262 | Since there is usually no more than one server running on a workstation, | |
263 | specifying | |
264 | .RB \(oq "Xnest :1" \(cq | |
265 | on the command line will be sufficient for most users. | |
266 | For each server running on the workstation, the display number needs to be | |
267 | incremented by one. | |
268 | Thus, if you wish to start another | |
269 | .BR Xnest , | |
270 | you will need to type | |
271 | .RB \(oq "Xnest :2" \(cq | |
272 | on the command line. | |
273 | .PP | |
274 | To run clients in the nested server, each client needs to be given the same | |
275 | display number as the nested server. | |
276 | For example, | |
277 | .RB \(oq "xterm \-display :1" \(cq | |
278 | will start up an | |
279 | .B xterm | |
280 | process in the first nested server | |
281 | and | |
282 | .RB \(oq "xterm \-display :2" \(cq | |
283 | will start an | |
284 | .B xterm | |
285 | in the second nested server from the example above. | |
286 | Additional clients can be started from these | |
287 | .BR xterm s | |
288 | in each nested server. | |
289 | .SS "Xnest as a client" | |
290 | .B Xnest | |
291 | behaves and looks to the real server and other real clients as another real | |
292 | client. | |
293 | It is a rather demanding client, however, since almost any window or graphics | |
294 | request from a nested client will result in a window or graphics request from | |
295 | .B Xnest | |
296 | to the real server. | |
297 | Therefore, it is desirable that | |
298 | .B Xnest | |
299 | and the real server are on a local network, or even better, on the same machine. | |
300 | .B Xnest | |
301 | assumes that the real server supports the SHAPE extension. | |
302 | There is no way to turn off this assumption dynamically. | |
303 | .B Xnest | |
304 | can be compiled without the SHAPE extension built in, in which case the real | |
305 | server need not support it. | |
306 | Dynamic SHAPE extension selection support may be considered in further | |
307 | development of | |
308 | .BR Xnest . | |
309 | .PP | |
310 | Since | |
311 | .B Xnest | |
312 | need not use the same default visual as the the real server, the top-level | |
313 | window of the | |
314 | .B Xnest | |
315 | client always has its own color map. | |
316 | This implies that other windows' colors will not be displayed properly while the | |
317 | keyboard or pointer focus is in the | |
318 | .B Xnest | |
319 | window, unless the real server has support for more than one installed color map | |
320 | at any time. | |
321 | The color map associated with the top window of the | |
322 | .B Xnest | |
323 | client need not be the appropriate color map that the nested server wants | |
324 | installed in the real server. | |
325 | In the case that a nested client attempts to install a color map of a different | |
326 | visual from the default visual of the nested server, | |
327 | .B Xnest | |
328 | will put the top window of this nested client and all other top windows of the | |
329 | nested clients that use the same color map into the | |
330 | .I WM_COLORMAP_WINDOWS | |
331 | property of the top-level | |
332 | .B Xnest | |
333 | window on the real server. | |
334 | Thus, it is important that the real window manager that manages the | |
335 | .B Xnest | |
336 | top-level window looks at the | |
337 | .I WM_COLORMAP_WINDOWS | |
338 | property rather than the color map associated with the top-level | |
339 | .B Xnest | |
340 | window. | |
341 | Since most window managers don't yet appear to implement this convention | |
342 | properly, | |
343 | .B Xnest | |
344 | can optionally do direct installation of color maps into the real server | |
345 | bypassing the real window manager. | |
346 | If the user chooses this option, it is usually necessary to temporarily disable | |
347 | the real window manager since it will interfere with the | |
348 | .B Xnest | |
349 | scheme of color map installation. | |
350 | .PP | |
351 | Keyboard and pointer control procedures of the nested server change the keyboard | |
352 | and pointer control parameters of the real server. | |
353 | Therefore, after | |
354 | .B Xnest | |
355 | is started up, it will change the keyboard and pointer controls of the real | |
356 | server to its own internal defaults. | |
357 | .SS "Xnest as a server" | |
358 | .B Xnest | |
359 | as a server looks exactly like a real server to its own clients. | |
360 | For the clients, there is no way of telling if they are running on a real or a | |
361 | nested server. | |
362 | .PP | |
363 | As already mentioned, | |
364 | .B Xnest | |
365 | is a very user-friendly server when it comes to customization. | |
366 | .B Xnest | |
367 | will pick up a number of command-line arguments that can configure its default | |
368 | visual class and depth, number of screens, etc. | |
369 | .PP | |
370 | The only apparent intricacy from the users' perspective about using | |
371 | .B Xnest | |
372 | as a server is the selection of fonts. | |
373 | .B Xnest | |
374 | manages fonts by loading them locally and then passing the font name to the real | |
375 | server and asking it to load that font remotely. | |
376 | This approach avoids the overload of sending the glyph bits across the network | |
377 | for every text operation, although it is really a bug. | |
378 | The consequence of this approach is that the user will have to worry about two | |
379 | different font paths \(em a local one for the nested server and a remote one for | |
380 | the real server \(em since | |
381 | .B Xnest | |
382 | does not propagate its font path to the real server. | |
383 | The reason for this is because real and nested servers need not run on the same | |
384 | file system which makes the two font paths mutually incompatible. | |
385 | Thus, if there is a font in the local font path of the nested server, there is | |
386 | no guarantee that this font exists in the remote font path of the real server. | |
387 | The | |
388 | .BR xlsfonts (__appmansuffix__) | |
389 | client, if run on the nested server, will list fonts in the local font path and, | |
390 | if run on the real server, will list fonts in the remote font path. | |
391 | Before a font can be successfully opened by the nested server, it has to exist | |
392 | in local and remote font paths. | |
393 | It is the users' responsibility to make sure that this is the case. | |
394 | .SH "FUTURE DIRECTIONS" | |
395 | Make dynamic the requirement for the SHAPE extension in the real server, rather | |
396 | than having to recompile | |
397 | .B Xnest | |
398 | to turn this requirement on and off. | |
399 | .PP | |
400 | Perhaps there should be a command-line option to tell | |
401 | .B Xnest | |
402 | to inherit the keyboard and pointer control parameters from the real server | |
403 | rather than imposing its own. | |
404 | .PP | |
405 | .B Xnest | |
406 | should read a customization input file to provide even greater freedom and | |
407 | simplicity in selecting the desired layout. | |
408 | .PP | |
409 | There is no support for backing store and save unders, but this should also be | |
410 | considered. | |
411 | .PP | |
412 | .\" Is the following still true now that client-side font rendering is | |
413 | .\" considered the way to go? | |
414 | The proper implementation of fonts should be moved into the | |
415 | .I os | |
416 | layer. | |
417 | .SH BUGS | |
418 | Doesn't run well on servers supporting different visual depths. | |
419 | .PP | |
420 | Still crashes randomly. | |
421 | .PP | |
422 | Probably has some memory leaks. | |
423 | .SH AUTHOR | |
424 | Davor Matic, MIT X Consortium | |
425 | .SH "SEE ALSO" | |
426 | .BR Xserver (__appmansuffix__), | |
427 | .BR xdpyinfo (__appmansuffix__), | |
428 | .BR X (__miscmansuffix__) |