[0m


XSM(1)		    UNIX Programmer's Manual		   XSM(1)



[1mNAME
     [0mxsm - X Session Manager

[1mSYNOPSIS
     xsm [0m[ [1m-i [0m] [ [1m-f [0m_s_e_s_s_i_o_n_f_i_l_e ] [ [1m-sf [0m_s_e_s_s_i_o_n_t_y_p_e_s_f_i_l_e ]

[1mDESCRIPTION
     [0m_X_s_m is a session management tool for users of the X Window
     System.  It is intended to take the place of the login shell
     in a character terminal connection in that it is the program
     that defines the duration of the session; when _x_s_m ter-
     minates, the session is over and the user is logged out.

     _X_s_m also provides a comfortable environment for novice users
     to start and stop commonly-used X client programs and pro-
     vides a mechanism for starting chosen clients automatically
     when the user logs in.

     Control of window managers is facilitated by a mechanism
     which lets the user choose from a list of window managers.
     When a new one is selected, the one currently running is
     automatically killed before the new one is started.  This
     helps to avoid the unfortunate situation of being left
     without a window manager and being unable to start one.

     An error log window is provided which captures any messages
     that client programs print to standard output or standard
     error.

[1mSTARTING XSM
     [0m_X_s_m is typically started automatically by _x_d_m(_1) or
     _s_t_a_r_t_x(_1) as the final action in their default session
     scripts.  This means that when a user who has not written
     their own script starts X with one of these interfaces, _x_s_m
     is started automatically on their behalf.	The user who has
     written a customised startup script can still make use of
     _x_s_m by simply calling it as the last action in that script.

[1mOPTIONS
     -f [0m_s_e_s_s_i_o_n_f_i_l_e: use named file instead of .xsmrc
     [1m-sf [0m_s_e_s_s_i_o_n_t_y_p_e_s_f_i_l_e: get session types from the named file
     [1m-i[0m: ignore user's .xsmrc file

[1mUSING XSM
     [0mAfter starting _x_s_m the configuration file ._x_s_m_r_c is sought
     in the user's home directory.  If this file is present, then
     the the session selection process about to be described is
     skipped, and the session described in this file is used.

     If ._x_s_m_r_c is not found, or if the -_i switch was specified,
     then a window is displayed in the centre of the screen.  The
     window lists a number of predefined sessions, which are



Printed 11/2/92     Revision 1.7 of 09/11/90			1






XSM(1)		    UNIX Programmer's Manual		   XSM(1)



     briefly described in the on-line help window available by
     pressing the _H_e_l_p button.	The user chooses a session type
     by pressing its button and the session selection window is
     removed.

     The user is now running the chosen session.  A small window
     appears in the bottom right-hand corner of the screen; this
     is _x_s_m'_s control window.  A window manager will start, and
     some other X client programs may start too, depending on the
     session chosen.  The X Window System is now ready for use.

[1mTHE CONTROL WINDOW
     [0mThe small control window contains five pushbuttons.  The
     _H_e_l_p button opens a window containing help on using _x_s_m. The
     _C_l_i_e_n_t_s button opens the client window, which is described
     below.  The _S_a_v_e button prompts the user for a filename, and
     saves the current state of the session.  See the section
     below on session files.  The _E_r_r_o_r_s button opens the error
     log window, which is a scrolling log of recent error mes-
     sages from client programs.  The _L_o_g_o_u_t button quits _x_s_m
     after asking for confirmation.

[1mTHE CLIENT WINDOW
     [0mThe client window is divided into two sections.  The top
     part contains a list of window managers, the bottom a list
     of other client programs.	Each program is shown as a name
     and a small indicator to show if the program is running.  At
     most one window manager may be running at once, but other
     clients may be mixed as required.

     To turn a client on, simply click on its name.  The indica-
     tor will be highlighted, and the program started.	The
     client may be exited by using its own exit option, or by
     clicking on the name again, turning the indicator off.

     Window managers are slightly different.  Since at most one
     window manager may be running at once, clicking on a dif-
     ferent one automatically kills the one that is currently
     running before starting the new one.  It is desirable to
     have a window manager running all the time, so if the
     current window manager exits unexpectedly a dialogue box is
     displayed offering the user the option of restarting it.

[1mEDITING THE CLIENT WINDOW
     [0mThe contents of the client window can be changed interac-
     tively.  Place the mouse pointer over one of the client
     labels and press the right-hand mouse button.  A pop up menu
     will be displayed.  This menu allows you to manipulate the
     entry that the mouse pointer was over.

     The menu contains five buttons:




Printed 11/2/92     Revision 1.7 of 09/11/90			2






XSM(1)		    UNIX Programmer's Manual		   XSM(1)



     _C_u_t: Delete this client, and move it to an internal clip-
	  board.  The clipboard only has room for one client;
	  cutting another will cause the first to be lost.  You
	  cannot cut a running client, because the semantics of
	  this operation are unclear with respect to killing the
	  client.  Similarly you cannot cut a client which is
	  being edited (see below).

     _C_o_p_y:
	  Copy this client to the clipboard without deleting it.
	  Unlike _C_u_t, you may do this to a running client.

     _P_a_s_t_e:
	  Paste the contents of the clipboard immediately after
	  the client under the pointer.  To paste before the
	  first client, summon the menu with the pointer on the
	  label that says `Clients:'.  Pasted clients always
	  start turned off.  You may paste the same client multi-
	  ple times to replicate it.

     _E_d_i_t...:
	  Edit the client under the pointer.  A window will
	  appear containing two editable strings.  The upper
	  string is the title to be displayed in the clients win-
	  dow.	The lower string is the command to execute in
	  order to run the program.  Click `OK' to accept your
	  changes or `Cancel' to dispose of them.  You may simul-
	  taneously edit as many clients as you wish, but can
	  only open one edit window per client.

     _N_e_w...:
	  Creates a new client entry immediately after the one
	  under the pointer.  To insert it before the first
	  client, summon the menu with the pointer on the label
	  that says `Clients:'.  The entry `New Client' will
	  appear in the window, and its edit window will be
	  automatically opened.  Type in the name and program,
	  then press OK.

     After changes have been made it may be necessary to resize
     the clients window to obtain a nice layout.  Remember to use
     the _S_a_v_e button if you want your changes to persist to the
     your session.

     Note that the editing facility is not available on window
     managers.	To change these you will have to edit your confi-
     guration file with a text editor.

[1mTHE ERROR LOG
     [0mThe error log may be examined at any time by clicking the
     _E_r_r_o_r_s button in the control window.  The error log contains
     any messages displayed by window managers and clients to



Printed 11/2/92     Revision 1.7 of 09/11/90			3






XSM(1)		    UNIX Programmer's Manual		   XSM(1)



     either standard output or standard error.	It is a good
     place to look if a client unexpectedly dies or fails to
     start.

     The error log remembers the last 80 lines, which can be
     reviewed using the scrollbars.  When new messages arrive the
     scrollbar is automatically kept at the bottom of the file.
     This is so that new messages will be immediately visible.
     However this behaviour is awkward if you are trying to
     review an old message, so it will only happen if the
     scrollbar is already at the bottom of its travel.	Keep the
     scrollbar in this position in normal use, and new messages
     will be visible immediately.

[1mCONFIGURATION FILES
     [0mThe rest of this manual page is aimed at the system adminis-
     trator or advanced user.  _X_s_m can be configured to suit
     local requirements by editing the files in /_u_s_r/_l_i_b/_X_1_1/_x_s_m.
     The master configuration file is called _s_e_s_s_i_o_n_t_y_p_e_s.  This
     file contains the mapping from session names (which appear
     in the pushbuttons in the session selection window) and ses-
     sion files which describe the sessions.  A typical session-
     types file is shown below.

	  ! Session types file
	  session "Motif session" /usr/lib/X11/xsm/motif.sess
	  session "MIT session" /usr/lib/X11/xsm/mit.sess
	  help /usr/lib/X11/xsm/select.help


     Each _s_e_s_s_i_o_n line introduces another session type into the
     selection window.	A session line has two additional fields;
     the name of the session and the filename which describes it.
     The fields are separated by spaces or tabs; if these charac-
     ters are needed in a field then the whole field should be
     enclosed in double quote characters.

     The _H_e_l_p line tells _x_s_m where to find the help text for the
     session selection window.

     Comments are denoted by a ! character in the first non-blank
     position of a line.  Note that all filenames must be abso-
     lute pathnames.

     The files named by the _s_e_s_s_i_o_n lines are known as _s_e_s_s_i_o_n
     _f_i_l_e_s.  Each describes the window managers and clients
     available in a particular session.  This format is also used
     when saving the user's ._x_s_m_r_c file.







Printed 11/2/92     Revision 1.7 of 09/11/90			4






XSM(1)		    UNIX Programmer's Manual		   XSM(1)



     A typical session file is shown below.

	  ! Motif session
	  wm Mwm on /usr/bin/X11/mwm
	  wm Twm off /usr/bin/X11/twm
	  client "XTerm 1" off /usr/bin/X11/xterm -title "XTerm 1"
	  client "XEdit" off /usr/bin/X11/xedit
	  client "Control Panel" off /usr/bin/X11/xcontrol
	  client "Square Clock" on /usr/bin/X11/xclock
	  client "Round Clock" off /usr/bin/X11/oclock
	  help /usr/lib/X11/xsm/session.help
	  resources /usr/lib/X11/xsm/motif.res

     The file format is similar to that of the session types
     file.  Each _w_m line adds a window manager to the list of
     available ones in the client window.  The second field is
     the label to be displayed, and may be enclosed in double
     quotes if spaces are required.  The next field should be
     either "on" or "off" and indicates whether this window
     manager should be started automatically when the session is
     started.  Only one window manager should be "on".	The
     remainder of the line is the command to execute to run this
     window manager.

     The _c_l_i_e_n_t lines each describe a client to add to the bottom
     part of the clients window.  They take the same format as
     the _w_m lines, except that any number of clients may be set
     "on".

     The _h_e_l_p line tells _x_s_m where to find the help text for the
     help window.  There may be at most one _h_e_l_p line.

     The _r_e_s_o_u_r_c_e_s line instructs _x_s_m to load the specified
     resource database into the X server before starting any of
     the client programs.  The resources are merged into any
     resources that are already there, and if there are multiple
     _r_e_s_o_u_r_c_e_s lines, then they are handled in the order they are
     mentioned.

     Comments are denoted by a ! character in the first non-blank
     position of a line.  Note that all filenames must be abso-
     lute pathnames.  Command lines may not contain shell meta-
     characters like < and >, but they may contain double quote
     characters.

     Help files are plain ASCII text, with lines delimited by
     newline characters.  There is no formatting capability, so
     the files must be hand-tuned to obtain a reasonable appear-
     ance.  The file may be as long as required as the help win-
     dow is fitted with scrollbars.





Printed 11/2/92     Revision 1.7 of 09/11/90			5






XSM(1)		    UNIX Programmer's Manual		   XSM(1)



[1mX RESOURCES
     [0mAlmost every widget resource needed by _x_s_m is located in the
     file /_u_s_r/_l_i_b/_X_1_1/_a_p_p-_d_e_f_a_u_l_t_s/_X_s_m.  This file may require
     some changes to suit local requirements.  The file is com-
     mented to assist the system administrator to understand the
     widget hierarchy, but a copy of the _O_S_F/_M_o_t_i_f _P_r_o_g_r_a_m_m_e_r'_s
     _R_e_f_e_r_e_n_c_e will be needed for advanced customisation.

     There are a few application-specific resources.  In each
     case the class is formed by capitalising the first letter of
     the name.

     _u_s_e_r_S_e_s_s_i_o_n_F_i_l_e:
	  name of the user session file.  Equivalent to the [1m-f
	  [0mcommand line flag.  Default: ~/.xsmrc

     _s_e_s_s_i_o_n_T_y_p_e_s_F_i_l_e:
	  name of the master session types file.  Equivalent to
	  the [1m-sf [0mcommand line flag.  Default:
	  /usr/lib/X11/xsm/sessiontypes

     _s_e_l_e_c_t_i_o_n_H_e_l_p_F_i_l_e:
	  name of the default session selection help file.  This
	  is overridden by a _h_e_l_p specification in the session-
	  types file.  Default: /usr/lib/X11/xsm/selection.help

     _s_e_s_s_i_o_n_H_e_l_p_F_i_l_e:
	  name of the default session help file.  This is over-
	  ridden by a _h_e_l_p specification in the session descrip-
	  tion file.  Default: /usr/lib/X11/xsm/session.help

     _i_g_n_o_r_e_U_s_e_r_S_e_s_s_i_o_n:
	  if True, ignore the user's .xsmrc file and always go
	  through the session selection step.  Equivalent to the
	  [1m-i [0mcommand line flag.  Default: False

     _w_m_D_e_a_t_h_P_a_u_s_e:
	  length of time to wait (in seconds) for window managers
	  to die.  Default: one second

[1mWARNINGS
     [0mBoth the _m_w_m(1) and _t_w_m(1) window managers also provide an
     interface to start clients.  In both cases the clients
     started from these window managers belong to the same pro-
     cess group as a the window manger itself, this has the
     consequence that killing the window manager (by clicking in
     the window manager section of the clients window) will also
     kill all the clients started from that window manager.  Nor-
     mally it is better to use the _x_s_m interface to start new
     clients.





Printed 11/2/92     Revision 1.7 of 09/11/90			6






XSM(1)		    UNIX Programmer's Manual		   XSM(1)



[1mFILES
     [0m/usr/lib/X11/xsm - configuration directory
     /usr/lib/X11/xsm/sessiontypes - master sessiontypes file
     /usr/lib/X11/app-defaults/Xsm - default resource set

[1mSEE ALSO
     [0mxdm(1), xinit(1)
     RISCiX X Window System Administrator's Guide

[1mCOPYRIGHT
     [0mCopyright 1990, Acorn Computers Ltd.

[1mAUTHOR
     [0mSteve Hunt, Acorn Computers Ltd.









































Printed 11/2/92     Revision 1.7 of 09/11/90			7



[0m