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
XSM(1)									XSM(1)

NAME
       xsm - X Session Manager

SYNOPSIS
       xsm [-display display] [-session	sessionName] [-verbose]

DESCRIPTION
       xsm  is	a session manager.  A session is a group of applications, each
       of which	has a particular state.	 xsm allows you	 to  create  arbitrary
       sessions	 -  for	example, you might have	a "light" session, a "develop-
       ment" session, or an "xterminal"	session.  Each session	can  have  its
       own  set	 of applications.  Within a session, you can perform a "check-
       point" to save application state, or a "shutdown"  to  save  state  and
       exit  the  session.  When you log back in to the	system,	you can	load a
       specific	session, and you can delete sessions you  no  longer  want  to
       keep.

       Some  session  managers	simply allow you to manually specify a list of
       applications to be started in a session.	 xsm is	more powerful  because
       it lets you run applications and	have them automatically	become part of
       the session.  On	a simple level,	xsm is useful  because	it  gives  you
       this ability to easily define which applications	are in a session.  The
       true power of xsm, however, can be taken	advantage  of  when  more  and
       more applications learn to save and restore their state.

OPTIONS
       -display	display
	       Causes xsm to connect to	the specified X	display.

       -session	sessionName
	       Causes xsm to load the specified	session, bypassing the session
	       menu.

       -verbose
	       Turns on	debugging information.

SETUP
   .xsession file
       Using xsm requires a change to your .xsession file:

       The last	program	executed by your .xsession file	should be  xsm.	  With
       this  configuration,  when  the	user  chooses to shut down the session
       using xsm, the session will truly be over.

       Since the goal of the session manager is	to restart clients  when  log-
       ging  into  a  session,	your  .xsession	 file,	in general, should not
       directly	start up applications.	Rather,	 the  applications  should  be
       started	within	a  session.  When xsm shuts down the session, xsm will
       know to restart these applications.  Note however that there  are  some
       types  of applications that are not "session aware".  xsm allows	you to
       manually	add these applications to your session (see the	section	titled
       Client List).

   SM_SAVE_DIR environment variable
       If  the	SM_SAVE_DIR environment	variable is defined, xsm will save all
       configuration files in this directory.  Otherwise, they will be	stored
       in  the	user's	home  directory.   Session aware applications are also
       encouraged to save their	checkpoint files in the	SM_SAVE_DIR directory,
       although	the user should	not depend on this convention.

   Default Startup Applications
       The  first time xsm is started, it will need to locate a	list of	appli-
       cations to start	up.  For example, this list  might  include  a	window
       manager,	a session management proxy, and	an xterm.  xsm will first look
       for the file .xsmstartup	in the user's home directory.	If  that  file
       does not	exist, it will look for	the system.xsm file that was set up at
       installation time.  Note	that xsm provides a "fail  safe"  option  when
       the  user  chooses  a session to	start up.  The fail safe option	simply
       loads the default applications described	above.

       Each line in the	startup	file should contain  a	command	 to  start  an
       application.  A sample startup file might look this:

       <start of file>
       twm
       smproxy
       xterm
       <end of file>

STARTING A SESSION
       When xsm	starts up, it first checks to see if the user previously saved
       any sessions.  If no saved sessions exist,  xsm	starts	up  a  set  of
       default	applications (as described above in the	section	titled Default
       Startup Applications).  If at least one session exists, a session  menu
       is  presented.	The [-session sessionName] option forces the specified
       session to be loaded, bypassing the session menu.

   The session menu
       The session menu	presents the user with a list of  sessions  to	choose
       from.   The  user  can  change  the currently selected session with the
       mouse, or by using the up and down arrows on the	keyboard.   Note  that
       sessions	which are locked (i.e. running on a different display) can not
       be loaded or deleted.

       The following operations	can be performed from the session menu:

       Load Session	     Pressing this  button  will  load	the  currently
			     selected  session.	  Alternatively,  hitting  the
			     Return key	will also load the currently  selected
			     session,  or  the user can	double click a session
			     from the list.

       Delete Session	     This operation will delete	the currently selected
			     session, along with all of	the application	check-
			     point files associated with the  session.	 After
			     pressing  this  button, the user will be asked to
			     press the button a	second time in order  to  con-
			     firm the operation.

       Default/Fail Safe     xsm  will	start up a set of default applications
			     (as described above in the	section	titled Default
			     Startup  Applications).   This is useful when the
			     user wants	to start a fresh session,  or  if  the
			     session  configuration  files  were corrupted and
			     the user wants a "fail safe" session.

       Cancel		     Pressing this button will cause xsm to exit.   It
			     can  also	be  used  to cancel a "Delete Session"
			     operation.

CONTROLLING A SESSION
       After xsm determines which session to load, it brings up	its main  win-
       dow, then starts	up all applications that are part of the session.  The
       title bar for the session manager's main	window will contain  the  name
       of the session that was loaded.

       The following options are available from	xsm's main window:

       Client List	 Pressing  this	button brings up a window containing a
			 list of all clients that are in the current  session.
			 For  each client, the host machine that the client is
			 running on is presented.  As clients  are  added  and
			 removed  from	the  session,  this list is updated to
			 reflect the changes.  The user	is able	to control how
			 these clients are restarted (see below).

			 By  pressing the View Properties button, the user can
			 view the  session  management	properties  associated
			 with the currently selected client.

			 By  pressing  the  Clone button, the user can start a
			 copy of the selected application.

			 By pressing the Kill  Client  button,	the  user  can
			 remove	a client from the session.

			 By  selecting	a  restart  hint from the Restart Hint
			 menu, the  user  can  control	the  restarting	 of  a
			 client.  The following	hints are available:

			 -  The	 Restart  If  Running  hint indicates that the
			 client	should be restarted in the next	session	if  it
			 is connected to the session manager at	the end	of the
			 current session.

			 - The Restart Anyway hint indicates that  the	client
			 should	 be  restarted	in the next session even if it
			 exits before the current session is terminated.

			 - The Restart Immediately  hint  is  similar  to  the
			 Restart  Anyway  hint,	but in addition, the client is
			 meant to run continuously.  If	the client exits,  the
			 session manager will try to restart it	in the current
			 session.

			 - The Restart Never hint indicates  that  the	client
			 should	not be restarted in the	next session.

			 Note  that  all  X  applications  may not be "session
			 aware".  Applications that are	not session aware  are
			 ones  that  do	 not  support the X Session Management
			 Protocol or they can not be detected by  the  Session
			 Management  Proxy (see	the section titled THE PROXY).
			 xsm allows the	user to	manually add such applications
			 to the	session.  The bottom of	the Client List	window
			 contains a text entry field in	which application com-
			 mands can be typed in.	 Each command should go	on its
			 own line.  This information will be  saved  with  the
			 session  at  checkpoint  or  shutdown time.  When the
			 session is restarted, xsm will	restart	these applica-
			 tions	in  addition  to  the  regular "session	aware"
			 applications.

			 Pressing the Done button removes the Client List win-
			 dow.

       Session Log...	 The  Session  Log  window presents useful information
			 about the session.  For example, when	a  session  is
			 restarted,  all  of the restart commands will be dis-
			 played	in the log window.

       Checkpoint	 By performing a checkpoint, all applications that are
			 in  the  session  are asked to	save their state.  Not
			 every application will	save its complete  state,  but
			 at  a minimum,	the session manager is guaranteed that
			 it will receive the command required to  restart  the
			 application (along with all command line options).  A
			 window	manager	participating in  the  session	should
			 guarantee  that  the  applications  will come back up
			 with the same window configurations.

			 If the	session	being checkpointed was never  assigned
			 a  name,  the user will be required to	specify	a ses-
			 sion name.   Otherwise,  the  user  can  perform  the
			 checkpoint  using  the	current	session	name, or a new
			 session name can be specified.	 If the	 session  name
			 specified  already exists, the	user will be given the
			 opportunity to	specify	a different name or  to	 over-
			 write the already existing session.  Note that	a ses-
			 sion which is locked can not be overwritten.

			 When performing a checkpoint, the user	must specify a
			 Save  Type which informs the applications in the ses-
			 sion how much state they should save.

			 The Local type	indicates that the application	should
			 save  enough information to restore the state as seen
			 by the	user.  It should not affect the	state as  seen
			 by  other users.  For example,	an editor would	create
			 a temporary file containing the contents of its edit-
			 ing buffer, the location of the cursor, etc...

			 The Global type indicates that	the application	should
			 commit	all of its data	to permanent, globally	acces-
			 sible	storage.  For example, the editor would	simply
			 save the edited file.

			 The Both type indicates that the  application	should
			 do both of these.  For	example, the editor would save
			 the edited file, then create a	 temporary  file  with
			 information  such  as	the  location  of  the cursor,
			 etc...

			 In addition to	the Save Type, the user	 must  specify
			 an Interact Style.

			 The  None  type indicates that	the application	should
			 not interact with the user while saving state.

			 The Errors type indicates that	 the  application  may
			 interact  with	 the  user  only if an error condition
			 arises.

			 The Any  type	indicates  that	 the  application  may
			 interact  with	 the  user for any purpose.  Note that
			 xsm will only allow one application to	interact  with
			 the user at a time.

			 After	the checkpoint is completed, xsm will, if nec-
			 essary, display  a  window  containing	 the  list  of
			 applications  which  did not report a successful save
			 of state.

       Shutdown		 A shutdown provides all of the	 options  found	 in  a
			 checkpoint, but in addition, can cause	the session to
			 exit.	Note that if the interaction style  is	Errors
			 or  Any,  the user may	cancel the shutdown.  The user
			 may also cancel the shutdown if any of	 the  applica-
			 tions report an unsuccessful save of state.

			 The  user may choose to shutdown the session with our
			 without performing a checkpoint.

HOW XSM	RESPONDS TO SIGNALS
       xsm will	respond	to a SIGTERM signal by performing a shutdown with  the
       following  options: fast, no interaction, save type local.  This	allows
       the user's session to be	saved when the system is being	shutdown.   It
       can also	be used	to perform a remote shutdown of	a session.

       xsm  will  respond  to a	SIGUSR1	signal by performing a checkpoint with
       the following options: no interaction, save type	 local.	  This	signal
       can be used to perform a	remote checkpoint of a session.

THE PROXY
       Since  not  all	applications have been ported to support the X Session
       Management Protocol, a proxy service exists to allow "old"  clients  to
       work  with  the	session	 manager.  In order for	the proxy to detect an
       application joining a session, one of the following must	be true:

       -  The  application  maps   a   top   level   window   containing   the
       WM_CLIENT_LEADER	 property.   This  property  provides a	pointer	to the
       client leader window which contains the WM_CLASS, WM_NAME,  WM_COMMAND,
       and WM_CLIENT_MACHINE properties.

       or ...

       -  The  application  maps a top level window which does not contain the
       WM_CLIENT_LEADER	property.  However, this top level window contains the
       WM_CLASS, WM_NAME, WM_COMMAND, and WM_CLIENT_MACHINE properties.

       An  application that support the	WM_SAVE_YOURSELF protocol will receive
       a WM_SAVE_YOURSELF client message each time the session manager	issues
       a  checkpoint  or shutdown.  This allows	the application	to save	state.
       If an application does not support the WM_SAVE_YOURSELF protocol,  then
       the  proxy  will	 provide  enough information to	the session manager to
       restart the application	(using	WM_COMMAND),  but  no  state  will  be
       restored.

REMOTE APPLICATIONS
       xsm  requires  a	remote execution protocol in order to restart applica-
       tions on	remote machines.  Currently, xsm supports the rstart protocol.
       In  order to restart an application on remote machine X,	machine	X must
       have rstart installed.  In the future, additional remote	execution pro-
       tocols may be supported.

SEE ALSO
       smproxy(1), rstart(1)

AUTHORS
       Ralph Mor, X Consortium
       Jordan Brown, Quarterdeck Office	Systems

XFree86				 Version 4.7.0				XSM(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | SETUP | STARTING A SESSION | CONTROLLING A SESSION | HOW XSM RESPONDS TO SIGNALS | THE PROXY | REMOTE APPLICATIONS | SEE ALSO | AUTHORS

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

home | help