14 .TH XScreenSaver 1 "25-Oct-98 (3.02)" "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 like ``couldn't get password of \fIuser\fP''
918 then this probably means that you're on a system in which the
920 library routine can only be effectively used by root. If this is the case,
921 then \fIxscreensaver\fP must be installed as setuid to root in order for
922 locking to work. Care has been taken to make this a safe thing to do.
924 It also may mean that your system uses shadow passwords instead of the standard
926 interface; in that case, you may need to change some options
927 with \fIconfigure\fP and recompile.
929 If you change your password after xscreensaver has been launched, it will
930 continue using your old password to unlock the screen until xscreensaver
931 is restarted. So, after you change your password, you'll have to do
933 xscreensaver-command -restart
935 to make \fIxscreensaver\fP notice.
937 .B Colormap lossage: TWM
938 The \fBinstallColormap\fP option doesn't work very well with the
940 window manager and its descendants.
942 There is a race condition between the screensaver and this window manager,
943 which can result in the screensaver's colormap not getting installed
944 properly, meaning the graphics hacks will appear in essentially random
945 colors. (If the screen goes white instead of black, this is probably why.)
951 window managers don't seem to have this problem. The race condition exists
952 because X does not provide a way for an OverrideRedirect window to have its
953 own colormap, short of grabbing the server (which is neither a good idea, nor
954 really possible with the current design.) What happens is that, as soon as
955 the screensaver installs its colormap, \fBtwm\fP responds to
956 the \fBColormapNotify\fP event that is generated by re-instaling the default
957 colormap. Apparently, \fBtwm\fP doesn't \fIalways\fP do this; it seems to do
958 it regularly if the screensaver is activated from a menu item, but seems to
959 not do it if the screensaver comes on of its own volition, or is activated
960 from another console. Any thoughts on this problem are welcome...
962 .B Colormap lossage: XV, XAnim, XEarth
963 Some programs don't operate properly on visuals other than the default one,
964 or with colormaps other than the default one. See the discussion of the
965 magic "default-n" visual name in the description of the \fBprograms\fP
966 resource in the \fIConfiguration\fP section. When programs only work with
967 the default colormap, you need to use a syntax like this:
969 default-n: xv -root image-1.gif -quit \\n\\
970 default-n: xearth -nostars -wait 0 \\n\\
972 It would also work to turn off the \fBinstallColormap\fP option altogether,
973 but that would deny extra colors to those programs that \fIcan\fP take
977 Although this program ``nices'' the subprocesses that it starts,
978 graphics-intensive subprograms can still overload the machine by causing
979 the X server process itself (which is not ``niced'') to suck a lot of
980 cycles. Care should be taken to slow down programs intended for use as
981 screensavers by inserting strategic calls to
985 (or making liberal use of any \fI\-delay\fP options which the programs
988 Note that the OpenGL-based graphics demos are real pigs on machines that
989 don't have texture hardware.
991 Also, an active screensaver will cause your X server to be pretty much
992 permanently swapped in; but the same is true of any program that draws
999 On some systems, Doom, Quake, and other games intercept the keyboard in
1000 ways that X programs can never detect. Therefore, when running these games,
1001 xscreensaver might think the console is idle, and activate. In the worst
1002 case, xscreensaver might blank the screen and mess up the game. Alternately,
1003 xscreensaver might activate on the X display while leaving the game visible,
1004 and merely cause the game to slow down.
1006 I don't know how to fix this, because I don't know how to detect the kind
1007 of keyboard activity that occurs during these games. Suggestions are welcome.
1009 .B Latency and Responsiveness
1010 If the subprocess is drawing too quickly and the connection to the X
1011 server is a slow one (such as an X terminal running over a phone line) then
1012 the screensaver might not turn off right away when the user becomes active
1015 demo has this problem if being run in full-speed mode). This can be
1016 alleviated by inserting strategic calls to
1018 in code intended for use as a screensaver. This prevents too much graphics
1019 activity from being buffered up.
1022 Apparently there are some problems with XView programs getting confused
1023 and thinking that the screensaver window is the real root window even when
1024 the screensaver is not active: ClientMessages intended for the window manager
1025 are sent to the screensaver window instead. This could be solved by making
1026 xscreensaver forward all unrecognised ClientMessages to the real root window,
1027 but there may be other problems as well. If anyone has any insight on the
1028 cause of this problem, please let me know. (XView is an X11 toolkit that
1029 implements the (quite abominable) Sun OpenLook look-and-feel.)
1031 .B MIT Extension and Fading
1032 The \fBMIT-SCREEN-SAVER\fP extension is junk. Don't use it.
1034 When using the \fBMIT-SCREEN-SAVER\fP extension in conjunction with
1035 the \fBfade\fP option, you'll notice an unattractive flicker just before
1036 the fade begins. This is because the server maps a black window just before
1037 it tells the \fIxscreensaver\fP process to activate. The \fIxscreensaver\fP
1038 process immediately unmaps that window, but this results in a flicker. I
1039 haven't figured a way to get around this; it seems to be a fundamental
1040 property of the (mis-) design of this server extension.
1042 It sure would be nice if someone would implement the \fBSGI SCREEN_SAVER\fP
1043 extension in XFree86; it's dead simple, and works far better than the
1044 overengineered and broken \fBMIT-SCREEN-SAVER\fP extension.
1047 If you're running Irix 6.3, you might find that your monitor is powering down
1048 after an hour or two even if you've told it not to. This is fixed by SGI
1049 patches 2447 and 2537.
1051 .B OpenGL Programs and Visuals
1052 Some of the graphics demos included with xscreensaver make use of the
1053 OpenGL (or MesaGL) 3D library, if it is available. It is possible (even
1054 likely) that \fIxscreensaver\fP's notion of the ``\fIbest\fP'' visual is
1055 not quite right for these GL programs.
1057 The odd thing about GL programs is that, unlike normal X11 programs, they
1058 tend to work best on a visual \fIhalf\fP as deep as the depth of the screen,
1059 since that way, they can do double-buffering. Try it and see, but you will
1060 probably find that, for these particular programs, you should specify the
1061 deepest visual that is half as deep as the screen. (See the discussion
1062 of the \fBprograms\fP resource in the \fIConfiguration\fP section, above.)
1064 For example, on a screen that supports both 24-bit TrueColor and 12-bit
1065 PseudoColor visuals, the 12-bit visual will probably work best (this is true
1066 of base-model SGI Indys: the 0x29 visual is the one you want.)
1068 Oddly, on SGI O2s (machines that have serious hardware support for GL), the
1069 12-bit PseudoColor visual looks awful (you get a black and white, flickery
1070 image.) On these machines, the visual you want turns out to be 0x31.
1071 However, 0x31 is but \fIone\fP of the \fIeight\fP 15-bit TrueColor visuals
1072 (yes, 8, and yes, 15) that the O2 X server provides. This is the only visual
1073 that works properly: as far as
1075 is concerned, all of the 15-bit TrueColor visuals are identical, but some
1076 flicker like mad, and some have deeply weird artifacts (such as hidden
1077 surfaces that show through, as if depth worked backwards!)
1079 I suppose these other visuals must be tied to some arcane hardware feature...
1080 If anyone would care to explain it to me, that would be great.
1082 Your mileage, therefore, may vary dramatically.
1084 .B MesaGL and Voodoo Cards
1085 If you have a 3Dfx/Voodoo card, the default settings for xscreensaver will
1086 run the GL-based graphics demos in such a way that they will not take
1087 advantage of the 3D acceleration hardware. The solution is to change
1088 the \fBprograms\fP entries for the GL hacks from this:
1094 MESA_GLX_FX=fullscreen gears \\n\\
1096 That is, make sure that \fB$MESA_GLX_FX\fP is set to \fIfullscreen\fP, and
1097 don't tell the program to draw on the root window. This may seem strange,
1098 but the setup used by Mesa and these kinds of cards \fIis\fP strange!
1100 For those who don't know, these cards work by sitting between your normal
1101 video card and the monitor, and seizing control of the monitor when it's
1102 time to do 3D. But this means that accelerated 3D only happens in full-screen
1103 mode (you can't do it in a window, and you can't see the output of 3D and 2D
1104 programs simultaniously), and that 3D will probably drive your monitor at a
1105 lower resolution, as well. It's bizarre.
1108 If you are not making use of one of the server extensions (\fBXIDLE\fP,
1109 \fBSGI SCREEN_SAVER\fP, or \fBMIT-SCREEN-SAVER\fP), then it is possible, in
1110 rare situations, for \fIxscreensaver\fP to interfere with event propagation
1111 and make another X program malfunction. For this to occur, that other
1112 application would need to \fInot\fP select \fBKeyPress\fP events on its
1113 non-leaf windows within the first 30 seconds of their existence, but then
1114 select for them later. In this case, that client \fImight\fP fail to receive
1115 those events. This isn't very likely, since programs generally select a
1116 constant set of events immediately after creating their windows and then
1117 don't change them, but this is the reason that it's a good idea to install
1118 and use one of the server extensions instead, to work around this shortcoming
1121 In all these years, I've not heard of even a single case of this happening,
1122 but it is theoretically possible, so I'm mentioning it for completeness...
1125 There need to be a lot more graphics hacks. In particular, there should be
1126 a simulation of a Lavalite (tm).
1131 to get the default host and display number, and to inform the sub-programs
1132 of the screen on which to draw.
1135 to find the sub-programs to run.
1138 for the directory in which to read and write the \fI.xscreensaver\fP file.
1141 to get the name of a resource file that overrides the global resources
1142 stored in the RESOURCE_MANAGER property.
1144 The latest version can always be found at
1145 http://www.jwz.org/xscreensaver/
1148 .BR xscreensaver\-demo (1),
1149 .BR xscreensaver\-command (1),
1166 .BR decayscreen (1),
1185 .BR interference (1),
1188 .BR kaleidescope (1),
1213 .BR slidescreen (1),
1221 .BR superquadrics (1),
1233 .BR xbouncebits (1),
1244 Copyright \(co 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998
1245 by Jamie Zawinski. Permission to use, copy, modify, distribute, and sell
1246 this software and its documentation for any purpose is hereby granted without
1247 fee, provided that the above copyright notice appear in all copies and that
1248 both that copyright notice and this permission notice appear in supporting
1249 documentation. No representations are made about the suitability of this
1250 software for any purpose. It is provided "as is" without express or implied
1253 Jamie Zawinski <jwz@jwz.org>. Written in late 1991; first posted
1254 to comp.sources.x on 13-Aug-1992.
1256 Please let me know if you find any bugs or make any improvements.
1257 .SH ACKNOWLEDGEMENTS
1258 Thanks to David Wojtowicz for implementing \fIlockTimeout\fP.
1260 Thanks to Martin Kraemer for adding support for shadow passwords and
1261 locking-disabled diagnostics.
1263 Thanks to the many people who have contributed graphics demos to the package.
1265 Thanks to Patrick Moreau for the VMS port.
1267 Thanks to Mark Bowyer for figuring out how to hook it up to CDE.
1269 And huge thanks to Jon A. Christopher for implementing the Athena dialog
1270 support, back in the days before Lesstif was a viable alternative to Motif.