diff options
Diffstat (limited to 'xsm.man')
| -rw-r--r-- | xsm.man | 343 |
1 files changed, 343 insertions, 0 deletions
@@ -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 |