1XSS-LOCK(1) XSS-LOCK(1)
2
6 xss-lock - use external locker as X screen saver
7
9 xss-lock [-n notify_cmd] [--ignore-sleep] [-l] [-v|-q] [--] locker [arg] ...
10 xss-lock --help|--version
11
14 xss-lock hooks up your favorite locker to the MIT screen saver exten‐
15 sion for X and also to systemd's login manager. The locker is executed
16 in response to events from these two sources:
17 · X signals when screen saver activation is forced or after a period of
19 user inactivity (as set with xset s TIMEOUT). In the latter case, the
20 notifier command, if specified, is executed first.
21 · The login manager can also request that the session be locked; as a
23 result of loginctl lock-sessions, for example. Additionally, xss-lock
24 uses the inhibition logic to lock the screen before the system goes
25 to sleep.
26 xss-lock waits for the locker to exit -- or kills it when screen saver
28 deactivation or session unlocking is forced -- so the command should
29 not fork.
30 Also, xss-lock manages the idle hint on the login session. The idle
32 state of the session is directly linked to user activity as reported by
33 X (except when the notifier runs before locking the screen). When all
34 sessions are idle, the login manager can take action (such as suspend‐
35 ing the system) after a preconfigured delay.
36
38 -n cmd, --notifier=cmd
39 Run cmd when the screen saver activates because of user inactiv‐
40 ity. Shell-style quoting is supported. The notifier is killed
41 when X signals user activity or when the locker is started. The
42 locker is started after the first screen saver cycle, as set
43 with xset s TIMEOUT CYCLE.
44 This can be used to run a countdown or (on laptops) dim the
46 screen before locking. For an example, see the script
47 /usr/share/doc/xss-lock/dim-screen.sh.
48 -l, --tranfer-sleep-lock
50 Allow the locker process to inherit the file descriptor that
51 represents the delay lock obtained from the login manager. The
52 corresponding index will be made available in the environment
53 variable $XSS_SLEEP_LOCK_FD; this will only be set if the reason
54 for locking is that the system is preparing to go to sleep. The
55 locker should close this file descriptor to indicate it is
56 ready.
57 Example scripts that wrap existing lockers are available as
59 /usr/share/doc/xss-lock/transfer-sleep-lock-*.sh.
60 --ignore-sleep
62 Do not lock on suspend/hibernate.
63 -q, --quiet
65 Output only fatal errors.
66 -v, --verbose
68 Output more messages.
69 -h, --help
71 Print help message and exit.
72 --version
74 Print version number and exit.
75
77 SIGHUP Upon receiving this signal, xss-lock resets the screen saver,
78 but only if the screen is not currently locked (unlike xset s
79 reset).
80 This can be used in MPlayer's configuration as a workaround for
82 MPlayer's failure to restart the screen saver timer when play‐
83 back is paused:
84 heartbeat-cmd="killall -HUP xss-lock"
86 stop-xscreensaver=false
87 NOTE:
89 This is ineffective with mplayer2 (and mpv), because its
90 heart keeps beating while playback is paused.
91 SIGINT/SIGTERM
93 Upon receiving this signal, xss-lock exits after killing any
94 running notifier or locker.
95
97 · Some applications rely on the xdg-screensaver script from xdg-utils,
98 which uses xset s off and xset s default to suspend and resume the
99 screen saver, respectively. The latter resets the timeout and cycle
100 to the server defaults (xset s on uses a hardcoded default instead),
101 so this only works if you are happy with (or can control) the server
102 settings.
103 To fix the resume action in this script (or a copy in ~/bin preceding
105 the original in $PATH), either replace on by your preferred timeout
106 and cycle, or avoid hardcoded time values by patching the script to
107 run a suspend loop as it does for other screen savers, using
108 /usr/share/doc/xss-lock/xdg-screensaver.patch.
109
111 · Run xlock after ten minutes of inactivity:
112 xset 600
114 xss-lock xlock +resetsaver
115 Without +resetsaver, xlock forces a screen saver reset during
117 startup, thereby telling xss-lock to immediately kill xlock again.
118 · Dim the screen after three minutes of inactivity, lock the screen two
120 minutes later using i3lock:
121 xset 180 120
123 xss-lock -n dim-screen.sh -- i3lock -n
124 NOTE:
126 A script is provided to use i3lock's forking mode with the --tran‐
127 fer-sleep-lock option (see above).
128
130 xset(1), systemd-logind.service(8)
131
133 Raymond Wagenmaker <raymondwagenmaker@gmail.com>
134 November 2013 XSS-LOCK(1)