XScreenSaver(1)

NAME
xscreensaver - run graphics hacks after the user has been idle for a while

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] [-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
    Use the XIdle server extension to decide whether the user is idle. This is the default if xscreensaver 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.

-no-xidle
    Don't use XIdle.

-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.

-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)
    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.

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.

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 file:
        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.

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), hypercube(1), flame(1), maze(1), ico(1), xdaliclock(1), xbouncebits(1), xswarm(1), xwave(1), xfishtank(1)

BUGS
If you are not using XIdle, and an application does not select KeyPress events on its non-leaf windows within the first 30 seconds of their existence, but selects them later, then it is possible that xscreensaver 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 XIdle extension.

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 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.)

If you don't have Motif, you can't compile with support for locking or demo mode.

When the Run Next and Run Previous 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.

Locking doesn't work if the screensaver is launched by xdm.

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.

There need to be a lot more graphics hacks. In particular, there should be a simulation of a Lavalite (tm).

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...

The installColormap 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.

For this same reason, locking doesn't work too well along with installColormap; the dialog box's colors are random.

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.

COPYRIGHT
Copyright © 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.

AUTHOR
Jamie Zawinski <jwz@lucid.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.