Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
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.

       -noinput
	   This	 option	 disables  input  for Xnest, running it	in a view-only
	   mode.

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

XFree86				 Version 4.7.0			      XNEST(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | USAGE | XNEST AS A CLIENT | XNEST AS A SERVER | BUGS | AUTHOR

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=Xnest&sektion=1&manpath=XFree86+4.7.0>

home | help