XSM(1) General Commands Manual 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 ses-
sions - for example, you might have a "light" session, a "development"
session, or an "xterminal" session. Each session can have its own set
of applications. Within a session, you can perform a "checkpoint" to
save application state, or a "shutdown" to save state and exit the ses-
sion. When you log back in to the system, you can load a specific ses-
sion, and you can delete sessions you no longer want to keep.
Some session managers simply allow you to manually specify a list of ap-
plications 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 ap-
plications 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 logging
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 en-
couraged 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 applica-
tions to start up. For example, this list might include a window man-
ager, 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 in-
stallation 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 ap-
plication. 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 de-
fault applications (as described above in the section titled Default
Startup Applications). If at least one session exists, a session menu
is presented. The -session option forces the specified sessionName ses-
sion 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 se-
lected 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 confirm
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" op-
eration.
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 re-
moved from the session, this list is updated to re-
flect 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 re-
move 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 ex-
its 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 Pro-
tocol or they can not be detected by the Session Man-
agement 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 ses-
sion is restarted, xsm will restart these applications
in addition to the regular "session aware" applica-
tions.
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 ap-
plication (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 session
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 al-
ready exists, the user will be given the opportunity
to specify a different name or to overwrite the al-
ready existing session. Note that a session 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 editing
buffer, the location of the cursor, etc...
The Global type indicates that the application should
commit all of its data to permanent, globally accessi-
ble 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 infor-
mation 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 in-
teract with the user only if an error condition
arises.
The Any type indicates that the application may inter-
act 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 neces-
sary, display a window containing the list of applica-
tions 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 applications
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 ap-
plication 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
X Version 11 xsm 1.0.5 XSM(1)
Generated by dwww version 1.16 on Sat Oct 3 06:26:11 CEST 2026.