1XSS-LOCK(1)                                                        XSS-LOCK(1)
2
3
4

NAME

6       xss-lock - use external locker as X screen saver
7

SYNOPSIS

9       xss-lock [-n notify_cmd] [--ignore-sleep] [-l] [-v|-q] [--] locker [arg] ...
10       xss-lock --help|--version
11
12

DESCRIPTION

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
18       · 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
22       · 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
27       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
31       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

OPTIONS

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
45              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
49       -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
58              Example scripts that wrap  existing  lockers  are  available  as
59              /usr/share/doc/xss-lock/transfer-sleep-lock-*.sh.
60
61       --ignore-sleep
62              Do not lock on suspend/hibernate.
63
64       -q, --quiet
65              Output only fatal errors.
66
67       -v, --verbose
68              Output more messages.
69
70       -h, --help
71              Print help message and exit.
72
73       --version
74              Print version number and exit.
75

SIGNALS

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
81              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
85                 heartbeat-cmd="killall -HUP xss-lock"
86                 stop-xscreensaver=false
87
88              NOTE:
89                 This  is  ineffective  with  mplayer2  (and mpv), because its
90                 heart keeps beating while playback is paused.
91
92       SIGINT/SIGTERM
93              Upon receiving this signal, xss-lock  exits  after  killing  any
94              running notifier or locker.
95

NOTES

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
104         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

EXAMPLES

111       · Run xlock after ten minutes of inactivity:
112
113            xset 600
114            xss-lock xlock +resetsaver
115
116         Without  +resetsaver,  xlock  forces  a  screen  saver  reset  during
117         startup, thereby telling xss-lock to immediately kill xlock again.
118
119       · Dim the screen after three minutes of inactivity, lock the screen two
120         minutes later using i3lock:
121
122            xset 180 120
123            xss-lock -n dim-screen.sh -- i3lock -n
124
125         NOTE:
126            A script is provided to use i3lock's forking mode with the --tran‐
127            fer-sleep-lock option (see above).
128

SEE ALSO

130       xset(1), systemd-logind.service(8)
131

AUTHOR

133       Raymond Wagenmaker <raymondwagenmaker@gmail.com>
134
135
136
137
138                                 November 2013                     XSS-LOCK(1)
Impressum