1xscreensaver(1) XScreenSaver manual xscreensaver(1)
2
6 xscreensaver - extensible screen saver framework, plus locking
7
9 xscreensaver [-display host:display.screen] [-verbose] [-no-splash]
10 [-no-capture-stderr] [-log filename]
11
13 The xscreensaver program waits until the keyboard and mouse have been
14 idle for a period, and then runs a graphics demo chosen at random. It
15 turns off as soon as there is any mouse or keyboard activity.
16 This program can lock your terminal in order to prevent others from
18 using it, though its default mode of operation is merely to display
19 pretty pictures on your screen when it is not in use.
20 It also provides configuration and control of your monitor's power-sav‐
22 ing features.
23
25 For the impatient, try this:
26 xscreensaver &
27 xscreensaver-demo
28 The xscreensaver-demo(1) program pops up a dialog box that lets you
29 configure the screen saver, and experiment with the various display
30 modes.
31 Note that xscreensaver has a client-server model: the xscreensaver pro‐
33 gram is a daemon that runs in the background; it is controlled by the
34 foreground xscreensaver-demo(1) and xscreensaver-command(1) programs.
35
37 The easiest way to configure xscreensaver is to simply run the xscreen‐
38 saver-demo(1) program, and change the settings through the GUI. The
39 rest of this manual page describes lower level ways of changing set‐
40 tings.
41 I'll repeat that because it's important:
43 The easy way to configure xscreensaver is to run the xscreensaver-
45 demo(1) program. You shouldn't need to know any of the stuff
46 described in this manual unless you are trying to do something
47 tricky, like customize xscreensaver for site-wide use or something.
48 Options to xscreensaver are stored in one of two places: in a .xscreen‐
50 saver file in your home directory; or in the X resource database. If
51 the .xscreensaver file exists, it overrides any settings in the
52 resource database.
53 The syntax of the .xscreensaver file is similar to that of the .Xde‐
55 faults file; for example, to set the timeout paramter in the .xscreen‐
56 saver file, you would write the following:
57 timeout: 5
58 whereas, in the .Xdefaults file, you would write
59 xscreensaver.timeout: 5
60 If you change a setting in the .xscreensaver file while xscreensaver is
61 already running, it will notice this, and reload the file. (The file
62 will be reloaded the next time the screen saver needs to take some
63 action, such as blanking or unblanking the screen, or picking a new
64 graphics mode.)
65 If you change a setting in your X resource database, or if you want
67 xscreensaver to notice your changes immediately instead of the next
68 time it wakes up, then you will need to reload your .Xdefaults file,
69 and then tell the running xscreensaver process to restart itself, like
70 so:
71 xrdb < ~/.Xdefaults
72 xscreensaver-command -restart
73 If you want to set the system-wide defaults, then make your edits to
74 the xscreensaver app-defaults file, which should have been installed
75 when xscreensaver itself was installed. The app-defaults file will
76 usually be named /usr/lib/X11/app-defaults/XScreenSaver, but different
77 systems might keep it in a different place (for example, /usr/open‐
78 win/lib/app-defaults/XScreenSaver on Solaris.)
79 When settings are changed in the Preferences dialog box (see above) the
81 current settings will be written to the .xscreensaver file. (The .Xde‐
82 faults file and the app-defaults file will never be written by xscreen‐
83 saver itself.)
84
86 xscreensaver also accepts a few command-line options, mostly for use
87 when debugging: for normal operation, you should configure things via
88 the ~/.xscreensaver file.
89 -display host:display.screen
91 The X display to use. For displays with multiple screens,
92 XScreenSaver will manage all screens on the display simultan‐
93 iously.
94 -verbose
96 Same as setting the verbose resource to true: print diagnostics
97 on stderr and on the xscreensaver window.
98 -no-capture-stderr
100 Do not redirect the stdout and stderr streams to the xscreen‐
101 saver window itself. If xscreensaver is crashing, you might
102 need to do this in order to see the error message.
103 -log filename
105 This is exactly the same as redirecting stdout and stderr to
106 the given file (for append). This is useful when reporting
107 bugs.
108
110 When it is time to activate the screensaver, a full-screen black window
111 is created on each screen of the display. Each window is created in
112 such a way that, to any subsequently-created programs, it will appear
113 to be a "virtual root" window. Because of this, any program which
114 draws on the root window (and which understands virtual roots) can be
115 used as a screensaver. The various graphics demos are, in fact, just
116 standalone programs that know how to draw on the provided window.
117 When the user becomes active again, the screensaver windows are
119 unmapped, and the running subprocesses are killed by sending them
120 SIGTERM. This is also how the subprocesses are killed when the screen‐
121 saver decides that it's time to run a different demo: the old one is
122 killed and a new one is launched.
123 You can control a running screensaver process by using the xscreen‐
125 saver-command(1) program (which see.)
126
128 Modern X servers contain support to power down the monitor after an
129 idle period. If the monitor has powered down, then xscreensaver will
130 notice this (after a few minutes), and will not waste CPU by drawing
131 graphics demos on a black screen. An attempt will also be made to
132 explicitly power the monitor back up as soon as user activity is
133 detected.
134 The ~/.xscreensaver file controls the configuration of your display's
136 power management settings: if you have used xset(1) to change your
137 power management settings, then xscreensaver will override those
138 changes with the values specified in ~/.xscreensaver (or with its
139 built-in defaults, if there is no ~/.xscreensaver file yet.)
140 To change your power management settings, run xscreensaver-demo(1) and
142 change the various timeouts through the user interface. Alternately,
143 you can edit the ~/.xscreensaver file directly.
144 If the power management section is grayed out in the xscreen‐
146 saver-demo(1) window, then that means that your X server does not sup‐
147 port the XDPMS extension, and so control over the monitor's power state
148 is not available.
149 If you're using a laptop, don't be surprised if changing the DPMS set‐
151 tings has no effect: many laptops have monitor power-saving behavior
152 built in at a very low level that is invisible to Unix and X. On such
153 systems, you can typically adjust the power-saving delays only by
154 changing settings in the BIOS in some hardware-specific way.
155 If DPMS seems not to be working with XFree86, make sure the "DPMS"
157 option is set in your /etc/X11/XF86Config file. See the XF86Config(5)
158 manual for details.
159
161 For the better part of a decade, GNOME shipped xscreensaver as-is, and
162 everything just worked out of the box. In 2005, however, they decided
163 to re-invent the wheel and ship their own replacement for the xscreen‐
164 saver daemon called "gnome-screensaver", rather than improving xscreen‐
165 saver and contributing their changes back. As a result, the "gnome-
166 screensaver" program is insecure, bug-ridden, and missing many features
167 of xscreensaver. You shouldn't use it.
168 To replace gnome-screensaver with xscreensaver:
170 1: Turn off gnome-screensaver.
172 Open the "System / Preferences / Screensaver" panel and uncheck
173 both boxes.
174 2: Stop gnome-screensaver from launching at login.
176 Run the command:
177 gconftool-2 --type boolean -s \
179 /apps/gnome_settings_daemon/screensaver/start_screensaver \
180 false
181 Or, just uninstall the "gnome-screensaver" package entirely.
183 3: Launch xscreensaver at login.
185 Open the "System / Preferences / Sessions / Startup Programs"
186 panel. Click "Add" and type "xscreensaver".
187 4: Tell Preferences to use the xscreensaver configurator.
189 Edit /usr/share/applications/gnome-screensaver-preferences.desk‐
190 top and change the Exec= line to say
191 Exec=xscreensaver-demo
192 5: Make "System / Quit / Lock Screen" use xscreensaver.
194 Run the command:
195 sudo ln -sf /usr/bin/xscreensaver-command \
196 /usr/bin/gnome-screensaver-command
197
199 Like GNOME, KDE also decided to invent their own screen saver framework
200 from scratch instead of simply using xscreensaver. To replace the KDE
201 screen saver with xscreensaver, do the following:
202 1: Turn off KDE's screen saver.
204 Open the "Control Center" and select the "Appearance & Themes /
205 Screensaver" page. Un-check "Start Automatically".
206 2: Find your Autostart directory.
208 Open the "System Administration / Paths" page, and see what your
209 "Autostart path" is set to: it will probably be
210 ~/.kde/Autostart/ or something similar.
211 3: Make xscreensaver be an Autostart program.
213 Create a .desktop file in your autostart directory called
214 xscreensaver.desktop that contains the following five lines:
215 [Desktop Entry]
217 Exec=xscreensaver
218 Name=XScreenSaver
219 Type=Application
220 X-KDE-StartupNotify=false
221 4: Make the various "lock session" buttons call xscreensaver.
223 The file you want to replace next has moved around over the
224 years. It might be called /usr/libexec/kde4/kscreenlocker, or it
225 might be called "kdesktop_lock" or "krunner_lock", and it might
226 be in /usr/lib/kde4/libexec/ or in /usr/kde/3.5/bin/ or even in
227 /usr/bin/, depending on the distro and phase of the moon.
228 Replace the contents of that file with these two lines:
229 #!/bin/sh
231 xscreensaver-command -lock
232 Make sure the file is executable (chmod a+x).
234 Now use xscreensaver normally, controlling it via the usual xscreen‐
236 saver-demo(1) and xscreensaver-command(1) mechanisms.
237
239 You can run xscreensaver from your gdm(1) session, so that the screen‐
240 saver will run even when nobody is logged in on the console. To do
241 this, run gdmconfig(1) and on the Background page, type the command
242 "xscreensaver -nosplash" into the Background Program field. That will
243 cause gdm to run xscreensaver while nobody is logged in, and kill it as
244 soon as someone does log in. (The user will then be responsible for
245 starting xscreensaver on their own, if they want.)
246 Another way to accomplish the same thing is to edit the file
248 /etc/X11/gdm/gdm.conf to include:
249 BackgroundProgram=xscreensaver -nosplash
250 RunBackgroundProgramAlways=true
251 In this situation, the xscreensaver process will probably be running as
252 user gdm instead of root. You can configure the settings for this
253 nobody-logged-in state (timeouts, DPMS, etc.) by editing the
254 ~gdm/.xscreensaver file.
255 To get gdm to run the BackgroundProgram, you may need to switch it from
257 the "Graphical Greeter" to the "Standard Greeter".
258 It is safe to run xscreensaver as root (as xdm or gdm may do.) If run
260 as root, xscreensaver changes its effective user and group ids to some‐
261 thing safe (like "nobody") before connecting to the X server or launch‐
262 ing user-specified programs.
263 An unfortunate side effect of this (important) security precaution is
265 that it may conflict with cookie-based authentication.
266 If you get "connection refused" errors when running xscreensaver from
268 gdm, then this probably means that you have xauth(1) or some other
269 security mechanism turned on. For information on the X server's access
270 control mechanisms, see the man pages for X(1), Xsecurity(1), xauth(1),
271 and xhost(1).
272
274 Bugs? There are no bugs. Ok, well, maybe. If you find one, please
275 let me know. http://www.jwz.org/xscreensaver/bugs.html explains how to
276 construct the most useful bug reports.
277 Locking and root logins
279 In order for it to be safe for xscreensaver to be launched by xdm,
280 certain precautions had to be taken, among them that xscreensaver
281 never runs as root. In particular, if it is launched as root (as
282 xdm is likely to do), xscreensaver will disavow its privileges, and
283 switch itself to a safe user id (such as nobody.)
284 An implication of this is that if you log in as root on the con‐
286 sole, xscreensaver will refuse to lock the screen (because it can't
287 tell the difference between root being logged in on the console,
288 and a normal user being logged in on the console but xscreensaver
289 having been launched by the xdm(1) Xsetup file.)
290 The solution to this is simple: you shouldn't be logging in on the
292 console as root in the first place! (What, are you crazy or some‐
293 thing?)
294 Proper Unix hygiene dictates that you should log in as yourself,
296 and su(1) to root as necessary. People who spend their day logged
297 in as root are just begging for disaster.
298 XAUTH and XDM
300 For xscreensaver to work when launched by xdm(1) or gdm(1), pro‐
301 grams running on the local machine as user "nobody" must be able to
302 connect to the X server. This means that if you want to run
303 xscreensaver on the console while nobody is logged in, you may need
304 to disable cookie-based access control (and allow all users who can
305 log in to the local machine to connect to the display.)
306 You should be sure that this is an acceptable thing to do in your
308 environment before doing it. See the "Using GDM" section, above,
309 for more details.
310 Passwords
312 If you get an error message at startup like "couldn't get password
313 of user" then this probably means that you're on a system in which
314 the getpwent(3) library routine can only be effectively used by
315 root. If this is the case, then xscreensaver must be installed as
316 setuid to root in order for locking to work. Care has been taken
317 to make this a safe thing to do.
318 It also may mean that your system uses shadow passwords instead of
320 the standard getpwent(3) interface; in that case, you may need to
321 change some options with configure and recompile.
322 If you change your password after xscreensaver has been launched,
324 it will continue using your old password to unlock the screen until
325 xscreensaver is restarted. On some systems, it may accept both
326 your old and new passwords. So, after you change your password,
327 you'll have to do
328 xscreensaver-command -restart
329 to make xscreensaver notice.
330 PAM Passwords
332 If your system uses PAM (Pluggable Authentication Modules), then in
333 order for xscreensaver to use PAM properly, PAM must be told about
334 xscreensaver. The xscreensaver installation process should update
335 the PAM data (on Linux, by creating the file /etc/pam.d/xscreen‐
336 saver for you, and on Solaris, by telling you what lines to add to
337 the /etc/pam.conf file.)
338 If the PAM configuration files do not know about xscreensaver, then
340 you might be in a situation where xscreensaver will refuse to ever
341 unlock the screen.
342 This is a design flaw in PAM (there is no way for a client to tell
344 the difference between PAM responding "I have never heard of your
345 module", and responding, "you typed the wrong password".) As far
346 as I can tell, there is no way for xscreensaver to automatically
347 work around this, or detect the problem in advance, so if you have
348 PAM, make sure it is configured correctly!
349 Machine Load
351 Although this program "nices" the subprocesses that it starts,
352 graphics-intensive subprograms can still overload the machine by
353 causing the X server process itself (which is not "niced") to con‐
354 sume many cycles. Care has been taken in all the modules shipped
355 with xscreensaver to sleep periodically, and not run full tilt, so
356 as not to cause appreciable load.
357 However, if you are running the OpenGL-based screen savers on a
359 machine that does not have a video card with 3D acceleration, they
360 will make your machine slow, despite nice(1).
361 Your options are: don't use the OpenGL display modes; or, collect
363 the spare change hidden under the cushions of your couch, and use
364 it to buy a video card manufactured after 1998. (It doesn't even
365 need to be fast 3D hardware: the problem will be fixed if there is
366 any 3D hardware at all.)
367 XFree86's Magic Keystrokes
369 The XFree86 X server traps certain magic keystrokes before client
370 programs ever see them. Two that are of note are
371 Ctrl+Alt+Backspace, which causes the X server to exit; and
372 Ctrl+Alt+Fn, which switches virtual consoles. The X server will
373 respond to these keystrokes even if xscreensaver has the screen
374 locked. Depending on your setup, you might consider this a prob‐
375 lem.
376 Unfortunately, there is no way for xscreensaver itself to override
378 the interpretation of these keys. If you want to disable
379 Ctrl+Alt+Backspace globally, you need to set the DontZap flag in
380 your /etc/X11/XF86Config file. To globally disable VT switching,
381 you can set the DontVTSwitch flag. See the XF86Config(5) manual
382 for details.
383
385 These are the X resources use by the xscreensaver program. You proba‐
386 bly won't need to change these manually (that's what the xscreen‐
387 saver-demo(1) program is for).
388 timeout (class Time)
390 The screensaver will activate (blank the screen) after the key‐
391 board and mouse have been idle for this many minutes. Default
392 10 minutes.
393 cycle (class Time)
395 After the screensaver has been running for this many minutes,
396 the currently running graphics-hack sub-process will be killed
397 (with SIGTERM), and a new one started. If this is 0, then the
398 graphics hack will never be changed: only one demo will run
399 until the screensaver is deactivated by user activity. Default
400 10 minutes.
401 lock (class Boolean)
403 Enable locking: before the screensaver will turn off, it will
404 require you to type the password of the logged-in user (really,
405 the person who ran xscreensaver), or the root password. (Note:
406 this doesn't work if the screensaver is launched by xdm(1)
407 because it can't know the user-id of the logged-in user. See
408 the "Using XDM(1)" section, below.
409 lockTimeout (class Time)
411 If locking is enabled, this controls the length of the "grace
412 period" between when the screensaver activates, and when the
413 screen becomes locked. For example, if this is 5, and -timeout
414 is 10, then after 10 minutes, the screen would blank. If there
415 was user activity at 12 minutes, no password would be required
416 to un-blank the screen. But, if there was user activity at 15
417 minutes or later (that is, -lock-timeout minutes after activa‐
418 tion) then a password would be required. The default is 0,
419 meaning that if locking is enabled, then a password will be
420 required as soon as the screen blanks.
421 passwdTimeout (class Time)
423 If the screen is locked, then this is how many seconds the
424 password dialog box should be left on the screen before giving
425 up (default 30 seconds.) This should not be too large: the X
426 server is grabbed for the duration that the password dialog box
427 is up (for security purposes) and leaving the server grabbed
428 for too long can cause problems.
429 dpmsEnabled (class Boolean)
431 Whether power management is enabled.
432 dpmsStandby (class Time)
434 If power management is enabled, how long until the monitor goes
435 solid black.
436 dpmsSuspend (class Time)
438 If power management is enabled, how long until the monitor goes
439 into power-saving mode.
440 dpmsOff (class Time)
442 If power management is enabled, how long until the monitor pow‐
443 ers down completely. Note that these settings will have no
444 effect unless both the X server and the display hardware sup‐
445 port power management; not all do. See the Power Management
446 section, below, for more information.
447 dpmsQuickOff (class Boolean)
449 If mode is blank and this is true, then the screen will be pow‐
450 ered down immediately upon blanking, regardless of other power-
451 management settings.
452 visualID (class VisualID)
454 Specify which X visual to use by default. (Note carefully that
455 this resource is called visualID, not merely visual; if you set
456 the visual resource instead, things will malfunction in obscure
457 ways for obscure reasons.)
458 Legal values for the VisualID resource are:
460 default Use the screen's default visual (the visual of the root
462 window.) This is the default.
463 best Use the visual which supports the most colors. Note,
465 however, that the visual with the most colors might be
466 a TrueColor visual, which does not support colormap
467 animation. Some programs have more interesting behav‐
468 ior when run on PseudoColor visuals than on TrueColor.
469 mono Use a monochrome visual, if there is one.
471 gray Use a grayscale or staticgray visual, if there is one
473 and it has more than one plane (that is, it's not mono‐
474 chrome.)
475 color Use the best of the color visuals, if there are any.
477 GL Use the visual that is best for OpenGL programs.
479 (OpenGL programs have somewhat different requirements
480 than other X programs.)
481 class where class is one of StaticGray, StaticColor, True‐
483 Color, GrayScale, PseudoColor, or DirectColor. Selects
484 the deepest visual of the given class.
485 number where number (decimal or hex) is interpreted as a vis‐
487 ual id number, as reported by the xdpyinfo(1) program;
488 in this way you can have finer control over exactly
489 which visual gets used, for example, to select a shal‐
490 lower one than would otherwise have been chosen.
491 Note that this option specifies only the default visual that
493 will be used: the visual used may be overridden on a program-
494 by-program basis. See the description of the programs
495 resource, below.
496 installColormap (class Boolean)
498 On PseudoColor (8-bit) displays, install a private colormap
499 while the screensaver is active, so that the graphics hacks can
500 get as many colors as possible. This is the default. (This
501 only applies when the screen's default visual is being used,
502 since non-default visuals get their own colormaps automati‐
503 cally.) This can also be overridden on a per-hack basis: see
504 the discussion of the default-n name in the section about the
505 programs resource.
506 This does nothing if you have a TrueColor (16-bit or deeper)
508 display.
509 verbose (class Boolean)
511 Whether to print diagnostics. Default false.
512 timestamp (class Boolean)
514 Whether to print the time of day along with any other diagnos‐
515 tic messages. Default true.
516 splash (class Boolean)
518 Whether to display a splash screen at startup. Default true.
519 splashDuration (class Time)
521 How long the splash screen should remain visible; default 5
522 seconds.
523 helpURL (class URL)
525 The splash screen has a Help button on it. When you press it,
526 it will display the web page indicated here in your web
527 browser.
528 loadURL (class LoadURL)
530 This is the shell command used to load a URL into your web
531 browser. The default setting will load it into Mozilla/Net‐
532 scape if it is already running, otherwise, will launch a new
533 browser looking at the helpURL.
534 demoCommand (class DemoCommand)
536 This is the shell command run when the Demo button on the
537 splash window is pressed. It defaults to xscreensaver-demo(1).
538 prefsCommand (class PrefsCommand)
540 This is the shell command run when the Prefs button on the
541 splash window is pressed. It defaults to xscreen‐
542 saver-demo -prefs.
543 newLoginCommand (class NewLoginCommand)
545 If set, this is the shell command that is run when the "New
546 Login" button is pressed on the unlock dialog box, in order to
547 create a new desktop session without logging out the user who
548 has locked the screen. Typically this will be some variant of
549 gdmflexiserver(1) or kdmctl(1).
550 nice (class Nice)
552 The sub-processes created by xscreensaver will be "niced" to
553 this level, so that they are given lower priority than other
554 processes on the system, and don't increase the load unneces‐
555 sarily. The default is 10. (Higher numbers mean lower prior‐
556 ity; see nice(1) for details.)
557 fade (class Boolean)
559 If this is true, then when the screensaver activates, the cur‐
560 rent contents of the screen will fade to black instead of sim‐
561 ply winking out. This only works on certain systems. A fade
562 will also be done when switching graphics hacks (when the cycle
563 timer expires.) Default: true.
564 unfade (class Boolean)
566 If this is true, then when the screensaver deactivates, the
567 original contents of the screen will fade in from black instead
568 of appearing immediately. This only works on certain systems,
569 and if fade is true as well. Default false.
570 fadeSeconds (class Time)
572 If fade is true, this is how long the fade will be in seconds
573 (default 3 seconds.)
574 fadeTicks (class Integer)
576 If fade is true, this is how many times a second the colormap
577 will be changed to effect a fade. Higher numbers yield
578 smoother fades, but may make the fades take longer than the
579 specified fadeSeconds if your server isn't fast enough to keep
580 up. Default 20.
581 captureStderr (class Boolean)
583 Whether xscreensaver should redirect its stdout and stderr
584 streams to the window itself. Since its nature is to take over
585 the screen, you would not normally see error messages generated
586 by xscreensaver or the sub-programs it runs; this resource will
587 cause the output of all relevant programs to be drawn on the
588 screensaver window itself, as well as being written to the con‐
589 trolling terminal of the screensaver driver process. Default
590 true.
591 ignoreUninstalledPrograms (class Boolean)
593 There may be programs in the list that are not installed on the
594 system, yet are marked as "enabled." If this preference is
595 true, then such programs will simply be ignored. If false,
596 then a warning will be printed if an attempt is made to run the
597 nonexistent program. Also, the xscreensaver-demo(1) program
598 will suppress the non-existent programs from the list if this
599 is true. Default: false.
600 GetViewPortIsFullOfLies (class Boolean)
602 Set this to true if the xscreensaver window doesn't cover the
603 whole screen. This works around a longstanding XFree86 bug
604 #421. See the xscreensaver FAQ for details.
605 font (class Font)
607 The font used for the stdout/stderr text, if captureStderr is
608 true. Default *-medium-r-*-140-*-m-* (a 14 point fixed-width
609 font.)
610 mode (class Mode)
612 Controls the behavior of xscreensaver. Legal values are:
613 random When blanking the screen, select a random display mode
615 from among those that are enabled and applicable. This
616 is the default.
617 random-same
619 Like random, but if there are multiple screens, each
620 screen will run the same random display mode, instead
621 of each screen running a different one.
622 one When blanking the screen, only ever use one particular
624 display mode (the one indicated by the selected set‐
625 ting.)
626 blank When blanking the screen, just go black: don't run any
628 graphics hacks.
629 off Don't ever blank the screen, and don't ever allow the
631 monitor to power down.
632 selected (class Integer)
635 When mode is set to one, this is the one, indicated by its
636 index in the programs list. You're crazy if you count them and
637 set this number by hand: let xscreensaver-demo(1) do it for
638 you!
639 programs (class Programs)
641 The graphics hacks which xscreensaver runs when the user is
642 idle. The value of this resource is a multi-line string, one
643 sh-syntax command per line. Each line must contain exactly one
644 command: no semicolons, no ampersands.
645 When the screensaver starts up, one of these is selected
647 (according to the mode setting), and run. After the cycle
648 period expires, it is killed, and another is selected and run.
649 If a line begins with a dash (-) then that particular program
651 is disabled: it won't be selected at random (though you can
652 still select it explicitly using the xscreensaver-demo(1) pro‐
653 gram.)
654 If all programs are disabled, then the screen will just be made
656 blank, as when mode is set to blank.
657 To disable a program, you must mark it as disabled with a dash
659 instead of removing it from the list. This is because the sys‐
660 tem-wide (app-defaults) and per-user (.xscreensaver) settings
661 are merged together, and if a user just deletes an entry from
662 their programs list, but that entry still exists in the system-
663 wide list, then it will come back. However, if the user dis‐
664 ables it, then their setting takes precedence.
665 If the display has multiple screens, then a different program
667 will be run for each screen. (All screens are blanked and
668 unblanked simultaneously.)
669 Note that you must escape the newlines; here is an example of
671 how you might set this in your ~/.xscreensaver file:
672 programs: \
674 qix -root \n\
675 ico -r -faces -sleep 1 -obj ico \n\
676 xdaliclock -builtin2 -root \n\
677 xv -root -rmode 5 image.gif -quit \n
678 Make sure your $PATH environment variable is set up correctly
679 before xscreensaver is launched, or it won't be able to find
680 the programs listed in the programs resource.
681 To use a program as a screensaver, two things are required:
683 that that program draw on the root window (or be able to be
684 configured to draw on the root window); and that that program
685 understand "virtual root" windows, as used by virtual window
686 managers such as tvtwm(1). (Generally, this is accomplished by
687 just including the "vroot.h" header file in the program's
688 source.)
689 Visuals:
691 Because xscreensaver was created back when dinosaurs roamed the
693 earth, it still contains support for some things you've proba‐
694 bly never seen, such as 1-bit monochrome monitors, grayscale
695 monitors, and monitors capable of displaying only 8-bit col‐
696 ormapped images.
697 If there are some programs that you want to run only when using
699 a color display, and others that you want to run only when
700 using a monochrome display, you can specify that like this:
701 mono: mono-program -root \n\
702 color: color-program -root \n\
703 More generally, you can specify the kind of visual that should
704 be used for the window on which the program will be drawing.
705 For example, if one program works best if it has a colormap,
706 but another works best if it has a 24-bit visual, both can be
707 accommodated:
708 PseudoColor: cmap-program -root \n\
709 TrueColor: 24bit-program -root \n\
710 In addition to the symbolic visual names described above (in
711 the discussion of the visualID resource) one other visual name
712 is supported in the programs list:
713 default-n
715 This is like default, but also requests the use of the
716 default colormap, instead of a private colormap. (That
717 is, it behaves as if the -no-install command-line option
718 was specified, but only for this particular hack.) This
719 is provided because some third-party programs that draw on
720 the root window (notably: xv(1), and xearth(1)) make
721 assumptions about the visual and colormap of the root win‐
722 dow: assumptions which xscreensaver can violate.
723 If you specify a particular visual for a program, and that vis‐
725 ual does not exist on the screen, then that program will not be
726 chosen to run. This means that on displays with multiple
727 screens of different depths, you can arrange for appropriate
728 hacks to be run on each. For example, if one screen is color
729 and the other is monochrome, hacks that look good in mono can
730 be run on one, and hacks that only look good in color will show
731 up on the other.
732 You shouldn't ever need to change the following resources:
734 pointerPollTime (class Time)
736 When server extensions are not in use, this controls how fre‐
737 quently xscreensaver checks to see if the mouse position or
738 buttons have changed. Default 5 seconds.
739 pointerHysteresis (class Integer)
741 If the mouse moves less than this-many pixels in a second,
742 ignore it (do not consider that to be "activity.") This is so
743 that the screen doesn't un-blank (or fail to blank) just
744 because you bumped the desk. Default: 10 pixels.
745 windowCreationTimeout (class Time)
747 When server extensions are not in use, this controls the delay
748 between when windows are created and when xscreensaver selects
749 events on them. Default 30 seconds.
750 initialDelay (class Time)
752 When server extensions are not in use, xscreensaver will wait
753 this many seconds before selecting events on existing windows,
754 under the assumption that xscreensaver is started during your
755 login procedure, and the window state may be in flux. Default
756 0. (This used to default to 30, but that was back in the days
757 when slow machines and X terminals were more common...)
758 procInterrupts (class Boolean)
760 This resource controls whether the /proc/interrupts file should
761 be consulted to decide whether the user is idle. This is the
762 default if xscreensaver has been compiled on a system which
763 supports this mechanism (i.e., Linux systems.)
764 The benefit to doing this is that xscreensaver can note that
766 the user is active even when the X console is not the active
767 one: if the user is typing in another virtual console, xscreen‐
768 saver will notice that and will fail to activate. For example,
769 if you're playing Quake in VGA-mode, xscreensaver won't wake up
770 in the middle of your game and start competing for CPU.
771 The drawback to doing this is that perhaps you really do want
773 idleness on the X console to cause the X display to lock, even
774 if there is activity on other virtual consoles. If you want
775 that, then set this option to False. (Or just lock the X con‐
776 sole manually.)
777 The default value for this resource is True, on systems where
779 it works.
780 overlayStderr (class Boolean)
782 If captureStderr is True, and your server supports "overlay"
783 visuals, then the text will be written into one of the higher
784 layers instead of into the same layer as the running screen‐
785 hack. Set this to False to disable that (though you shouldn't
786 need to.)
787 overlayTextForeground (class Foreground)
789 The foreground color used for the stdout/stderr text, if cap‐
790 tureStderr is true. Default: Yellow.
791 overlayTextBackground (class Background)
793 The background color used for the stdout/stderr text, if cap‐
794 tureStderr is true. Default: Black.
795 bourneShell (class BourneShell)
797 The pathname of the shell that xscreensaver uses to start sub‐
798 processes. This must be whatever your local variant of /bin/sh
799 is: in particular, it must not be csh.
800
802 DISPLAY to get the default host and display number, and to inform the
803 sub-programs of the screen on which to draw.
804 XSCREENSAVER_WINDOW
806 Passed to sub-programs to indicate the ID of the window on
807 which they should draw. This is necessary on Xinerama/RANDR
808 systems where multiple physical monitors share a single X11
809 "Screen".
810 PATH to find the sub-programs to run.
812 HOME for the directory in which to read the .xscreensaver file.
814 XENVIRONMENT
816 to get the name of a resource file that overrides the global
817 resources stored in the RESOURCE_MANAGER property.
818
820 The latest version of xscreensaver, an online version of this manual,
821 and a FAQ can always be found at http://www.jwz.org/xscreensaver/
822
824 X(1), Xsecurity(1), xauth(1), xdm(1), gdm(1), xhost(1), xscreen‐
825 saver-demo(1), xscreensaver-command(1), xscreensaver-gl-helper(1),
826 xscreensaver-getimage(1), xscreensaver-text(1).
827
829 Copyright © 1991-2011 by Jamie Zawinski. Permission to use, copy, mod‐
830 ify, distribute, and sell this software and its documentation for any
831 purpose is hereby granted without fee, provided that the above copy‐
832 right notice appear in all copies and that both that copyright notice
833 and this permission notice appear in supporting documentation. No rep‐
834 resentations are made about the suitability of this software for any
835 purpose. It is provided "as is" without express or implied warranty.
836
838 Jamie Zawinski <jwz@jwz.org>. Written in late 1991; version 1.0 posted
839 to comp.sources.x on 17-Aug-1992.
840 Please let me know if you find any bugs or make any improvements.
842 And a huge thank you to the hundreds of people who have contributed, in
844 large ways and small, to the xscreensaver collection over the past two
845 decades!
846X Version 11 5.15-3.fc14 (18-Oct-2011) xscreensaver(1)