xss-lock(1)

💖 xss-lock — the manual page, but make it cute 💖

okay so bestie, this is the manual for xss-lock(1), from the General Commands Manual section. it's a little program that lets your fave screen locker do the whole screen-saver thing. let's get into it 🫶

---

✨ NAME ✨

xss-lock — use external locker as X screen saver

---

🌸 SYNOPSIS 🌸

xss-lock [-n notify_cmd] [-s session ID] [--ignore-sleep] [-l] [-v|-q] [--] locker [arg] ...
xss-lock --help|--version

---

🦋 DESCRIPTION 🦋

so xss-lock hooks up your favorite locker to the MIT screen saver extension for X, and to systemd's login manager. two boyfriends. iconic 💅

you should run xss-lock in your xsession — either by starting it in your .xsessionrc, or by other session-specific means (like your Window manager configuration, iykyk).

⚠️ heads up bestie: xss-lock runs in the foreground (i.e. it doesn't fork), so you may need to run it in the background. for example, by running it with &. don't forget the & or your whole session just sits there staring at you 😭

the locker gets executed in response to events from these two sources:

• X signals when screen saver activation is forced, or after a period of user inactivity (as set with xset s TIMEOUT). in that latter case, the notifier command — if you specified one — is executed first.
• The login manager can also request that the session be locked; as a result of loginctl lock-sessions, for example. and on top of that, xss-lock uses the inhibition logic to lock the screen before the system goes to sleep. sleepy girl behavior 💤

xss-lock waits for the locker to exit — or kills it when screen saver deactivation or session unlocking is forced — so the command should not fork. no cap.

also, xss-lock manages the idle hint on the login session. the idle state of the session is directly linked to user activity as reported by X (except when the notifier runs before locking the screen). when all sessions are idle, the login manager can take action (such as suspending the system) after a preconfigured delay. very main character of it ✨

---

👑 OPTIONS 👑

• -n cmd, --notifier=cmd — Run cmd when the screen saver activates because of user inactivity. Shell-style quoting is supported. The notifier is killed with the signal SIGHUP when X signals user activity, or with signal SIGTERM when the locker is started. The locker is started after the first screen saver cycle, as set with xset s TIMEOUT CYCLE. If the screen saver cycle time is 0, the notifier is not run and the locker is started immediately after timeout.

this can be used to run a countdown, or (on laptops) dim the screen before locking. for an example, see the script /usr/share/doc/xss-lock/dim-screen.sh.

for an example on how to use the two different signals received by the notifier command, see the script /usr/share/doc/xss-lock/dim-screen2.sh. two scripts, two vibes 💜

• -l, --transfer-sleep-lock — Allow the locker process to inherit the file descriptor that represents the delay lock obtained from the login manager. The corresponding index will be made available in the environment variable $XSS_SLEEP_LOCK_FD; this will only be set if the reason for locking is that the system is preparing to go to sleep. The locker should close this file descriptor to indicate it is ready.

example scripts that wrap existing lockers are available as /usr/share/doc/xss-lock/transfer-sleep-lock-*.sh.

• -s ID, --session=ID — Use the session ID instead of the current session.

example: /usr/share/doc/xss-lock/xss-lock.service.

• --ignore-sleep — Do not lock on suspend/hibernate. (letting it slide fr fr 🙈)
• -q, --quiet — Output only fatal errors.
• -v, --verbose — Output more messages. she's chatty 💬
• -h, --help — Print help message and exit.
• --version — Print version number and exit.

---

🎀 SIGNALS 🎀

• SIGHUP — Upon receiving this signal, xss-lock resets the screen saver, but only if the screen is not currently locked (unlike xset s reset).

this can be used in MPlayer's configuration as a workaround for MPlayer's failure to restart the screen saver timer when playback is paused:

heartbeat-cmd="killall -HUP xss-lock"
stop-xscreensaver=false

Note: This is ineffective with mplayer2 (and mpv), because its heart keeps beating while playback is paused. 💔

• SIGINT/SIGTERM — Upon receiving this signal, xss-lock exits after killing any running notifier or locker.

---

🌈 NOTES 🌈

• Some applications rely on the xdg-screensaver script from xdg-utils, which uses xset s off and xset s default to suspend and resume the screen saver, respectively. The latter resets the timeout and cycle to the server defaults (xset s on uses a hardcoded default instead), so this only works if you are happy with (or can control) the server settings.

to fix the resume action in this script (or a copy in ~/bin preceding the original in $PATH), either replace on by your preferred timeout and cycle, or avoid hardcoded time values by patching the script to run a suspend loop as it does for other screen savers, using /usr/share/doc/xss-lock/xdg-screensaver.patch. patch it bestie, slay 🧚

---

⭐ EXAMPLES ⭐

• Use with xscreensaver via .xsessionrc (hence in the background):

xscreensaver &
xss-lock -- xscreensaver-command --lock &

• Run xlock after ten minutes of inactivity:

xset s 600
xss-lock xlock +resetsaver

Without +resetsaver, xlock forces a screen saver reset during startup, thereby telling xss-lock to immediately kill xlock again. not the glow-up we wanted 😭

• Dim the screen after three minutes of inactivity, lock the screen two minutes later using i3lock:

xset s 180 120
xss-lock -n dim-screen.sh -- i3lock -n

Note: A script is provided to use i3lock's forking mode with the --transfer-sleep-lock option (see above).

---

🔥 SEE ALSO 🔥

loginctl(1), xset(1), systemd-logind.service(8)

---

💖 AUTHOR 💖

Raymond Wagenmaker <raymondwagenmaker@gmail.com>

---

and that's the whole page, bestie — written up back in November 2018 for the xss-lock(1) manual, and you just read all of it. ate and left no crumbs 👑✨ bye pookie 💅