XScreenSaver(1)XScreenSaver(1)NAME
xscreensaver - extensible screen saver framework, plus
locking
SYNOPSIS
xscreensaver [-display host:display.screen] [-verbose]
[-no-capture-stderr] [-no-splash]
DESCRIPTION
The xscreensaver program waits until the keyboard and
mouse have been idle for a period, and then runs a graph
ics 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 moni
tor's power-saving features.
GETTING STARTED
For the impatient, try this:
xscreensaver &
xscreensaver-demo
The xscreensaver-demo(1) program pops up a dialog box that
lets you configure the screen saver, and experiment with
the various display modes.
Note: unlike xlock(1), xscreensaver has a client-server
model: the xscreensaver program is a daemon that runs in
the background; it is controlled by the foreground
xscreensaver-demo(1) and xscreensaver-command(1) programs.
CONFIGURATION
The easiest way to configure xscreensaver is to simply run
the xscreensaver-demo(1) program, and change the settings
through the GUI. The rest of this manual page describes
lower level ways of changing settings.
Options to xscreensaver are stored in one of two places:
in a .xscreensaver file in your home directory; or in the
X resource database. If the .xscreensaver file exists, it
overrides any settings in the resource database.
The syntax of the .xscreensaver file is similar to that of
the .Xdefaults file; for example, to set the timeout
paramter in the .xscreensaver file, you would write the
following:
timeout: 5
whereas, in the .Xdefaults file, you would write
xscreensaver.timeout: 5
If you change a setting in the .xscreensaver 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 blank
ing 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 tell the running xscreensaver process to re-initialize
itself, like so:
xscreensaver-command -restart
Note that if you changed the .Xdefaults file, you might
also need to run xrdb(1):
xrdb < ~/.Xdefaults
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 sys
tems 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
.xscreensaver file. (The .Xdefaults file and the app-
defaults file will never be written by xscreensaver
itself.)
timeout (class Time)
The screensaver will activate (blank the screen)
after the keyboard and mouse have been idle for
this many minutes. Default 10 minutes.
cycle (class Time)
After the screensaver has been running for this
many minutes, the currently running graphics-hack
sub-process will be killed (with SIGTERM), 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.
lock (class Boolean)
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. (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. See the ``Using XDM(1)'' section,
below.
lockTimeout (class Time)
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 -timeout 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, -lock-timeout 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.
passwdTimeout (class Time)
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.
dpmsEnabled (class Boolean)
Whether power management is enabled.
dpmsStandby (class Time)
If power management is enabled, how long until the
monitor goes solid black.
dpmsSuspend (class Time)
If power management is enabled, how long until the
monitor goes into power-saving mode.
dpmsOff (class Time)
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 man
agement; not all do. See the Power Management
section, below, for more information.
visualID (class VisualID)
Specify which X visual to use by default. (Note
carefully that this resource is called visualID,
not merely visual; if you set the visual resource
instead, things will malfunction in obscure ways
for obscure reasons.)
Legal values for the VisualID resource are:
default Use the screen's default visual (the
visual of the root window.) This is the
default.
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 inter
esting behavior when run on PseudoColor
visuals than on TrueColor.
mono Use a monochrome visual, if there is one.
gray Use a grayscale or staticgray visual, if
there is one and it has more than one
plane (that is, it's not monochrome.)
color Use the best of the color visuals, if
there are any.
GL Use the visual that is best for OpenGL
programs. (OpenGL programs have somewhat
different requirements than other X
programs.)
class where class is one of StaticGray, Static
Color, TrueColor, GrayScale, PseudoColor,
or DirectColor. Selects the deepest
visual of the given class.
number where number (decimal or hex) is inter
preted as a visual id number, as reported
by the 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 other
wise have been chosen.
Note that this option specifies only the default
visual that will be used: the visual used may be
overridden on a program-by-program basis. See the
description of the programs resource, below.
installColormap (class Boolean)
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 default-n name in the section
about the programs resource.
verbose (class Boolean)
Whether to print diagnostics. Default false.
timestamp (class Boolean)
Whether to print the time of day along with any
other diagnostic messages. Default false.
splash (class Boolean)
Whether to display a splash screen at startup.
Default true.
splashDuration (class Time)
How long the splash screen should remain visible;
default 5 seconds.
helpURL (class URL)
The splash screen has a Help button on it. When
you press it, it will display the web page indi
cated here in your web browser.
loadURL (class LoadURL)
This is the shell command used to load a URL into
your web browser. The default setting will load
it into Netscape if it is already running, other
wise, will launch a new Netscape looking at the
helpURL.
demoCommand (class DemoCommand)
This is the shell command run when the Demo button
on the splash window is pressed. It defaults to
xscreensaver-demo.
prefsCommand (class PrefsCommand)
This is the shell command run when the Prefs but
ton on the splash window is pressed. It defaults
to xscreensaver-demo -prefs.
nice (class Nice)
The sub-processes created by xscreensaver 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 nice(1)
for details.)
memoryLimit (class MemoryLimit)
The sub-processes created by xscreensaver will not
be allowed to allocate more than this much memory
(more accurately, this is the maximum size their
address space may become.) If any sub-process
tries to allocate more than this, malloc(3) will
fail, and the process will likely exit (or safely
crash) rather than going forth and hogging memory.
The assumption here is that if one of the screen
hacks is trying to use a lot of memory, then some
thing has gone wrong, and it's better to kill that
program than to overload the machine.
Default: 0, meaning "no limit." 30M is a good
choice on most systems. (But beware that setting
this to a small value can cause OpenGL programs to
malfunction on certain systems.)
fade (class Boolean)
If this is true, then when the screensaver acti
vates, 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
cycle timer expires.) Default: true.
unfade (class Boolean)
If this is true, then when the screensaver deacti
vates, the original contents of the screen will
fade in from black instead of appearing immedi
ately. This only works on certain systems, 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 3 seconds.)
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 than the specified fadeSec_
onds if your server isn't fast enough to keep up.
Default 20.
captureStderr (class Boolean)
Whether xscreensaver 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 control
ling terminal of the screensaver driver process.
Default true.
font (class Font)
The font used for the stdout/stderr text, if cap
tureStderr is true. Default
*-medium-r-*-140-*-m-* (a 14 point fixed-width
font.)
mode (class Mode)
Controls the behavior of xscreensaver. Legal val
ues are:
random When blanking the screen, select a random
display mode from among those that are
enabled and applicable. This is the
default.
one When blanking the screen, only ever use
one particular display mode (the one indi
cated by the selected setting.)
blank When blanking the screen, just go black:
don't run any graphics hacks.
off Don't ever blank the screen, and don't
ever allow the monitor to power down.
selected (class Integer)
When mode is set to one, this is the one, indi
cated by its index in the programs list. You're
crazy if you count them and set this number by
hand: let xscreensaver-demo(1) do it for you!
programs (class Programs)
The graphics hacks which xscreensaver runs when
the user is idle. The value of this resource is a
string, one sh-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 at random, and run. After the cycle
period expires, it is killed, and another is
selected and run.
If a line begins with a dash (-) then that partic
ular program is disabled: it won't be selected at
random (though you can still select it explicitly
using the xscreensaver-demo(1) program.)
If all programs are disabled, then the screen will
just be made blank, as when mode is set to blank.
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 deletes 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 disables it, then their set
ting takes precedence.
If the display has multiple screens, then a dif
ferent program will be run for each screen. (All
screens are blanked and unblanked simultaniously.)
Note that you must escape the newlines; here is an
example of how you might set this in your
~/.xscreensaver file:
programs: \
qix -root \n\
ico -r -faces -sleep 1 -obj ico \n\
xdaliclock -builtin2 -root \n\
xv -root -rmode 5 image.gif -quit \n
Make sure your $PATH environment variable is set
up correctly before xscreensaver is launched, or
it won't be able to find the programs listed in
the programs resource.
To use a program as a screensaver, two things are
required: that that program draw on the root win
dow (or be able to be configured to draw on the
root window); and that that program understand
``virtual root'' windows, as used by virtual win
dow managers such as tvtwm(1). (Generally, this
is accomplished by just including the "vroot.h"
header file in the program's source.)
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 dis
play, you can specify that like this:
mono: mono-program -root \n\
color: color-program -root \n\
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 pro
gram works best if it has a colormap, but another
works best if it has a 24-bit visual, both can be
accommodated:
PseudoColor: cmap-program -root \n\
TrueColor: 24bit-program -root \n\
In addition to the symbolic visual names described
above (in the discussion of the visualID resource)
one other visual name is supported in the programs
list:
default-n
This is like default, but also requests the
use of the default colormap, instead of a
private colormap. (That is, it behaves as if
the -no-install command-line option was spec
ified, but only for this particular hack.)
This is provided because some third-party
programs that draw on the root window
(notably: xv(1), and xearth(1)) make assump
tions about the visual and colormap of the
root window: assumptions which xscreensaver
can violate.
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.
Normally you won't need to change the following resources:
pointerPollTime (class Time)
When server extensions are not in use, this con
trols how frequently xscreensaver checks to see if
the mouse position or buttons have changed.
Default 5 seconds.
windowCreationTimeout (class Time)
When server extensions are not in use, this con
trols the delay between when windows are created
and when xscreensaver selects events on them.
Default 30 seconds.
initialDelay (class Time)
When server extensions are not in use, xscreen_
saver 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 0. (This used to default to 30, but that
was back in the days when slow machines and X ter
minals were more common...)
sgiSaverExtension (class Boolean)
There are a number of different X server exten
sions which can make xscreensaver's job easier.
The next few resources specify whether these
extensions should be utilized if they are avail
able.
This resource controls whether the SGI
SCREEN_SAVER server extension will be used to
decide whether the user is idle. This is the
default if xscreensaver has been compiled with
support for this extension (which is the default
on SGI systems.). If it is available, the
SCREEN_SAVER method is faster and more reliable
than what will be done otherwise, so use it if you
can. (This extension is only available on Silicon
Graphics systems, unfortunately.)
mitSaverExtension (class Boolean)
This resource controls whether the
MIT-SCREEN-SAVER server extension will be used to
decide whether the user is idle. However, the
default for this resource is false, because even
if this extension is available, it is flaky (and
it also makes the fade option not work properly.)
Use of this extension is not recommended.
xidleExtension (class Boolean)
This resource controls whether the XIDLE server
extension will be used to decide whether the user
is idle. This is the default if xscreensaver has
been compiled with support for this extension.
(This extension is only available for X11R4 and
X11R5 systems, unfortunately.)
procInterrupts (class Boolean)
This resource controls whether the /proc/inter
rupts file should be consulted to decide whether
the user is idle. This is the default if xscreen_
saver has been compiled on a system which supports
this mechanism (i.e., Linux systems.)
The benefit to doing this is that xscreensaver can
note that the user is active even when the X con
sole is not the active one: if the user is typing
in another virtual console, xscreensaver will
notice that and will fail to activate. For exam
ple, if you're playing Quake in VGA-mode, xscreen
saver won't wake up in the middle of your game and
start competing for CPU.
The drawback to doing this is that perhaps you
really do 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.
overlayStderr (class Boolean)
If captureStderr 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.)
overlayTextForeground (class Foreground)
The foreground color used for the stdout/stderr
text, if captureStderr is true. Default: Yellow.
overlayTextBackground (class Background)
The background color used for the stdout/stderr
text, if captureStderr is true. Default: Black.
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.
COMMAND-LINE OPTIONS
xscreensaver also accepts a few command-line options,
mostly for use when debugging: for normal operation, you
should configure things via the ~/.xscreensaver file.
-display host:display.screen
The X display to use. For displays with multiple
screens, XScreenSaver will manage all screens on
the display simultaniously.
-verbose
Same as setting the verbose resource to true:
print diagnostics on stderr and on the
xscreensaver window.
-no-capture-stderr
Same as setting the captureStderr resource to
false: 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.
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 subse
quently-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 win
dows are unmapped, and the running subprocesses are killed
by sending them SIGTERM. This is also how the subpro
cesses 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 receive. (This is so that if you start
xscreensaver with a -display argument, the programs which
xscreensaver launches will draw on the same display; and
so that the child will end up drawing on the appropriate
screen of a multi-headed 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 run
ning 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.)
POWER MANAGEMENT
Modern X servers contain support to power down the monitor
after an idle period. If the monitor has powered down,
then xscreensaver 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.
As of version 3.28, the ~/.xscreensaver file controls the
configuration of your display's power management settings:
if you have used xset(1) to change your power management
settings, then xscreensaver will override those changes
with the values specified in ~/.xscreensaver (or with its
built-in defaults, if there is no ~/.xscreensaver file
yet.)
To change your power management settings, run
xscreensaver-demo(1) and change the various timeouts
through the user interface. Alternately, you can edit the
~/.xscreensaver file directly.
If the power management section is grayed out in the
xscreensaver-demo(1) window, then that means that your X
server does not support the XDPMS extension, and so con
trol 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 typi
cally adjust the power-saving delays only by changing set
tings 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 /etc/X11/XF86Config file.
See the XF86Config(5) manual for details.
USING XDM(1)
You can run xscreensaver from your xdm(1) session, so that
the screensaver will run even when nobody is logged in on
the console.
The trick to using xscreensaver with xdm is this: keep in
mind the two very different states in which xscreensaver
will be running:
1: Nobody logged in.
If you're thinking of running xscreensaver from XDM
at all, then it's probably because you want graph
ics demos to be running on the console when nobody
is logged in there. In this case, xscreensaver
will function only as a screen saver, not a screen
locker: it doesn't make sense for xscreensaver to
lock the screen, since nobody is logged in yet!
The only thing on the screen is the XDM login
prompt.
2: Somebody logged in.
Once someone has logged in through the XDM login
window, the situation is very different. For exam
ple: now it makes sense to lock the screen (and
prompt for the logged in user's password); and now
xscreensaver should consult that user's ~/.xscreen_
saver file; and so on.
The difference between these two states comes down to a
question of, which user is the xscreensaver process run
ning as? For the first state, it doesn't matter. If you
start xscreensaver in the usual XDM way, then xscreensaver
will probably end up running as root, which is fine for
the first case (the ``nobody logged in'' case.)
However, once someone is logged in, running as root is no
longer fine: because xscreensaver will be consulting
root's .xscreensaver file instead of that of the logged in
user, and won't be prompting for the logged in user's
password, and so on. (This is not a security problem,
it's just not what you want.)
So, once someone has logged in, you want xscreensaver to
be running as that user. The way to accomplish this is to
kill the old xscreensaver process and start a new one (as
the new user.)
The simplest way to accomplish all of this is as follows:
1: Launch xscreensaver before anyone logs in.
To the file /usr/lib/X11/xdm/Xsetup, add the lines
xhost +localhost
xscreensaver-command -exit
xscreensaver &
This will run xscreensaver as root, over the XDM
login window. Moving the mouse will cause the
screen to un-blank, and allow the user to type
their password at XDM to log in.
2: Restart xscreensaver when someone logs in.
Near the top of the file /usr/lib/X11/xdm/Xsession,
add those same lines:
xscreensaver-command -exit
xscreensaver &
When someone logs in, this will kill off the exist
ing (root) xscreensaver process, and start a new
one, running as the user who has just logged in.
If the user's .xscreensaver file requests locking,
they'll get it. They will also get their own
choice of timeouts, and graphics demos, and so on.
Alternately, each user could just put those lines
in their personal ~/.xsession files.
Make sure you have $PATH set up correctly in the Xsetup
and Xsession scripts, or xdm won't be able to find
xscreensaver, and/or xscreensaver won't be able to find
its graphics demos.
(If your system does not seem to be executing the Xsetup
file, you may need to configure it to do so: the tradi
tional way to do this is to make that file the value of
the DisplayManager*setup resource in the
/usr/lib/X11/xdm/xdm-config file. See the man page for
xdm(1) for more details.)
It is safe to run xscreensaver as root (as xdm is likely
to do.) If run as root, xscreensaver changes its effec
tive user and group ids to something safe (like "nobody")
before connecting to the X server or launching user-speci
fied 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
xscreensaver from xdm, then this probably means that you
have xauth(1) or some other security mechanism turned on.
One way around this is to add "xhost +localhost" to
Xsetup, just before xscreensaver is launched.
Note that this will give access to the X server to anyone
capable of logging in to the local machine, so in some
environments, this might not be appropriate. If turning
off file-system-based access control is not acceptable,
then running xscreensaver from the Xsetup file might not
be possible, and xscreensaver will only work when running
as a normal, unprivileged user.
For more information on the X server's access control
mechanisms, see the man pages for X(1), Xsecurity(1),
xauth(1), and xhost(1).
USING GDM(1)
Using xscreensaver with gdm(1) is easy, because gdm has a
configuration tool. Just fire up gdmconfig(1) and on the
Background page, type "xscreensaver -nosplash" into the
Background Program 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.)
In this situation, the xscreensaver process will probably
be running as user gdm instead of root. You can configure
the settings for this nobody-logged-in state (timeouts,
DPMS, etc.) by editing the ~gdm/.xscreensaver file.
USING CDE (COMMON DESKTOP ENVIRONMENT)
The easiest way to use xscreensaver on a system with CDE
is to simply switch off the built-in CDE screensaver, and
use xscreensaver instead; and second, to tell the front
panel to run xscreensaver-command(1) with the -lock option
when the Lock icon is clicked.
To accomplish this involves five steps:
1: Switch off CDE's locker
Do this by turning off ``Screen Saver and Screen
Lock'' in the Screen section of the Style Manager.
2: Edit sessionetc
Edit the file ~/.dt/sessions/sessionetc and add to
it the line
xscreensaver &
And make sure the sessionetc file is executable.
This will cause xscreensaver to be launched when
you log in. (As always, make sure that xscreen
saver and the graphics demos are on your $PATH; the
path needs to be set in .cshrc and/or .dtprofile,
not .login.)
3: Create XScreenSaver.dt
Create a file called ~/.dt/types/XScreenSaver.dt
with the following contents:
ACTION XScreenSaver
{
LABEL XScreenSaver
TYPE COMMAND
EXEC_STRING xscreensaver-command -lock
ICON Dtkey
WINDOW_TYPE NO_STDIO
}
This defines a ``lock'' command for the CDE front
panel, that knows how to talk to xscreensaver.
4: Create Lock.fp
Create a file called ~/.dt/types/Lock.fp with the
following contents:
CONTROL Lock
{
TYPE icon
CONTAINER_NAME Switch
CONTAINER_TYPE SWITCH
POSITION_HINTS 1
ICON Fplock
LABEL Lock
PUSH_ACTION XScreenSaver
HELP_TOPIC FPOnItemLock
HELP_VOLUME FPanel
}
This associates the CDE front panel ``Lock'' icon
with the lock command we just defined in step 3.
5: Restart
Select ``Restart Workspace Manager'' from the popup
menu to make your changes take effect. If things
seem not to be working, check the file ~/.dt/error_
log for error messages.
USING HP VUE (VISUAL USER ENVIRONMENT)
Since CDE is a descendant of VUE, the instructions for
using xscreensaver under VUE are similar to the above:
1: Switch off VUE's locker
Open the ``Style Manager'' and select ``Screen.''
Turn off ``Screen Saver and Screen Lock'' option.
2: Make sure you have a Session
Next, go to the Style Manager's, ``Startup'' page.
Click on ``Set Home Session'' to create a session,
then on ``Return to Home Session'' to select this
session each time you log in.
3: Edit vue.session
Edit the file ~/.vue/sessions/home/vue.session and
add to it the line
vuesmcmd -screen 0 -cmd "xscreensaver"
This will cause xscreensaver to be launched when
you log in. (As always, make sure that xscreen
saver and the graphics demos are on your $PATH; the
path needs to be set in .cshrc and/or .profile, not
.login.)
3: Edit vuewmrc
Edit the file ~/.vue/vuewmrc and add (or change)
the Lock control:
CONTROL Lock
{
TYPE button
IMAGE lock
PUSH_ACTION f.exec "xscreensaver-command -lock"
HELP_TOPIC FPLock
}
This associates the VUE front panel ``Lock'' icon
with the xscreensaver lock command.
USING KDE (K DESKTOP ENVIRONMENT)
I understand that KDE has invented their own wrapper
around xscreensaver, that is inferior to xscreensaver-
demo(1) in any number of ways. I've never actually seen
it. Presumably, there is some way to turn off KDE's
screensaver framework, and make it so that the usual
xscreensaver-demo(1) and xscreensaver-command(1) mecha
nisms are used, in a similar way to how one can reconfig
ure CDE and VUE environments, above.
But I don't know how. If you do, please let me know, and
I'll document it here.
ADDING TO MENUS
The xscreensaver-command(1) program is a perfect candidate
for something to add to your window manager's popup menus.
If you use mwm(1), 4Dwm(1), twm(1), or (probably) any of
twm's many descendants, you can do it like this:
1. Create ~/.mwmrc (or ~/.twmrc or ...)
If you don't have a ~/.mwmrc file (or, on SGIs, a
~/.4Dwmrc file; or, with twm, a ~/.twmrc file) then
create one by making a copy of the /usr/lib/X11/sys_
tem.mwmrc file (or /usr/lib/X11/twm/system.twmrc, and
so on.)
2. Add a menu definition.
Something like this:
menu XScreenSaver
{
"Blank Screen Now" !"sleep 3; xscreensaver-command -activate"
"Lock Screen Now" !"sleep 3; xscreensaver-command -lock"
"Screen Saver Demo" !"xscreensaver-demo"
"Screen Saver Preferences" !"xscreensaver-demo -prefs"
"Reinitialize Screen Saver" !"xscreensaver-command -restart"
"Kill Screen Saver" !"xscreensaver-command -exit"
"Launch Screen Saver" !"xscreensaver &"
}
3. Add the menu
For mwm(1) and 4Dwm(1), find the section of the file
that says Menu DefaultRootMenu. For twm(1), it will
probably be menu "defops". If you add a line somewhere
in that menu definition that reads
"XScreenSaver" f.menu XScreenSaver
then this will add an XScreenSaver sub-menu to your
default root-window popup menu. Alternately, you could
just put the xscreensaver menu items directly into the
root menu.
For Fvwm2, the process is similar: first create a
~/.fvwm2rc file if you don't already have one, by making a
copy of the /etc/X11/fvwm2/system.fvwm2rc file. Then, add
a menu definition to it:
AddToMenu XScreenSaver "XScreenSaver" Title
+ "Blank Screen Now" Exec xscreensaver-command -activate
+ "Lock Screen Now" Exec xscreensaver-command -lock
+ "Screen Saver Demo" Exec xscreensaver-command -demo
+ "Screen Saver Preferences" Exec xscreensaver-command -prefs
+ "Reinitialize Screen Saver" Exec xscreensaver-command -restart
+ "Kill Screen Saver" Exec xscreensaver-command -exit
+ "Launch Screen Saver" Exec xscreensaver
+ "Run Next Demo" Exec xscreensaver-command -next
+ "Run Previous Demo" Exec xscreensaver-command -prev
# To put the XScreenSaver sub-menu at the end of the root menu:
AddToMenu RootMenu "XScreenSaver" Popup XScreenSaver
The Enlightenment window manager keeps each of its menus
in a separate file. So, you need to create a file named
~/.enlightenment/xscreensaver.menu with the contents:
"XScreenSaver Commands"
"Blank Screen Now" NULL exec "xscreensaver-command -activate"
"Lock Screen Now" NULL exec "xscreensaver-command -lock"
"Screen Saver Demo" NULL exec "xscreensaver-command -demo"
"Screen Saver Prefs" NULL exec "xscreensaver-command -prefs"
"Reinitialize Saver" NULL exec "xscreensaver-command -restart"
"Kill Screen Saver" NULL exec "xscreensaver-command -exit"
"Launch Screen Saver" NULL exec "xscreensaver"
then add
"XScreenSaver" NULL menu "xscreensaver.menu"
to ~/.enlightenment/file.menu to put the XScreenSaver sub
menu on your left-button root-window menu.
As you see, every window manager does this stuff gratu
itously differently, just to make your life difficult.
You are in a maze of twisty menu configuration languages,
all alike.
BUGS
Bugs? There are no bugs. Ok, well, maybe. If you find
one, please let me know. http://www.jwz.org/xscreen
saver/bugs.html explains how to construct the most useful
bug reports.
Locking and XDM
If xscreensaver has been launched from xdm(1)
before anyone has logged in, you will need to kill
and then restart the xscreensaver daemon after you
have logged in, or you will be confused by the
results. (For example, locking won't work, and
your ~/.xscreensaver file will be ignored.)
When you are logged in, you want the xscreensaver
daemon to be running under your user id, not as
root or some other user.
If it has already been started by xdm, you can
kill it by sending it the exit command, and then
re-launching it as you, by putting something like
the following in your personal X startup script:
xscreensaver-command -exit
xscreensaver &
The ``Using XDM(1)'' section, above, goes into
more detail, and explains how to configure the
system to do this for all users automatically.
Locking and root logins
In order for it to be safe for xscreensaver to be
launched by xdm, certain precautions had to be
taken, among them that xscreensaver never runs as
root. In particular, if it is launched as root
(as xdm is likely to do), xscreensaver will dis
avow its privileges, and switch itself to a safe
user id (such as nobody.)
An implication of this is that if you log in as
root on the console, xscreensaver will refuse to
lock the screen (because it can't tell the differ
ence between root being logged in on the console,
and a normal user being logged in on the console
but xscreensaver having been launched by the
xdm(1) Xsetup file.)
The solution to this is simple: you shouldn't be
logging in on the console as root in the first
place! (What, are you crazy or something?)
Proper Unix hygiene dictates that you should log
in as yourself, and su(1) to root as necessary.
People who spend their day logged in as root are
just begging for disaster.
XAUTH and XDM
For xscreensaver to work when launched by xdm(1),
programs running on the local machine as user
"nobody" 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 ``Using XDM(1)'' section, above, for more
details.
If anyone has suggestions on how xscreensaver
could be made to work with xdm(1) without first
turning off .Xauthority-based access control,
please let me know.
Passwords
If you get an error message at startup like
``couldn't get password of user'' then this proba
bly means that you're on a system in which the
getpwent(3) library routine can only be effec
tively used by root. If this is the case, then
xscreensaver 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 getpwent(3)
interface; in that case, you may need to change
some options with configure 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. So, after you change your password,
you'll have to do
xscreensaver-command -restart
to make xscreensaver notice.
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 /etc/pam.d/xscreensaver for you, and on
Solaris, by telling you what lines to add to the
/etc/pam.conf file.)
If the PAM configuration files do not know about
xscreensaver, then you might 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 xscreen
saver to automatically work around this, or detect
the problem in advance, so if you have PAM, make
sure it is configured correctly!
Colormap lossage: TWM
The installColormap option doesn't work very well
with the twm(1) window manager and its descen
dants.
There is a race condition between the screensaver
and this window manager, which can result in the
screensaver's colormap not getting installed prop
erly, meaning the graphics hacks will appear in
essentially random colors. (If the screen goes
white instead of black, this is probably why.)
The mwm(1) and olwm(1) window managers don't have
this problem. The race condition exists because X
(really, ICCCM) 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
xscreensaver installs its colormap, twm responds
to the resultant ColormapNotify event by re-
instaling the default colormap. Apparently, twm
doesn't always do this; it seems to do it regu
larly 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.
Attention, window manager authors!
You should only call XInstallColormap(3) in
response to user events. That is, it is
appropriate to install a colormap in response
to FocusIn, FocusOut, EnterNotify, and
LeaveNotify events; but it is not appropriate
to call it in response to ColormapNotify
events. If you install colormaps in response
to application actions as well as in response
to user actions, then you create the situation
where it is impossible for override-redirect
applications (such as xscreensaver) to display
their windows in the proper colors.
Colormap lossage: XV, XAnim, XEarth
Some programs don't operate properly on visuals
other than the default one, or with colormaps
other than the default one. See the discussion of
the magic "default-n" visual name in the descrip
tion of the programs resource in the Configuration
section. When programs only work with the default
colormap, you need to use a syntax like this:
default-n: xv -root image-1.gif -quit \n\
default-n: xearth -nostars -wait 0 \n\
It would also work to turn off the installColormap
option altogether, but that would deny extra col
ors to those programs that can take advantage of
them.
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 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)
(or making liberal use of any -delay options which
the programs may provide.)
Note that the OpenGL-based graphics demos are real
pigs on machines that don't have texture hardware.
Also, an active screensaver 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(1) or xload(1).
Latency and Responsiveness
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.
XFree86's Magic Keystrokes
The XFree86 X server traps certain magic
keystrokes before client programs ever see them.
Two that are of note are Ctrl+Alt+Backspace, which
causes the X server to exit; and Ctrl+Alt+Fn,
which switches virtual consoles. The X server
will respond to these keystrokes even if xscreen
saver has the screen locked. Depending on your
setup, you might consider this a problem.
Unfortunately, there is no way for xscreensaver
itself to override the interpretation of these
keys. If you want to disable Ctrl+Alt+Backspace
globally, you need to set the DontZap flag in your
/etc/X11/XF86Config file. See the XF86Config(5)
manual for details.
There is no way (as far as I can tell) to disable
the VT-switching keystrokes.
Some Linux systems come with a VT_LOCKSWITCH
ioctl, that one could theoretically use to prevent
VT-switching while the screen is locked; but
unfortunately, this ioctl can only be used by
root, which means that xscreensaver can't use it
(since xscreensaver disavows its privileges
shortly after startup, for security reasons.)
Any suggestions for other solutions to this prob
lem are welcome.
XView Clients
Apparently there are some problems with XView pro
grams 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. If anyone has any
insight on the cause of this problem, please let
me know. (XView is an X11 toolkit that implements
the (quite abominable) Sun OpenLook look-and-
feel.)
MIT Extension and Fading
The MIT-SCREEN-SAVER extension is junk. Don't use
it.
When using the MIT-SCREEN-SAVER extension in con
junction with the fade option, you'll 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 a way to get around this; it
seems to be a fundamental property of the (mis-)
design of this server extension.
It sure would be nice if someone would implement
the SGI SCREEN_SAVER extension in XFree86; it's
dead simple, and works far better than the
overengineered and broken MIT-SCREEN-SAVER exten
sion.
SGI Power Saver
If you're running Irix 6.3, you might find that
your monitor is powering down after an hour or two
even if you've told it not to. This is fixed by
SGI patches 2447 and 2537.
If you're running Irix 6.5, this bug is back. I
don't know a fix.
MesaGL and Voodoo Cards
If you have a 3Dfx/Voodoo card, the default
settings for xscreensaver will run the GL-based
graphics demos in such a way that they will not
take advantage of the 3D acceleration hardware.
The solution is to change the programs entries for
the GL hacks from this:
gears -root \n\
to this:
MESA_GLX_FX=fullscreen gears \n\
That is, make sure that $MESA_GLX_FX is set to
fullscreen, and don't tell the program to draw on
the root window. This may seem strange, but the
setup used by Mesa and these kinds of cards is
strange!
For those who don't know, these cards work by sit
ting between your normal video card and the moni
tor, and seizing control of the monitor when it's
time to do 3D. But this means that accelerated 3D
only happens in full-screen mode (you can't do it
in a window, and you can't see the output of 3D
and 2D programs simultaniously), and that 3D will
probably drive your monitor at a lower resolution,
as well. It's bizarre.
This probably isn't ever necessary on more modern
cards; I'm not sure.
If you find that GL programs only work properly
when run as root, and not as normal users, then
the problem is that your /dev/3dfx file is not
configured properly. Check the Linux 3Dfx FAQ.
Keyboard LEDs
If procInterrupts is on (which is the default on
Linux systems) and you're using some program that
toggles the state of your keyboard LEDs, xscreen
saver won't work right: turning those LEDs on or
off causes a keyboard interrupt, which xscreen
saver will interpret as user activity. So if
you're using such a program, set the procInter_
rupts resource to False.
Extensions
If you are not making use of one of the server
extensions (XIDLE, SGI SCREEN_SAVER, or MIT-
SCREEN-SAVER), then it is possible, in rare situa
tions, for xscreensaver to interfere with event
propagation and make another X program malfunc
tion. 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 pro
grams 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.
In all these years, I've not heard of even a
single case of this happening, but it is theoreti
cally possible, so I'm mentioning it for complete
ness...
Red Hot Lava
There need to be a lot more graphics hacks. In
particular, there should be a simulation of a
Lavalite (tm).
ENVIRONMENT
DISPLAY to get the default host and display number, and to
inform the sub-programs of the screen on which to
draw.
PATH to find the sub-programs to run.
HOME for the directory in which to read the .xscreen_
saver file.
XENVIRONMENT
to get the name of a resource file that overrides
the global resources stored in the RESOURCE_MAN
AGER property.
UPGRADES
The latest version of xscreensaver, an online version of
this manual, and a FAQ can always be found at
http://www.jwz.org/xscreensaver/
SEE ALSOX(1), xscreensaver-demo(1), xscreensaver-command(1),
xscreensaver-gl-helper(1), xdm(1), xset(1), Xsecurity(1),
xauth(1), xhost(1). ant(1), atlantis(1), attraction(1),
blitspin(1), bouboule(1), braid(1), bsod(1), bubble3d(1),
bubbles(1), cage(1), compass(1), coral(1), critical(1),
crystal(1), cynosure(1), decayscreen(1), deco(1),
deluxe(1), demon(1), discrete(1), distort(1), drift(1),
epicycle(1), fadeplot(1), flag(1), flame(1), flow(1), for
est(1), galaxy(1), gears(1), glplanet(1), goop(1),
grav(1), greynetic(1), halo(1), helix(1), hopalong(1),
hypercube(1), ifs(1), imsmap(1), interference(1), jig
saw(1), julia(1), kaleidescope(1), kumppa(1), lament(1),
laser(1), lightning(1), lisa(1), lissie(1), lmorph(1),
loop(1), maze(1), moebius(1), moire(1), moire2(1),
morph3d(1), mountain(1), munch(1), noseguy(1), pedal(1),
penetrate(1), penrose(1), petri(1), phosphor(1), pipes(1),
pulsar(1), pyro(1), qix(1), rd-bomb(1), rocks(1),
rorschach(1), rotor(1), rubik(1), sierpinski(1),
slidescreen(1), slip(1), sonar(1), sphere(1), spiral(1),
spotlight(1), sproingies(1), squiral(1), stairs(1),
starfish(1), strange(1), superquadrics(1), swirl(1),
t3d(1), triangle(1), truchet(1), vines(1), wander(1),
worm(1), xflame(1), xjack(1), xlyap(1), xmatrix(1),
bongo(1), ico(1), xaos(1), xbouncebits(1), xcthugha(1),
xdaliclock(1), xfishtank(1), xmountains(1), xsplinefun(1),
xswarm(1), xtacy(1), xv(1), chbg(1), xwave(1).
COPYRIGHT
Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997,
1998, 1999, 2000, 2001, 2002 by Jamie Zawinski. Permis
sion to use, copy, modify, distribute, and sell this soft
ware 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 pro
vided "as is" without express or implied warranty.
AUTHOR
Jamie Zawinski <jwz@jwz.org>. Written in late 1991; ver
sion 1.0 posted to comp.sources.x on 17-Aug-1992.
Please let me know if you find any bugs or make any
improvements.
ACKNOWLEDGEMENTS
Thanks to Angela Goodman for the XScreenSaver logo.
Thanks to the many people who have contributed graphics
demos to the package.
Thanks to David Wojtowicz for implementing lockTimeout.
Thanks to Martin Kraemer for adding support for shadow
passwords and locking-disabled diagnostics.
Thanks to Patrick Moreau for the VMS port.
Thanks to Mark Bowyer for figuring out how to hook it up
to CDE.
Thanks to Nat Lanza for the Kerberos support.
Thanks to Bill Nottingham for the initial PAM support.
And thanks to Jon A. Christopher for implementing the
Athena dialog support, back in the days before Lesstif or
Gtk were viable alternatives to Motif.
X Version 11 24-Feb-2002 (4.01) XScreenSaver(1)
