summaryrefslogtreecommitdiff
path: root/desktop/xss-lock/xss-lock.1
diff options
context:
space:
mode:
Diffstat (limited to 'desktop/xss-lock/xss-lock.1')
-rw-r--r--desktop/xss-lock/xss-lock.1200
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 0000000000..6004824c48
--- /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.
+.