QSessionManager(3qt)

📦 version 3.3.8b, in fedora 43, fedora 44

👑 QSessionManager(3qt) 👑

okay bestie, so this whole page is QSessionManager from the 3qt manual, and it's literally the glow-up guide to talking to your session manager. no cap, it's giving main character energy for your app's whole do I get to come back after reboot situation 💅

✨ NAME ✨

QSessionManager — your all-access pass to the session manager 🎀

🦋 SYNOPSIS 🦋

#include <qsessionmanager.h>

Inherits QObject.

🌸 Public Members 🌸

QString sessionId () const
QString sessionKey () const
void * handle () const
bool allowsInteraction ()
bool allowsErrorInteraction ()
void release ()
void cancel ()
enum RestartHint { RestartIfRunning, RestartAnyway, RestartImmediately, RestartNever }
void setRestartHint ( RestartHint hint )
RestartHint restartHint () const
void setRestartCommand ( const QStringList & command )
QStringList restartCommand () const
void setDiscardCommand ( const QStringList & )
QStringList discardCommand () const
void setManagerProperty ( const QString & name, const QString & value )
void setManagerProperty ( const QString & name, const QStringList & value )
bool isPhase2 () const
void requestPhase2 ()

💖 DESCRIPTION 💖

The QSessionManager class provides access to the session manager. that's the whole vibe fr fr ✨

So like, the session manager is the one handling session management — most importantly interruption and resumption. A "session" is basically a little record of the state of the system, like which applications were run at start up and which applications are currently running. The session manager saves the session (think: machine shutting down 😭) and restores a session (think: machine starting up 🌅). If you just wanna save/restore one app's own lil settings — window positions, recently used files, that kind of thing — you want QSettings for that instead, okay bestie? 🫶

QSessionManager is the interface between your application and the session manager so your program can be a good collaborative citizen. In Qt, session management requests for action get handled by the two virtual functions QApplication::commitData() and QApplication::saveState(). Both of them hand you a reference to a session manager object as an argument, so your application can talk back to the session manager. 💬

During a session management action (like, inside commitData() and saveState()), no user interaction is possible unless your application got explicit permission from the session manager. so rude, but okay 🙈

You ask for permission by calling allowsInteraction() or — if it's really urgent, like emergency emergency — allowsErrorInteraction(). Qt itself does not enforce this, but the session manager absolutely may. so don't try it. 👀

You can try to abort the shutdown process by calling cancel(). The default commitData() function does exactly that if some top-level window rejected its closeEvent(). iconic behavior, honestly. 🚫

For the sophisticated session managers on Unix/X11, QSessionManager offers even more ways to fine-tune an application's session management behavior: setRestartCommand(), setDiscardCommand(), setRestartHint(), setProperty(), requestPhase2(). Go read the respective function descriptions for the details, iykyk 📖

See also Main Window and Related Classes and Environment Classes.

🧚 Member Type Documentation 🧚

`QSessionManager::RestartHint`

This enum type defines the circumstances under which this application wants to be restarted by the session manager. The current values are:

QSessionManager::RestartIfRunning — if the application is still running when the session is shut down, it wants to be restarted at the start of the next session. ✨
QSessionManager::RestartAnyway — the application wants to be started at the start of the next session, no matter what. (This is useful for utilities that run just after startup and then quit.) 💫
QSessionManager::RestartImmediately — the application wants to be started immediately whenever it is not running. 🔥
QSessionManager::RestartNever — the application does not want to be restarted automatically. bye bye 💀

The default hint is RestartIfRunning. that's the factory setting bestie 🎀

🌈 MEMBER FUNCTION DOCUMENTATION 🌈

`bool QSessionManager::allowsErrorInteraction ()`

This is similar to allowsInteraction(), but it also tells the session manager that an error occurred. Session managers may give error interaction requests higher priority, which means it's more likely that an error interaction is permitted. However, you are still not guaranteed that the session manager will allow interaction. no promises, babe 😭

See also allowsInteraction(), release(), and cancel().

`bool QSessionManager::allowsInteraction ()`

Asks the session manager for permission to interact with the user. Returns TRUE if interaction is permitted; otherwise returns FALSE. permission check, but make it ✨social✨

The rationale behind this mechanism is to make it possible to synchronize user interaction during a shutdown. Advanced session managers may ask all applications simultaneously to commit their data, resulting in a much faster shutdown. teamwork makes the dream work fr fr 🫶

When the interaction is completed we strongly recommend releasing the user interaction semaphore with a call to release(). This way, other applications may get the chance to interact with the user while your application is still busy saving data. (The semaphore is implicitly released when the application exits, so don't stress too hard. 😌)

If the user decides to cancel the shutdown process during the interaction phase, you must tell the session manager that this has happened by calling cancel(). non-negotiable bestie 💅

Here's an example of how an application's QApplication::commitData() might be implemented:

void MyApplication::commitData( QSessionManager& sm ) {
    if ( sm.allowsInteraction() ) {
        switch ( QMessageBox::warning(
                    yourMainWindow,
                    tr("Application Name"),
                    tr("Save changes to document Foo?"),
                    tr("&Yes"),
                    tr("&No"),
                    tr("Cancel"),
                    0, 2) ) {
        case 0: // yes
            sm.release();
            // save document here; if saving fails, call sm.cancel()
            break;
        case 1: // continue without saving
            break;
        default: // cancel
            sm.cancel();
            break;
        }
    } else {
        // we did not get permission to interact, then
        // do something reasonable instead.
    }
}

If an error occurred within the application while saving its data, you may want to try allowsErrorInteraction() instead. 🙈

See also QApplication::commitData(), release(), and cancel().

`void QSessionManager::cancel ()`

Tells the session manager to cancel the shutdown process. Applications should not call this function without first asking the user. like. ask. the. user. first. that's the rule 🚨

See also allowsInteraction() and allowsErrorInteraction().

`QStringList QSessionManager::discardCommand () const`

Returns the currently set discard command.

Note that if you want to iterate over the list, you should iterate over a copy, e.g.

QStringList list = mySession.discardCommand();
QStringList::Iterator it = list.begin();
while( it != list.end() ) {
    myProcessing( *it );
    ++it;
}

See also setDiscardCommand(), restartCommand(), and setRestartCommand().

`void * QSessionManager::handle () const`

X11 only: returns a handle to the current SmcConnection. very niche, very X11 of it 🖥️✨

`bool QSessionManager::isPhase2 () const`

Returns TRUE if the session manager is currently performing a second session management phase; otherwise returns FALSE.

`void QSessionManager::release ()`

Releases the session manager's interaction semaphore after an interaction phase. hand the mic back bestie 🎤

See also allowsInteraction() and allowsErrorInteraction().

`void QSessionManager::requestPhase2 ()`

Requests a second session management phase for the application. The application may then return immediately from the QApplication::commitData() or QApplication::saveState() function, and they will be called again once most or all other applications have finished their session management. round two, let's go 💫

The two phases are useful for applications such as the X11 window manager that need to store information about another application's windows and therefore have to wait until these applications have completed their respective session management tasks. waiting for the group project to finish, essentially 😭

Note that if another application has requested a second phase it may get called before, simultaneously with, or after your application's second phase. no ordering guarantees, so don't build your whole personality on the timeline 🕐

`QStringList QSessionManager::restartCommand () const`

Returns the currently set restart command.

Note that if you want to iterate over the list, you should iterate over a copy, e.g.

QStringList list = mySession.restartCommand();
QStringList::Iterator it = list.begin();
while( it != list.end() ) {
    myProcessing( *it );
    ++it;
}

See also setRestartCommand() and restartHint().

`RestartHint QSessionManager::restartHint () const`

Returns the application's current restart hint. The default is RestartIfRunning.

`QString QSessionManager::sessionId () const`

Returns the identifier of the current session. 🪪

If the application has been restored from an earlier session, this identifier is the same as it was in that earlier session. consistency, we love to see it ✨

See also sessionKey() and QApplication::sessionId().

`QString QSessionManager::sessionKey () const`

Returns the session key in the current session. 🔑

If the application has been restored from an earlier session, this key is the same as it was when the previous session ended.

The session key changes with every call of commitData() or saveState(). so don't go memorizing it, bestie, it's not that kind of relationship 💀

See also sessionId() and QApplication::sessionKey().

`void QSessionManager::setDiscardCommand ( const QStringList & )`

See also discardCommand() and setRestartCommand().

`void QSessionManager::setManagerProperty ( const QString & name, const QStringList & value )`

Low-level write access to the application's identification and state record are kept in the session manager. low-level, we're going under the hood 🔧

The property called name has its value set to the string list value.

`void QSessionManager::setManagerProperty ( const QString & name, const QString & value )`

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. same energy, different argument type 💅

Low-level write access to the application's identification and state records are kept in the session manager.

The property called name has its value set to the string value.

✨ `void QSessionManager::setRestartCommand ( const QStringList & command )` ✨

Okay bestie, this one is lowkey the main character of session restoring 💅 so listen up.

If the session manager is capable of restoring sessions, it's gonna run command to bring your app back to life. The command defaults to:

appname -session id

The -session option is mandatory — like, non-negotiable, periodt. Because otherwise QApplication literally cannot tell whether it's been restored or what the current session identifier even is 🙈. Go peep QApplication::isSessionRestored() and QApplication::sessionId() for the details, bestie.

Now, if your app is super simple, you might think "ooh let me just stuff the whole app state into extra command line options 🥰" — and ngl that's usually a very bad idea, because command lines are often limited to just a few hundred bytes. So like, do not. Instead, use QSettings, or temporary files, or a database for that purpose. By marking the data with the unique sessionId(), you'll be able to restore the application in a future session. Slay 💖

See also restartCommand(), setDiscardCommand(), and setRestartHint().

🌸 `void QSessionManager::setRestartHint ( RestartHint hint )` 🌸

Sets the application's restart hint to hint. On application startup the hint is set to RestartIfRunning. Iconic behaviour, honestly.

Heads up though — these flags are only hints. A session manager may or may not respect them 😭. It's giving "suggestion, not a command."

We recommend setting the restart hint inside QApplication::saveState(), because most session managers perform a checkpoint shortly after an application's startup. So like, timing matters, iykyk ⏰✨

🔗 SEE ALSO 🔗

📜 COPYRIGHT 📜

✍️ AUTHOR ✍️

Generated automatically from the source code. (no cap, a robot did this 💀)

🐛 BUGS 🐛

If you find a bug in Qt, please report it as described in http://doc.trolltech.com/bughowto.html. Good bug reports help us to help you. Thank you 🫶

The definitive Qt documentation is provided in HTML format; it is located at $QTDIR/doc/html and can be read using Qt Assistant or with a web browser. This man page is provided as a convenience for those users who prefer man pages, although this format is not officially supported by Trolltech.

If you find errors in this manual page, please report them to qt-bugs@trolltech.com. Please include the name of the manual page (qsessionmanager.3qt) and the Qt version (3.3.8).

and that's a wrap, bestie!! 🎀 This little beauty came from the Trolltech AS era — dated 2 February 2007, and it's the QSessionManager(3qt) page, version 3.3.8 vibes all the way through. Go forth and restore those sessions responsibly 💜✨

📦 where this page comes from

fedora 43: qt3-devel-docs 3.3.8b-102.fc43 · QPL-1.0 OR GPL-2.0-only OR GPL-3.0-only
fedora 44: qt3-devel-docs 3.3.8b-103.fc44 · QPL-1.0 OR GPL-2.0-only OR GPL-3.0-only
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

QSessionManager(3qt)