1xscreensaver(1) XScreenSaver manual xscreensaver(1)
2
6 xscreensaver - extensible screen saver and screen locking framework
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 parameter 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. Alternatively,
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: Fully uninstall the gnome-screensaver package.
172 sudo apt-get remove gnome-screensaver
173 or possibly
174 sudo dpkg -P gnome-screensaver
175 2: Launch xscreensaver at login.
177 Select "Startup Applications" from the menu (or manually launch
178 "gnome-session-properties") and add "xscreensaver".
179 Do this as your normal user account, not as root. (This should
181 go without saying, because you should never, ever, ever be
182 logged in to the graphical desktop as user "root".)
183 3: Make GNOME's "Lock Screen" use xscreensaver.
185 sudo ln -sf /usr/bin/xscreensaver-command \
186 /usr/bin/gnome-screensaver-command
187 That doesn't work under Unity, though. Apparently it has its
188 own built-in screen locker which is not gnome-screensaver, and
189 cannot be removed, and yet still manages to be bug-addled and
190 insecure. Keep reinventing that wheel, guys! (If you have fig‐
191 ured out how to replace Unity's locking "feature" with xscreen‐
192 saver, let me know.)
193 4: Turn off Unity's built-in blanking.
195 Open "System Settings / Brightness & Lock";
196 Un-check "Start Automatically";
197 Set "Turn screen off when inactive for" to "Never".
198
200 Like GNOME, KDE also decided to invent their own screen saver framework
201 from scratch instead of simply using xscreensaver. To replace the KDE
202 screen saver with xscreensaver, do the following:
203 1: Turn off KDE's screen saver.
205 Open the "Control Center" and select the "Appearance & Themes /
206 Screensaver" page. Un-check "Start Automatically".
207 Or possibly: Open "System Settings" and select "Screen Locking".
209 Un-check "Lock Screen Automatically".
210 2: Find your Autostart directory.
212 Open the "System Administration / Paths" page, and see what your
213 "Autostart path" is set to: it will probably be something like
214 ~/.kde/Autostart/ or ~/.config/autostart/
215 If that doesn't work, then try this:
217 Open "System Settings / Startup/Shutdown / Autostart", and then
219 add "/usr/bin/xscreensaver".
220 If you are lucky, that will create a xscreensaver.desktop" file
222 for you in ~/.config/autostart/ or ~/.kde/Autostart/.
223 3: Make xscreensaver be an Autostart program.
225 If it does not already exist, create a file in your autostart
226 directory called xscreensaver.desktop that contains the follow‐
227 ing six lines:
228 [Desktop Entry]
229 Exec=xscreensaver
230 Name=XScreenSaver
231 Type=Application
232 StartupNotify=false
233 X-KDE-StartupNotify=false
234 4: Make the various "lock session" buttons call xscreensaver.
236 The file you want to replace next has moved around over the
237 years. It might be called /usr/libexec/kde4/kscreenlocker, or it
238 might be called "kdesktop_lock" or "krunner_lock" or "kscreen‐
239 locker_greet", and it might be in /usr/lib/kde4/libexec/ or in
240 /usr/kde/3.5/bin/ or even in /usr/bin/, depending on the distro
241 and phase of the moon. Replace the contents of that file with
242 these two lines:
243 #!/bin/sh
244 xscreensaver-command -lock
245 Make sure the file is executable (chmod a+x).
246 Now use xscreensaver normally, controlling it via the usual xscreen‐
248 saver-demo(1) and xscreensaver-command(1) mechanisms.
249
251 If the above didn't do it, and your system has systemd(1), then give
252 this a try:
253 1: Create a service.
255 Create the file ~/.config/systemd/user/xscreensaver.service contain‐
256 ing:
257 [Unit]
258 Description=XScreenSaver
259 [Service]
260 ExecStart=/usr/bin/xscreensaver
261 [Install]
262 WantedBy=default.target
263 2. Enable it.
265 systemctl --user enable xscreensaver
266 Then restart X11.
267
269 If it's still not working, but on your distro, that newfangled sys‐
270 temd(1) nonsense has already fallen out of favor? Then maybe this will
271 work: launch the "Startup Applications" applet, click "Add", enter
272 these lines, then restart X11:
273 Name: XScreenSaver
274 Command: xscreensaver
275 Comment: xscreensaver
276
278 You can run xscreensaver from your gdm(1) session, so that the screen‐
279 saver will run even when nobody is logged in on the console. To do
280 this, run gdmconfig(1).
281 On the General page set the Local Greeter to Standard Greeter.
283 On the Background page, type the command "xscreensaver -nosplash" into
285 the Background Program field. That will cause gdm to run xscreensaver
286 while nobody is logged in, and kill it as soon as someone does log in.
287 (The user will then be responsible for starting xscreensaver on their
288 own, if they want.)
289 If that doesn't work, you can edit the config file directly. Edit
291 /etc/X11/gdm/gdm.conf to include:
292 Greeter=/usr/bin/gdmlogin
293 BackgroundProgram=xscreensaver -nosplash
294 RunBackgroundProgramAlways=true
295 In this situation, the xscreensaver process will probably be running as
296 user gdm instead of root. You can configure the settings for this
297 nobody-logged-in state (timeouts, DPMS, etc.) by editing the
298 ~gdm/.xscreensaver file.
299 It is safe to run xscreensaver as root (as xdm or gdm may do). If run
301 as root, xscreensaver changes its effective user and group ids to some‐
302 thing safe (like "nobody") before connecting to the X server or launch‐
303 ing user-specified programs.
304 An unfortunate side effect of this (important) security precaution is
306 that it may conflict with cookie-based authentication.
307 If you get "connection refused" errors when running xscreensaver from
309 gdm, then this probably means that you have xauth(1) or some other
310 security mechanism turned on. For information on the X server's access
311 control mechanisms, see the man pages for X(1), Xsecurity(1), xauth(1),
312 and xhost(1).
313
315 Bugs? There are no bugs. Ok, well, maybe. If you find one, please
316 let me know. https://www.jwz.org/xscreensaver/bugs.html explains how
317 to construct the most useful bug reports.
318 Locking and root logins
320 In order for it to be safe for xscreensaver to be launched by xdm,
321 certain precautions had to be taken, among them that xscreensaver
322 never runs as root. In particular, if it is launched as root (as
323 xdm is likely to do), xscreensaver will disavow its privileges, and
324 switch itself to a safe user id (such as nobody).
325 An implication of this is that if you log in as root on the con‐
327 sole, xscreensaver will refuse to lock the screen (because it can't
328 tell the difference between root being logged in on the console,
329 and a normal user being logged in on the console but xscreensaver
330 having been launched by the xdm(1) Xsetup file).
331 The solution to this is simple: you shouldn't be logging in on the
333 console as root in the first place! (What, are you crazy or some‐
334 thing?)
335 Proper Unix hygiene dictates that you should log in as yourself,
337 and su(1) to root as necessary. People who spend their day logged
338 in as root are just begging for disaster.
339 XAUTH and XDM
341 For xscreensaver to work when launched by xdm(1) or gdm(1), pro‐
342 grams running on the local machine as user "nobody" must be able to
343 connect to the X server. This means that if you want to run
344 xscreensaver on the console while nobody is logged in, you may need
345 to disable cookie-based access control (and allow all users who can
346 log in to the local machine to connect to the display).
347 You should be sure that this is an acceptable thing to do in your
349 environment before doing it. See the "Using GDM" section, above,
350 for more details.
351 Passwords
353 If you get an error message at startup like "couldn't get password
354 of user" then this probably means that you're on a system in which
355 the getpwent(3) library routine can only be effectively used by
356 root. If this is the case, then xscreensaver must be installed as
357 setuid to root in order for locking to work. Care has been taken
358 to make this a safe thing to do.
359 It also may mean that your system uses shadow passwords instead of
361 the standard getpwent(3) interface; in that case, you may need to
362 change some options with configure and recompile.
363 If you change your password after xscreensaver has been launched,
365 it will continue using your old password to unlock the screen until
366 xscreensaver is restarted. On some systems, it may accept both
367 your old and new passwords. So, after you change your password,
368 you'll have to do
369 xscreensaver-command -restart
370 to make xscreensaver notice.
371 PAM Passwords
373 If your system uses PAM (Pluggable Authentication Modules), then in
374 order for xscreensaver to use PAM properly, PAM must be told about
375 xscreensaver. The xscreensaver installation process should update
376 the PAM data (on Linux, by creating the file /etc/pam.d/xscreen‐
377 saver for you, and on Solaris, by telling you what lines to add to
378 the /etc/pam.conf file).
379 If the PAM configuration files do not know about xscreensaver, then
381 you might be in a situation where xscreensaver will refuse to ever
382 unlock the screen.
383 This is a design flaw in PAM (there is no way for a client to tell
385 the difference between PAM responding "I have never heard of your
386 module", and responding, "you typed the wrong password"). As far
387 as I can tell, there is no way for xscreensaver to automatically
388 work around this, or detect the problem in advance, so if you have
389 PAM, make sure it is configured correctly!
390 Machine Load
392 Although this program "nices" the subprocesses that it starts,
393 graphics-intensive subprograms can still overload the machine by
394 causing the X server process itself (which is not "niced") to con‐
395 sume many cycles. Care has been taken in all the modules shipped
396 with xscreensaver to sleep periodically, and not run full tilt, so
397 as not to cause appreciable load.
398 However, if you are running the OpenGL-based screen savers on a
400 machine that does not have a video card with 3D acceleration, they
401 will make your machine slow, despite nice(1).
402 Your options are: don't use the OpenGL display modes; or, collect
404 the spare change hidden under the cushions of your couch, and use
405 it to buy a video card manufactured after 1998. (It doesn't even
406 need to be fast 3D hardware: the problem will be fixed if there is
407 any 3D hardware at all.)
408 Magic Backdoor Keystrokes
410 The XFree86 X server and the Linux kernel both trap certain magic
411 keystrokes before X11 client programs ever see them. If you care
412 about keeping your screen locked, this is a big problem.
413 Ctrl+Alt+Backspace
415 This keystroke kills the X server, and on some systems, leaves
416 you at a text console. If the user launched X11 manually, that
417 text console will still be logged in. To disable this keystroke
418 globally and permanently, you need to set the DontZap flag in
419 your xorg.conf or XF86Config or XF86Config-4 file, depending
420 which is in use on your system. See XF86Config(5) for details.
421 Ctrl-Alt-F1, Ctrl-Alt-F2, etc.
423 These keystrokes will switch to a different virtual console,
424 while leaving the console that X11 is running on locked. If you
425 left a shell logged in on another virtual console, it is unpro‐
426 tected. So don't leave yourself logged in on other consoles.
427 You can disable VT switching globally and permanently by setting
428 DontVTSwitch in your xorg.conf, but that might make your system
429 harder to use, since VT switching is an actual useful feature.
430 There is no way to disable VT switching only when the screen is
432 locked. It's all or nothing.
433 Ctrl-Alt-KP_Multiply
435 This keystroke kills any X11 app that holds a lock, so typing
436 this will kill xscreensaver and unlock the screen. This so-
437 called "feature" showed up in the X server in 2008, and as of
438 2011, some vendors are shipping it turned on by default. How
439 nice. You can disable it by turning off AllowClosedownGrabs in
440 xorg.conf.
441 Alt-SysRq-F
443 This is the Linux kernel "OOM-killer" keystroke. It shoots down
444 random long-running programs of its choosing, and so might might
445 target and kill xscreensaver, and there's no way for xscreen‐
446 saver to protect itself from that. You can disable it globally
447 with:
448 echo 176 > /proc/sys/kernel/sysrq
449 There's little that I can do to make the screen locker be secure so
450 long as the kernel and X11 developers are actively working against
451 security like this. The strength of the lock on your front door
452 doesn't matter much so long as someone else in the house insists on
453 leaving a key under the welcome mat.
454 Dangerous Backdoor Server Extensions
456 Many distros enable by default several X11 server extensions that
457 can be used to bypass grabs, and thus snoop on you while you're
458 typing your password. These extensions are nominally for debugging
459 and automation, but they are also security-circumventing keystroke
460 loggers. If your server is configured to load the RECORD, XTRAP or
461 XTEST extensions, you absolutely should disable those, 100% of the
462 time. Look for them in xorg.conf or whatever it is called.
463
465 These are the X resources use by the xscreensaver program. You proba‐
466 bly won't need to change these manually (that's what the xscreen‐
467 saver-demo(1) program is for).
468 timeout (class Time)
470 The screensaver will activate (blank the screen) after the key‐
471 board and mouse have been idle for this many minutes. Default
472 10 minutes.
473 cycle (class Time)
475 After the screensaver has been running for this many minutes,
476 the currently running graphics-hack sub-process will be killed
477 (with SIGTERM), and a new one started. If this is 0, then the
478 graphics hack will never be changed: only one demo will run
479 until the screensaver is deactivated by user activity. Default
480 10 minutes.
481 The running saver will be restarted every cycle minutes even
483 when mode is one, since some savers tend to converge on a
484 steady state.
485 lock (class Boolean)
487 Enable locking: before the screensaver will turn off, it will
488 require you to type the password of the logged-in user (really,
489 the person who ran xscreensaver), or the root password. (Note:
490 this doesn't work if the screensaver is launched by xdm(1)
491 because it can't know the user-id of the logged-in user. See
492 the "Using XDM(1)" section, below.
493 lockTimeout (class Time)
495 If locking is enabled, this controls the length of the "grace
496 period" between when the screensaver activates, and when the
497 screen becomes locked. For example, if this is 5, and -timeout
498 is 10, then after 10 minutes, the screen would blank. If there
499 was user activity at 12 minutes, no password would be required
500 to un-blank the screen. But, if there was user activity at 15
501 minutes or later (that is, -lock-timeout minutes after activa‐
502 tion) then a password would be required. The default is 0,
503 meaning that if locking is enabled, then a password will be
504 required as soon as the screen blanks.
505 passwdTimeout (class Time)
507 If the screen is locked, then this is how many seconds the
508 password dialog box should be left on the screen before giving
509 up (default 30 seconds). This should not be too large: the X
510 server is grabbed for the duration that the password dialog box
511 is up (for security purposes) and leaving the server grabbed
512 for too long can cause problems.
513 dpmsEnabled (class Boolean)
515 Whether power management is enabled.
516 dpmsStandby (class Time)
518 If power management is enabled, how long until the monitor goes
519 solid black.
520 dpmsSuspend (class Time)
522 If power management is enabled, how long until the monitor goes
523 into power-saving mode.
524 dpmsOff (class Time)
526 If power management is enabled, how long until the monitor pow‐
527 ers down completely. Note that these settings will have no
528 effect unless both the X server and the display hardware sup‐
529 port power management; not all do. See the Power Management
530 section, below, for more information.
531 dpmsQuickOff (class Boolean)
533 If mode is blank and this is true, then the screen will be pow‐
534 ered down immediately upon blanking, regardless of other power-
535 management settings.
536 visualID (class VisualID)
538 This is an historical artifacts left over from when 8-bit dis‐
539 plays were still common. You should probably ignore this.
540 Specify which X visual to use by default. (Note carefully that
542 this resource is called visualID, not merely visual; if you set
543 the visual resource instead, things will malfunction in obscure
544 ways for obscure reasons.)
545 Legal values for the VisualID resource are:
547 default Use the screen's default visual (the visual of the root
549 window). This is the default.
550 best Use the visual which supports the most colors. Note,
552 however, that the visual with the most colors might be
553 a TrueColor visual, which does not support colormap
554 animation. Some programs have more interesting behav‐
555 ior when run on PseudoColor visuals than on TrueColor.
556 mono Use a monochrome visual, if there is one.
558 gray Use a grayscale or staticgray visual, if there is one
560 and it has more than one plane (that is, it's not mono‐
561 chrome).
562 color Use the best of the color visuals, if there are any.
564 GL Use the visual that is best for OpenGL programs.
566 (OpenGL programs have somewhat different requirements
567 than other X programs.)
568 class where class is one of StaticGray, StaticColor, True‐
570 Color, GrayScale, PseudoColor, or DirectColor. Selects
571 the deepest visual of the given class.
572 number where number (decimal or hex) is interpreted as a vis‐
574 ual id number, as reported by the xdpyinfo(1) program;
575 in this way you can have finer control over exactly
576 which visual gets used, for example, to select a shal‐
577 lower one than would otherwise have been chosen.
578 Note that this option specifies only the default visual that
580 will be used: the visual used may be overridden on a program-
581 by-program basis. See the description of the programs
582 resource, below.
583 installColormap (class Boolean)
585 On PseudoColor (8-bit) displays, install a private colormap
586 while the screensaver is active, so that the graphics hacks can
587 get as many colors as possible. This is the default. (This
588 only applies when the screen's default visual is being used,
589 since non-default visuals get their own colormaps automati‐
590 cally.) This can also be overridden on a per-hack basis: see
591 the discussion of the default-n name in the section about the
592 programs resource.
593 This does nothing if you have a TrueColor (16-bit or deeper)
595 display. (Which, in this century, you do.)
596 verbose (class Boolean)
598 Whether to print diagnostics. Default false.
599 timestamp (class Boolean)
601 Whether to print the time of day along with any other diagnos‐
602 tic messages. Default true.
603 splash (class Boolean)
605 Whether to display a splash screen at startup. Default true.
606 splashDuration (class Time)
608 How long the splash screen should remain visible; default 5
609 seconds.
610 helpURL (class URL)
612 The splash screen has a Help button on it. When you press it,
613 it will display the web page indicated here in your web
614 browser.
615 loadURL (class LoadURL)
617 This is the shell command used to load a URL into your web
618 browser. The default setting will load it into Mozilla/Net‐
619 scape if it is already running, otherwise, will launch a new
620 browser looking at the helpURL.
621 demoCommand (class DemoCommand)
623 This is the shell command run when the Demo button on the
624 splash window is pressed. It defaults to xscreensaver-demo(1).
625 prefsCommand (class PrefsCommand)
627 This is the shell command run when the Prefs button on the
628 splash window is pressed. It defaults to xscreen‐
629 saver-demo -prefs.
630 newLoginCommand (class NewLoginCommand)
632 If set, this is the shell command that is run when the "New
633 Login" button is pressed on the unlock dialog box, in order to
634 create a new desktop session without logging out the user who
635 has locked the screen. Typically this will be some variant of
636 gdmflexiserver(1), kdmctl(1), lxdm(1) or dm-tool(1).
637 nice (class Nice)
639 The sub-processes created by xscreensaver will be "niced" to
640 this level, so that they are given lower priority than other
641 processes on the system, and don't increase the load unneces‐
642 sarily. The default is 10. (Higher numbers mean lower prior‐
643 ity; see nice(1) for details.)
644 fade (class Boolean)
646 If this is true, then when the screensaver activates, the cur‐
647 rent contents of the screen will fade to black instead of sim‐
648 ply winking out. This only works on certain systems. A fade
649 will also be done when switching graphics hacks (when the cycle
650 timer expires). Default: true.
651 unfade (class Boolean)
653 If this is true, then when the screensaver deactivates, the
654 original contents of the screen will fade in from black instead
655 of appearing immediately. This only works on certain systems,
656 and if fade is true as well. Default false.
657 fadeSeconds (class Time)
659 If fade is true, this is how long the fade will be in seconds
660 (default 3 seconds).
661 fadeTicks (class Integer)
663 If fade is true, this is how many times a second the colormap
664 will be changed to effect a fade. Higher numbers yield
665 smoother fades, but may make the fades take longer than the
666 specified fadeSeconds if your server isn't fast enough to keep
667 up. Default 20.
668 captureStderr (class Boolean)
670 Whether xscreensaver should redirect its stdout and stderr
671 streams to the window itself. Since its nature is to take over
672 the screen, you would not normally see error messages generated
673 by xscreensaver or the sub-programs it runs; this resource will
674 cause the output of all relevant programs to be drawn on the
675 screensaver window itself, as well as being written to the con‐
676 trolling terminal of the screensaver driver process. Default
677 true.
678 ignoreUninstalledPrograms (class Boolean)
680 There may be programs in the list that are not installed on the
681 system, yet are marked as "enabled". If this preference is
682 true, then such programs will simply be ignored. If false,
683 then a warning will be printed if an attempt is made to run the
684 nonexistent program. Also, the xscreensaver-demo(1) program
685 will suppress the non-existent programs from the list if this
686 is true. Default: false.
687 authWarningSlack (class Integer)
689 If all failed unlock attempts (incorrect password entered) were
690 made within this period of time, the usual dialog that warns
691 about such attempts after a successful login will be sup‐
692 pressed. The assumption is that incorrect passwords entered
693 within a few seconds of a correct one are user error, rather
694 than hostile action. Default 20 seconds.
695 GetViewPortIsFullOfLies (class Boolean)
697 Set this to true if the xscreensaver window doesn't cover the
698 whole screen. This works around a longstanding XFree86 bug
699 #421. See the xscreensaver FAQ for details.
700 font (class Font)
702 The font used for the stdout/stderr text, if captureStderr is
703 true. Default *-medium-r-*-140-*-m-* (a 14 point fixed-width
704 font).
705 mode (class Mode)
707 Controls the behavior of xscreensaver. Legal values are:
708 random When blanking the screen, select a random display mode
710 from among those that are enabled and applicable. This
711 is the default.
712 random-same
714 Like random, but if there are multiple screens, each
715 screen will run the same random display mode, instead
716 of each screen running a different one.
717 one When blanking the screen, only ever use one particular
719 display mode (the one indicated by the selected set‐
720 ting).
721 blank When blanking the screen, just go black: don't run any
723 graphics hacks.
724 off Don't ever blank the screen, and don't ever allow the
726 monitor to power down.
727 selected (class Integer)
730 When mode is set to one, this is the one, indicated by its
731 index in the programs list. You're crazy if you count them and
732 set this number by hand: let xscreensaver-demo(1) do it for
733 you!
734 programs (class Programs)
736 The graphics hacks which xscreensaver runs when the user is
737 idle. The value of this resource is a multi-line string, one
738 sh-syntax command per line. Each line must contain exactly one
739 command: no semicolons, no ampersands.
740 When the screensaver starts up, one of these is selected
742 (according to the mode setting), and run. After the cycle
743 period expires, it is killed, and another is selected and run.
744 If a line begins with a dash (-) then that particular program
746 is disabled: it won't be selected at random (though you can
747 still select it explicitly using the xscreensaver-demo(1) pro‐
748 gram).
749 If all programs are disabled, then the screen will just be made
751 blank, as when mode is set to blank.
752 To disable a program, you must mark it as disabled with a dash
754 instead of removing it from the list. This is because the sys‐
755 tem-wide (app-defaults) and per-user (.xscreensaver) settings
756 are merged together, and if a user just deletes an entry from
757 their programs list, but that entry still exists in the system-
758 wide list, then it will come back. However, if the user dis‐
759 ables it, then their setting takes precedence.
760 If the display has multiple screens, then a different program
762 will be run for each screen. (All screens are blanked and
763 unblanked simultaneously.)
764 Note that you must escape the newlines; here is an example of
766 how you might set this in your ~/.xscreensaver file:
767 programs: \
769 qix -root \n\
770 ico -r -faces -sleep 1 -obj ico \n\
771 xdaliclock -builtin2 -root \n\
772 xv -root -rmode 5 image.gif -quit \n
773 Make sure your $PATH environment variable is set up correctly
774 before xscreensaver is launched, or it won't be able to find
775 the programs listed in the programs resource.
776 To use a program as a screensaver, two things are required:
778 that that program draw on the root window (or be able to be
779 configured to draw on the root window); and that that program
780 understand "virtual root" windows, as used by virtual window
781 managers such as tvtwm(1). (Generally, this is accomplished by
782 just including the "vroot.h" header file in the program's
783 source.)
784 Visuals:
786 Because xscreensaver was created back when dinosaurs roamed the
788 earth, it still contains support for some things you've proba‐
789 bly never seen, such as 1-bit monochrome monitors, grayscale
790 monitors, and monitors capable of displaying only 8-bit col‐
791 ormapped images.
792 If there are some programs that you want to run only when using
794 a color display, and others that you want to run only when
795 using a monochrome display, you can specify that like this:
796 mono: mono-program -root \n\
797 color: color-program -root \n\
798 More generally, you can specify the kind of visual that should
799 be used for the window on which the program will be drawing.
800 For example, if one program works best if it has a colormap,
801 but another works best if it has a 24-bit visual, both can be
802 accommodated:
803 PseudoColor: cmap-program -root \n\
804 TrueColor: 24bit-program -root \n\
805 In addition to the symbolic visual names described above (in
806 the discussion of the visualID resource) one other visual name
807 is supported in the programs list:
808 default-n
810 This is like default, but also requests the use of the
811 default colormap, instead of a private colormap. (That
812 is, it behaves as if the -no-install command-line option
813 was specified, but only for this particular hack.) This
814 is provided because some third-party programs that draw on
815 the root window (notably: xv(1), and xearth(1)) make
816 assumptions about the visual and colormap of the root win‐
817 dow: assumptions which xscreensaver can violate.
818 If you specify a particular visual for a program, and that vis‐
820 ual does not exist on the screen, then that program will not be
821 chosen to run. This means that on displays with multiple
822 screens of different depths, you can arrange for appropriate
823 hacks to be run on each. For example, if one screen is color
824 and the other is monochrome, hacks that look good in mono can
825 be run on one, and hacks that only look good in color will show
826 up on the other.
827 You shouldn't ever need to change the following resources:
829 pointerPollTime (class Time)
831 When server extensions are not in use, this controls how fre‐
832 quently xscreensaver checks to see if the mouse position or
833 buttons have changed. Default 5 seconds.
834 pointerHysteresis (class Integer)
836 If the mouse moves less than this-many pixels in a second,
837 ignore it (do not consider that to be "activity"). This is so
838 that the screen doesn't un-blank (or fail to blank) just
839 because you bumped the desk. Default: 10 pixels.
840 windowCreationTimeout (class Time)
842 When server extensions are not in use, this controls the delay
843 between when windows are created and when xscreensaver selects
844 events on them. Default 30 seconds.
845 initialDelay (class Time)
847 When server extensions are not in use, xscreensaver will wait
848 this many seconds before selecting events on existing windows,
849 under the assumption that xscreensaver is started during your
850 login procedure, and the window state may be in flux. Default
851 0. (This used to default to 30, but that was back in the days
852 when slow machines and X terminals were more common...)
853 procInterrupts (class Boolean)
855 This resource controls whether the /proc/interrupts file should
856 be consulted to decide whether the user is idle. This is the
857 default if xscreensaver has been compiled on a system which
858 supports this mechanism (i.e., Linux systems).
859 The benefit to doing this is that xscreensaver can note that
861 the user is active even when the X console is not the active
862 one: if the user is typing in another virtual console, xscreen‐
863 saver will notice that and will fail to activate. For example,
864 if you're playing Quake in VGA-mode, xscreensaver won't wake up
865 in the middle of your game and start competing for CPU.
866 The drawback to doing this is that perhaps you really do want
868 idleness on the X console to cause the X display to lock, even
869 if there is activity on other virtual consoles. If you want
870 that, then set this option to False. (Or just lock the X con‐
871 sole manually.)
872 The default value for this resource is True, on systems where
874 it works.
875 overlayStderr (class Boolean)
877 If captureStderr is True, and your server supports "overlay"
878 visuals, then the text will be written into one of the higher
879 layers instead of into the same layer as the running screen‐
880 hack. Set this to False to disable that (though you shouldn't
881 need to).
882 overlayTextForeground (class Foreground)
884 The foreground color used for the stdout/stderr text, if cap‐
885 tureStderr is true. Default: Yellow.
886 overlayTextBackground (class Background)
888 The background color used for the stdout/stderr text, if cap‐
889 tureStderr is true. Default: Black.
890 bourneShell (class BourneShell)
892 The pathname of the shell that xscreensaver uses to start sub‐
893 processes. This must be whatever your local variant of /bin/sh
894 is: in particular, it must not be csh.
895
897 DISPLAY to get the default host and display number, and to inform the
898 sub-programs of the screen on which to draw.
899 XSCREENSAVER_WINDOW
901 Passed to sub-programs to indicate the ID of the window on
902 which they should draw. This is necessary on Xinerama/RANDR
903 systems where multiple physical monitors share a single X11
904 "Screen".
905 PATH to find the sub-programs to run.
907 HOME for the directory in which to read the .xscreensaver file.
909 XENVIRONMENT
911 to get the name of a resource file that overrides the global
912 resources stored in the RESOURCE_MANAGER property.
913
915 The latest version of xscreensaver, an online version of this manual,
916 and a FAQ can always be found at https://www.jwz.org/xscreensaver/
917
919 X(1), Xsecurity(1), xauth(1), xdm(1), gdm(1), xhost(1), xscreen‐
920 saver-demo(1), xscreensaver-command(1), xscreensaver-gl-helper(1),
921 xscreensaver-getimage(1), xscreensaver-text(1).
922
924 Copyright © 1991-2018 by Jamie Zawinski. Permission to use, copy, mod‐
925 ify, distribute, and sell this software and its documentation for any
926 purpose is hereby granted without fee, provided that the above copy‐
927 right notice appear in all copies and that both that copyright notice
928 and this permission notice appear in supporting documentation. No rep‐
929 resentations are made about the suitability of this software for any
930 purpose. It is provided "as is" without express or implied warranty.
931
933 Jamie Zawinski <jwz@jwz.org>. Written in late 1991; version 1.0 posted
934 to comp.sources.x on 17-Aug-1992.
935 Please let me know if you find any bugs or make any improvements.
937 And a huge thank you to the hundreds of people who have contributed, in
939 large ways and small, to the xscreensaver collection over the past two
940 decades!
941X Version 11 5.42-1.fc29 (30-Dec-2018) xscreensaver(1)