.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "XSS-LOCK" "1" "November 2018" ""
.SH NAME
xss-lock \- use external locker as X screen saver
.SH SYNOPSIS
.nf
xss\-lock [\-n \fInotify_cmd\fP] [\-s \fIsession ID\fP] [\-\-ignore\-sleep] [\-l] [\-v|\-q] [\-\-] \fIlocker\fP [\fIarg\fP] ...
xss\-lock \-\-help|\-\-version
.fi
.sp
.SH DESCRIPTION
.sp
\fBxss\-lock\fP hooks up your favorite locker to the MIT screen saver extension
for X and also to systemd\(aqs login manager.
.sp
\fBxss\-lock\fP should be run in your xsession either by starting it in
your \fI\&.xsessionrc\fP or by other session specific means (e.g. Window
manager configuration). Note that \fBxss\-lock\fP runs in the foreground
(i.e. doesn\(aqt fork) and therefore you may need to run it in the
background (for example by running with \fI&\fP).
.sp
The locker is executed in response to events from these two sources:
.INDENT 0.0
.IP \(bu 2
X signals when screen saver activation is forced or after a period of user
inactivity (as set with \fBxset s TIMEOUT\fP). In the latter case, the notifier
command, if specified, is executed first.
.IP \(bu 2
The login manager can also request that the session be locked; as a result of
\fBloginctl lock\-sessions\fP, for example. Additionally, \fBxss\-lock\fP uses the
inhibition logic to lock the screen before the system goes to sleep.
.UNINDENT
.sp
\fBxss\-lock\fP waits for the locker to exit \-\- or kills it when screen saver
deactivation or session unlocking is forced \-\- so the command should not fork.
.sp
Also, \fBxss\-lock\fP 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.
.SH OPTIONS
.INDENT 0.0
.TP
.BI \-n \ cmd\fR,\fB \ \-\-notifier\fB= cmd
Run \fIcmd\fP 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
\fBxset s TIMEOUT CYCLE\fP\&. If the screen saver cycle time is 0,
the notifier is not run and the locker is started immediately
after timeout.
.sp
This can be used to run a countdown or (on laptops) dim the
screen before locking. For an example, see the script
\fI/usr/share/doc/xss\-lock/dim\-screen.sh\fP\&.
.sp
For an example on how to use the two different signals received
by the notifier command, see the script
\fI/usr/share/doc/xss\-lock/dim\-screen2.sh\fP\&.
.TP
.B  \-l\fP,\fB  \-\-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 \fB$XSS_SLEEP_LOCK_FD\fP; 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.
.sp
Example scripts that wrap existing lockers are available as
\fI/usr/share/doc/xss\-lock/transfer\-sleep\-lock\-*.sh\fP\&.
.TP
.BI \-s \ ID\fR,\fB \ \-\-session\fB= ID
Use the session \fBID\fP instead of the current session.
.sp
Example: \fI/usr/share/doc/xss\-lock/xss\-lock.service\fP\&.
.TP
.B  \-\-ignore\-sleep
Do not lock on suspend/hibernate.
.TP
.B  \-q\fP,\fB  \-\-quiet
Output only fatal errors.
.TP
.B  \-v\fP,\fB  \-\-verbose
Output more messages.
.TP
.B  \-h\fP,\fB  \-\-help
Print help message and exit.
.TP
.B  \-\-version
Print version number and exit.
.UNINDENT
.SH SIGNALS
.INDENT 0.0
.TP
.B SIGHUP
Upon receiving this signal, \fBxss\-lock\fP resets the screen saver, but only
if the screen is not currently locked (unlike \fBxset s reset\fP).
.sp
This can be used in MPlayer\(aqs configuration as a workaround for MPlayer\(aqs
failure to restart the screen saver timer when playback is paused:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
heartbeat\-cmd=\(dqkillall \-HUP xss\-lock\(dq
stop\-xscreensaver=false
.EE
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This is ineffective with mplayer2 (and mpv), because its heart keeps
beating while playback is paused.
.UNINDENT
.UNINDENT
.TP
.B SIGINT/SIGTERM
Upon receiving this signal, \fBxss\-lock\fP exits after killing any running
notifier or locker.
.UNINDENT
.SH NOTES
.INDENT 0.0
.IP \(bu 2
Some applications rely on the \fBxdg\-screensaver\fP script from xdg\-utils,
which uses \fBxset s off\fP and \fBxset s default\fP to suspend and resume the
screen saver, respectively. The latter resets the timeout and cycle to the
server defaults (\fBxset s on\fP uses a hardcoded default instead), so this
only works if you are happy with (or can control) the server settings.
.sp
To fix the resume action in this script (or a copy in \fI~/bin\fP preceding the
original in \fB$PATH\fP), either replace \fBon\fP 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
\fI/usr/share/doc/xss\-lock/xdg\-screensaver.patch\fP\&.
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.IP \(bu 2
Use with \fBxscreensaver\fP via \fI\&.xsessionrc\fP (hence in the background):
.INDENT 2.0
.INDENT 3.5
.sp
.EX
xscreensaver &
xss\-lock \-\- xscreensaver\-command \-\-lock &
.EE
.UNINDENT
.UNINDENT
.IP \(bu 2
Run \fBxlock\fP after ten minutes of inactivity:
.INDENT 2.0
.INDENT 3.5
.sp
.EX
xset s 600
xss\-lock xlock +resetsaver
.EE
.UNINDENT
.UNINDENT
.sp
Without \fB+resetsaver\fP, \fBxlock\fP forces a screen saver reset during
startup, thereby telling \fBxss\-lock\fP to immediately kill \fBxlock\fP again.
.IP \(bu 2
Dim the screen after three minutes of inactivity, lock the screen two minutes
later using \fBi3lock\fP:
.INDENT 2.0
.INDENT 3.5
.sp
.EX
xset s 180 120
xss\-lock \-n dim\-screen.sh \-\- i3lock \-n
.EE
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 2.0
.INDENT 3.5
A script is provided to use \fBi3lock\fP\(aqs forking mode with the
\fB\-\-transfer\-sleep\-lock\fP option (see above).
.UNINDENT
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fBloginctl\fP(1),
\fBxset\fP(1),
\fBsystemd\-logind.service\fP(8)
.SH AUTHOR
Raymond Wagenmaker <raymondwagenmaker@gmail.com>
.\" Generated by docutils manpage writer.
.