MirBSD manpage: xsm(1)

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


     xsm - X Session Manager


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


     xsm is a session manager.  A session is a group of applica-
     tions, each of which has a particular state.  xsm allows you
     to create arbitrary sessions - 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 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.


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

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

             Turns on debugging information.


     .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 gen-
     eral, 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

XFree86                   Version 4.5.0                         1

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

     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 check-
     point 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 applications 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 exists, it
     will look for the system.xsm file that was set up at instal-
     lation 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

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

     <start of file>
     <end of file>


     When xsm starts up, it first checks to see if the user pre-
     viously 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

     The following operations can be performed from the session

XFree86                   Version 4.5.0                         2

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

     Load Session          Pressing this button will load the
                           currently selected session.  Alterna-
                           tively, hitting the Return key will
                           also load the currently selected ses-
                           sion, 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 checkpoint
                           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

     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 ses-
                           sion, 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.


     After xsm determines which session to load, it brings up its
     main window, 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

     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 run-
                       ning 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.

XFree86                   Version 4.5.0                         3

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

                       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 Res-
                       tart 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

                       - 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 addi-
                       tion, the client is meant to run continu-
                       ously.  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 manu-
                       ally add such applications to the session.
                       The bottom of the Client List window con-
                       tains a text entry field in which applica-
                       tion commands can be typed in. Each com-
                       mand 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 applications in addition to the reg-
                       ular "session aware" applications.

                       Pressing the Done button removes the

XFree86                   Version 4.5.0                         4

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

                       Client List window.

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

     Checkpoint        By performing a checkpoint, all applica-
                       tions 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 configura-

                       If the session being checkpointed was
                       never assigned a name, the user will be
                       required to specify a session name.  Oth-
                       erwise, the user can perform the check-
                       point 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 overwrite
                       the already existing session.  Note that a
                       session which is locked can not be

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

                       The Local type indicates that the applica-
                       tion 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 loca-
                       tion of the cursor, etc...

                       The Global type indicates that the appli-
                       cation should commit all of its data to
                       permanent, globally accessible storage.
                       For example, the editor would simply save

XFree86                   Version 4.5.0                         5

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

                       the edited file.

                       The Both type indicates that the applica-
                       tion should do both of these.  For exam-
                       ple, 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 applica-
                       tion should not interact with the user
                       while saving state.

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

                       The Any type indicates that the applica-
                       tion 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 necessary, display a window con-
                       taining 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 applications report an unsuccessful
                       save of state.

                       The user may choose to shutdown the ses-
                       sion with our without performing a check-


     xsm will respond to a SIGTERM signal by performing a shut-
     down 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 per-
     form a remote shutdown of a session.

XFree86                   Version 4.5.0                         6

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

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


     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,

     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.


     xsm requires a remote execution protocol in order to restart
     applications 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 protocols may be


     smproxy(1), rstart(1)


     Ralph Mor, X Consortium
     Jordan Brown, Quarterdeck Office Systems

XFree86                   Version 4.5.0                         7

Generated on 2021-12-07 11:07:08 by $MirOS: src/scripts/roff2htm,v 1.103 2021/01/23 20:24:35 tg Exp $ — This product includes material provided by mirabilos.

These manual pages and other documentation are copyrighted by their respective writers; their sources are available at the project’s CVSweb, AnonCVS and other mirrors. The rest is Copyright © 2002–2021 MirBSD.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report — diffs preferred.