1XSM(1) General Commands Manual XSM(1)
2
6 xsm - X Session Manager
7
9 xsm [-display display] [-session sessionName] [-verbose]
10
12 xsm is a session manager. A session is a group of applications, each
13 of which has a particular state. xsm allows you to create arbitrary
14 sessions - for example, you might have a "light" session, a "develop‐
15 ment" session, or an "xterminal" session. Each session can have its
16 own set of applications. Within a session, you can perform a "check‐
17 point" to save application state, or a "shutdown" to save state and
18 exit the session. When you log back in to the system, you can load a
19 specific session, and you can delete sessions you no longer want to
20 keep.
21 Some session managers simply allow you to manually specify a list of
23 applications to be started in a session. xsm is more powerful because
24 it lets you run applications and have them automatically become part of
25 the session. On a simple level, xsm is useful because it gives you
26 this ability to easily define which applications are in a session. The
27 true power of xsm, however, can be taken advantage of when more and
28 more applications learn to save and restore their state.
29
31 -display display
32 Causes xsm to connect to the specified X display.
33 -session sessionName
35 Causes xsm to load the specified session, bypassing the session
36 menu.
37 -verbose
39 Turns on debugging information.
40
42 .xsession file
43 Using xsm requires a change to your .xsession file:
44 The last program executed by your .xsession file should be xsm. With
46 this configuration, when the user chooses to shut down the session
47 using xsm, the session will truly be over.
48 Since the goal of the session manager is to restart clients when log‐
50 ging into a session, your .xsession file, in general, should not
51 directly start up applications. Rather, the applications should be
52 started within a session. When xsm shuts down the session, xsm will
53 know to restart these applications. Note however that there are some
54 types of applications that are not "session aware". xsm allows you to
55 manually add these applications to your session (see the section titled
56 Client List).
57 SM_SAVE_DIR environment variable
59 If the SM_SAVE_DIR environment variable is defined, xsm will save all
60 configuration files in this directory. Otherwise, they will be stored
61 in the user's home directory. Session aware applications are also
62 encouraged to save their checkpoint files in the SM_SAVE_DIR directory,
63 although the user should not depend on this convention.
64 Default Startup Applications
66 The first time xsm is started, it will need to locate a list of appli‐
67 cations to start up. For example, this list might include a window
68 manager, a session management proxy, and an xterm. xsm will first look
69 for the file .xsmstartup in the user's home directory. If that file
70 does not exist, it will look for the system.xsm file that was set up at
71 installation time. Note that xsm provides a "fail safe" option when
72 the user chooses a session to start up. The fail safe option simply
73 loads the default applications described above.
74 Each line in the startup file should contain a command to start an
76 application. A sample startup file might look this:
77 <start of file>
79 twm
80 smproxy
81 xterm
82 <end of file>
83
85 When xsm starts up, it first checks to see if the user previously saved
86 any sessions. If no saved sessions exist, xsm starts up a set of
87 default applications (as described above in the section titled Default
88 Startup Applications). If at least one session exists, a session menu
89 is presented. The [-session sessionName] option forces the specified
90 session to be loaded, bypassing the session menu.
91 The session menu
93 The session menu presents the user with a list of sessions to choose
94 from. The user can change the currently selected session with the
95 mouse, or by using the up and down arrows on the keyboard. Note that
96 sessions which are locked (i.e. running on a different display) can not
97 be loaded or deleted.
98 The following operations can be performed from the session menu:
100 Load Session Pressing this button will load the currently
102 selected session. Alternatively, hitting the
103 Return key will also load the currently selected
104 session, or the user can double click a session
105 from the list.
106 Delete Session This operation will delete the currently selected
108 session, along with all of the application check‐
109 point files associated with the session. After
110 pressing this button, the user will be asked to
111 press the button a second time in order to con‐
112 firm the operation.
113 Default/Fail Safe xsm will start up a set of default applications
115 (as described above in the section titled Default
116 Startup Applications). This is useful when the
117 user wants to start a fresh session, or if the
118 session configuration files were corrupted and
119 the user wants a "fail safe" session.
120 Cancel Pressing this button will cause xsm to exit. It
122 can also be used to cancel a "Delete Session"
123 operation.
124
126 After xsm determines which session to load, it brings up its main win‐
127 dow, then starts up all applications that are part of the session. The
128 title bar for the session manager's main window will contain the name
129 of the session that was loaded.
130 The following options are available from xsm's main window:
132 Client List Pressing this button brings up a window containing a
134 list of all clients that are in the current session.
135 For each client, the host machine that the client is
136 running on is presented. As clients are added and
137 removed from the session, this list is updated to
138 reflect the changes. The user is able to control how
139 these clients are restarted (see below).
140 By pressing the View Properties button, the user can
142 view the session management properties associated
143 with the currently selected client.
144 By pressing the Clone button, the user can start a
146 copy of the selected application.
147 By pressing the Kill Client button, the user can
149 remove a client from the session.
150 By selecting a restart hint from the Restart Hint
152 menu, the user can control the restarting of a
153 client. The following hints are available:
154 - The Restart If Running hint indicates that the
156 client should be restarted in the next session if it
157 is connected to the session manager at the end of the
158 current session.
159 - The Restart Anyway hint indicates that the client
161 should be restarted in the next session even if it
162 exits before the current session is terminated.
163 - The Restart Immediately hint is similar to the
165 Restart Anyway hint, but in addition, the client is
166 meant to run continuously. If the client exits, the
167 session manager will try to restart it in the current
168 session.
169 - The Restart Never hint indicates that the client
171 should not be restarted in the next session.
172 Note that all X applications may not be "session
174 aware". Applications that are not session aware are
175 ones that do not support the X Session Management
176 Protocol or they can not be detected by the Session
177 Management Proxy (see the section titled THE PROXY).
178 xsm allows the user to manually add such applications
179 to the session. The bottom of the Client List window
180 contains a text entry field in which application com‐
181 mands can be typed in. Each command should go on its
182 own line. This information will be saved with the
183 session at checkpoint or shutdown time. When the
184 session is restarted, xsm will restart these applica‐
185 tions in addition to the regular "session aware"
186 applications.
187 Pressing the Done button removes the Client List win‐
189 dow.
190 Session Log... The Session Log window presents useful information
192 about the session. For example, when a session is
193 restarted, all of the restart commands will be dis‐
194 played in the log window.
195 Checkpoint By performing a checkpoint, all applications that are
197 in the session are asked to save their state. Not
198 every application will save its complete state, but
199 at a minimum, the session manager is guaranteed that
200 it will receive the command required to restart the
201 application (along with all command line options). A
202 window manager participating in the session should
203 guarantee that the applications will come back up
204 with the same window configurations.
205 If the session being checkpointed was never assigned
207 a name, the user will be required to specify a ses‐
208 sion name. Otherwise, the user can perform the
209 checkpoint using the current session name, or a new
210 session name can be specified. If the session name
211 specified already exists, the user will be given the
212 opportunity to specify a different name or to over‐
213 write the already existing session. Note that a ses‐
214 sion which is locked can not be overwritten.
215 When performing a checkpoint, the user must specify a
217 Save Type which informs the applications in the ses‐
218 sion how much state they should save.
219 The Local type indicates that the application should
221 save enough information to restore the state as seen
222 by the user. It should not affect the state as seen
223 by other users. For example, an editor would create
224 a temporary file containing the contents of its edit‐
225 ing buffer, the location of the cursor, etc...
226 The Global type indicates that the application should
228 commit all of its data to permanent, globally acces‐
229 sible storage. For example, the editor would simply
230 save the edited file.
231 The Both type indicates that the application should
233 do both of these. For example, the editor would save
234 the edited file, then create a temporary file with
235 information such as the location of the cursor,
236 etc...
237 In addition to the Save Type, the user must specify
239 an Interact Style.
240 The None type indicates that the application should
242 not interact with the user while saving state.
243 The Errors type indicates that the application may
245 interact with the user only if an error condition
246 arises.
247 The Any type indicates that the application may
249 interact with the user for any purpose. Note that
250 xsm will only allow one application to interact with
251 the user at a time.
252 After the checkpoint is completed, xsm will, if nec‐
255 essary, display a window containing the list of
256 applications which did not report a successful save
257 of state.
258 Shutdown A shutdown provides all of the options found in a
260 checkpoint, but in addition, can cause the session to
261 exit. Note that if the interaction style is Errors
262 or Any, the user may cancel the shutdown. The user
263 may also cancel the shutdown if any of the applica‐
264 tions report an unsuccessful save of state.
265 The user may choose to shutdown the session with our
267 without performing a checkpoint.
268
270 xsm will respond to a SIGTERM signal by performing a shutdown with the
271 following options: fast, no interaction, save type local. This allows
272 the user's session to be saved when the system is being shutdown. It
273 can also be used to perform a remote shutdown of a session.
274 xsm will respond to a SIGUSR1 signal by performing a checkpoint with
276 the following options: no interaction, save type local. This signal
277 can be used to perform a remote checkpoint of a session.
278
280 Since not all applications have been ported to support the X Session
281 Management Protocol, a proxy service exists to allow "old" clients to
282 work with the session manager. In order for the proxy to detect an
283 application joining a session, one of the following must be true:
284 - The application maps a top level window containing the
286 WM_CLIENT_LEADER property. This property provides a pointer to the
287 client leader window which contains the WM_CLASS, WM_NAME, WM_COMMAND,
288 and WM_CLIENT_MACHINE properties.
289 or ...
291 - The application maps a top level window which does not contain the
293 WM_CLIENT_LEADER property. However, this top level window contains the
294 WM_CLASS, WM_NAME, WM_COMMAND, and WM_CLIENT_MACHINE properties.
295 An application that support the WM_SAVE_YOURSELF protocol will receive
297 a WM_SAVE_YOURSELF client message each time the session manager issues
298 a checkpoint or shutdown. This allows the application to save state.
299 If an application does not support the WM_SAVE_YOURSELF protocol, then
300 the proxy will provide enough information to the session manager to
301 restart the application (using WM_COMMAND), but no state will be
302 restored.
303
305 xsm requires a remote execution protocol in order to restart applica‐
306 tions on remote machines. Currently, xsm supports the rstart protocol.
307 In order to restart an application on remote machine X, machine X must
308 have rstart installed. In the future, additional remote execution pro‐
309 tocols may be supported.
310
312 smproxy(1), rstart(1)
313
315 Ralph Mor, X Consortium
316 Jordan Brown, Quarterdeck Office Systems
317X Version 11 xsm 1.0.1 XSM(1)