-1 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]
-2 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.
-
-2 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 xscreencommand (1) program.
-
-2 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.
-
-2 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 xscreencommand (1)
-program (which see.)
-
-2 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.
-
-2 USING_XDM
-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.
-
-2 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 xscreencommand (1)
-except that when executed from this button, the screensaver will
-automatically return to demo mode after restarting.
-
-2 SEE_ALSO
- xscreencommand (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)
-
-2 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 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.
-
-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.
-
-2 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
-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.
-
-2 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.
-
-2 VMS_PORT
-
-Patrick MOREAU - CENA/Athis-Mons - FRANCE (pmoreau@cena.dgac.fr)