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)