diff options
Diffstat (limited to 'desktop/xss-lock/xss-lock.1')
| -rw-r--r-- | desktop/xss-lock/xss-lock.1 | 200 |
1 files changed, 200 insertions, 0 deletions
diff --git a/desktop/xss-lock/xss-lock.1 b/desktop/xss-lock/xss-lock.1 new file mode 100644 index 000000000000..6004824c48f1 --- /dev/null +++ b/desktop/xss-lock/xss-lock.1 @@ -0,0 +1,200 @@ +.\" Man page generated from reStructuredText. +. +.TH "XSS-LOCK" 1 "November 2013" "" "" +.SH NAME +xss-lock \- use external locker as X screen saver +. +.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 +.. +.SH SYNOPSIS +.nf +xss\-lock [\-n \fInotify_cmd\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. 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 when X signals user activity or when the locker is +started. The locker is started after the first screen saver +cycle, as set with \fBxset s TIMEOUT CYCLE\fP\&. +.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\&. +.TP +.B \-l\fP,\fB \-\-tranfer\-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 +.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 +.nf +.ft C +heartbeat\-cmd="killall \-HUP xss\-lock" +stop\-xscreensaver=false +.ft P +.fi +.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 +Run \fBxlock\fP after ten minutes of inactivity: +.INDENT 2.0 +.INDENT 3.5 +.sp +.nf +.ft C +xset 600 +xss\-lock xlock +resetsaver +.ft P +.fi +.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 +.nf +.ft C +xset 180 120 +xss\-lock \-n dim\-screen.sh \-\- i3lock \-n +.ft P +.fi +.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\-\-tranfer\-sleep\-lock\fP option (see above). +.UNINDENT +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +\fBxset\fP(1), +\fBsystemd\-logind.service\fP(8) +.SH AUTHOR +Raymond Wagenmaker <raymondwagenmaker@gmail.com> +.\" Generated by docutils manpage writer. +. |