NAME

xsm − X Session Manager

SYNOPSIS

xsm [ −i ] [ −f sessionfile ] [ −sf sessiontypesfile ]

DESCRIPTION

Xsm 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 xsm terminates, the session is over and the user is logged out. 

Xsm also provides a comfortable environment for novice users to start and stop commonly-used X client programs and provides 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. 

STARTING XSM

Xsm is typically started automatically by xdm(1) or startx(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, xsm is started automatically on their behalf.  The user who has written a customised startup script can still make use of xsm by simply calling it as the last action in that script. 

OPTIONS

−f sessionfile: use named file instead of .xsmrc
−sf sessiontypesfile: get session types from the named file
−i: ignore user’s .xsmrc file

USING XSM

After starting xsm the configuration file .xsmrc 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 .xsmrc 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 briefly described in the on-line help window available by pressing the Help 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 xsm’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. 

THE CONTROL WINDOW

The small control window contains five pushbuttons.  The Help button opens a window containing help on using xsm.  The Clients button opens the client window, which is described below.  The Save button prompts the user for a filename, and saves the current state of the session.  See the section below on session files.  The Errors button opens the error log window, which is a scrolling log of recent error messages from client programs.  The Logout button quits xsm after asking for confirmation. 

THE CLIENT WINDOW

The 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 indicator 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 different 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. 

EDITING THE CLIENT WINDOW

The contents of the client window can be changed interactively.  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:

Cut: Delete this client, and move it to an internal clipboard.  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). 

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

Paste:
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 multiple times to replicate it.

Edit...:
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 window.  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 simultaneously edit as many clients as you wish, but can only open one edit window per client.

New...:
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 Save 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 configuration file with a text editor. 

THE ERROR LOG

The error log may be examined at any time by clicking the Errors button in the control window.  The error log contains any messages displayed by window managers and clients to 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. 

CONFIGURATION FILES

The rest of this manual page is aimed at the system administrator or advanced user.  Xsm can be configured to suit local requirements by editing the files in /usr/lib/X11/xsm. The master configuration file is called sessiontypes. This file contains the mapping from session names (which appear in the pushbuttons in the session selection window) and session files which describe the sessions.  A typical sessiontypes 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 session 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 characters are needed in a field then the whole field should be enclosed in double quote characters. 

The Help line tells xsm 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 absolute pathnames. 

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

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 wm 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 client lines each describe a client to add to the bottom part of the clients window.  They take the same format as the wm lines, except that any number of clients may be set "on". 

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

The resources line instructs xsm 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 resources 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 absolute pathnames.  Command lines may not contain shell metacharacters 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 appearance.  The file may be as long as required as the help window is fitted with scrollbars. 

X RESOURCES

Almost every widget resource needed by xsm is located in the file /usr/lib/X11/app-defaults/Xsm. This file may require some changes to suit local requirements.  The file is commented to assist the system administrator to understand the widget hierarchy, but a copy of the OSF/Motif Programmer’s Reference 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. 

userSessionFile:
name of the user session file.  Equivalent to the −f command line flag.  Default: ~/.xsmrc

sessionTypesFile:
name of the master session types file.  Equivalent to the −sf command line flag.  Default: /usr/lib/X11/xsm/sessiontypes

selectionHelpFile:
name of the default session selection help file. This is overridden by a help specification in the sessiontypes file.  Default: /usr/lib/X11/xsm/selection.help

sessionHelpFile:
name of the default session help file.  This is overridden by a help specification in the session description file.  Default: /usr/lib/X11/xsm/session.help

ignoreUserSession:
if True, ignore the user’s .xsmrc file and always go through the session selection step.  Equivalent to the −i command line flag.  Default: False

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

WARNINGS

Both the mwm(1) and twm(1) window managers also provide an interface to start clients.  In both cases the clients started from these window managers belong to the same process 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.  Normally it is better to use the xsm interface to start new clients. 

FILES

/usr/lib/X11/xsm − configuration directory
/usr/lib/X11/xsm/sessiontypes − master sessiontypes file
/usr/lib/X11/app-defaults/Xsm − default resource set

SEE ALSO

xdm(1), xinit(1)
RISCiX X Window System Administrator’s Guide

COPYRIGHT

Copyright 1990, Acorn Computers Ltd. 

AUTHOR

Steve Hunt, Acorn Computers Ltd. 

Acorn Computers Ltd  —  Revision 1.7 of 09/11/90