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)                  FreeBSD General Commands Manual                 XSM(1)

       xsm - X Session Manager

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

       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
       "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

       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

               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 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
       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 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>
       <end of file>

       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
                             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 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"

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

                         - 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
                         commands 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
                         applications in addition to the regular "session
                         aware" applications.

                         Pressing the Done button removes the Client List

       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
                         displayed 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
                         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 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 overwritten.

                         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 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
                         accessible 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,

                         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

                         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
                         necessary, 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
                         applications report an unsuccessful save of state.

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

       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.

       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

       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

       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 supported.

       smproxy(1), rstart(1)

       Ralph Mor, X Consortium
       Jordan Brown, Quarterdeck Office Systems

XFree86                          Version 4.7.0                          XSM(1)


Want to link to this manual page? Use this URL:

home | help