.if n .sp 1
.if t .sp .5
..
-.TH XScreenSaver 1 "22-mar-93" "X Version 11"
+.TH XScreenSaver 1 "6-Jan-95" "X Version 11"
.SH NAME
-xscreensaver - run graphics hacks after the user has been idle for a while
+xscreensaver - graphics hack and screen locker, launched when the user is idle
.SH SYNOPSIS
.B xscreensaver
-[\-display \fIhost:display.screen\fP] [\-timeout \fIint\fP] [\-cycle \fIint\fP] [\-nice \fIint\fP] [\-verbose] [\-silent] [\-xidle] [\-no-xidle] [\-lock] [\-no-lock] [\-lock\-timeout \fIint\fP] [\-demo] [\-xrm \fIresources\fP]
+[\-display \fIhost:display.screen\fP] [\-timeout \fIint\fP] [\-cycle \fIint\fP] [\-nice \fIint\fP] [\-verbose] [\-silent] [\-lock] [\-no\-lock] [\-lock\-timeout \fIint\fP] [\-demo] [\-visual \fIvisual\fP] [\-install] [\-no\-install] [\-xidle\-extension] [\-no\-xidle\-extension] [\-sgi\-extension] [\-no\-sgi\-extension] [\-mit\-extension] [\-no\-mit\-extension] [\-xrm \fIresources\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
.B \-silent
.TP 8
-.B \-xidle
-Use the \fIXIdle\fP server extension to decide whether the user is idle.
+.B \-xidle\-extension
+Use the \fBXIDLE\fP server extension to decide whether the user is idle.
This is the default if \fIxscreensaver\fP has been compiled with support
-for XIdle. The XIdle method is faster and more reliable than what will
-be done otherwise, so use it if you can.
+for this extension. On X11R4 or X11R5 systems, the XIdle method is faster
+and more reliable than what will be done otherwise, so use it if you can.
.TP 8
-.B \-no\-xidle
-Don't use \fIXIdle\fP.
+.B \-no\-xidle\-extension
+Don't use the \fBXIDLE\fP server extension.
+.TP 8
+.B \-sgi\-extension
+Use the SGI \fBSCREEN_SAVER\fP server extension to decide whether the user
+is idle. This is the default if \fIxscreensaver\fP has been compiled with
+support for this extension. On SGI systems, the \fBSCREEN_SAVER\fP
+method is faster and more reliable than what will be done otherwise, so use
+it if you can.
+.TP 8
+.B \-no\-sgi\-extension
+Don't use the SGI \fBSCREEN_SAVER\fP server extension.
+.TP 8
+.B \-mit\-extension
+Use the \fBMIT\-SCREEN\-SAVER\fP server extension to decide whether the user
+is idle. This is the default if \fIxscreensaver\fP has been compiled with
+support for this extension. This extension is flaky, so it's use is not
+really recommended.
+.TP 8
+.B \-no\-mit\-extension
+Don't use the \fBMIT\-SCREEN\-SAVER\fP server extension.
.TP 8
.B \-lock
Enable locking: before the screensaver will turn off, it requires you to
required. The default is 0, meaning that if locking is enabled, then
a password will be required as soon as the screensaver activates.
.TP 8
+.B \-visual \fIvisual\fP
+Specify which visual to use. Legal values are:
+.RS 8
+.TP 8
+.B best
+Use the visual which supports the most writable color cells; this is
+the default.
+.TP 8
+.B default
+Use the screen's default visual (the visual of the root window.) This is
+not necessarily the most colorful visual, which is why it is not the default.
+.TP 8
+.I class
+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
+A number (decimal or hex) is interpreted as a visual id number, as reported
+by the
+.BR xdpyinfo (1)
+program; in this way you can select a shallower visual if desired.
+.RE
+.TP 8
+.B \-no\-install
+Use the default colormap. This is the default.
+.TP 8
+.B \-install
+Install a private colormap while the screensaver is on, so that the graphics
+hacks can get as many colors as possible.
+.TP 8
.B \-demo
Enter the interactive demo mode immediately after startup. Normally
demo mode is invoked via the
up. Default 75.
.TP 8
.B installColormap \fR(class \fBBoolean\fP)
-Whether a new colormap should be installed while the screensaver is on,
-so that the graphics hacks can get as many colors as possible. Default
-false.
+Same as the \fI\-install\fP command-line option. Default false.
.TP 8
.B passwdTimeout \fR(class \fBTime\fP)
If \fIlock\fP is true, this is how many seconds the password dialog box
dialog box is up (for security purposes) and leaving the server grabbed for
too long can cause problems.
.TP 8
+.B visualID \fR(class \fBVisualID\fP)
+Same as the \fI\-visual\fP command-line option. Default \fBbest\fP.
+.TP 8
+.B captureStderr \fR(class \fBBoolean\fP)
+Whether \fIxscreensaver\fP should redirect its standard-error stream to the
+window itself. Since its nature is to take over the screen, you would not
+normally see error messages generated by the screensaver or the programs it
+runs; this resource will cause the output of all relevant programs to be
+drawn on the screensaver window itself instead of written to the controlling
+terminal of the screensaver driver process. Default: True.
+.TP 8
+.B captureStdout \fR(class \fBBoolean\fP)
+Like \fBcaptureStderr\fP but for the standard-output stream. Default: True.
+.TP 8
+.B font \fR(class \fBFont\fP)
+The font used for the stdout/stderr text, if \fBcaptureStdout\fP or
+\fBcaptureStderr\fP are true. Default \fB*\-medium\-r\-*\-140\-*\-m\-*\fP
+(a 14 point fixed-width font.)
+.TP 8
+.B textForeground \fR(class \fBForeground\fP)
+The foreground color used for the stdout/stderr text, if \fBcaptureStdout\fP
+or \fBcaptureStderr\fP are true. Default: Yellow.
+.TP 8
+.B textBackground \fR(class \fBBackground\fP)
+The background color used for the stdout/stderr text, if \fBcaptureStdout\fP
+or \fBcaptureStderr\fP are true. Default: Black.
+.TP 8
.B programs \fR(class \fBPrograms\fP)
-The graphics hacks which \fIxscreensaver\fP runs when the user is idle.
-The value of this resource is a string, one \fIsh\fP command per line.
-Each line must contain exactly one command -- no semicolons.
+The graphics hacks which \fIxscreensaver\fP runs when the user is idle,
+in addition to those specified in colorPrograms or monoPrograms (as
+appropriate.) The value of this resource is a string, one \fIsh\fP command
+per line. Each line must contain exactly one command -- no semicolons.
When the screensaver starts up, one of these is selected at random, and
run. After the \fIcycle\fP period expires, it is killed, and another
This resource is appended to the value of the \fIprograms\fP resource if
the display on which the screensaver is running is not monochrome.
.PP
+.RS 4
+\fBNOTE: this means that if you want to completely replace the list of
+programs which xscreensaver runs, you must set at least \fItwo\fP,
+possibly \fIthree\fP resources. It is not enough to just set
+the \fBprograms\fP resource -- you must also set \fBcolorPrograms\fP
+or \fBmonoPrograms\fP or both.\fP
+.RE
+.PP
Normally you won't need to change the following resources:
.TP 8
.B bourneShell \fR(class \fBBourneShell\fP)
it must not be \fBcsh\fP.
.TP 8
.B windowCreationTimeout \fR(class \fBTime\fP)
-When \fIXIdle\fP is not in use, this controls the delay between when
+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 pointerPollTime \fR(class \fBTime\fP)
-When \fIXIdle\fP is not in use, this controls how frequently \fIxscreensaver\fP
-checks to see if the mouse position or buttons have changed. Default 5 seconds.
+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 initialDelay \fR(class \fBTime\fP)
-When \fIXIdle\fP is not in use, \fIxscreensaver\fP will wait this many seconds
-before selecting events on existing windows, under the assumption that
+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 30 seconds.
.SH "HOW IT WORKS"
file. Because \fIxdm\fP grabs the keyboard, keypresses will not make
the screensaver deactivate, but any mouse activity will.
.PP
+(If your system does not seem to be executing the \fIXsetup\fP file, you
+may need to configure it to do so -- the traditional way to do this is
+to make that file the value of the \fIDisplayManager*setup\fP resource
+in the \fIxdm-config\fP file. See the man page for
+.BR xdm (1)
+for more details.)
+.PP
Users may want to add \fB"xscreensaver-command -restart"\fP to their
startup scripts, so that the screensaver will be reinitialized with
their private resource settings when they log in.
.BR blitspin (1),
.BR imsmap (1),
.BR slidescreen (1),
+.BR decayscreen (1),
.BR hypercube (1),
+.BR flame (1),
+.BR bubbles (1),
.BR maze (1),
.BR ico (1),
.BR xdaliclock (1),
.BR xwave (1),
.BR xfishtank (1)
.SH BUGS
-If you are not using \fIXIdle\fP, and an application does not
-select \fBKeyPress\fP events on its non-leaf windows within the first
-30 seconds of their existence, but selects them later, then it is
-possible that \fIxscreensaver\fP could interfere with the propagation
-of those events. This isn't very likely, but this is the reason that
-it's a good idea to install the \fIXIdle\fP extension.
+If you think you have changed the \fBprograms\fP resource but the
+screensaver is ignoring it, you are confused -- you need to set
+the \fBcolorPrograms\fP and/or \fBmonoPrograms\fP resources as well.
+(This is not a bug, but I mention it here because people think that
+it is with great regularity.)
+.PP
+If you are not making use of one of the server extensions (\fBXIDLE\fP,
+\fBSCREEN_SAVER\fP, or \fBMIT-SCREEN-SAVER\fP), then it is possible, in rare
+situations, for \fIxscreensaver\fP to interfere with event propagation and make
+another X program malfunction. For this to occur, that other application
+would need to \fInot\fP select \fBKeyPress\fP events on its non-leaf windows
+within the first 30 seconds of their existence, but then select for them later.
+In this case, that client \fImight\fP fail to receive those events.
+This isn't very likely, since programs generally select a constant set
+of events immediately after creating their windows and then don't change
+them, but this is the reason that it's a good idea to install and use one
+of the server extensions instead, to work around this shortcoming in the
+X protocol.
.PP
Although this program ``nices'' the subprocesses that it starts,
graphics-intensive subprograms can still overload the machine by causing
activity from being buffered up.
.PP
The screensaver only runs on the default screen of the display. If you have
-more than one screen, you must run multiple screensaver processes, one for
-each screen. (I don't actually know whether this works, because I don't
-have access to a multi-screen machine. Comments welcome.)
+more than one screen, you can run multiple screensaver processes, one for
+each screen. This interacts poorly with locking. In an ideal world, the
+screensaver would save (and lock) both screens simultaniously, and any activity
+would restore both screens. It would be nice if one could run different hacks
+on each screen simultaniously. However, I don't have access to a multi-headed
+workstation, so it would be hard for me to implement something like this.
.PP
If you don't have Motif, you can't compile with support for locking or
demo mode.
.PP
-When the \fBRun Next\fP and \fBRun Previous\fP buttons are used, the selected
-item may not be visible in the window. It's a Motif bug that selecting a
-different item doesn't scroll the list to show the new selected item.
-.PP
Locking doesn't work if the screensaver is launched by \fIxdm\fP.
+The reason for this is that when it is launched by \fIxdm\fP, the
+screensaver process is owned by some standard user id (such as \fIroot\fP
+or \fIdaemon\fP) instead of the user who is logged in on the console.
+In order for the screensaver to prompt for the password of the person
+who had logged in from \fIxdm\fP, it would need to know who that user was,
+and there is no reliable and safe way to figure that out. (And even if
+there was, there would be some other security issues here as well.)
+
+So if you want to use it as a locker, you must start it with your user id.
+If it has already been started by \fIxdm\fP, you can kill it with
+\fBxscreensaver-command -exit\fP, and then start it again as you.
.PP
If you get an error message like ``couldn't get password of foo'' then
this probably means that you're on a system in which the
then \fIxscreensaver\fP must be installed as setuid to root. Care has
been taken to make this a safe thing to do.
.PP
-There need to be a lot more graphics hacks. In particular, there should be
-a simulation of a Lavalite (tm).
-.PP
The \fBinstallColormap\fP option doesn't work very well with the
.BR twm (1)
window manager and its descendants. There is a race condition between the
screensaver and this window manager, which can result in the screensaver's
colormap not getting installed properly, meaning the graphics hacks will
-appear in essentially random colors. The
+appear in essentially random colors. (If the screen goes white instead of
+black, this is probably why.) The
.BR mwm (1)
and
.BR olwm (1)
not do it if the screensaver comes on of its own volition, or is activated
from another console. Any thoughts on this problem are welcome...
.PP
-The \fBinstallColormap\fP option has no effect in "demo" mode, since the
-dialog boxes allocate their colors out of the screen's default colormap
-instead of the installed colormap.
-.PP
-For this same reason, locking doesn't work too well along
-with \fBinstallColormap\fP; the dialog box's colors are random.
-.PP
Apparently there are some problems with ``XView'' programs getting confused
and thinking that the screensaver window is the real root window even when
the screensaver is not active: ClientMessages intended for the window manager
are sent to the screensaver window instead. This could be solved by making
xscreensaver forward all unrecognised ClientMessages to the real root window,
but there may be other problems as well.
+.PP
+When using the \fBMIT-SCREEN-SAVER\fP extension in conjunction with
+the \fBfade\fP option, you may notice an unattractive flicker just before
+the fade begins. This is because the server maps a black window just before
+it tells the \fIxscreensaver\fP process to activate. The \fIxscreensaver\fP
+process immediately unmaps that window, but this results in a flicker. I
+haven't figured a way to get around this; it seems to be a fundamental
+property of the (mis-) design of this server extension.
+.PP
+There need to be a lot more graphics hacks. In particular, there should be
+a simulation of a Lavalite (tm).
+.SH UPGRADES
+The latest version can always be found at http://www.netscape.com/people/jwz/.
+There is also usually an up-to-date copy at ftp://ftp.x.org/.
.SH COPYRIGHT
-Copyright \(co 1992, 1993 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.
+Copyright \(co 1992, 1993, 1994, 1995, 1996 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@lucid.com>, 13-aug-92.
+Jamie Zawinski <jwz@netscape.com>, 13-aug-92.
Please let me know if you find any bugs or make any improvements.
Thanks to David Wojtowicz for implementing \fIlockTimeout\fP.
+
+Thanks to Martin Kraemer for adding support for shadow passwords and
+locking-disabled diagnostics.
projects / xscreensaver / blobdiff