.if n .sp 1
.if t .sp .5
..
-.TH XScreenSaver 1 "12-May-94" "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] [\-visual \fIvisual\fP] [\-xrm \fIresources\fP]
+[\-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] [\-visual \fIvisual\fP] [\-install] [\-no-install] [\-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 \-ss\-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. On X11R6 systems, the \fBMIT\-SCREEN\-SAVER\fP
+method is faster and more reliable than what will be done otherwise, so use
+it if you can.
+.TP 8
+.B \-no\-ss\-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
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
.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)
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 maze (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
+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
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
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 out how to get around this yet.
+.PP
+There need to be a lot more graphics hacks. In particular, there should be
+a simulation of a Lavalite (tm).
.SH COPYRIGHT
-Copyright \(co 1992, 1993, 1994 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
+Copyright \(co 1992, 1993, 1994, 1995 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.
projects / xscreensaver / blobdiff