Original 5.40

1 files changed, 1035 insertions, 0 deletions

diff --git a/driver/xscreensaver.man b/driver/xscreensaver.man
new file mode 100644
index 0000000..a99845b
--- /dev/null
+++ b/driver/xscreensaver.man
@@ -0,0 +1,1035 @@
+.de EX		\"Begin example
+.ne 5
+.if n .sp 1
+.if t .sp .5
+.nf
+.in +.5i
+..
+.de EE
+.fi
+.in -.5i
+.if n .sp 1
+.if t .sp .5
+..
+.TH XScreenSaver 1 "09-Nov-2013 (5.23)" "X Version 11"
+.SH NAME
+xscreensaver - extensible screen saver and screen locking framework
+.SH SYNOPSIS
+.B xscreensaver
+[\-display \fIhost:display.screen\fP] \
+[\-verbose] \
+[\-no\-splash] \
+[\-no\-capture\-stderr] \
+[\-log \fIfilename\fP]
+.SH DESCRIPTION
+The \fIxscreensaver\fP program waits until the keyboard and mouse have been 
+idle for a period, and then runs a graphics demo chosen at random.  It 
+turns off as soon as there is any mouse or keyboard activity.
+
+This program can lock your terminal in order to prevent others from using it,
+though its default mode of operation is merely to display pretty pictures on
+your screen when it is not in use.
+
+It also provides configuration and control of your monitor's power-saving
+features.
+.SH GETTING STARTED
+For the impatient, try this:
+.EX
+xscreensaver &
+xscreensaver-demo
+.EE
+The
+.BR xscreensaver-demo (1)
+program pops up a dialog box that lets you configure the screen saver,
+and experiment with the various display modes.
+
+.B Note that xscreensaver has a client-server model:
+the \fIxscreensaver\fP program is a daemon that runs in the background;
+it is controlled by the foreground
+.BR xscreensaver-demo (1)
+and
+.BR xscreensaver-command (1)
+programs.
+.SH CONFIGURATION
+The easiest way to configure \fIxscreensaver\fP is to simply run the
+.BR xscreensaver-demo (1)
+program, and change the settings through the GUI.  The rest of this
+manual page describes lower level ways of changing settings.
+
+I'll repeat that because it's important:
+
+.RS 4
+The easy way to configure xscreensaver is to run the 
+.BR xscreensaver-demo (1)
+program.  You shouldn't need to know any of the stuff described 
+in \fIthis\fP manual unless you are trying to do something tricky,
+like customize xscreensaver for site-wide use or something.
+.RE
+
+Options to \fIxscreensaver\fP are stored in one of two places: in 
+a \fI.xscreensaver\fP file in your home directory; or in the X resource
+database.  If the \fI.xscreensaver\fP file exists, it overrides any settings
+in the resource database.  
+
+The syntax of the \fI.xscreensaver\fP file is similar to that of
+the \fI.Xdefaults\fP file; for example, to set the \fItimeout\fP parameter
+in the \fI.xscreensaver\fP file, you would write the following:
+.EX
+timeout: 5
+.EE
+whereas, in the \fI.Xdefaults\fP file, you would write
+.EX
+xscreensaver.timeout: 5
+.EE
+If you change a setting in the \fI.xscreensaver\fP file while xscreensaver
+is already running, it will notice this, and reload the file.  (The file will
+be reloaded the next time the screen saver needs to take some action, such as
+blanking or unblanking the screen, or picking a new graphics mode.)
+
+If you change a setting in your X resource database, or if you want
+xscreensaver to notice your changes immediately instead of the next time
+it wakes up, then you will need to reload your \fI.Xdefaults\fP file,
+and then tell the running xscreensaver process to restart itself, like so:
+.EX
+xrdb < ~/.Xdefaults
+xscreensaver-command -restart
+.EE
+If you want to set the system-wide defaults, then make your edits to
+the xscreensaver app-defaults file, which should have been installed
+when xscreensaver itself was installed.  The app-defaults file will
+usually be named /usr/lib/X11/app-defaults/XScreenSaver, but different
+systems might keep it in a different place (for example,
+/usr/openwin/lib/app-defaults/XScreenSaver on Solaris).
+
+When settings are changed in the Preferences dialog box (see above)
+the current settings will be written to the \fI.xscreensaver\fP file.
+(The \fI.Xdefaults\fP file and the app-defaults file will never be
+written by xscreensaver itself.)
+.SH COMMAND-LINE OPTIONS
+.I xscreensaver
+also accepts a few command-line options, mostly for use when debugging:
+for normal operation, you should configure things via the \fI~/.xscreensaver\fP
+file.
+.TP 8
+.B \-display \fIhost:display.screen\fP
+The X display to use.  For displays with multiple screens, XScreenSaver
+will manage all screens on the display simultaniously.
+.TP 8
+.B \-verbose
+Same as setting the \fIverbose\fP resource to \fItrue\fP: print diagnostics
+on stderr and on the xscreensaver window.
+.TP 8
+.B \-no-capture-stderr
+Do not redirect the stdout and stderr streams to the xscreensaver window
+itself.  If xscreensaver is crashing, you might need to do this in order
+to see the error message.
+.TP 8
+.B \-log \fIfilename\fP
+This is exactly the same as redirecting stdout and stderr to the given
+file (for append).  This is useful when reporting bugs.
+.SH HOW IT WORKS
+When it is time to activate the screensaver, a full-screen black window is
+created on each screen of the display.  Each window is created in such a way
+that, to any subsequently-created programs, it will appear to be a "virtual
+root" window.  Because of this, any program which draws on the root 
+window (and which understands virtual roots) can be used as a screensaver.
+The various graphics demos are, in fact, just standalone programs that
+know how to draw on the provided window.
+
+When the user becomes active again, the screensaver windows are unmapped, and
+the running subprocesses are killed by sending them \fBSIGTERM\fP.  This is 
+also how the subprocesses are killed when the screensaver decides that it's
+time to run a different demo: the old one is killed and a new one is launched.
+
+You can control a running screensaver process by using the
+.BR xscreensaver\-command (1)
+program (which see).
+.SH POWER MANAGEMENT
+Modern X servers contain support to power down the monitor after an idle
+period.  If the monitor has powered down, then \fIxscreensaver\fP will
+notice this (after a few minutes), and will not waste CPU by drawing 
+graphics demos on a black screen.  An attempt will also be made to
+explicitly power the monitor back up as soon as user activity is detected.
+
+The \fI~/.xscreensaver\fP file controls the configuration of your
+display's power management settings: if you have used
+.BR xset (1)
+to change your power management settings, then xscreensaver will
+override those changes with the values specified 
+in \fI~/.xscreensaver\fP (or with its built-in defaults, if there
+is no \fI~/.xscreensaver\fP file yet).
+
+To change your power management settings, run
+.BR xscreensaver\-demo (1)
+and change the various timeouts through the user interface.
+Alternatively, you can edit the \fI~/.xscreensaver\fP file directly.
+
+If the power management section is grayed out in the
+.BR xscreensaver\-demo (1)
+window,  then that means that your X server does not support
+the XDPMS extension, and so control over the monitor's power state
+is not available.
+
+If you're using a laptop, don't be surprised if changing the DPMS
+settings has no effect: many laptops have monitor power-saving behavior
+built in at a very low level that is invisible to Unix and X.  On such
+systems, you can typically adjust the power-saving delays only by
+changing settings in the BIOS in some hardware-specific way.
+
+If DPMS seems not to be working with XFree86, make sure the "DPMS"
+option is set in your \fI/etc/X11/XF86Config\fP file.  See the
+.BR XF86Config (5)
+manual for details.
+.SH USING GNOME OR UNITY
+For the better part of a decade, GNOME shipped xscreensaver as-is,
+and everything just worked out of the box.  In 2005, however, they
+decided to re-invent the wheel and ship their own replacement for
+the \fIxscreensaver\fP daemon called "\fIgnome-screensaver\fP",
+rather than improving xscreensaver and contributing their changes
+back.  As a result, the "\fIgnome-screensaver\fP" program is insecure,
+bug-ridden, and missing many features of xscreensaver.  You shouldn't
+use it.
+
+To replace gnome-screensaver with xscreensaver:
+.RS 4
+.TP 3
+\fB1: Fully uninstall the gnome-screensaver package.\fP
+.EX
+sudo apt-get remove gnome-screensaver
+.EE
+or possibly
+.EX
+sudo dpkg -P gnome-screensaver
+.EE
+.TP 3
+\fB2: Launch xscreensaver at login.\fP
+Select "\fIStartup Applications\fP" from the menu (or manually
+launch "\fIgnome-session-properties\fP") and add "\fIxscreensaver\fP".
+
+Do this as your normal user account, not as root.
+(This should go without saying, because you should never, ever, ever
+be logged in to the graphical desktop as user "root".)
+.TP 3
+\fB3: Make GNOME's "Lock Screen" use xscreensaver.\fP
+.EX
+sudo ln -sf /usr/bin/xscreensaver-command \\
+            /usr/bin/gnome-screensaver-command
+.EE
+That doesn't work under Unity, though.  Apparently it has its own
+built-in screen locker which is not gnome-screensaver, and cannot be
+removed, and yet still manages to be bug-addled and insecure. 
+Keep reinventing that wheel, guys!  (If you have figured out how to
+replace Unity's locking "feature" with xscreensaver, let me know.)
+.TP 3
+\fB4: Turn off Unity's built-in blanking.\fP
+Open "\fISystem Settings / Brightness & Lock\fP";
+.br
+Un-check "\fIStart Automatically\fP";
+.br
+Set \fI"Turn screen off when inactive for"\fP to \fI"Never".\fP
+.SH USING KDE
+Like GNOME, KDE also decided to invent their own screen saver framework
+from scratch instead of simply using xscreensaver.  To replace the KDE
+screen saver with xscreensaver, do the following:
+.RS 4
+.TP 3
+\fB1: Turn off KDE's screen saver.\fP
+Open the "\fIControl Center\fP" and
+select the "\fIAppearance & Themes / Screensaver\fP" page.
+Un-check "\fIStart Automatically\fP".
+
+Or possibly:
+Open "\fISystem Settings\fP" and
+select "\fIScreen Locking\fP".
+Un-check "\fILock Screen Automatically\fP".
+.TP 3
+\fB2: Find your Autostart directory.\fP
+Open the "\fISystem Administration / Paths\fP" page,
+and see what your "Autostart path" is set to: it will
+probably be something like \fI~/.kde/Autostart/\fP
+or \fI~/.config/autostart/\fP
+
+If that doesn't work, then try this:
+
+Open "\fISystem Settings / Startup/Shutdown / Autostart\fP", and then
+add "\fI/usr/bin/xscreensaver\fP".
+
+If you are lucky, that will create a \fIxscreensaver.desktop"\fP file 
+for you in \fI~/.config/autostart/\fP or \fI~/.kde/Autostart/\fP.
+.TP 3
+\fB3: Make xscreensaver be an Autostart program.\fP
+If it does not already exist, create a file in your autostart directory 
+called \fIxscreensaver.desktop\fP that contains the following six lines:
+.EX
+[Desktop Entry]
+Exec=xscreensaver
+Name=XScreenSaver
+Type=Application
+StartupNotify=false
+X-KDE-StartupNotify=false
+.EE
+.TP 3
+\fB4: Make the various "lock session" buttons call xscreensaver.\fP
+The file you want to replace next has moved around over the years. It
+might be called \fI/usr/libexec/kde4/kscreenlocker\fP,
+or it might be called "\fIkdesktop_lock\fP" or "\fIkrunner_lock\fP"
+or "\fIkscreenlocker_greet\fP", and
+it might be in \fI/usr/lib/kde4/libexec/\fP
+or in \fI/usr/kde/3.5/bin/\fP or even in \fI/usr/bin/\fP,
+depending on the distro and phase of the moon.  Replace the contents
+of that file with these two lines:
+.EX
+#!/bin/sh
+xscreensaver-command -lock
+.EE
+Make sure the file is executable (chmod a+x).
+.RE
+.PP
+Now use xscreensaver normally, controlling it via the usual
+.BR xscreensaver-demo (1)
+and
+.BR xscreensaver-command (1)
+mechanisms.
+.SH USING SYSTEMD
+If the above didn't do it, and your system has
+.BR systemd (1),
+then give this a try:
+.TP 3
+\fB1: Create a service.\fP
+Create the file \fI~/.config/systemd/user/xscreensaver.service\fP
+containing:
+.EX
+[Unit]
+Description=XScreenSaver
+[Service]
+ExecStart=/usr/bin/xscreensaver
+[Install]
+WantedBy=default.target
+.EE
+.TP 3
+\fB2. Enable it.\fP
+.EX
+systemctl --user enable xscreensaver
+.EE
+Then restart X11.
+.SH USING UPSTART
+If it's still not working, but on your distro, that newfangled
+.BR systemd (1)
+nonsense has already fallen out of favor?  Then maybe this will work:
+launch the \fI"Startup Applications"\fP applet, click \fI"Add"\fP,
+enter these lines, then restart X11:
+.EX
+Name: XScreenSaver
+Command: xscreensaver
+Comment: xscreensaver
+.EE
+.SH USING GDM
+You can run \fIxscreensaver\fP from your 
+.BR gdm (1)
+session, so that the screensaver will run even when nobody is logged 
+in on the console.  To do this, run
+.BR gdmconfig (1).
+
+On the \fIGeneral\fP page set the \fILocal Greeter\fP to
+\fIStandard Greeter\fP.
+
+On the \fIBackground\fP page, type the
+command \fB"xscreensaver -nosplash"\fP into the \fIBackground Program\fP
+field.  That will cause gdm to run xscreensaver while nobody is logged
+in, and kill it as soon as someone does log in.  (The user will then
+be responsible for starting xscreensaver on their own, if they want.)
+
+If that doesn't work, you can edit the config file directly. Edit
+\fI/etc/X11/gdm/gdm.conf\fP to include:
+.EX
+Greeter=/usr/bin/gdmlogin
+BackgroundProgram=xscreensaver -nosplash
+RunBackgroundProgramAlways=true
+.EE
+In this situation, the \fIxscreensaver\fP process will probably be running
+as user \fIgdm\fP instead of \fIroot\fP.  You can configure the settings
+for this nobody-logged-in state (timeouts, DPMS, etc.) by editing
+the \fI~gdm/.xscreensaver\fP file.
+
+It is safe to run \fIxscreensaver\fP as root (as \fIxdm\fP or \fIgdm\fP may do).
+If run as root, \fIxscreensaver\fP changes its effective user and group ids 
+to something safe (like \fI"nobody"\fP) before connecting to the X server
+or launching user-specified programs.
+
+An unfortunate side effect of this (important) security precaution is that
+it may conflict with cookie-based authentication.
+
+If you get "connection refused" errors when running \fIxscreensaver\fP
+from \fIgdm\fP, then this probably means that you have
+.BR xauth (1)
+or some other security mechanism turned on.  For information on the
+X server's access control mechanisms, see the man pages for
+.BR X (1),
+.BR Xsecurity (1),
+.BR xauth (1),
+and
+.BR xhost (1).
+.SH BUGS
+Bugs?  There are no bugs.  Ok, well, maybe.  If you find one, please let
+me know.  https://www.jwz.org/xscreensaver/bugs.html explains how to
+construct the most useful bug reports.
+.PP
+.TP 4
+.B Locking and root logins
+In order for it to be safe for xscreensaver to be launched by \fIxdm\fP,
+certain precautions had to be taken, among them that xscreensaver never
+runs as \fIroot\fP.  In particular, if it is launched as root (as \fIxdm\fP
+is likely to do), xscreensaver will disavow its privileges, and switch 
+itself to a safe user id (such as \fInobody\fP).
+
+An implication of this is that if you log in as \fIroot\fP on the console, 
+xscreensaver will refuse to lock the screen (because it can't tell
+the difference between \fIroot\fP being logged in on the console, and a
+normal user being logged in on the console but xscreensaver having been 
+launched by the
+.BR xdm (1)
+.I Xsetup
+file).
+
+The solution to this is simple: you shouldn't be logging in on the console
+as \fIroot\fP in the first place!  (What, are you crazy or something?)  
+
+Proper Unix hygiene dictates that you should log in as yourself, and
+.BR su (1)
+to \fIroot\fP as necessary.  People who spend their day logged in
+as \fIroot\fP are just begging for disaster.
+.TP 4
+.B XAUTH and XDM
+For xscreensaver to work when launched by
+.BR xdm (1)
+or
+.BR gdm (1),
+programs running on the local machine as user \fI"nobody"\fP must be
+able to connect to the X server.  This means that if you want to run
+xscreensaver on the console while nobody is logged in, you may need
+to disable cookie-based access control (and allow all users who can log
+in to the local machine to connect to the display).  
+
+You should be sure that this is an acceptable thing to do in your
+environment before doing it.  See the "\fIUsing GDM\fP" section, 
+above, for more details.
+.TP 4
+.B Passwords
+If you get an error message at startup like "couldn't get password
+of \fIuser\fP" then this probably means that you're on a system in which 
+the
+.BR getpwent (3)
+library routine can only be effectively used by root.  If this is the case, 
+then \fIxscreensaver\fP must be installed as setuid to root in order for
+locking to work.  Care has been taken to make this a safe thing to do.  
+
+It also may mean that your system uses shadow passwords instead of the standard
+.BR getpwent (3)
+interface; in that case, you may need to change some options 
+with \fIconfigure\fP and recompile.
+
+If you change your password after xscreensaver has been launched, it will
+continue using your old password to unlock the screen until xscreensaver
+is restarted.  On some systems, it may accept \fIboth\fP your old and new
+passwords.  So, after you change your password, you'll have to do
+.EX
+xscreensaver-command -restart
+.EE
+to make \fIxscreensaver\fP notice.
+.TP 4
+.B PAM Passwords
+If your system uses PAM (Pluggable Authentication Modules), then in order
+for xscreensaver to use PAM properly, PAM must be told about xscreensaver.
+The xscreensaver installation process should update the PAM data (on Linux,
+by creating the file \fI/etc/pam.d/xscreensaver\fP for you, and on Solaris, 
+by telling you what lines to add to the \fI/etc/pam.conf\fP file).  
+
+If the PAM configuration files do not know about xscreensaver, then 
+you \fImight\fP be in a situation where xscreensaver will refuse to ever
+unlock the screen.
+
+This is a design flaw in PAM (there is no way for a client to tell the
+difference between PAM responding "I have never heard of your module",
+and responding, "you typed the wrong password").  As far as I can tell,
+there is no way for xscreensaver to automatically work around this, or
+detect the problem in advance, so if you have PAM, make sure it is
+configured correctly!
+.TP 4
+.B Machine Load
+Although this program "nices" the subprocesses that it starts, 
+graphics-intensive subprograms can still overload the machine by causing
+the X server process itself (which is not "niced") to consume many
+cycles.  Care has been taken in all the modules shipped with xscreensaver
+to sleep periodically, and not run full tilt, so as not to cause
+appreciable load.
+
+However, if you are running the OpenGL-based screen savers on a machine
+that does not have a video card with 3D acceleration, they \fIwill\fP
+make your machine slow, despite
+.BR nice (1).
+
+Your options are: don't use the OpenGL display modes; or, collect the
+spare change hidden under the cushions of your couch, and use it to
+buy a video card manufactured after 1998.  (It doesn't even need to be
+\fIfast\fP 3D hardware: the problem will be fixed if there is any
+3D hardware \fIat all.\fP)
+.TP 4
+.B Magic Backdoor Keystrokes
+The XFree86 X server and the Linux kernel both trap certain magic
+keystrokes before X11 client programs ever see them.  If you care
+about keeping your screen locked, this is a big problem.
+.RS 4
+.TP 3
+.B Ctrl+Alt+Backspace
+This keystroke kills the X server, and on some systems, leaves you at
+a text console.  If the user launched X11 manually, that text console
+will still be logged in.  To disable this keystroke globally and
+permanently, you need to set the \fBDontZap\fP flag in your
+\fIxorg.conf\fP or \fIXF86Config\fP or \fIXF86Config-4\fP file,
+depending which is in use on your system.  See
+.BR XF86Config (5)
+for details.
+.TP 3
+.B Ctrl-Alt-F1, Ctrl-Alt-F2, etc.
+These keystrokes will switch to a different virtual console, while
+leaving the console that X11 is running on locked.  If you left a
+shell logged in on another virtual console, it is unprotected.  So
+don't leave yourself logged in on other consoles.  You can disable VT
+switching globally and permanently by setting \fBDontVTSwitch\fP in
+your \fIxorg.conf\fP, but that might make your system harder to use,
+since VT switching is an actual useful feature.
+
+There is no way to disable VT switching only when the screen is
+locked.  It's all or nothing.
+.TP 3
+.B Ctrl-Alt-KP_Multiply
+This keystroke kills any X11 app that holds a lock, so typing this
+will kill xscreensaver and unlock the screen.  This so-called
+"feature" showed up in the X server in 2008, and as of 2011, some
+vendors are shipping it turned on by default.  How nice.  You can
+disable it by turning off
+\fBAllowClosedownGrabs\fP in \fIxorg.conf\fP.
+.TP 3
+.B Alt-SysRq-F
+This is the Linux kernel "OOM-killer" keystroke.  It shoots down
+random long-running programs of its choosing, and so might might
+target and kill xscreensaver, and there's no way for xscreensaver to
+protect itself from that.  You can disable it globally with:
+.EX
+echo 176 > /proc/sys/kernel/sysrq
+.EE
+.RE
+There's little that I can do to make the screen locker be secure so long
+as the kernel and X11 developers are \fIactively\fP working against
+security like this.  The strength of the lock on your front door
+doesn't matter much so long as someone else in the house insists on
+leaving a key under the welcome mat.
+.TP 4
+.B Dangerous Backdoor Server Extensions
+Many distros enable by default several X11 server extensions that can
+be used to bypass grabs, and thus snoop on you while you're typing
+your password.  These extensions are nominally for debugging and
+automation, but they are also security-circumventing keystroke
+loggers.  If your server is configured to load the \fBRECORD, XTRAP\fP
+or \fBXTEST\fP extensions, you absolutely should disable those, 100%
+of the time.  Look for them in \fIxorg.conf\fP or whatever it is
+called.
+.SH X RESOURCES
+These are the X resources use by the \fIxscreensaver\fP program.
+You probably won't need to change these manually (that's what the
+.BR xscreensaver\-demo (1)
+program is for).
+.TP 8
+.B timeout\fP (class \fBTime\fP)
+The screensaver will activate (blank the screen) after the keyboard and
+mouse have been idle for this many minutes.  Default 10 minutes.
+.TP 8
+.B cycle\fP (class \fBTime\fP)
+After the screensaver has been running for this many minutes, the currently
+running graphics-hack sub-process will be killed (with \fBSIGTERM\fP), and a
+new one started.  If this is 0, then the graphics hack will never be changed:
+only one demo will run until the screensaver is deactivated by user activity.
+Default 10 minutes.
+
+The running saver will be restarted every \fIcycle\fP minutes even when
+\fImode\fP is \fIone\fP, since some savers tend to converge on a steady
+state.
+.TP 8
+.B lock\fP (class \fBBoolean\fP)
+Enable locking: before the screensaver will turn off, it will require you 
+to type the password of the logged-in user (really, the person who ran
+xscreensaver), or the root password.  (\fBNote:\fP this doesn't work if the
+screensaver is launched by
+.BR xdm (1)
+because it can't know the user-id of the logged-in user.  See 
+the "\fIUsing XDM(1)\fP" section, below.
+.TP 8
+.B lockTimeout\fP (class \fBTime\fP)
+If locking is enabled, this controls the length of the "grace period"
+between when the screensaver activates, and when the screen becomes locked.
+For example, if this is 5, and \fI\-timeout\fP is 10, then after 10 minutes,
+the screen would blank.  If there was user activity at 12 minutes, no password
+would be required to un-blank the screen.  But, if there was user activity
+at 15 minutes or later (that is, \fI\-lock\-timeout\fP minutes after 
+activation) then a password would be required.  The default is 0, meaning
+that if locking is enabled, then a password will be required as soon as the 
+screen blanks.
+.TP 8
+.B passwdTimeout\fP (class \fBTime\fP)
+If the screen is locked, then this is how many seconds the password dialog box
+should be left on the screen before giving up (default 30 seconds).  This
+should not be too large: the X server is grabbed for the duration that the
+password dialog box is up (for security purposes) and leaving the server 
+grabbed for too long can cause problems.
+.TP 8
+.B dpmsEnabled\fP (class \fBBoolean\fP)
+Whether power management is enabled.
+.TP 8
+.B dpmsStandby\fP (class \fBTime\fP)
+If power management is enabled, how long until the monitor goes solid black.
+.TP 8
+.B dpmsSuspend\fP (class \fBTime\fP)
+If power management is enabled, how long until the monitor goes into
+power-saving mode.
+.TP 8
+.B dpmsOff\fP (class \fBTime\fP)
+If power management is enabled, how long until the monitor powers down
+completely.  Note that these settings will have no effect unless both
+the X server and the display hardware support power management; not 
+all do.  See the \fIPower Management\fP section, below, for more 
+information.
+.TP 8
+.B dpmsQuickOff\fP (class \fBBoolean\fP)
+If \fImode\fP is \fIblank\fP and this is true, then the screen will be
+powered down immediately upon blanking, regardless of other
+power-management settings.
+.TP 8
+.B visualID\fP (class \fBVisualID\fP)
+This is an historical artifacts left over from when 8-bit
+displays were still common.  You should probably ignore this.
+
+Specify which X visual to use by default.  (Note carefully that this resource
+is called \fBvisualID\fP, not merely \fBvisual\fP; if you set the \fBvisual\fP
+resource instead, things will malfunction in obscure ways for obscure reasons.)
+
+Legal values for the \fBVisualID\fP resource are:
+.RS 8
+.TP 8
+.B default
+Use the screen's default visual (the visual of the root window).  
+This is the default.
+.TP 8
+.B best
+Use the visual which supports the most colors.  Note, however, that the
+visual with the most colors might be a TrueColor visual, which does not
+support colormap animation.  Some programs have more interesting behavior
+when run on PseudoColor visuals than on TrueColor.
+.TP 8
+.B mono
+Use a monochrome visual, if there is one.
+.TP 8
+.B gray
+Use a grayscale or staticgray visual, if there is one and it has more than
+one plane (that is, it's not monochrome).
+.TP 8
+.B color
+Use the best of the color visuals, if there are any.
+.TP 8
+.B GL
+Use the visual that is best for OpenGL programs.  (OpenGL programs have
+somewhat different requirements than other X programs.)
+.TP 8
+.I class
+where \fIclass\fP is one of \fBStaticGray\fP, \fBStaticColor\fP, 
+\fBTrueColor\fP, \fBGrayScale\fP, \fBPseudoColor\fP, or \fBDirectColor\fP.
+Selects the deepest visual of the given class.
+.TP 8
+.I number
+where \fInumber\fP (decimal or hex) is interpreted as a visual id number, 
+as reported by the
+.BR xdpyinfo (1)
+program; in this way you can have finer control over exactly which visual
+gets used, for example, to select a shallower one than would otherwise
+have been chosen.
+
+.RE
+.RS 8
+Note that this option specifies only the \fIdefault\fP visual that will
+be used: the visual used may be overridden on a program-by-program basis.
+See the description of the \fBprograms\fP resource, below.
+.RE
+.TP 8
+.B installColormap\fP (class \fBBoolean\fP)
+On PseudoColor (8-bit) displays, install a private colormap while the
+screensaver is active, so that the graphics hacks can get as many
+colors as possible.  This is the default.  (This only applies when the
+screen's default visual is being used, since non-default visuals get
+their own colormaps automatically.)  This can also be overridden on a
+per-hack basis: see the discussion of the \fBdefault\-n\fP name in the
+section about the \fBprograms\fP resource.
+
+This does nothing if you have a TrueColor (16-bit or deeper) display.
+(Which, in this century, you do.)
+.TP 8
+.B verbose\fP (class \fBBoolean\fP)
+Whether to print diagnostics.  Default false.
+.TP 8
+.B timestamp\fP (class \fBBoolean\fP)
+Whether to print the time of day along with any other diagnostic messages.
+Default true.
+.TP 8
+.B splash\fP (class \fBBoolean\fP)
+Whether to display a splash screen at startup.  Default true.
+.TP 8
+.B splashDuration\fP (class \fBTime\fP)
+How long the splash screen should remain visible; default 5 seconds.
+.TP 8
+.B helpURL\fP (class \fBURL\fP)
+The splash screen has a \fIHelp\fP button on it.  When you press it, it will
+display the web page indicated here in your web browser.
+.TP 8
+.B loadURL\fP (class \fBLoadURL\fP)
+This is the shell command used to load a URL into your web browser.
+The default setting will load it into Mozilla/Netscape if it is already
+running, otherwise, will launch a new browser looking at the \fIhelpURL\fP.
+.TP 8
+.B demoCommand\fP (class \fBDemoCommand\fP)
+This is the shell command run when the \fIDemo\fP button on the splash window
+is pressed.  It defaults to
+.BR xscreensaver\-demo (1).
+.TP 8
+.B prefsCommand\fP (class \fBPrefsCommand\fP)
+This is the shell command run when the \fIPrefs\fP button on the splash window
+is pressed.  It defaults to \fIxscreensaver\-demo\ \-prefs\fP.
+.TP 8
+.B newLoginCommand\fP (class \fBNewLoginCommand\fP)
+If set, this is the shell command that is run when the "New Login" button
+is pressed on the unlock dialog box, in order to create a new desktop
+session without logging out the user who has locked the screen.
+Typically this will be some variant of
+.BR gdmflexiserver (1),
+.BR kdmctl (1),
+.BR lxdm (1)
+or
+.BR dm-tool (1).
+.TP 8
+.B nice\fP (class \fBNice\fP)
+The sub-processes created by \fIxscreensaver\fP will be "niced" to this
+level, so that they are given lower priority than other processes on the
+system, and don't increase the load unnecessarily.  The default is 10.  
+(Higher numbers mean lower priority; see 
+.BR nice (1)
+for details.)
+.TP 8
+.B fade\fP (class \fBBoolean\fP)
+If this is true, then when the screensaver activates, the current contents
+of the screen will fade to black instead of simply winking out.  This only
+works on certain systems.  A fade will also be done when switching graphics
+hacks (when the \fIcycle\fP timer expires).  Default: true.  
+.TP 8
+.B unfade\fP (class \fBBoolean\fP)
+If this is true, then when the screensaver deactivates, the original contents
+of the screen will fade in from black instead of appearing immediately.  This
+only works on certain systems, and if \fIfade\fP is true as well.
+Default false.
+.TP 8
+.B fadeSeconds\fP (class \fBTime\fP)
+If \fIfade\fP is true, this is how long the fade will be in 
+seconds (default 3 seconds).
+.TP 8
+.B fadeTicks\fP (class \fBInteger\fP)
+If \fIfade\fP is true, this is how many times a second the colormap will
+be changed to effect a fade.  Higher numbers yield smoother fades, but
+may make the fades take longer than the specified \fIfadeSeconds\fP if
+your server isn't fast enough to keep up.  Default 20.
+.TP 8
+.B captureStderr\fP (class \fBBoolean\fP)
+Whether \fIxscreensaver\fP should redirect its stdout and stderr streams to
+the window itself.  Since its nature is to take over the screen, you would not
+normally see error messages generated by xscreensaver or the sub-programs it
+runs; this resource will cause the output of all relevant programs to be
+drawn on the screensaver window itself, as well as being written to the
+controlling terminal of the screensaver driver process.  Default true.
+.TP 8
+.B ignoreUninstalledPrograms\fP (class \fBBoolean\fP)
+There may be programs in the list that are not installed on the system,
+yet are marked as "enabled".  If this preference is true, then such 
+programs will simply be ignored.  If false, then a warning will be printed
+if an attempt is made to run the nonexistent program.  Also, the
+.BR xscreensaver-demo (1)
+program will suppress the non-existent programs from the list if this
+is true.  Default: false.
+.TP 8
+.B authWarningSlack\fP (class \fBInteger\fP)
+If \fIall\fP failed unlock attempts (incorrect password entered) were
+made within this period of time, the usual dialog that warns about such
+attempts after a successful login will be suppressed. The assumption
+is that incorrect passwords entered within a few seconds of a correct
+one are user error, rather than hostile action.  Default 20 seconds.
+.TP 8
+.B GetViewPortIsFullOfLies\fP (class \fBBoolean\fP)
+Set this to true if the xscreensaver window doesn't cover the whole screen.
+This works around a longstanding XFree86 bug #421.  See the 
+xscreensaver FAQ for details.
+.TP 8
+.B font\fP (class \fBFont\fP)
+The font used for the stdout/stderr text, if \fBcaptureStderr\fP is true.
+Default \fB*\-medium\-r\-*\-140\-*\-m\-*\fP (a 14 point fixed-width font).
+.TP 8
+.B mode\fP (class \fBMode\fP)
+Controls the behavior of xscreensaver.  Legal values are:
+.RS 8
+.TP 8
+.B random
+When blanking the screen, select a random display mode from among those
+that are enabled and applicable.  This is the default.
+.TP 8
+.B random-same
+Like \fIrandom\fP, but if there are multiple screens, each screen
+will run the \fIsame\fP random display mode, instead of each screen
+running a different one.
+.TP 8
+.B one
+When blanking the screen, only ever use one particular display mode (the
+one indicated by the \fIselected\fP setting).
+.TP 8
+.B blank
+When blanking the screen, just go black: don't run any graphics hacks.
+.TP 8
+.B off
+Don't ever blank the screen, and don't ever allow the monitor to power down.
+
+.RE
+.TP 8
+.B selected\fP (class \fBInteger\fP)
+When \fImode\fP is set to \fIone\fP, this is the one, indicated by its
+index in the \fIprograms\fP list.  You're crazy if you count them and
+set this number by hand: let
+.BR xscreensaver\-demo (1)
+do it for you!
+.TP 8
+.B programs\fP (class \fBPrograms\fP)
+The graphics hacks which \fIxscreensaver\fP runs when the user is idle.
+The value of this resource is a multi-line string, one \fIsh\fP-syntax
+command per line.  Each line must contain exactly one command: no
+semicolons, no ampersands.
+
+When the screensaver starts up, one of these is selected (according to
+the \fBmode\fP setting), and run.  After the \fIcycle\fP period
+expires, it is killed, and another is selected and run.
+
+If a line begins with a dash (-) then that particular program is
+disabled: it won't be selected at random (though you can still select
+it explicitly using the
+.BR xscreensaver\-demo (1)
+program).
+
+If all programs are disabled, then the screen will just be made blank,
+as when \fImode\fP is set to \fIblank\fP.
+
+To disable a program, you must mark it as disabled with a dash instead
+of removing it from the list.  This is because the system-wide (app-defaults)
+and per-user (.xscreensaver) settings are merged together, and if a user
+just \fIdeletes\fP an entry from their programs list, but that entry still
+exists in the system-wide list, then it will come back.  However, if the
+user \fIdisables\fP it, then their setting takes precedence.
+
+If the display has multiple screens, then a different program will be run
+for each screen.  (All screens are blanked and unblanked simultaneously.)
+
+Note that you must escape the newlines; here is an example of how you
+might set this in your \fI~/.xscreensaver\fP file:
+
+.RS 8
+.EX
+programs:  \\
+       qix -root                          \\n\\
+       ico -r -faces -sleep 1 -obj ico    \\n\\
+       xdaliclock -builtin2 -root         \\n\\
+       xv -root -rmode 5 image.gif -quit  \\n
+.EE
+.RE
+.RS 8
+Make sure your \fB$PATH\fP environment variable is set up correctly
+\fIbefore\fP xscreensaver is launched, or it won't be able to find the
+programs listed in the \fIprograms\fP resource.
+
+To use a program as a screensaver, two things are required: that that
+program draw on the root window (or be able to be configured to draw on
+the root window); and that that program understand "virtual root"
+windows, as used by virtual window managers such as
+.BR tvtwm (1).
+(Generally, this is accomplished by just including the \fI"vroot.h"\fP 
+header file in the program's source.)
+
+.B Visuals:
+
+Because xscreensaver was created back when dinosaurs roamed the earth,
+it still contains support for some things you've probably never seen,
+such as 1-bit monochrome monitors, grayscale monitors, and monitors
+capable of displaying only 8-bit colormapped images.
+
+If there are some programs that you want to run only when using a color
+display, and others that you want to run only when using a monochrome
+display, you can specify that like this:
+.EX
+       mono:   mono-program  -root        \\n\\
+       color:  color-program -root        \\n\\
+.EE
+.RE
+.RS 8
+More generally, you can specify the kind of visual that should be used for
+the window on which the program will be drawing.  For example, if one 
+program works best if it has a colormap, but another works best if it has
+a 24-bit visual, both can be accommodated:
+.EX
+       PseudoColor: cmap-program  -root   \\n\\
+       TrueColor:   24bit-program -root   \\n\\
+.EE
+.RE
+.RS 8
+In addition to the symbolic visual names described above (in the discussion
+of the \fIvisualID\fP resource) one other visual name is supported in
+the \fIprograms\fP list:
+.RS 1
+.TP 4
+.B default-n
+This is like \fBdefault\fP, but also requests the use of the default colormap,
+instead of a private colormap.  (That is, it behaves as if 
+the \fI\-no\-install\fP command-line option was specified, but only for
+this particular hack.)  This is provided because some third-party programs
+that draw on the root window (notably: 
+.BR xv (1),
+and
+.BR xearth (1))
+make assumptions about the visual and colormap of the root window: 
+assumptions which xscreensaver can violate.
+
+.RE
+If you specify a particular visual for a program, and that visual does not
+exist on the screen, then that program will not be chosen to run.  This
+means that on displays with multiple screens of different depths, you can
+arrange for appropriate hacks to be run on each.  For example, if one screen
+is color and the other is monochrome, hacks that look good in mono can be 
+run on one, and hacks that only look good in color will show up on the other.
+.RE
+.PP
+.PP
+You shouldn't ever need to change the following resources:
+.PP
+.TP 8
+.B pointerPollTime\fP (class \fBTime\fP)
+When server extensions are not in use, this controls how 
+frequently \fIxscreensaver\fP checks to see if the mouse position or buttons
+have changed.  Default 5 seconds.
+.TP 8
+.B pointerHysteresis\fP (class \fBInteger\fP)
+If the mouse moves less than this-many pixels in a second, ignore it
+(do not consider that to be "activity").  This is so that the screen
+doesn't un-blank (or fail to blank) just because you bumped the desk.
+Default: 10 pixels.
+.TP 8
+.B windowCreationTimeout\fP (class \fBTime\fP)
+When server extensions are not in use, this controls the delay between when 
+windows are created and when \fIxscreensaver\fP selects events on them.
+Default 30 seconds.
+.TP 8
+.B initialDelay\fP (class \fBTime\fP)
+When server extensions are not in use, \fIxscreensaver\fP will wait this many
+seconds before selecting events on existing windows, under the assumption that 
+\fIxscreensaver\fP is started during your login procedure, and the window 
+state may be in flux.  Default 0.  (This used to default to 30, but that was
+back in the days when slow machines and X terminals were more common...)
+.TP 8
+.B procInterrupts\fP (class \fBBoolean\fP)
+This resource controls whether the \fB/proc/interrupts\fP file should be
+consulted to decide whether the user is idle.  This is the default
+if \fIxscreensaver\fP has been compiled on a system which supports this
+mechanism (i.e., Linux systems).  
+
+The benefit to doing this is that \fIxscreensaver\fP can note that the user
+is active even when the X console is not the active one: if the user is 
+typing in another virtual console, xscreensaver will notice that and will
+fail to activate.  For example, if you're playing Quake in VGA-mode, 
+xscreensaver won't wake up in the middle of your game and start competing 
+for CPU.
+
+The drawback to doing this is that perhaps you \fIreally do\fP want idleness
+on the X console to cause the X display to lock, even if there is activity
+on other virtual consoles.  If you want that, then set this option to False.
+(Or just lock the X console manually.)
+
+The default value for this resource is True, on systems where it works.
+.TP 8
+.B overlayStderr\fP (class \fBBoolean\fP)
+If \fBcaptureStderr\fP is True, and your server supports "overlay" visuals,
+then the text will be written into one of the higher layers instead of into
+the same layer as the running screenhack.  Set this to False to disable 
+that (though you shouldn't need to).
+.TP 8
+.B overlayTextForeground\fP (class \fBForeground\fP)
+The foreground color used for the stdout/stderr text, if \fBcaptureStderr\fP
+is true.  Default: Yellow.
+.TP 8
+.B overlayTextBackground\fP (class \fBBackground\fP)
+The background color used for the stdout/stderr text, if \fBcaptureStderr\fP
+is true.  Default: Black.
+.TP 8
+.B bourneShell\fP (class \fBBourneShell\fP)
+The pathname of the shell that \fIxscreensaver\fP uses to start subprocesses.
+This must be whatever your local variant of \fB/bin/sh\fP is: in particular,
+it must not be \fBcsh\fP.
+.SH ENVIRONMENT
+.PP
+.TP 8
+.B DISPLAY
+to get the default host and display number, and to inform the sub-programs
+of the screen on which to draw.
+.TP 8
+.B XSCREENSAVER_WINDOW
+Passed to sub-programs to indicate the ID of the window on which they
+should draw.  This is necessary on Xinerama/RANDR systems where
+multiple physical monitors share a single X11 "Screen".
+.TP 8
+.B PATH
+to find the sub-programs to run.
+.TP 8
+.B HOME
+for the directory in which to read the \fI.xscreensaver\fP file.
+.TP 8
+.B XENVIRONMENT
+to get the name of a resource file that overrides the global resources
+stored in the RESOURCE_MANAGER property.
+.SH UPGRADES
+The latest version of xscreensaver, an online version of this manual,
+and a FAQ can always be found at https://www.jwz.org/xscreensaver/
+.SH SEE ALSO
+.BR X (1),
+.BR Xsecurity (1),
+.BR xauth (1),
+.BR xdm (1),
+.BR gdm (1),
+.BR xhost (1),
+.BR xscreensaver\-demo (1),
+.BR xscreensaver\-command (1),
+.BR xscreensaver\-gl\-helper (1),
+.BR xscreensaver\-getimage (1),
+.BR xscreensaver\-text (1).
+.SH COPYRIGHT
+Copyright \(co 1991-2018 by Jamie Zawinski.
+Permission to use, copy, modify, distribute, and sell this software
+and its documentation for any purpose is hereby granted without fee,
+provided that the above copyright notice appear in all copies and that
+both that copyright notice and this permission notice appear in
+supporting documentation.  No representations are made about the
+suitability of this software for any purpose.  It is provided "as is"
+without express or implied warranty.
+.SH AUTHOR
+Jamie Zawinski <jwz@jwz.org>.  Written in late 1991; version 1.0 posted
+to comp.sources.x on 17-Aug-1992.
+
+Please let me know if you find any bugs or make any improvements.
+
+And a huge thank you to the hundreds of people who have contributed, in
+large ways and small, to the xscreensaver collection over the past
+two decades!