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

       xss-lock hooks up your favorite locker to the MIT screen saver extension for X and also to
       systemd's login manager.

       xss-lock should be run in your xsession either by starting it in your  .xsessionrc  or  by
       other  session specific means (e.g. Window manager configuration). Note that xss-lock runs
       in the foreground (i.e. doesn't fork) and  therefore  you  may  need  to  run  it  in  the
       background (for example by running with &).

       The locker is 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 the latter case, the notifier command, if specified, is
         executed first.

       • The  login  manager can also request that the session be locked; as a result of loginctl
         lock-sessions, for example. Additionally, xss-lock uses the inhibition logic to lock the
         screen before the system goes to sleep.

       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.

       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.

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.

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

       -q, --quiet
              Output only fatal errors.

       -v, --verbose
              Output more messages.

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

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.

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

                                          November 2018                               XSS-LOCK(1)