14 .TH XScreenSaver 1 "16-Nov-98 (3.04)" "X Version 11"
16 xscreensaver - graphics hack and screen locker, launched when the user is idle
19 [\-display \fIhost:display.screen\fP] \
20 [\-timeout \fIint\fP] \
24 [\-lock\-timeout \fIint\fP] \
25 [\-visual \fIvisual\fP] \
32 [\-no\-capture\-stderr] \
37 [\-no\-mit\-extension] \
39 [\-no\-sgi\-extension] \
40 [\-xidle\-extension] \
41 [\-no\-xidle\-extension] \
42 [\-xrm \fIresources\fP]
44 The \fIxscreensaver\fP program waits until the keyboard and mouse have been
45 idle for a period, and then runs a graphics demo chosen at random. It
46 turns off as soon as there is any mouse or keyboard activity.
48 This program can lock your terminal in order to prevent others from using it,
49 though its default mode of operation is merely to display pretty pictures on
50 your screen when it is not in use.
52 The benefit that this program has over the combination of the
56 programs is the ease with which new graphics hacks can be installed. You
57 don't need to recompile (or even re-run) this program to add a new display
60 For the impatient, try this:
66 .BR xscreensaver-demo (1)
67 program should pop up a dialog box that lets you experiment with the
68 xscreensaver settings and graphics modes.
73 xscreensaver has a client-server model: the \fIxscreensaver\fP program is a
74 daemon that runs in the background; it is controlled by the foreground
75 .BR xscreensaver-demo (1)
77 .BR xscreensaver-command (1)
80 Options to \fIxscreensaver\fP are specified in one of two places: in
81 a \fI.xscreensaver\fP file in your home directory; or in the X resource
82 database. If the \fI.xscreensaver\fP file exists, it overrides any settings
83 in the resource database.
85 The syntax of the \fI.xscreensaver\fP file is similar to that of
86 the \fI.Xdefaults\fP file; for example, to set the \fItimeout\fP paramter
87 in the \fI.xscreensaver\fP file, you would write the following:
91 whereas, in the \fI.Xdefaults\fP file, you would write
93 xscreensaver.timeout: 5
95 If you change a setting in the \fI.xscreensaver\fP file while xscreensaver
96 is already running, it will notice this, and reload the file. (The file will
97 be reloaded the next time the screen saver needs to take some action, such as
98 blanking or unblanking the screen, or picking a new graphics mode.)
100 If you change a setting in your X resource database, or if you want
101 xscreensaver to notice your changes immediately instead of the next time
102 it wakes up, then you will need to tell the running xscreensaver process
103 to re-initialize itself, like so:
105 xscreensaver-command -restart
107 Note that if you changed the \fI.Xdefaults\fP file, you might also need to run
112 If you want to set the system-wide defaults, then make your edits to
113 the xscreensaver app-defaults file, which should have been installed
114 when xscreensaver itself was installed. The app-defaults file will
115 usually be named /usr/lib/X11/app-defaults/XScreenSaver, but different
116 systems might keep it in a different place (for example,
117 /usr/openwin/lib/app-defaults/XScreenSaver on Solaris.)
119 When settings are changed in the Preferences dialog box (see above)
120 the current settings will be written to the \fI.xscreensaver\fP file.
121 (The \fI.Xdefaults\fP file and the app-defaults file will never be
122 written by xscreensaver itself.)
125 .B timeout\fP (class \fBTime\fP)
126 The screensaver will activate (blank the screen) after the keyboard and
127 mouse have been idle for this many minutes. Default 10 minutes.
129 .B cycle\fP (class \fBTime\fP)
130 After the screensaver has been running for this many minutes, the currently
131 running graphics-hack sub-process will be killed (with \fBSIGTERM\fP), and a
132 new one started. If this is 0, then the graphics hack will never be changed:
133 only one demo will run until the screensaver is deactivated by user activity.
136 .B lock\fP (class \fBBoolean\fP)
137 Enable locking: before the screensaver will turn off, it will require you
138 to type the password of the logged-in user (really, the person who ran
139 xscreensaver), or the root password. (\fBNote:\fP this doesn't work if the
140 screensaver is launched by
142 because it can't know the user-id of the logged-in user. See
143 the ``\fIUsing XDM(1)\fP'' section, below.
145 .B lockTimeout\fP (class \fBTime\fP)
146 If locking is enabled, this controls the length of the ``grace period''
147 between when the screensaver activates, and when the screen becomes locked.
148 For example, if this is 5, and \fI\-timeout\fP is 10, then after 10 minutes,
149 the screen would blank. If there was user activity at 12 minutes, no password
150 would be required to un-blank the screen. But, if there was user activity
151 at 15 minutes or later (that is, \fI\-lock\-timeout\fP minutes after
152 activation) then a password would be required. The default is 0, meaning
153 that if locking is enabled, then a password will be required as soon as the
156 .B passwdTimeout\fP (class \fBTime\fP)
157 If the screen is locked, then this is how many seconds the password dialog box
158 should be left on the screen before giving up (default 30 seconds.) This
159 should not be too large: the X server is grabbed for the duration that the
160 password dialog box is up (for security purposes) and leaving the server
161 grabbed for too long can cause problems.
163 .B visualID\fP (class \fBVisualID\fP)
164 Specify which X visual to use by default. (Note carefully that this resource
165 is called \fBvisualID\fP, not merely \fBvisual\fP; if you set the \fBvisual\fP
166 resource instead, things will malfunction in obscure ways for obscure reasons.)
168 Legal values for the \fBVisualID\fP resource are:
172 Use the screen's default visual (the visual of the root window.)
176 Use the visual which supports the most colors. Note, however, that the
177 visual with the most colors might be a TrueColor visual, which does not
178 support colormap animation. Some programs have more interesting behavior
179 when run on PseudoColor visuals than on TrueColor.
182 Use a monochrome visual, if there is one.
185 Use a grayscale or staticgray visual, if there is one and it has more than
186 one plane (that is, it's not monochrome.)
189 Use the best of the color visuals, if there are any.
192 where \fIclass\fP is one of \fBStaticGray\fP, \fBStaticColor\fP,
193 \fBTrueColor\fP, \fBGrayScale\fP, \fBPseudoColor\fP, or \fBDirectColor\fP.
194 Selects the deepest visual of the given class.
197 where \fInumber\fP (decimal or hex) is interpreted as a visual id number,
200 program; in this way you can have finer control over exactly which visual
201 gets used, for example, to select a shallower one than would otherwise
206 Note that this option specifies only the \fIdefault\fP visual that will
207 be used: the visual used may be overridden on a program-by-program basis.
208 See the description of the \fBprograms\fP resource, below.
211 .B installColormap\fP (class \fBBoolean\fP)
212 Install a private colormap while the screensaver is active, so that the
213 graphics hacks can get as many colors as possible. This is the
214 default. (This only applies when the screen's default visual is being
215 used, since non-default visuals get their own colormaps automatically.)
216 This can also be overridden on a per-hack basis: see the discussion of
217 the \fBdefault\-n\fP name in the section about the \fBprograms\fP resource.
219 .B verbose\fP (class \fBBoolean\fP)
220 Whether to print diagnostics. Default false.
222 .B timestamp\fP (class \fBBoolean\fP)
223 Whether to print the time of day along with any other diagnostic messages.
226 .B splash\fP (class \fBBoolean\fP)
227 Whether to display a splash screen at startup. Default true.
229 .B splashDuration\fP (class \fBTime\fP)
230 How long the splash screen should remain visible; default 5 seconds.
232 .B helpURL\fP (class \fBURL\fP)
233 The splash screen has a \fIHelp\fP button on it. When you press it, it will
234 display the web page indicated here in your web browser.
236 .B loadURL\fP (class \fBLoadURL\fP)
237 This is the shell command used to load a URL into your web browser.
238 The default setting will load it into Netscape if it is already running,
239 otherwise, will launch a new Netscape looking at the \fIhelpURL\fP.
241 .B demoCommand\fP (class \fBDemoCommand\fP)
242 This is the shell command run when the \fIDemo\fP button on the splash window
243 is pressed. It defaults to \fIxscreensaver\-demo\fP.
245 .B prefsCommand\fP (class \fBPrefsCommand\fP)
246 This is the shell command run when the \fIPrefs\fP button on the splash window
247 is pressed. It defaults to \fIxscreensaver\-demo\ \-prefs\fP.
249 .B nice\fP (class \fBNice\fP)
250 The sub-processes created by \fIxscreensaver\fP will be ``niced'' to this
251 level, so that they are given lower priority than other processes on the
252 system, and don't increase the load unnecessarily. The default is 10.
254 (Higher numbers mean lower priority; see
258 .B fade\fP (class \fBBoolean\fP)
259 If this is true, then when the screensaver activates, the current contents
260 of the screen will fade to black instead of simply winking out. This only
261 works on displays with writable colormaps, that is, if the screen's default
262 visual is a PseudoColor visual. A fade will also be done when
263 switching graphics hacks (when the \fIcycle\fP timer expires.)
266 .B unfade\fP (class \fBBoolean\fP)
267 If this is true, then when the screensaver deactivates, the original contents
268 of the screen will fade in from black instead of appearing immediately. This
269 only works on displays with writable colormaps, and if \fIfade\fP is true
270 as well. Default false.
272 .B fadeSeconds\fP (class \fBTime\fP)
273 If \fIfade\fP is true, this is how long the fade will be in
274 seconds (default 3 seconds.)
276 .B fadeTicks\fP (class \fBInteger\fP)
277 If \fIfade\fP is true, this is how many times a second the colormap will
278 be changed to effect a fade. Higher numbers yield smoother fades, but
279 may make the fades take longer than the specified \fIfadeSeconds\fP if
280 your server isn't fast enough to keep up. Default 20.
282 .B captureStderr\fP (class \fBBoolean\fP)
283 Whether \fIxscreensaver\fP should redirect its stdout and stderr streams to
284 the window itself. Since its nature is to take over the screen, you would not
285 normally see error messages generated by xscreensaver or the sub-programs it
286 runs; this resource will cause the output of all relevant programs to be
287 drawn on the screensaver window itself, as well as being written to the
288 controlling terminal of the screensaver driver process. Default true.
290 .B font\fP (class \fBFont\fP)
291 The font used for the stdout/stderr text, if \fBcaptureStderr\fP is true.
292 Default \fB*\-medium\-r\-*\-140\-*\-m\-*\fP (a 14 point fixed-width font.)
294 .B programs\fP (class \fBPrograms\fP)
295 The graphics hacks which \fIxscreensaver\fP runs when the user is idle.
296 The value of this resource is a string, one \fIsh\fP-syntax command per line.
297 Each line must contain exactly one command: no semicolons, no ampersands.
299 When the screensaver starts up, one of these is selected at random, and
300 run. After the \fIcycle\fP period expires, it is killed, and another
303 If the value of this resource is empty, then no programs will be run; the
304 screen will simply be made black.
306 If the display has multiple screens, then a different program will be run
307 for each screen. (All screens are blanked and unblanked simultaniously.)
309 Note that you must escape the newlines; here is an example of how you
310 might set this in your \fI~/.xscreensaver\fP file:
316 ico -r -faces -sleep 1 -obj ico \\n\\
317 xdaliclock -builtin2 -root \\n\\
318 xv -root -rmode 5 image.gif -quit \\n
322 Make sure your \fB$PATH\fP environment variable is set up correctly
323 \fIbefore\fP xscreensaver is launched, or it won't be able to find the
324 programs listed in the \fIprograms\fP resource.
326 To use a program as a screensaver, two things are required: that that
327 program draw on the root window (or be able to be configured to draw on
328 the root window); and that that program understand ``virtual root''
329 windows, as used by virtual window managers such as
331 (Generally, this is accomplished by just including the \fI"vroot.h"\fP
332 header file in the program's source.)
334 If there are some programs that you want to run only when using a color
335 display, and others that you want to run only when using a monochrome
336 display, you can specify that like this:
338 mono: mono-program -root \\n\\
339 color: color-program -root \\n\\
343 More generally, you can specify the kind of visual that should be used for
344 the window on which the program will be drawing. For example, if one
345 program works best if it has a colormap, but another works best if it has
346 a 24-bit visual, both can be accommodated:
348 PseudoColor: cmap-program -root \\n\\
349 TrueColor: 24bit-program -root \\n\\
353 In addition to the symbolic visual names described above (in the discussion
354 of the \fIvisualID\fP resource) one other visual name is supported in
355 the \fIprograms\fP list:
359 This is like \fBdefault\fP, but also requests the use of the default colormap,
360 instead of a private colormap. (That is, it behaves as if
361 the \fI\-no\-install\fP command-line option was specified, but only for
362 this particular hack.) This is provided because some third-party programs
363 that draw on the root window (notably:
367 make assumptions about the visual and colormap of the root window:
368 assumptions which xscreensaver can violate.
371 If you specify a particular visual for a program, and that visual does not
372 exist on the screen, then that program will not be chosen to run. This
373 means that on displays with multiple screens of different depths, you can
374 arrange for appropriate hacks to be run on each. For example, if one screen
375 is color and the other is monochrome, hacks that look good in mono can be
376 run on one, and hacks that only look good in color will show up on the other.
380 Normally you won't need to change the following resources:
383 .B pointerPollTime\fP (class \fBTime\fP)
384 When server extensions are not in use, this controls how
385 frequently \fIxscreensaver\fP checks to see if the mouse position or buttons
386 have changed. Default 5 seconds.
388 .B windowCreationTimeout\fP (class \fBTime\fP)
389 When server extensions are not in use, this controls the delay between when
390 windows are created and when \fIxscreensaver\fP selects events on them.
393 .B initialDelay\fP (class \fBTime\fP)
394 When server extensions are not in use, \fIxscreensaver\fP will wait this many
395 seconds before selecting events on existing windows, under the assumption that
396 \fIxscreensaver\fP is started during your login procedure, and the window
397 state may be in flux. Default 0. (This used to default to 30, but that was
398 back in the days when slow machines and X terminals were more common...)
400 .B sgiSaverExtension\fP (class \fBBoolean\fP)
401 There are a number of different X server extensions which can make
402 xscreensaver's job easier. The next few resources specify whether these
403 extensions should be utilized if they are available.
405 This resource controls whether the SGI \fBSCREEN_SAVER\fP server extension
406 will be used to decide whether the user is idle. This is the default
407 if \fIxscreensaver\fP has been compiled with support for this
408 extension (which is the default on SGI systems.). If it is available,
409 the \fBSCREEN_SAVER\fP method is faster and more reliable than what will
410 be done otherwise, so use it if you can. (This extension is only available
411 on Silicon Graphics systems, unfortunately.)
413 .B mitSaverExtension\fP (class \fBBoolean\fP)
414 This resource controls whether the \fBMIT\-SCREEN\-SAVER\fP server extension
415 will be used to decide whether the user is idle. However, the default for
416 this resource is \fIfalse\fP, because even if this extension is available,
417 it is flaky (and it also makes the \fBfade\fP option not work properly.)
418 Use of this extension is not recommended.
420 .B xidleExtension\fP (class \fBBoolean\fP)
421 This resource controls whether the \fBXIDLE\fP server extension will be
422 used to decide whether the user is idle. This is the default
423 if \fIxscreensaver\fP has been compiled with support for this extension.
424 (This extension is only available for X11R4 and X11R5 systems, unfortunately.)
426 .B overlayStderr\fP (class \fBBoolean\fP)
427 If \fBcaptureStderr\fP is True, and your server supports ``overlay'' visuals,
428 then the text will be written into one of the higher layers instead of into
429 the same layer as the running screenhack. Set this to False to disable
430 that (though you shouldn't need to.)
432 .B overlayTextForeground\fP (class \fBForeground\fP)
433 The foreground color used for the stdout/stderr text, if \fBcaptureStderr\fP
434 is true. Default: Yellow.
436 .B overlayTextBackground\fP (class \fBBackground\fP)
437 The background color used for the stdout/stderr text, if \fBcaptureStderr\fP
438 is true. Default: Black.
440 .B bourneShell\fP (class \fBBourneShell\fP)
441 The pathname of the shell that \fIxscreensaver\fP uses to start subprocesses.
442 This must be whatever your local variant of \fB/bin/sh\fP is: in particular,
443 it must not be \fBcsh\fP.
444 .SH COMMAND-LINE OPTIONS
446 also accepts the following command line options. Except for
447 the \fI\-display\fP option, these command-line options are all
448 simply shorthand for the X resources described in
449 the \fIConfiguration\fP section, above.
451 .B \-display \fIhost:display.screen\fP
452 The X display to use. For displays with multiple screens, XScreenSaver
453 will manage all screens on the display simultaniously; the \fIscreen\fP
454 argument (the ``default'' screen) says which screen should be used for
455 dialog boxes (the password window, \fIDemo Mode\fP, etc.)
457 .B \-timeout \fIminutes\fP
458 Same as the \fItimeout\fP resource.
460 .B \-cycle \fIminutes\fP
461 Same as the \fIcycle\fP resource.
464 Same as setting the \fIlock\fP resource to \fItrue\fP.
467 Same as setting the \fIlock\fP resource to \fIfalse\fP.
469 .B \-lock\-timeout \fIminutes\fP
470 Same as the \fIlockTimeout\fP resource.
472 .B \-visual \fIvisual\fP
473 Same as the \fIvisualID\fP resource.
476 Same as setting the \fIinstallColormap\fP resource to \fItrue\fP.
479 Same as setting the \fIinstallColormap\fP resource to \fIfalse\fP.
482 Same as setting the \fIverbose\fP resource to \fItrue\fP.
485 Same as setting the \fIverbose\fP resource to \fIfalse\fP.
488 Same as setting the \fItimestamp\fP resource to \fItrue\fP.
491 Same as setting the \fIcaptureStderr\fP resource to \fItrue\fP.
493 .B \-no\-capture\-stderr
494 Same as setting the \fIcaptureStderr\fP resource to \fIfalse\fP.
497 Same as setting the \fIsplash\fP resource to \fItrue\fP.
500 Same as setting the \fIsplash\fP resource to \fIfalse\fP.
502 .B \-nice \fIinteger\fP
503 Same as the \fInice\fP resource.
506 Same as setting the \fIsgiSaverExtension\fP resource to \fItrue\fP.
508 .B \-no\-sgi\-extension
509 Same as setting the \fIsgiSaverExtension\fP resource to \fIfalse\fP.
512 Same as setting the \fImitSaverExtension\fP resource to \fItrue\fP.
514 .B \-no\-mit\-extension
515 Same as setting the \fImitSaverExtension\fP resource to \fIfalse\fP.
517 .B \-xidle\-extension
518 Same as setting the \fIxidleExtension\fP resource to \fItrue\fP.
520 .B \-no\-xidle\-extension
521 Same as setting the \fIxidleExtension\fP resource to \fIfalse\fP.
523 .B \-xrm \fIresource-specification\fP
524 As with all other Xt programs, you can specify X resources on the command-line
525 using the \fI\-xrm\fP argument. Most of the interesting resources have
526 command-line equivalents, however.
528 When it is time to activate the screensaver, a full-screen black window is
529 created on each screen of the display. Each window is created in such a way
530 that, to any subsequently-created programs, it will appear to be a ``virtual
531 root'' window. Because of this, any program which draws on the root
532 window (and which understands virtual roots) can be used as a screensaver.
534 When the user becomes active again, the screensaver windows are unmapped, and
535 the running subprocesses are killed by sending them \fBSIGTERM\fP. This is
536 also how the subprocesses are killed when the screensaver decides that it's
537 time to run a different demo: the old one is killed and a new one is launched.
539 Before launching a subprocess, \fIxscreensaver\fP stores an appropriate value
540 for \fB$DISPLAY\fP in the environment that the child will recieve. (This is
541 so that if you start \fIxscreensaver\fP with a \fI-display\fP argument, the
542 programs which \fIxscreensaver\fP launches will draw on the same display;
543 and so that the child will end up drawing on the appropriate screen of a
544 multi-headed display.)
546 When the screensaver turns off, or is killed, care is taken to restore
547 the ``real'' virtual root window if there is one. Because of this, it is
548 important that you not kill the screensaver process with \fIkill -9\fP if
549 you are running a virtual-root window manager. If you kill it with \-9,
550 you may need to restart your window manager to repair the damage. This
551 isn't an issue if you aren't running a virtual-root window manager.
553 For all the gory details, see the commentary at the top of xscreensaver.c.
555 You can control a running screensaver process by using the
556 .BR xscreensaver\-command (1)
559 Modern X servers contain support to power down the monitor after an idle
560 period. If the monitor has powered down, then \fIxscreensaver\fP will
561 notice this, and will not waste CPU by drawing graphics demos on a black
562 screen. An attempt will also be made to explicitly power the monitor
563 back up as soon as user activity is detected.
565 If your X server supports power management, then
567 will accept a \fBdpms\fP option. So, if you wanted \fIxscreensaver\fP
568 to activate after 5 minutes, but you wanted your monitor to power down
569 after one hour (3600 seconds) you would do this:
573 See the man page for the
575 program for details. (Note that power management requires both software
576 support in the X server, and hardware support in the monitor itself.)
578 You can run \fIxscreensaver\fP from your
580 session, so that the screensaver will run even when nobody is logged
583 The trick to using xscreensaver with \fIxdm\fP is this: keep in mind the
584 two very different states in which xscreensaver will be running:
587 .B 1: Nobody logged in.
589 If you're thinking of running xscreensaver from XDM at all, then it's
590 probably because you want graphics demos to be running on the console
591 when nobody is logged in there. In this case, xscreensaver will function
592 only as a screen saver, not a screen locker: it doesn't make sense
593 for xscreensaver to lock the screen, since nobody is logged in yet!
594 The only thing on the screen is the XDM login prompt.
596 .B 2: Somebody logged in.
598 Once someone has logged in through the XDM login window, the situation is
599 very different. For example: now it makes sense to lock the screen (and
600 prompt for the logged in user's password); and now xscreensaver should
601 consult that user's \fI~/.xscreensaver\fP file; and so on.
604 The difference between these two states comes down to a question of,
605 which user is the \fIxscreensaver\fP process running as? For the first
606 state, it doesn't matter. If you start \fIxscreensaver\fP in the usual
607 XDM way, then xscreensaver will probably end up running as root, which
608 is fine for the first case (the ``nobody logged in'' case.)
610 However, once someone is logged in, running as root is no longer fine:
611 because xscreensaver will be consulting root's \fI.xscreensaver\fP file
612 instead of that of the logged in user, and won't be prompting for the
613 logged in user's password, and so on. (This is not a security problem,
614 it's just not what you want.)
616 So, once someone has logged in, you want xscreensaver to be running as that
617 user. The way to accomplish this is to kill the old xscreensaver process
618 and start a new one (as the new user.)
620 The simplest way to accomplish all of this is as follows:
623 .B 1: Launch xscreensaver before anyone logs in.
625 To the file \fI/usr/lib/X11/xdm/Xsetup\fP, add the lines
627 xscreensaver-command -exit
630 This will run xscreensaver as root, over the XDM login window.
631 Moving the mouse will cause the screen to un-blank, and allow the user
632 to type their password at XDM to log in.
634 .B 2: Restart xscreensaver when someone logs in.
636 Near the top of the file \fI/usr/lib/X11/xdm/Xsession\fP, add those same lines:
638 xscreensaver-command -exit
641 When someone logs in, this will kill off the existing (root) xscreensaver
642 process, and start a new one, running as the user who has just logged in.
643 If the user's .xscreensaver file requests locking, they'll get it. They
644 will also get their own choice of timeouts, and graphics demos, and so on.
646 Alternately, each user could just put those lines in their
647 personal \fI~/.xsession\fP files.
650 Make sure you have \fB$PATH\fP set up correctly in the \fIXsetup\fP
651 and \fIXsession\fP scripts, or \fIxdm\fP won't be able to
652 find \fIxscreensaver\fP, and/or \fIxscreensaver\fP won't be able to
653 find its graphics demos.
655 (If your system does not seem to be executing the \fIXsetup\fP file, you
656 may need to configure it to do so: the traditional way to do this is
657 to make that file the value of the \fIDisplayManager*setup\fP resource
658 in the \fI/usr/lib/X11/xdm/xdm-config\fP file. See the man page for
662 It is safe to run \fIxscreensaver\fP as root (as \fIxdm\fP is likely to do.)
663 If run as root, \fIxscreensaver\fP changes its effective user and group ids
664 to something safe (like \fI"nobody"\fP) before connecting to the X server
665 or launching user-specified programs.
667 An unfortunate side effect of this (important) security precaution is that
668 it may conflict with cookie-based authentication.
670 If you get "connection refused" errors when running \fIxscreensaver\fP
671 from \fIxdm\fP, then this probably means that you have
673 or some other security mechanism turned on. One way around this is to
674 add \fB"xhost\ +localhost"\fP to \fIXsetup\fP, just before \fIxscreensaver\fP
677 Note that this will give access to the X server to anyone capable of logging
678 in to the local machine, so in some environments, this might not be
679 appropriate. If turning off file-system-based access control is not
680 acceptable, then running \fIxscreensaver\fP from the \fIXsetup\fP file
681 might not be possible, and xscreensaver will only work when running as
682 a normal, unprivileged user.
684 For more information on the X server's access control mechanisms, see the
691 .SH USING CDE (COMMON DESKTOP ENVIRONMENT)
692 The easiest way to use \fIxscreensaver\fP on a system with CDE is to simply
693 switch off the built-in CDE screensaver, and use \fIxscreensaver\fP instead;
694 and second, to tell the front panel to run
695 .BR xscreensaver\-command (1)
696 with the \fI\-lock\fP option when the \fILock\fP icon is clicked.
698 To accomplish this involves five steps:
701 \fB1: Switch off CDE's locker\fP
702 Do this by turning off ``\fIScreen Saver and Screen Lock\fP'' in the
703 Screen section of the Style Manager.
705 \fB2: Edit sessionetc\fP
706 Edit the file \fI~/.dt/sessions/sessionetc\fP and add to it the line
710 This will cause \fIxscreensaver\fP to be launched when you log in.
711 (As always, make sure that xscreensaver and the graphics demos are on
712 your \fB$PATH\fP; the path needs to be set in \fI.cshrc\fP
713 and/or \fI.dtprofile\fP, not \fI.login\fP.)
715 \fB3: Create XScreenSaver.dt\fP
716 Create a file called \fI~/.dt/types/XScreenSaver.dt\fP with the following
723 EXEC_STRING xscreensaver-command -lock
728 This defines a ``lock'' command for the CDE front panel, that knows how
729 to talk to \fIxscreensaver\fP.
731 \fB4: Create Lock.fp\fP
732 Create a file called \fI~/.dt/types/Lock.fp\fP with the following
738 CONTAINER_NAME Switch
739 CONTAINER_TYPE SWITCH
743 PUSH_ACTION XScreenSaver
744 HELP_TOPIC FPOnItemLock
748 This associates the CDE front panel ``Lock'' icon with the lock command
749 we just defined in step 3.
752 Select ``\fIRestart Workspace Manager\fP'' from the popup menu to make
753 your changes take effect. If things seem not to be working, check the
754 file \fI~/.dt/errorlog\fP for error messages.
756 .SH USING HP VUE (VISUAL USER ENVIRONMENT)
757 Since CDE is a descendant of VUE, the instructions for using xscreensaver
758 under VUE are similar to the above:
761 \fB1: Switch off VUE's locker\fP
762 Open the ``\fIStyle Manager\fP'' and select ``\fIScreen\fP.''
763 Turn off ``\fIScreen Saver and Screen Lock\fP'' option.
765 \fB2: Make sure you have a Session\fP
766 Next, go to the Style Manager's, ``\fIStartup\fP'' page.
767 Click on ``\fISet Home Session\fP'' to create a session, then
768 on ``\fIReturn to Home Session\fP'' to select this session each
771 \fB3: Edit vue.session\fP
772 Edit the file \fI~/.vue/sessions/home/vue.session\fP and add to it
775 vuesmcmd -screen 0 -cmd "xscreensaver"
777 This will cause \fIxscreensaver\fP to be launched when you log in.
778 (As always, make sure that xscreensaver and the graphics demos are on
779 your \fB$PATH\fP; the path needs to be set in \fI.cshrc\fP
780 and/or \fI.profile\fP, not \fI.login\fP.)
782 \fB3: Edit vuewmrc\fP
783 Edit the file \fI~/.vue/vuewmrc\fP and add (or change) the Lock control:
789 PUSH_ACTION f.exec "xscreensaver-command -lock"
793 This associates the VUE front panel ``Lock'' icon with the xscreensaver
799 .BR xscreensaver-command (1)
800 program is a perfect candidate for something to add to your window manager's
801 popup menus. If you use
805 or (probably) any of \fItwm\fP's many descendants, you can do it like this:
808 \fB1. Create ~/.mwmrc (or ~/.twmrc or ...)\fP
809 If you don't have a \fI~/.mwmrc\fP file (or, on SGIs, a \fI~/.4Dwmrc\fP file;
810 or, with twm, a \fI~/.twmrc\fP file) then create one by making a copy of
811 the \fI/usr/lib/X11/system.mwmrc\fP
812 file (or \fI/usr/lib/X11/twm/system.twmrc\fP, and so on.)
814 \fB2. Add a menu definition.\fP
819 "Blank Screen Now" !"sleep 3; xscreensaver-command -activate"
820 "Lock Screen Now" !"sleep 3; xscreensaver-command -lock"
821 "Screen Saver Demo" !"xscreensaver-demo"
822 "Screen Saver Preferences" !"xscreensaver-demo -prefs"
823 "Reinitialize Screen Saver" !"xscreensaver-command -restart"
824 "Kill Screen Saver" !"xscreensaver-command -exit"
825 "Launch Screen Saver" !"xscreensaver &"
829 \fB3. Add the menu\fP
834 find the section of the file that says \fIMenu DefaultRootMenu\fP.
837 it will probably be \fImenu "defops"\fP. If you add a line somewhere
838 in that menu definition that reads
840 "XScreenSaver" f.menu XScreenSaver
842 then this will add an XScreenSaver sub-menu to your default root-window
843 popup menu. Alternately, you could just put the xscreensaver menu items
844 directly into the root menu.
847 Other window managers are guaranteed to do things gratuitously differently.
849 Bugs? There are no bugs. Ok, well, maybe. If you find one, please let
850 me know. http://www.jwz.org/xscreensaver/bugs.html explains how to
851 construct the most useful bug reports.
854 If xscreensaver has been launched from
856 before anyone has logged in, you will need to kill and then restart the
857 xscreensaver daemon after you have logged in, or you will be confused by
858 the results. (For example, locking won't work, and your \fI~/.xscreensaver\fP
859 file will be ignored.)
861 When you are logged in, you want the \fIxscreensaver\fP daemon to be
862 running under \fIyour\fP user id, not as root or some other user.
864 If it has already been started by \fIxdm\fP, you can kill it by sending
865 it the \fBexit\fP command, and then re-launching it as you, by putting
866 something like the following in your personal X startup script:
868 xscreensaver-command -exit
871 The ``\fIUsing XDM(1)\fP'' section, above, goes into more detail, and explains
872 how to configure the system to do this for all users automatically.
874 .B Locking and root logins
875 In order for it to be safe for xscreensaver to be launched by \fIxdm\fP,
876 certain precautions had to be taken, among them that xscreensaver never
877 runs as \fIroot\fP. In particular, if it is launched as root (as \fIxdm\fP
878 is likely to do), xscreensaver will disavow its privileges, and switch
879 itself to a safe user id (such as \fInobody\fP.)
881 An implication of this is that if you log in as \fIroot\fP on the console,
882 xscreensaver will refuse to lock the screen (because it can't tell
883 the difference between \fIroot\fP being logged in on the console, and a
884 normal user being logged in on the console but xscreensaver having been
890 The solution to this is simple: you shouldn't be logging in on the console
891 as \fIroot\fP in the first place! (What, are you crazy or something?)
893 Proper Unix hygiene dictates that you should log in as yourself, and
895 to \fIroot\fP as necessary. People who spend their day logged in
896 as \fIroot\fP are just begging for disaster.
899 For xscreensaver to work when launched by
901 programs running on the local machine as user \fI"nobody"\fP must be
902 able to connect to the X server. This means that if you want to run
903 xscreensaver on the console while nobody is logged in, you may need
904 to disable cookie-based access control (and allow all users who can log
905 in to the local machine to connect to the display.)
907 You should be sure that this is an acceptable thing to do in your
908 environment before doing it. See the ``\fIUsing XDM(1)\fP'' section,
909 above, for more details.
911 If anyone has suggestions on how xscreensaver could be made to work with
913 without first turning off \fI.Xauthority\fP-based access control, please
917 If you get an error message at startup like ``couldn't get password
918 of \fIuser\fP'' then this probably means that you're on a system in which
921 library routine can only be effectively used by root. If this is the case,
922 then \fIxscreensaver\fP must be installed as setuid to root in order for
923 locking to work. Care has been taken to make this a safe thing to do.
925 It also may mean that your system uses shadow passwords instead of the standard
927 interface; in that case, you may need to change some options
928 with \fIconfigure\fP and recompile.
930 If you change your password after xscreensaver has been launched, it will
931 continue using your old password to unlock the screen until xscreensaver
932 is restarted. So, after you change your password, you'll have to do
934 xscreensaver-command -restart
936 to make \fIxscreensaver\fP notice.
939 If your system uses PAM (Pluggable Authentication Modules), then in order
940 for xscreensaver to use PAM properly, PAM must be told about xscreensaver.
941 The xscreensaver installation process should update the PAM data (on Linux,
942 by creating the file \fI/etc/pam.d/xscreensaver\fP for you, and on Solaris,
943 by telling you what lines to add to the \fI/etc/pam.conf\fP file.)
945 If the PAM configuration files do not know about xscreensaver, then
946 you \fImight\fP be in a situation where xscreensaver will refuse to ever
949 This is a design flaw in PAM (there is no way for a client to tell the
950 difference between PAM responding ``I have never heard of your module,''
951 and responding, ``you typed the wrong password.'' As far as I can tell,
952 there is no way for xscreensaver to automatically work around this, or
953 detect the problem in advance, so if you have PAM, make sure it is
954 configured correctly!
956 .B Colormap lossage: TWM
957 The \fBinstallColormap\fP option doesn't work very well with the
959 window manager and its descendants.
961 There is a race condition between the screensaver and this window manager,
962 which can result in the screensaver's colormap not getting installed
963 properly, meaning the graphics hacks will appear in essentially random
964 colors. (If the screen goes white instead of black, this is probably why.)
970 window managers don't seem to have this problem. The race condition exists
971 because X does not provide a way for an OverrideRedirect window to have its
972 own colormap, short of grabbing the server (which is neither a good idea, nor
973 really possible with the current design.) What happens is that, as soon as
974 the screensaver installs its colormap, \fBtwm\fP responds to
975 the \fBColormapNotify\fP event that is generated by re-instaling the default
976 colormap. Apparently, \fBtwm\fP doesn't \fIalways\fP do this; it seems to do
977 it regularly if the screensaver is activated from a menu item, but seems to
978 not do it if the screensaver comes on of its own volition, or is activated
979 from another console. Any thoughts on this problem are welcome...
981 .B Colormap lossage: XV, XAnim, XEarth
982 Some programs don't operate properly on visuals other than the default one,
983 or with colormaps other than the default one. See the discussion of the
984 magic "default-n" visual name in the description of the \fBprograms\fP
985 resource in the \fIConfiguration\fP section. When programs only work with
986 the default colormap, you need to use a syntax like this:
988 default-n: xv -root image-1.gif -quit \\n\\
989 default-n: xearth -nostars -wait 0 \\n\\
991 It would also work to turn off the \fBinstallColormap\fP option altogether,
992 but that would deny extra colors to those programs that \fIcan\fP take
996 Although this program ``nices'' the subprocesses that it starts,
997 graphics-intensive subprograms can still overload the machine by causing
998 the X server process itself (which is not ``niced'') to suck a lot of
999 cycles. Care should be taken to slow down programs intended for use as
1000 screensavers by inserting strategic calls to
1004 (or making liberal use of any \fI\-delay\fP options which the programs
1007 Note that the OpenGL-based graphics demos are real pigs on machines that
1008 don't have texture hardware.
1010 Also, an active screensaver will cause your X server to be pretty much
1011 permanently swapped in; but the same is true of any program that draws
1018 On some systems, Doom, Quake, and other games intercept the keyboard in
1019 ways that X programs can never detect. Therefore, when running these games,
1020 xscreensaver might think the console is idle, and activate. In the worst
1021 case, xscreensaver might blank the screen and mess up the game. Alternately,
1022 xscreensaver might activate on the X display while leaving the game visible,
1023 and merely cause the game to slow down.
1025 I don't know how to fix this, because I don't know how to detect the kind
1026 of keyboard activity that occurs during these games. Suggestions are welcome.
1028 .B Latency and Responsiveness
1029 If the subprocess is drawing too quickly and the connection to the X
1030 server is a slow one (such as an X terminal running over a phone line) then
1031 the screensaver might not turn off right away when the user becomes active
1034 demo has this problem if being run in full-speed mode). This can be
1035 alleviated by inserting strategic calls to
1037 in code intended for use as a screensaver. This prevents too much graphics
1038 activity from being buffered up.
1041 Apparently there are some problems with XView programs getting confused
1042 and thinking that the screensaver window is the real root window even when
1043 the screensaver is not active: ClientMessages intended for the window manager
1044 are sent to the screensaver window instead. This could be solved by making
1045 xscreensaver forward all unrecognised ClientMessages to the real root window,
1046 but there may be other problems as well. If anyone has any insight on the
1047 cause of this problem, please let me know. (XView is an X11 toolkit that
1048 implements the (quite abominable) Sun OpenLook look-and-feel.)
1050 .B MIT Extension and Fading
1051 The \fBMIT-SCREEN-SAVER\fP extension is junk. Don't use it.
1053 When using the \fBMIT-SCREEN-SAVER\fP extension in conjunction with
1054 the \fBfade\fP option, you'll notice an unattractive flicker just before
1055 the fade begins. This is because the server maps a black window just before
1056 it tells the \fIxscreensaver\fP process to activate. The \fIxscreensaver\fP
1057 process immediately unmaps that window, but this results in a flicker. I
1058 haven't figured a way to get around this; it seems to be a fundamental
1059 property of the (mis-) design of this server extension.
1061 It sure would be nice if someone would implement the \fBSGI SCREEN_SAVER\fP
1062 extension in XFree86; it's dead simple, and works far better than the
1063 overengineered and broken \fBMIT-SCREEN-SAVER\fP extension.
1066 If you're running Irix 6.3, you might find that your monitor is powering down
1067 after an hour or two even if you've told it not to. This is fixed by SGI
1068 patches 2447 and 2537.
1070 .B OpenGL Programs and Visuals
1071 Some of the graphics demos included with xscreensaver make use of the
1072 OpenGL (or MesaGL) 3D library, if it is available. It is possible (even
1073 likely) that \fIxscreensaver\fP's notion of the ``\fIbest\fP'' visual is
1074 not quite right for these GL programs.
1076 The odd thing about GL programs is that, unlike normal X11 programs, they
1077 tend to work best on a visual \fIhalf\fP as deep as the depth of the screen,
1078 since that way, they can do double-buffering. Try it and see, but you will
1079 probably find that, for these particular programs, you should specify the
1080 deepest visual that is half as deep as the screen. (See the discussion
1081 of the \fBprograms\fP resource in the \fIConfiguration\fP section, above.)
1083 For example, on a screen that supports both 24-bit TrueColor and 12-bit
1084 PseudoColor visuals, the 12-bit visual will probably work best (this is true
1085 of base-model SGI Indys: the 0x29 visual is the one you want.)
1087 Oddly, on SGI O2s (machines that have serious hardware support for GL), the
1088 12-bit PseudoColor visual looks awful (you get a black and white, flickery
1089 image.) On these machines, the visual you want turns out to be 0x31.
1090 However, 0x31 is but \fIone\fP of the \fIeight\fP 15-bit TrueColor visuals
1091 (yes, 8, and yes, 15) that the O2 X server provides. This is the only visual
1092 that works properly: as far as
1094 is concerned, all of the 15-bit TrueColor visuals are identical, but some
1095 flicker like mad, and some have deeply weird artifacts (such as hidden
1096 surfaces that show through, as if depth worked backwards!)
1098 I suppose these other visuals must be tied to some arcane hardware feature...
1099 If anyone would care to explain it to me, that would be great.
1101 Your mileage, therefore, may vary dramatically.
1103 .B MesaGL and Voodoo Cards
1104 If you have a 3Dfx/Voodoo card, the default settings for xscreensaver will
1105 run the GL-based graphics demos in such a way that they will not take
1106 advantage of the 3D acceleration hardware. The solution is to change
1107 the \fBprograms\fP entries for the GL hacks from this:
1113 MESA_GLX_FX=fullscreen gears \\n\\
1115 That is, make sure that \fB$MESA_GLX_FX\fP is set to \fIfullscreen\fP, and
1116 don't tell the program to draw on the root window. This may seem strange,
1117 but the setup used by Mesa and these kinds of cards \fIis\fP strange!
1119 For those who don't know, these cards work by sitting between your normal
1120 video card and the monitor, and seizing control of the monitor when it's
1121 time to do 3D. But this means that accelerated 3D only happens in full-screen
1122 mode (you can't do it in a window, and you can't see the output of 3D and 2D
1123 programs simultaniously), and that 3D will probably drive your monitor at a
1124 lower resolution, as well. It's bizarre.
1127 If you are not making use of one of the server extensions (\fBXIDLE\fP,
1128 \fBSGI SCREEN_SAVER\fP, or \fBMIT-SCREEN-SAVER\fP), then it is possible, in
1129 rare situations, for \fIxscreensaver\fP to interfere with event propagation
1130 and make another X program malfunction. For this to occur, that other
1131 application would need to \fInot\fP select \fBKeyPress\fP events on its
1132 non-leaf windows within the first 30 seconds of their existence, but then
1133 select for them later. In this case, that client \fImight\fP fail to receive
1134 those events. This isn't very likely, since programs generally select a
1135 constant set of events immediately after creating their windows and then
1136 don't change them, but this is the reason that it's a good idea to install
1137 and use one of the server extensions instead, to work around this shortcoming
1140 In all these years, I've not heard of even a single case of this happening,
1141 but it is theoretically possible, so I'm mentioning it for completeness...
1144 There need to be a lot more graphics hacks. In particular, there should be
1145 a simulation of a Lavalite (tm).
1150 to get the default host and display number, and to inform the sub-programs
1151 of the screen on which to draw.
1154 to find the sub-programs to run.
1157 for the directory in which to read and write the \fI.xscreensaver\fP file.
1160 to get the name of a resource file that overrides the global resources
1161 stored in the RESOURCE_MANAGER property.
1163 The latest version can always be found at
1164 http://www.jwz.org/xscreensaver/
1167 .BR xscreensaver\-demo (1),
1168 .BR xscreensaver\-command (1),
1185 .BR decayscreen (1),
1204 .BR interference (1),
1207 .BR kaleidescope (1),
1232 .BR slidescreen (1),
1240 .BR superquadrics (1),
1252 .BR xbouncebits (1),
1263 Copyright \(co 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998
1264 by Jamie Zawinski. Permission to use, copy, modify, distribute, and sell
1265 this software and its documentation for any purpose is hereby granted without
1266 fee, provided that the above copyright notice appear in all copies and that
1267 both that copyright notice and this permission notice appear in supporting
1268 documentation. No representations are made about the suitability of this
1269 software for any purpose. It is provided "as is" without express or implied
1272 Jamie Zawinski <jwz@jwz.org>. Written in late 1991; first posted
1273 to comp.sources.x on 13-Aug-1992.
1275 Please let me know if you find any bugs or make any improvements.
1276 .SH ACKNOWLEDGEMENTS
1277 Thanks to David Wojtowicz for implementing \fIlockTimeout\fP.
1279 Thanks to Martin Kraemer for adding support for shadow passwords and
1280 locking-disabled diagnostics.
1282 Thanks to the many people who have contributed graphics demos to the package.
1284 Thanks to Patrick Moreau for the VMS port.
1286 Thanks to Mark Bowyer for figuring out how to hook it up to CDE.
1288 And huge thanks to Jon A. Christopher for implementing the Athena dialog
1289 support, back in the days before Lesstif was a viable alternative to Motif.