2 Run graphics hacks after the user has been idle for a while
6 $ xscreensaver [-display host:display.screen] [-timeout int]
7 [-cycle int] [-nice int] [-verbose] [-silent]
8 [-xidle] [-no-xidle] [-lock] [-no-lock] [-lock-timeout int]
9 [-demo] [-visual visual] [-xrm resources]
11 The xscreensaver program waits until the keyboard and mouse have been
12 idle for a period, and then runs a graphics demo chosen at random. It
13 turns off as soon as there is any mouse or keyboard activity.
15 This program can lock your terminal in order to prevent others from using it,
16 though its default mode of operation is merely to display pretty pictures on
17 your screen when it is not in use.
19 The benefit that this program has over the combination of the xlock (1)
20 and xautolock (1) programs is the ease with which new graphics hacks can be
21 installed. You don't need to recompile (or even re-run) this program to add
25 xscreensaver accepts the following options:
28 The screensaver will activate after the keyboard and mouse have been idle
29 for this many minutes.
32 After the screensaver has been running for this many minutes, the currently
33 running sub-process will be killed (with SIGTERM), and a new one
34 started. If this is 0, then the sub-process will not be killed; only one
35 demo will run until the screensaver is deactivated by user activity.
38 The sub-processes created by xscreensaver will be ``niced'' to this
39 level, so that they do not consume cycles that are needed elsewhere.
48 Use the XIdle server extension to decide whether the user is idle.
49 This is the default if xscreensaver has been compiled with support
50 for XIdle. The XIdle method is faster and more reliable than what will
51 be done otherwise, so use it if you can.
57 Enable locking: before the screensaver will turn off, it requires you to
58 type the password of the person who launched the screensaver, or the root
59 password. (Note: this doesn't work if the screensaver is launched
60 by xdm (1) because it can't know the user-id of the logged-in user.)
63 Disable locking. This is the default.
66 This is how long after the screensaver activates that locking is enabled.
67 For example, if this is 5, then any user activity within five minutes of
68 the time when the screensaver activated will cause the screen to unblank
69 without requiring a password. After 5 minutes, a password will be
70 required. The default is 0, meaning that if locking is enabled, then
71 a password will be required as soon as the screensaver activates.
74 Specify which visual to use. Legal values are:
77 Use the visual which supports the most writable color cells; this is
81 Use the screen's default visual (the visual of the root window.) This is
82 not necessarily the most colorful visual, which is why it is not the default.
85 One of StaticGray, StaticColor, TrueColor, GrayScale,
86 PseudoColor, or DirectColor. Selects the deepest visual of
90 A number (decimal or hex) is interpreted as a visual id number, as reported
91 by the xdpyinfo (1) program; in this way you can select a shallower visual
95 Enter the interactive demo mode immediately after startup. Normally
96 demo mode is invoked via the xscreencommand (1) program.
99 xscreensaver understands the following resources:
102 Same as the -timeout command-line option. Default 10 minutes.
105 Same as the -cycle command-line option. Default 10 minutes.
108 Same as the -nice command-line option. Default 10.
110 verbose (class Boolean)
111 Same as the -verbose command-line option.
113 xidle (class Boolean)
114 Same as the -xidle command-line option.
117 Same as the -lock command-line option.
119 lockTimeout (class Time)
120 Same as the -lock-timeout command-line option.
123 If this is true, then when the screensaver activates, the current contents
124 of the screen will fade to black instead of simply winking out. This only
125 works on displays with writable colormaps. Default true. A fade will also
126 be done when switching graphics hacks (when the cycle timer expires.)
128 unfade (class Boolean)
129 If this is true, then when the screensaver deactivates, the original contents
130 of the screen will fade in from black instead of appearing immediately. This
131 only works on displays with writable colormaps, and if fade is true
132 as well. Default false.
134 fadeSeconds (class Time)
135 If fade is true, this is how long the fade will be in seconds (default 1.)
137 fadeTicks (class Integer)
138 If fade is true, this is how many times a second the colormap will
139 be changed to effect a fade. Higher numbers yield smoother fades, but
140 may make the fades take longer if your server isn't fast enough to keep
143 installColormap (class Boolean)
144 Whether a new colormap should be installed while the screensaver is on,
145 so that the graphics hacks can get as many colors as possible. Default
148 passwdTimeout (class Time)
149 If lock is true, this is how many seconds the password dialog box
150 should be left on the screen before giving up (default 30.) This should
151 not be too large: the X server is grabbed for the duration that the password
152 dialog box is up (for security purposes) and leaving the server grabbed for
153 too long can cause problems.
155 visualID (class VisualID)
156 Same as the -visual command-line option. Default best.
159 programs (class Programs)
160 The graphics hacks which xscreensaver runs when the user is idle.
161 The value of this resource is a string, one sh command per line.
162 Each line must contain exactly one command -- no semicolons.
164 When the screensaver starts up, one of these is selected at random, and
165 run. After the cycle period expires, it is killed, and another
168 If the value of this resource (and the applicable one of colorPrograms
169 or monoPrograms) is empty, then no programs will be run; the screen
170 will simply be made black.
172 Note that you must escape the newlines; here is an example of how you
173 might set this in your .Xdefaults file:
175 xscreensaver.programs: \\
177 ico -r -faces -sleep 1 -obj ico \\n\\
178 xdaliclock -builtin2 -root \\n\\
181 To use a program as a screensaver, two things are required: that that
182 program draw on the root window (or be able to be configured to draw on
183 the root window); and that that program understand ``virtual root''
184 windows, as used by virtual window managers such as tvtwm.
186 It is quite easy to make programs understand virtual roots if they
187 don't already: you merely need to include the file "vroot.h" in
188 them after the standard X includes, and recompile. This file is distributed
189 with X11r5, and is included with xscreensaver as well.
191 monoPrograms (class MonoPrograms)
192 This resource is appended to the value of the programs resource if
193 the display on which the screensaver is running is monochrome.
195 colorPrograms (class ColorPrograms)
196 This resource is appended to the value of the programs resource if
197 the display on which the screensaver is running is not monochrome.
199 Normally you won't need to change the following resources:
201 bourneShell (class BourneShell)
202 The pathname of the shell that xscreensaver uses to start subprocesses.
203 This must be whatever your local variant of /bin/sh is -- in particular,
206 windowCreationTimeout (class Time)
207 When XIdle is not in use, this controls the delay between when
208 windows are created and when xscreensaver selects events on them.
211 pointerPollTime (class Time)
212 When XIdle is not in use, this controls how frequently xscreensaver
213 checks to see if the mouse position or buttons have changed. Default 5 seconds.
215 initialDelay (class Time)
216 When XIdle is not in use, xscreensaver will wait this many seconds
217 before selecting events on existing windows, under the assumption that
218 xscreensaver is started during your login procedure, and the window
219 state may be in flux. Default 30 seconds.
222 When it is time to activate the screensaver, a full-screen black window is
223 created. This window is given the appropriate properties so that, to any
224 subsequently-created programs, it will appear to be a ``virtual root''
225 window. Because of this, any program which draws on the root window (and
226 which understands virtual roots) can be used as a screensaver.
228 When the user becomes active again, the screensaver window is unmapped and
229 the running subprocess is killed by sending it SIGTERM. This is also
230 how the subprocesses are killed when the screensaver decides that it's time
231 to run a different demo: the old one is killed and a new one is launched.
233 Before launching a subprocess, xscreensaver stores an appropriate value
234 for $DISPLAY in the environment that the child will recieve. (This is
235 so that if you start xscreensaver with a -display argument, the
236 programs which xscreensaver launches will draw on the same display.)
238 When the screensaver turns off, or is killed, care is taken to restore
239 the ``real'' virtual root window if there is one. Because of this, it is
240 important that you not kill the screensaver process with kill -9 if
241 you are running a virtual-root window manager. If you kill it with -9,
242 you may need to restart your window manager to repair the damage. This
243 isn't an issue if you aren't running a virtual-root window manager.
245 For all the gory details, see the commentary at the top of xscreensaver.c.
247 You can control a running screensaver process by using the xscreencommand (1)
253 to get the default host and display number.
256 to get the name of a resource file that overrides the global resources
257 stored in the RESOURCE_MANAGER property.
260 You can run xscreensaver from your xdm session, so that the
261 screensaver will run even when nobody is logged in on the console.
262 Simply add "xscreensaver &" to your /usr/lib/X11/xdm/Xsetup
263 file. Because xdm grabs the keyboard, keypresses will not make
264 the screensaver deactivate, but any mouse activity will.
266 Users may want to add "xscreensaver-command -restart" to their
267 startup scripts, so that the screensaver will be reinitialized with
268 their private resource settings when they log in.
270 It is safe to run this program as root (as xdm is likely to do.) If
271 run as root, xscreensaver changes its effective user and group ids to
272 something safe (like "nobody") before connecting to the X server
273 or launching user-specified programs.
275 Locking doesn't work if the screensaver is launched by xdm. To get
276 around this, you can run the screensaver from xdm without locking,
277 and kill and restart it from your personal X startup script to enable
281 If xscreensaver receives the DEMO ClientMessage, it pops up
282 a dialog box from which you can examine and experiment with the screensaver's
285 Clicking left on an element in the scrolling list will place the indicated
286 program and its args in the text field to be edited. Edit the arguments and
287 hit return to run the program with the parameters you have specified.
289 Double-clicking on an element in the scrolling list will run the indicated
292 When a client program is launched, the dialog box is hidden. Clicking
293 any mouse button will re-expose the dialog box (but will not kill the
297 Clicking this button will run the next program in the list after the
298 currently-selected one, and will scroll around to the top when it reaches
302 Opposite of Run Next; at the top, it scrolls around to the bottom.
305 This pops up a second dialog box, in which you have the option to
306 interactively change most of the screensaver's operational parameters,
307 such as its timeouts, and whether it should hack colormaps. Changing
308 these parameters here will affect only the running xscreensaver
309 process; to make the changes permanent, you need to edit your X resource
313 Returns to normal screensaver operation.
316 Causes the screensaver process to exit and then restart with the same
317 command-line arguments. This causes the X resource database to be
318 re-read. This is just like the -restart argument to xscreencommand (1)
319 except that when executed from this button, the screensaver will
320 automatically return to demo mode after restarting.
351 If you are not using XIdle, and an application does not
352 select KeyPress events on its non-leaf windows within the first
353 30 seconds of their existence, but selects them later, then it is
354 possible that xscreensaver could interfere with the propagation
355 of those events. This isn't very likely, but this is the reason that
356 it's a good idea to install the XIdle extension.
358 Although this program ``nices'' the subprocesses that it starts,
359 graphics-intensive subprograms can still overload the machine by causing
360 the X server process itself (which is not ``niced'') to suck a lot of
361 cycles. Care should be taken to slow down programs intended for use as
362 screensavers by inserting strategic calls to
363 sleep (3) or usleep (3).
365 Also, it will cause your X server to be pretty much permanently swapped in.
366 (but the same is true of any program that draws periodically, like xclock or
369 If the subprocess is drawing too quickly and the connection to the X
370 server is a slow one (such as an X terminal running over a phone line) then
371 the screensaver might not turn off right away when the user becomes active
372 again (the ico (1) demo has this problem if being run in full-speed mode).
373 This can be alleviated by inserting strategic calls to XSync (3)
374 in code intended for use as a screensaver. This prevents too much graphics
375 activity from being buffered up.
377 The screensaver only runs on the default screen of the display. If you have
378 more than one screen, you can run multiple screensaver processes, one for
379 each screen. This interacts poorly with locking. In an ideal world, the
380 screensaver would save (and lock) both screens simultaniously, and any activity
381 would restore both screens. It would be nice if one could run different hacks
382 on each screen simultaniously. However, I don't have access to a multi-headed
383 workstation, so it would be hard for me to implement something like this.
385 If you don't have Motif, you can't compile with support for locking or
388 When the Run Next and Run Previous buttons are used, the selected
389 item may not be visible in the window. It's a Motif bug that selecting a
390 different item doesn't scroll the list to show the new selected item.
392 Locking doesn't work if the screensaver is launched by xdm.
394 If you get an error message like ``couldn't get password of foo'' then
395 this probably means that you're on a system in which the getpwent (3)
396 library routine can only be effectively used by root. If this is the case,
397 then xscreensaver must be installed as setuid to root. Care has
398 been taken to make this a safe thing to do.
400 There need to be a lot more graphics hacks. In particular, there should be
401 a simulation of a Lavalite (tm).
403 The installColormap option doesn't work very well with the twm (1)
404 window manager and its descendants. There is a race condition between the
405 screensaver and this window manager, which can result in the screensaver's
406 colormap not getting installed properly, meaning the graphics hacks will
407 appear in essentially random colors. The mwm (1) and olwm (1)
408 window managers don't seem to have this problem. The race condition exists
409 because X apparently does not provide a way for an OverrideRedirect window to
410 have its own colormap, short of grabbing the server (which is neither a good
411 idea, nor really possible with the current design.) What happens is that, as
412 soon as the screensaver installs its colormap, twm responds to
413 the ColormapNotify event that is generated by re-instaling the default
414 colormap. Apparently, twm doesn't always do this; it seems to do
415 it regularly if the screensaver is activated from a menu item, but seems to
416 not do it if the screensaver comes on of its own volition, or is activated
417 from another console. Any thoughts on this problem are welcome...
419 The installColormap option has no effect in "demo" mode, since the
420 dialog boxes allocate their colors out of the screen's default colormap
421 instead of the installed colormap.
423 For this same reason, locking doesn't work too well along
424 with installColormap; the dialog box's colors are random.
426 Apparently there are some problems with ``XView'' programs getting confused
427 and thinking that the screensaver window is the real root window even when
428 the screensaver is not active: ClientMessages intended for the window manager
429 are sent to the screensaver window instead. This could be solved by making
430 xscreensaver forward all unrecognised ClientMessages to the real root window,
431 but there may be other problems as well.
434 Copyright (co 1992, 1993, 1994 by Jamie Zawinski. Permission to use, copy,
435 modify, distribute, and sell this software and its documentation for any
436 purpose is hereby granted without fee, provided that the above copyright
437 notice appear in all copies and that both that copyright notice and this
438 permission notice appear in supporting documentation. No representations are
439 made about the suitability of this software for any purpose. It is provided
440 "as is" without express or implied warranty.
443 Jamie Zawinski <jwz@mcom.com>, 13-aug-92.
444 Please let me know if you find any bugs or make any improvements.
446 Thanks to David Wojtowicz for implementing lockTimeout.
448 Thanks to Martin Kraemer for adding support for shadow passwords and
449 locking-disabled diagnostics.
453 Patrick MOREAU - CENA/Athis-Mons - FRANCE (pmoreau@cena.dgac.fr)