R6.6 is the Xorg base-lineXORG-MAIN

1 files changed, 343 insertions, 0 deletions

diff --git a/xsm.man b/xsm.man
new file mode 100644
index 0000000..280621c
--- /dev/null
+++ b/xsm.man
@@ -0,0 +1,343 @@
+.\" $Xorg: xsm.man,v 1.4 2001/02/09 02:06:01 xorgcvs Exp $
+.\" Copyright 1994,1998  The Open Group
+.\" 
+.\" Permission to use, copy, modify, distribute, and sell this software and its
+.\" documentation for any purpose is hereby granted without fee, provided that
+.\" the above copyright notice appear in all copies and that both that
+.\" copyright notice and this permission notice appear in supporting
+.\" documentation.
+.\" 
+.\" The above copyright notice and this permission notice shall be included
+.\" in all copies or substantial portions of the Software.
+.\" 
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
+.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\" OTHER DEALINGS IN THE SOFTWARE.
+.\" 
+.\" Except as contained in this notice, the name of The Open Group shall
+.\" not be used in advertising or otherwise to promote the sale, use or
+.\" other dealings in this Software without prior written authorization
+.\" from The Open Group.
+.TH XSM 1 "Release 6.4" "X Version 11"
+.SH NAME
+xsm \- X Session Manager
+.SH SYNOPSIS
+.B xsm
+[-display display] [-session sessionName] [-verbose]
+.SH DESCRIPTION
+.PP
+\fIxsm\fP is a session manager.  A session is a group of applications, each
+of which has a particular state.  \fIxsm\fP 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.
+.br
+.sp
+Some session managers simply allow you to manually specify a list of
+applications to be started in a session.  \fIxsm\fP is more powerful
+because it lets you run applications and have them automatically become
+part of the session.  On a simple level, \fIxsm\fP is useful because it
+gives you this ability to easily define which applications are in a session.
+The true power of \fIxsm\fP, however, can be taken advantage of when more
+and more applications learn to save and restore their state.
+.SH OPTIONS
+.TP 8
+.B \-display \fIdisplay\fP
+Causes \fIxsm\fP to connect to the specified X display.
+.TP 8
+.B \-session \fIsessionName\fP
+Causes \fIxsm\fP to load the specified session, bypassing the session menu.
+.TP 8
+.B \-verbose
+Turns on debugging information.
+.SH SETUP
+.SS .xsession file
+Using \fIxsm\fP requires a change to your \fI.xsession\fP file:
+.PP
+The last program executed by your \fI.xsession\fP file should
+be \fIxsm\fP.  With this configuration, when the user chooses to shut
+down the session using \fIxsm\fP, the session will truly be over.
+.PP
+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 \fIxsm\fP shuts down the session, \fIxsm\fP will know to
+restart these applications.  Note however that there are some types of
+applications that are not "session aware".  \fIxsm\fP allows you to
+manually add these applications to your session (see the section titled
+\fIClient List\fP).
+.PP
+.SS SM_SAVE_DIR environment variable
+If the \fISM_SAVE_DIR\fP environment variable is defined, \fIxsm\fP 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 \fISM_SAVE_DIR\fP directory,
+although the user should not depend on this convention.
+.PP
+.SS Default Startup Applications
+The first time \fIxsm\fP 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.  \fIxsm\fP will first
+look for the file \fI.xsmstartup\fP in the user's home directory.  If that
+file does not exists, it will look for the \fIsystem.xsm\fP file that was
+set up at installation time.  Note that \fIxsm\fP 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.
+.PP
+Each line in the startup file should contain a command to start an application.
+A sample startup file might look this:
+.PP
+<start of file>
+.br
+twm
+.br
+smproxy
+.br
+xterm
+.br
+<end of file>
+.PP
+.SH STARTING A SESSION
+When \fIxsm\fP starts up, it first checks to see if the user previously
+saved any sessions.  If no saved sessions exist, \fIxsm\fP starts up a set
+of default applications (as described above in the section titled
+\fIDefault Startup Applications\fP).  If at least one session exists, a
+session menu is presented.  The \fB[-session sessionName]\fR option forces the
+specified session to be loaded, bypassing the session menu.
+.SS 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.
+.PP
+The following operations can be performed from the session menu:
+.PP
+.TP 22
+.B 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.
+.TP 22
+.B 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.
+.TP 22
+.B Default/Fail Safe
+\fIxsm\fP will start up a set of default applications (as described above
+in the section titled \fIDefault Startup Applications\fP).  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.
+.TP 22
+.B Cancel
+Pressing this button will cause \fIxsm\fP to exit.  It can also be used to
+cancel a "Delete Session" operation.
+.PP
+.SH CONTROLLING A SESSION
+After \fIxsm\fP 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.
+.PP
+The following options are available from \fIxsm\fP's main window:
+.TP 18
+.B 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).
+.br
+.sp
+By pressing the \fBView Properties\fR
+button, the user can view the session management properties associated with
+the currently selected client.
+.br
+.sp
+By pressing the \fBClone\fR button, the user can start a copy of the selected
+application.
+.br
+.sp
+By pressing the \fBKill Client\fR button, the user can remove a client from
+the session.
+.br
+.sp
+By selecting a restart hint from the \fBRestart Hint\fR menu, the user can
+control the restarting of a client.  The following hints are available:
+.br
+.sp
+.B \-
+The \fBRestart If Running\fR 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.
+.br
+.sp
+.B \-
+The \fBRestart Anyway\fR hint indicates that the client should be restarted
+in the next session even if it exits before the current session is terminated.
+.br
+.sp
+.B \-
+The \fBRestart Immediately\fR hint is similar to the \fBRestart Anyway\fR 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.
+.br
+.sp
+.B \-
+The \fBRestart Never\fR hint indicates that the client should not be restarted
+in the next session.
+.br
+.sp
+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 \fITHE PROXY\fP).  \fIxsm\fP allows the user to manually add
+such applications to the session.  The bottom of the \fIClient List\fP 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,
+\fIxsm\fP will restart these applications in addition to the regular "session
+aware" applications.
+.br
+.sp
+Pressing the \fBDone\fR button removes the \fBClient List\fR window.
+.TP 18
+.B 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.
+.TP 18
+.B 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.
+.br
+.sp
+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.
+.br
+.sp
+When performing a checkpoint, the user must specify a \fBSave Type\fR
+which informs the applications in the session how much state they should save.
+.br
+.sp
+The \fBLocal\fR
+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...
+.br
+.sp
+The \fBGlobal\fR
+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.
+.br
+.sp
+The \fBBoth\fR
+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, etc...
+.br
+.sp
+In addition to the \fBSave Type\fR, the user must specify an
+\fBInteract Style\fR.
+.br
+.sp
+The \fBNone\fR type indicates that the application should not interact with
+the user while saving state.
+.br
+.sp
+The \fBErrors\fR type indicates that the application may interact with
+the user only if an error condition arises.
+.br
+.sp
+The \fBAny\fR type indicates that the application may interact with
+the user for any purpose.  Note that \fIxsm\fP will only allow one
+application to interact with the user at a time.
+.br
+.sp
+.sp
+After the checkpoint is completed, \fIxsm\fP will, if necessary, display a
+window containing the list of applications which did not report a successful
+save of state.
+.TP 18
+.B 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
+\fBErrors\fR or \fBAny\fR, the user may cancel the shutdown.  The user may
+also cancel the shutdown if any of the applications report an
+unsuccessful save of state.
+.br
+.sp
+The user may choose to shutdown the session with our without performing a
+checkpoint.
+.PP
+.SH HOW \fIXSM\fP RESPONDS TO SIGNALS
+\fIxsm\fP 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.
+.br
+.sp
+\fIxsm\fP 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.
+.PP
+.SH 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
+application joining a session, one of the following must be true:
+.br
+.sp
+- The application maps a top level window containing the
+\fBWM_CLIENT_LEADER\fR property.  This property provides a pointer to
+the client leader window which contains the \fBWM_CLASS\fR, \fBWM_NAME\fR,
+\fBWM_COMMAND\fR, and \fBWM_CLIENT_MACHINE\fR properties.
+.br
+.sp
+or ...
+.br
+.sp
+- The application maps a top level window which does not contain the
+\fBWM_CLIENT_LEADER\fR property.  However, this top level window
+contains the \fBWM_CLASS\fR, \fBWM_NAME\fR, \fBWM_COMMAND\fR, and
+\fBWM_CLIENT_MACHINE\fR properties.
+.PP
+An application that support the \fBWM_SAVE_YOURSELF\fR protocol will receive
+a \fBWM_SAVE_YOURSELF\fR 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 \fBWM_SAVE_YOURSELF\fR protocol, then
+the proxy will provide enough information to the session manager to restart
+the application (using \fBWM_COMMAND\fR), but no state will be restored.
+.PP
+.SH REMOTE APPLICATIONS
+\fIxsm\fP requires a remote execution protocol in order to restart
+applications on remote machines.  Currently, \fIxsm\fP supports the
+\fIrstart\fP protocol.  In order to restart an application on remote
+machine \fBX\fR, machine \fBX\fR must have \fIrstart\fP installed.  In
+the future, additional remote execution protocols may be supported.
+.SH SEE ALSO
+smproxy(1), rstart(1)
+.SH AUTHORS
+Ralph Mor, X Consortium
+.br
+Jordan Brown, Quarterdeck Office Systems