XSM(1)

✨ XSM(1) — the X Session Manager, but make it bestie ✨

okay so first things first, the manual name is xsm and it lives in section 1 of the General Commands Manual, and honestly? she's iconic. let's get into it 💖

---

🌸 NAME 🌸

xsm — the X Session Manager. that's it, that's the name, she's booked and busy 🎀

---

🦋 SYNOPSIS 🦋

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

three little flags, no chaos, we love a low-maintenance queen ✨

---

💜 DESCRIPTION 💜

so like, xsm is a session manager. and a session is a group of applications, where each one has a particular state. xsm lets you create arbitrary sessions — like, literally whatever you want. for example bestie, you might have a "light" session, a "development" session, or an "xterminal" session. each session can have its own lil set of applications. no cap 🫶

within a session, you can do a "checkpoint" to save application state, or a "shutdown" to save state and exit the session. and then when you log back in to the system, you can load a specific session — and you can also delete sessions you no longer want to keep. spring cleaning energy 🧹✨

now, some session managers just let you 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. but the true power of xsm? that's unlocked when more and more applications learn to save and restore their state. it's giving ✨ ecosystem ✨ and honestly we're obsessed.

---

💅 OPTIONS 💅

• -display display — causes xsm to connect to the specified X display. go where you're told, bestie 🦋
• -session sessionName — causes xsm to load the specified session, bypassing the session menu. no menu, straight to business, main character energy 👑
• -verbose — turns on debugging information. she's telling you EVERYTHING, fr fr 💀

---

🌈 SETUP 🌈

🎀 .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. periodt.

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. iykyk 💖

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). don't worry bestie, we got them 🙈

💖 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. so like, it's a vibe, not a promise 🌸

⭐ 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. it's the "just make it work" button and honestly, we stan 🫶

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

<start of file>
twm
smproxy
xterm
<end of file>

look at her. three lines. no notes. slay 💅

---

🔥 STARTING A SESSION 🔥

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 option forces the specified sessionName session to be loaded, bypassing the session menu. skip the line, VIP entrance 👑

🦋 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. they're booked elsewhere, bestie, we can't touch them 💀

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. three ways to say yes, we love options ✨
• 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. yes, it double-checks, because deleting your whole vibe by accident is NOT the move 😭
• 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. fresh start, clean slate, we love a reset button 🧚
• Cancel — pressing this button will cause xsm to exit. it can also be used to cancel a "Delete Session" operation. the "never mind bestie" button 🙈

---

okay that's part one, and there's more coming so don't go anywhere — we are NOT done yet 💜

💖 CONTROLLING A SESSION 💖

So after xsm figures out which session to load, it pops up its main window, and then starts launching every single application that's part of the session. The title bar of the session manager's main window will literally contain the name of the session that got loaded. cute, right? 🎀

Here's everything you can do from xsm's main window:

• Client List — tap this button and a window pops up with a list of every client chillin' in the current session. For each client, you get the host machine that the client is running on. As clients get added and removed from the session, this list updates itself to reflect the changes, no cap. And bestie, you get to control how these clients are restarted (more on that below 👇).
  • Hit the View Properties button and you can view the session management properties associated with the currently selected client. 👀
  • Hit the Clone button and you can start a copy of the selected application. twin behavior fr fr. ✨
  • Hit the Kill Client button and you can remove a client from the session. 💀
  • Pick a restart hint from the Restart Hint menu and you can control the restarting of a client. Here are your options, bestie:
    • The Restart If Running hint means 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 means the client should be restarted in the next session even if it exits before the current session is terminated.
    • The Restart Immediately hint is giving Restart Anyway energy but turned up — the client is meant to run continuously. If the client exits, the session manager will try to restart it in the current session.
    • The Restart Never hint means the client should not be restarted in the next session. periodt.

Heads up: not all X applications are "session aware". 🙈 Applications that are not session aware are ones that don't support the X Session Management Protocol, or ones that can't be detected by the Session Management Proxy (go read the section titled THE PROXY). xsm lets you manually add these applications to the session, because of course it does, it's an icon.

The bottom of the Client List window has a text entry field where you can type in application commands. Each command should go on its own line, okay? This info gets 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" ones. 🫶

Pressing the Done button removes the Client List window. bye bestie 🌸

• Session Log... — the Session Log window serves up useful information about the session. Like, when a session is restarted, all of the restart commands will be displayed in the log window. it's giving receipts. 📜
• Checkpoint — performing a checkpoint means all applications in the session get 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, you'll be required to specify a session name. Otherwise, you can perform the checkpoint using the current session name, or you can specify a new session name. If the session name you specified already exists, you'll 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, you must specify a Save Type, which informs the applications in the session how much state they should save.

• The Local type means 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 means 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 means 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...

In addition to the Save Type, you must specify an Interact Style.

• The None type means the application should not interact with the user while saving state.
• The Errors type means the application may interact with the user only if an error condition arises.
• The Any type means 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. one at a time, bestie, we're not chaotic. ✋

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 gives you all of the options found in a checkpoint, but in addition, it can cause the session to exit. Note that if the interaction style is Errors or Any, you may cancel the shutdown. You may also cancel the shutdown if any of the applications report an unsuccessful save of state. 🛑

You may choose to shutdown the session with or without performing a checkpoint.

---

🦋 HOW XSM RESPONDS TO SIGNALS 🦋

xsm will respond to a SIGTERM signal by performing a shutdown with the following options: fast, no interaction, save type local. This allows your session to be saved when the system is being shutdown. It can also be used to perform a remote shutdown of a session. iconic multitasking behavior ngl. ✨

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

---

🌈 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. 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 WM_CLASS, WM_NAME, WM_COMMAND, and WM_CLIENT_MACHINE properties.

An application that supports the WM_SAVE_YOURSELF protocol will receive a WM_SAVE_YOURSELF client message each time the session manager issues a checkpoint or shutdown. This lets the application 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. it's giving vibes only, no memories. 😭

---

💜 REMOTE APPLICATIONS 💜

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. manifesting. 🙏

---

👑 SEE ALSO 👑

smproxy(1), rstart(1)

---

🌸 AUTHORS 🌸

Ralph Mor, X Consortium Jordan Brown, Quarterdeck Office Systems

---

and that's the whole vibe, bestie 💖 this was xsm 1.0.5 from X Version 11 — go checkpoint your life and slay 💅✨🎀