xscreensaver
NAME
xscreensaver - graphics hack and screen locker, launched
when the user is idle
SYNOPSIS
xscreensaver [-display host:display.screen] [-timeout int]
[-cycle int] [-nice int] [-verbose] [-silent] [-xidle]
[-no-xidle] [-lock] [-no-lock] [-lock-timeout int] [-demo]
[-visual visual] [-install] [-no-install] [-xrm resources]
DESCRIPTION
The xscreensaver 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.
The benefit that this program has over the combination of
the xlock(1) and xautolock(1) programs is the ease with
which new graphics hacks can be installed. You don't need
to recompile (or even re-run) this program to add a new
display mode.
OPTIONS
xscreensaver accepts the following options:
-timeout minutes
The screensaver will activate after the keyboard and
mouse have been idle for this many minutes.
-cycle minutes
After the screensaver has been running for this many
minutes, the currently running sub-process will be
killed (with SIGTERM), and a new one started. If
this is 0, then the sub-process will not be killed;
only one demo will run until the screensaver is
deactivated by user activity.
-nice integer
The sub-processes created by xscreensaver will be
``niced'' to this level, so that they do not consume
cycles that are needed elsewhere.
-verbose
Print diagnostics.
-silent
-xidle-extension
Use the XIDLE server extension to decide whether the
user is idle. This is the default if xscreensaver
has been compiled with support 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.
-no-xidle-extension
Don't use the XIDLE server extension.
-ss-extension
Use the MIT-SCREEN-SAVER server extension to decide
whether the user is idle. This is the default if
xscreensaver has been compiled with support for this
extension. On X11R6 systems, the MIT-SCREEN-SAVER
method is faster and more reliable than what will be
done otherwise, so use it if you can.
-no-ss-extension
Don't use the MIT-SCREEN-SAVER server extension.
-lock Enable locking: before the screensaver will turn
off, it requires you to type the password of the
person who launched the screensaver, or the root
password. (Note: this doesn't work if the
screensaver is launched by xdm(1) because it can't
know the user-id of the logged-in user.)
-no-lock
Disable locking. This is the default.
-lock-timeout minutes
This is how long after the screensaver activates
that locking is enabled. For example, if this is 5,
then any user activity within five minutes of the
time when the screensaver activated will cause the
screen to unblank without requiring a password.
After 5 minutes, a password will be required. The
default is 0, meaning that if locking is enabled,
then a password will be required as soon as the
screensaver activates.
-visual visual
Specify which visual to use. Legal values are:
best Use the visual which supports the most
writable color cells; this is the default.
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.
class One of StaticGray, StaticColor, TrueColor,
GrayScale, PseudoColor, or DirectColor.
Selects the deepest visual of the given
class.
number A number (decimal or hex) is interpreted as
a visual id number, as reported by the
xdpyinfo(1) program; in this way you can
select a shallower visual if desired.
-no-install
Use the default colormap. This is the default.
-install
Install a private colormap while the screensaver is
on, so that the graphics hacks can get as many
colors as possible.
-demo Enter the interactive demo mode immediately after
startup. Normally demo mode is invoked via the
xscreensaver-command(1) program.
X RESOURCES
xscreensaver understands the following resources:
timeout (class Time)
Same as the -timeout command-line option. Default
10 minutes.
cycle (class Time)
Same as the -cycle command-line option. Default 10
minutes.
nice (class Nice)
Same as the -nice command-line option. Default 10.
verbose (class Boolean)
Same as the -verbose command-line option.
xidle (class Boolean)
Same as the -xidle command-line option.
lock (class Boolean)
Same as the -lock command-line option.
lockTimeout (class Time)
Same as the -lock-timeout command-line option.
fade (class Boolean)
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 displays with writable colormaps.
Default true. A fade will also be done when
switching graphics hacks (when the cycle timer
expires.)
unfade (class Boolean)
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 displays with
writable colormaps, and if fade is true as well.
Default false.
fadeSeconds (class Time)
If fade is true, this is how long the fade will be
in seconds (default 1.)
fadeTicks (class Integer)
If fade 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 if your server isn't fast enough to keep
up. Default 75.
installColormap (class Boolean)
Same as the -install command-line option. Default
false.
passwdTimeout (class Time)
If lock is true, this is how many seconds the
password dialog box should be left on the screen
before giving up (default 30.) 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.
visualID (class VisualID)
Same as the -visual command-line option. Default
best.
captureStderr (class Boolean)
Whether xscreensaver 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.
captureStdout (class Boolean)
Like captureStderr but for the standard-output
stream. Default: True.
font (class Font)
The font used for the stdout/stderr text, if
captureStdout or captureStderr are true. Default
*-medium-r-*-140-*-m-* (a 14 point fixed-width
font.)
textForeground (class Foreground)
The foreground color used for the stdout/stderr
text, if captureStdout or captureStderr are true.
Default: Yellow.
textBackground (class Background)
The background color used for the stdout/stderr
text, if captureStdout or captureStderr are true.
Default: Black.
programs (class Programs)
The graphics hacks which xscreensaver runs when the
user is idle. The value of this resource is a
string, one sh 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 cycle period
expires, it is killed, and another is selected and
run.
If the value of this resource (and the applicable
one of colorPrograms or monoPrograms) is empty, then
no programs will be run; the screen will simply be
made black.
Note that you must escape the newlines; here is an
example of how you might set this in your .Xdefaults
xscreensaver.programs: \
qix -root \n\
ico -r -faces -sleep 1 -obj ico \n\
xdaliclock -builtin2 -root \n\
xwave -root
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 tvtwm.
It is quite easy to make programs understand virtual
roots if they don't already: you merely need to
include the file "vroot.h" in them after the
standard X includes, and recompile. This file is
distributed with X11r5, and is included with
xscreensaver as well.
monoPrograms (class MonoPrograms)
This resource is appended to the value of the
programs resource if the display on which the
screensaver is running is monochrome.
colorPrograms (class ColorPrograms)
This resource is appended to the value of the
programs resource if the display on which the
screensaver is running is not monochrome.
NOTE: this means that if you want to completely replace
the list of programs which xscreensaver runs, you must
set at least two, possibly three resources. It is not
enough to just set the programs resource -- you must
also set colorPrograms or monoPrograms or both.
Normally you won't need to change the following resources:
bourneShell (class BourneShell)
The pathname of the shell that xscreensaver uses to
start subprocesses. This must be whatever your
local variant of /bin/sh is -- in particular, it
must not be csh.
windowCreationTimeout (class Time)
When XIdle is not in use, this controls the delay
between when windows are created and when
xscreensaver selects events on them. Default 30
seconds.
pointerPollTime (class Time)
When XIdle is not in use, this controls how
frequently xscreensaver checks to see if the mouse
position or buttons have changed. Default 5
seconds.
initialDelay (class Time)
When XIdle is not in use, xscreensaver will wait
this many seconds before selecting events on
existing windows, under the assumption that
xscreensaver is started during your login procedure,
and the window state may be in flux. Default 30
seconds.
HOW IT WORKS
When it is time to activate the screensaver, a full-screen
black window is created. This window is given the
appropriate properties so 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.
When the user becomes active again, the screensaver window
is unmapped and the running subprocess is killed by sending
it SIGTERM. 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.
Before launching a subprocess, xscreensaver stores an
appropriate value for $DISPLAY in the environment that the
child will recieve. (This is so that if you start
xscreensaver with a -display argument, the programs which
xscreensaver launches will draw on the same display.)
When the screensaver turns off, or is killed, care is taken
to restore the ``real'' virtual root window if there is one.
Because of this, it is important that you not kill the
screensaver process with kill -9 if you are running a
virtual-root window manager. If you kill it with -9, you
may need to restart your window manager to repair the
damage. This isn't an issue if you aren't running a
virtual-root window manager.
For all the gory details, see the commentary at the top of
xscreensaver.c.
You can control a running screensaver process by using the
xscreensaver-command(1) program (which see.)
ENVIRONMENT
DISPLAY to get the default host and display number.
XENVIRONMENT
to get the name of a resource file that overrides
the global resources stored in the RESOURCE_MANAGER
property.
USING XDM(1)
You can run xscreensaver from your xdm session, so that the
screensaver will run even when nobody is logged in on the
console. Simply add "xscreensaver &" to your
/usr/lib/X11/xdm/Xsetup file. Because xdm grabs the
keyboard, keypresses will not make the screensaver
deactivate, but any mouse activity will.
Users may want to add "xscreensaver-command -restart" to
their startup scripts, so that the screensaver will be
reinitialized with their private resource settings when they
log in.
It is safe to run this program as root (as xdm is likely to
do.) If run as root, xscreensaver changes its effective
user and group ids to something safe (like "nobody") before
connecting to the X server or launching user-specified
programs.
Locking doesn't work if the screensaver is launched by xdm.
To get around this, you can run the screensaver from xdm
without locking, and kill and restart it from your personal
X startup script to enable locking.
DEMO MODE
If xscreensaver receives the DEMO ClientMessage, it pops up
a dialog box from which you can examine and experiment with
the screensaver's client programs.
Clicking left on an element in the scrolling list will place
the indicated program and its args in the text field to be
edited. Edit the arguments and hit return to run the
program with the parameters you have specified.
Double-clicking on an element in the scrolling list will run
the indicated program immediately.
When a client program is launched, the dialog box is hidden.
Clicking any mouse button will re-expose the dialog box (but
will not kill the client program.)
Run Next
Clicking this button will run the next program in
the list after the currently-selected one, and will
scroll around to the top when it reaches the bottom.
Run Previous
Opposite of Run Next; at the top, it scrolls around
to the bottom.
Edit Parameters
This pops up a second dialog box, in which you have
the option to interactively change most of the
screensaver's operational parameters, such as its
timeouts, and whether it should hack colormaps.
Changing these parameters here will affect only the
running xscreensaver process; to make the changes
permanent, you need to edit your X resource file.
Exit Demo Mode
Returns to normal screensaver operation.
Reinitialize
Causes the screensaver process to exit and then
restart with the same command-line arguments. This
causes the X resource database to be re-read. This
is just like the -restart argument to
xscreensaver-command(1) except that when executed
from this button, the screensaver will automatically
return to demo mode after restarting.
SEE ALSO
X(1), xscreensaver-command(1), xlock(1), xnlock(1),
xautolock(1), xdm(1), qix(1), pyro(1), helix(1),
rorschach(1), hopalong(1), attraction(1), greynetic(1),
rocks(1), noseguy(1), blitspin(1), imsmap(1),
slidescreen(1), decayscreen(1), hypercube(1), flame(1),
maze(1), ico(1), xdaliclock(1), xbouncebits(1), xswarm(1),
xwave(1), xfishtank(1)
BUGS
If you think you have changed the programs resource but the
screensaver is ignoring it, you are confused -- you need to
set the colorPrograms and/or monoPrograms resources as well.
(This is not a bug, but I mention it here because people
think that it is with great regularity.)
If you are not making use of one of the server extensions
(XIDLE or MIT-SCREEN-SAVER), then it is possible, in rare
situations, for xscreensaver to interfere with event
propagation and make another X program malfunction. For
this to occur, that other application would need to not
select KeyPress 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 might 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.
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 suck a lot of cycles. Care should be
taken to slow down programs intended for use as screensavers
by inserting strategic calls to sleep(3) or usleep(3)
Also, it will cause your X server to be pretty much
permanently swapped in. (but the same is true of any
program that draws periodically, like xclock or xload.)
If the subprocess is drawing too quickly and the connection
to the X server is a slow one (such as an X terminal running
over a phone line) then the screensaver might not turn off
right away when the user becomes active again (the ico(1)
demo has this problem if being run in full-speed mode).
This can be alleviated by inserting strategic calls to
XSync(3) in code intended for use as a screensaver. This
prevents too much graphics activity from being buffered up.
The screensaver only runs on the default screen of the
display. If you have 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.
If you don't have Motif, you can't compile with support for
locking or demo mode.
Locking doesn't work if the screensaver is launched by xdm.
The reason for this is that when it is launched by xdm, the
screensaver process is owned by some standard user id (such
as root or daemon) 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 xdm, 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 xdm, you
can kill it with xscreensaver-command -exit, and then start
it again as you.
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 getpwent(3) library routine can only be
effectively used by root. If this is the case, then
xscreensaver must be installed as setuid to root. Care has
been taken to make this a safe thing to do.
The installColormap option doesn't work very well with the
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 mwm(1) and olwm(1) window
managers don't seem to have this problem. The race
condition exists because X apparently does not provide a way
for an OverrideRedirect window to have its own colormap,
short of grabbing the server (which is neither a good idea,
nor really possible with the current design.) What happens
is that, as soon as the screensaver installs its colormap,
twm responds to the ColormapNotify event that is generated
by re-instaling the default colormap. Apparently, twm
doesn't always do this; it seems to do it regularly if the
screensaver is activated from a menu item, but seems to 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...
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.
When using the MIT-SCREEN-SAVER extension in conjunction
with the fade 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 xscreensaver
process to activate. The xscreensaver process immediately
unmaps that window, but this results in a flicker. I
haven't figured out how to get around this yet.
There need to be a lot more graphics hacks. In particular,
there should be a simulation of a Lavalite (tm).
COPYRIGHT
Copyright 8c9 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.
AUTHOR
Jamie Zawinski <jwz@mcom.com>, 13-aug-92. Please let me
know if you find any bugs or make any improvements.
Thanks to David Wojtowicz for implementing lockTimeout.
Thanks to Martin Kraemer for adding support for shadow
passwords and locking-disabled diagnostics.