1XScreenSaver(1) General Commands Manual XScreenSaver(1)
2
6 xscreensaver - extensible screen saver and screen locking framework
7
9 xscreensaver [--display host:display.screen] [--verbose] [--no-splash]
10 [--log filename]
11
13 XScreenSaver waits until the user is idle, and then runs graphics demos
14 chosen at random. It can also lock your screen, and provides configu‐
15 ration and control of display power management.
16 XScreenSaver is also available on macOS, iOS and Android.
18
20 XScreenSaver is a daemon that runs in the background. You configure it
21 with the xscreensaver-settings(1) program.
22 xscreensaver &
24 xscreensaver-settings
25
29 When it is time to activate the screensaver, a full-screen black window
30 is created that covers each monitor. A sub-process is launched for
31 each one running a graphics demo, pointed at the appropriate window.
32 Because of this, any program which can draw on a provided window can be
33 used as a screensaver. The various graphics demos are, in fact, just
34 standalone programs that do that.
35 When the user becomes active again, the screensaver windows are un‐
37 mapped, and the running subprocesses are killed.
38 The display modes are run at a low process priority, and spend most of
40 their time sleeping/idle by default, so they should not consume signif‐
41 icant system resources.
42
45 --display host:display.screen
46 The X display to use. For displays with multiple screens,
47 XScreenSaver will manage all screens on the display simultane‐
48 ously.
49 --verbose
51 Print diagnostics to stderr.
52 --log filename
54 Append all diagnostic output to the given file. This also im‐
55 plies --verbose. Use this when reporting bugs.
56 --no-splash
58 Don't display the splash screen at startup.
59
62 The xscreensaver-settings(1) program is where you configure if and when
63 your monitor should power off. It saves the settings in your
64 ~/.xscreensaver file.
65 If the power management section is grayed out in the xscreensaver-set‐
67 tings(1) window, then that means that your X server does not support
68 the XDPMS extension, and so control over the monitor's power state is
69 not available.
70 When the monitor is powered down, the display hacks are stopped (though
72 it may take a minute or two for XScreenSaver to notice).
73 Note: if you use xset(1) to change the power management settings,
75 XScreenSaver will override those changes. Whatever is in the
76 ~/.xscreensaver file takes precedence.
77
80 If your system has systemd(1) 221 or newer, or elogind(8), then closing
81 the lid of your laptop will cause the screen to lock immediately.
82 If not, then the screen might not lock until a few seconds after you
84 re-open the lid. Which is less than ideal. So if you don't use sys‐
85 temd, you might want to get in the habit of doing xscreensaver-command
86 --lock before closing the lid.
87
90 Likewise, if you have systemd(1) 221 or newer, or elogind(8), then all
91 of the popular video players and web browsers will prevent XScreenSaver
92 from blanking the screen while video is playing.
93 Both of these features require that xscreensaver-systemd(6) be able
95 connect to the systemd bus. Parts of KDE and GNOME may need to be dis‐
96 abled first for that to work; see below.
97
100 Each desktop environment has its own system for launching long-running
101 daemons like XScreenSaver, and since many of them come bundled with
102 their own (buggy, insecure, inferior) screen-locking frameworks, it is
103 also necessary to disable those other frameworks before XScreenSaver
104 can work.
105 INSTALLING XSCREENSAVER ON GNOME OR UNITY
108 For many years, GNOME shipped XScreenSaver as-is, and everything just
109 worked. In 2005, however, they decided to needlessly re-invent the
110 wheel and ship their own replacement for the xscreensaver daemon called
111 gnome-screensaver(1) rather than improving XScreenSaver and contribut‐
112 ing their changes back. As a result, the gnome-screensaver program is
113 insecure, bug-ridden, and missing many features of XScreenSaver. In
114 fact, in 2011 it lost the ability to run display modes at all.
115 In 2012 some distros forked and renamed it as both mate-screensaver(1)
117 and cinnamon-screensaver(1), which seem to be basically the same.
118 To replace gnome-screensaver with XScreenSaver:
120 1: Fully uninstall the other screen saver packages:
122 sudo apt-get remove gnome-screensaver
124 sudo apt-get remove mate-screensaver
125 sudo apt-get remove cinnamon-screensaver
126 or
127 sudo rpm -e gnome-screensaver
128 sudo rpm -e mate-screensaver
129 sudo rpm -e cinnamon-screensaver
130 Be careful that it doesn't try to uninstall all of GNOME.
132 2: Launch XScreenSaver at login.
135 Select "Startup Applications" from the menu (or manually launch
137 "gnome-session-properties") and add "xscreensaver". Do this as
138 your normal user account, not as root.
139 3: Make GNOME's "Lock Screen" use XScreenSaver.
141 sudo ln -sf /usr/bin/xscreensaver-command \
143 /usr/bin/gnome-screensaver-command
144 4: Turn off Unity's built-in blanking.
147 Open "System Settings / Brightness & Lock";
149 Un-check "Start Automatically";
150 Set "Turn screen off when inactive for" to "Never".
151 Or possibly that has been randomly renamed again:
153 Set "Settings / Power / Power Settings" to "Never".
154 5: Stop GNOME from blocking XScreenSaver's "systemd" integration:
156 sudo systemctl --user mask gsd-screensaver-proxy.service
158 sudo systemctl --user mask \
159 org.gnome.SettingsDaemon.ScreensaverProxy.service
160 Without the above, video players will not be able to tell
162 XScreenSaver not to blank the screen while videos are playing,
163 and the screen will not auto-lock when you close your laptop's
164 lid.
165 After running those commands, reboot. Yes, you have to reboot;
167 it won't let you simply stop the service. Logging out won't do
168 it either.
169 INSTALLING XSCREENSAVER ON KDE
172 Like GNOME, KDE also decided to invent their own screen saver framework
173 from scratch instead of simply using XScreenSaver. To replace the KDE
174 screen saver with XScreenSaver, do the following:
175 1: Turn off KDE's screen saver.
177 Open the "Control Center" and select the "Appearance & Themes /
178 Screensaver" page. Un-check "Start Automatically".
179 Or possibly: Open "System Settings" and select "Screen Locking".
181 Un-check "Lock Screen Automatically".
182 2: Find your Autostart directory.
184 Open the "System Administration / Paths" page, and see what your
185 "Autostart path" is set to: it will probably be something like
186 ~/.kde/Autostart/ or ~/.config/autostart/
187 If that doesn't work, then try this:
189 Open "System Settings / Startup/Shutdown / Autostart", and then
191 add "/usr/bin/xscreensaver".
192 If you are lucky, that will create an "xscreensaver.desktop"
194 file for you in ~/.config/autostart/ or ~/.kde/Autostart/.
195 3: Make XScreenSaver be an Autostart program.
197 If it does not already exist, create a file in your autostart
198 directory called xscreensaver.desktop that contains the follow‐
199 ing six lines:
200 [Desktop Entry]
202 Exec=xscreensaver
203 Name=XScreenSaver
204 Type=Application
205 StartupNotify=false
206 X-KDE-StartupNotify=false
207 4: Make the various "lock session" buttons call XScreenSaver.
210 The file you want to replace next has moved around over the
211 years. It might be called /usr/libexec/kde4/kscreenlocker, or it
212 might be called "kdesktop_lock" or "krunner_lock" or "kscreen‐
213 locker_greet", and it might be in /usr/lib/kde4/libexec/ or in
214 /usr/kde/3.5/bin/ or even in /usr/bin/, depending on the distro
215 and phase of the moon. Replace the contents of that file with
216 these two lines:
217 #!/bin/sh
219 xscreensaver-command --lock
220 Make sure the file is executable (chmod a+x).
222 This change will probably get blown away the next time your sys‐
224 tem upgrades KDE.
225 5: Stop KDE from blocking XScreenSaver's "systemd" integration:
227 You must arrange for KDE's ksmserver(1) daemon to be launched
228 with the command line option --no-lockscreen.
229 Under KDE 5.00 through 5.16, you can accomplish that by editing
231 the startkde(1) script in /usr/bin/ by hand, then logging out
232 and back in again.
233 Under KDE 5.17 through 5.20, you must wrap ksmserver(1) instead:
235 mv /usr/bin/ksmserver /usr/bin/ksmserver-orig
237 and replace /usr/bin/ksmserver with:
239 #!/bin/sh
241 ksmserver-orig --no-lockscreen
242 Either change will, of course, get blown away the next time your
244 system upgrades KDE.
245 Instead of being in /usr/bin/, the ksmserver program might be in
247 /usr/lib/ or /usr/lib*/libexec/ or usr/lib/*/libexec/ or some‐
248 where else, depending on your distro.
249 Under KDE 5.21+ this might work instead, and might persist
251 through upgrades:
252 systemctl edit plasma-ksmserver.service
254 and then put this in the file you get to edit:
256 [Service]
258 ExecStart=/usr/bin/ksmserver --no-lockscreen
259 Regardless of which approach you need to use, if you do not
261 force ksmserver(1) to stop squatting on the DBus endpoint, video
262 players will not be able to tell XScreenSaver not to blank the
263 screen while videos are playing, and the screen will not auto-
264 lock when you close your laptop's lid.
265 LAUNCHING XSCREENSAVER FROM SYSTEMD
267 If the above didn't do it, and your system has systemd(1), maybe this
268 is how it works:
269 1: Create a service.
271 Create the file ~/.config/systemd/user/xscreensaver.service con‐
272 taining:
273 [Unit]
275 Description=XScreenSaver
276 [Service]
277 ExecStart=/usr/bin/xscreensaver
278 Restart=on-failure
279 [Install]
280 WantedBy=default.target
281 2. Enable it.
284 systemctl --user enable xscreensaver
286 Then restart X11.
288 LAUNCHING XSCREENAVER FROM UPSTART
291 If your system has upstart(7) instead of systemd(1), maybe this will
292 work: launch the "Startup Applications" applet, click "Add", enter
293 these lines, then restart X11:
294 Name: XScreenSaver
296 Command: xscreensaver
297 Comment: XScreenSaver
298 LAUNCHING XSCREENSAVER FROM GDM
302 You can run xscreensaver from your gdm(1) session, so that the screen‐
303 saver will run even when nobody is logged in on the console. To do
304 this, run gdmconfig(1).
305 On the General page set the Local Greeter to Standard Greeter.
307 On the Background page, type the command "xscreensaver --nosplash" into
309 the Background Program field. That will cause gdm to run XScreenSaver
310 while nobody is logged in, and kill it as soon as someone does log in.
311 (The user will then be responsible for starting XScreenSaver on their
312 own, if they want.)
313 If that doesn't work, you can edit the config file directly. Edit
315 /etc/X11/gdm/gdm.conf to include:
316 Greeter=/usr/bin/gdmlogin
318 BackgroundProgram=xscreensaver --nosplash
319 RunBackgroundProgramAlways=true
320 In this situation, the xscreensaver process will probably be running as
322 user gdm instead of as root. You can configure the settings for this
323 nobody-logged-in state (timeouts, DPMS, etc.) by editing the
324 ~gdm/.xscreensaver file.
325 It is safe to run xscreensaver as root (as xdm or gdm may do). If run
327 as root, xscreensaver changes its effective user and group ids to some‐
328 thing safe (like "nobody") before connecting to the X server or launch‐
329 ing user-specified programs.
330 An unfortunate side effect of this (important) security precaution is
332 that it may conflict with cookie-based authentication.
333 If you get "connection refused" errors when running xscreensaver from
335 gdm, then this probably means that you have xauth(1) or some other se‐
336 curity mechanism turned on. For information on the X server's access
337 control mechanisms, see the man pages for X(1), Xsecurity(1), xauth(1),
338 and xhost(1).
339 LAPTOP LIDS WITHOUT SYSTEMD
342 BSD systems or other systems without systemd(1) or elogind(8) might
343 have luck by adding xscreensaver-command --suspend to some appropriate
344 spot in /etc/acpi/events/anything or in /etc/acpi/handler.sh, if those
345 files exist.
346
349 Wayland is a completely different window system that is intended to re‐
350 place X11. After 13+ years of trying, some Linux distros have finally
351 begun enabling it by default. Most deployments of it also include
352 XWayland, which is a compatibility layer that allows some X11 programs
353 to continue to work within a Wayland environment.
354 Unfortunately, XScreenSaver is not one of those programs.
356 If your system is running XWayland, XScreenSaver will malfunction in
358 two ways:
359 1: It will be unable to detect user activity in non-X11 programs.
361 This means that while a native Wayland program is selected, XScreen‐
363 Saver will think that you are idle, and may blank the screen prema‐
364 turely.
365 2: It will be unable to lock the screen.
367 This is because X11 grabs don't work properly under XWayland, so
369 there is no way for XScreenSaver to prevent the user from switching
370 away from the screen locker to another application.
371 In short, for XScreenSaver to work properly, you will need to switch
373 off Wayland and use the X Window System like in the "good old days".
374 TO DISABLE WAYLAND UNDER GNOME
376 The login screen should have a gear-icon menu that lets you change the
377 session type from "GNOME" (the Wayland session) to "GNOME on Xorg" (the
378 X11 session).
379 Alternately, edit /etc/gdm/custom.conf and make sure it includes this
381 line:
382 WaylandEnable=false
384 TO DISABLE WAYLAND UNDER KDE
386 The login screen should have a menu that lets you change the session
387 type to "Plasma (X11)".
388 Alternately, edit /etc/sddm.conf and change the SessionDir line under
390 the [Wayland] section to say:
391 SessionDir=/dev/null
393
396 XScreenSaver has a decades-long track record of securely locking your
397 screen. However, there are many things that can go wrong. X11 is a
398 very old system, and has a number of design flaws that make it suscep‐
399 tible to foot-shooting.
400 MAGIC BACKDOOR KEYSTROKES
402 The XFree86 and Xorg X servers, as well as the Linux kernel, both trap
403 certain magic keystrokes before X11 client programs ever see them. If
404 you care about keeping your screen locked, this is a big problem.
405 Ctrl+Alt+Backspace
408 This keystroke kills the X server, and on some systems, leaves you
409 at a text console. If the user launched X11 manually, that text
410 console will still be logged in. To disable this keystroke globally
411 and permanently, you need to set the DontZap flag in your xorg.conf
412 or XF86Config or XF86Config-4 file, depending which is in use on
413 your system. See XF86Config(5) for details.
414 Ctrl-Alt-F1, Ctrl-Alt-F2, etc.
417 These keystrokes will switch to a different virtual console, while
418 leaving the console that X11 is running on locked. If you left a
419 shell logged in on another virtual console, it is unprotected. So
420 don't leave yourself logged in on other consoles. You can disable
421 VT switching globally and permanently by setting DontVTSwitch in
422 your xorg.conf, but that might make your system harder to use, since
423 VT switching is an actual useful feature.
424 There is no way to disable VT switching only when the screen is
426 locked. It's all or nothing.
427 Ctrl-Alt-KP_Multiply
430 This keystroke kills any X11 app that holds a lock, so typing this
431 will kill XScreenSaver and unlock the screen. You can disable it by
432 turning off AllowClosedownGrabs in xorg.conf.
433 Alt-SysRq-F
436 This is the Linux kernel "OOM-killer" keystroke. It shoots down
437 random long-running programs of its choosing, and so might target
438 and kill XScreenSaver. You can disable this keystroke globally
439 with:
440 echo 176 > /proc/sys/kernel/sysrq
442 There's little that I can do to make the screen locker be secure so
444 long as the kernel and X11 developers are actively working against
445 security like this. The strength of the lock on your front door
446 doesn't matter much so long as someone else in the house insists on
447 leaving a key under the welcome mat.
448 THE OOM-KILLER
450 Even if you have disabled the Alt-SysRq-F OOM-killer keystroke, the
451 OOM-killer might still decide to assassinate XScreenSaver at random,
452 which will unlock your screen. If the xscreensaver-auth(6) program is
453 installed setuid, it attempts to tell the OOM-killer to leave the
454 XScreenSaver daemon alone, but that may or may not work.
455 You would think that the OOM-killer would pick the process using the
457 most memory, but most of the time it seems to pick the process that
458 would be most comically inconvenient, such as your screen locker, or
459 crond(8). You can disable the OOM-killer entirely with:
460 echo 2 > /proc/sys/vm/overcommit_memory
462 echo vm.overcommit_memory = 2 >> /etc/sysctl.conf
463 X SERVER ACCESS IS GAME OVER
467 X11's security model is all-or-nothing. If a program can connect to
468 your X server at all, either locally or over the network, it can log
469 all of your keystrokes, simulate keystrokes, launch arbitrary programs,
470 and change the settings of other programs. Assume that anything that
471 can connect to your X server can execute arbitrary code as the logged-
472 in user. See Xsecurity(1) and xauth(1).
473 PAM PASSWORDS
476 If your system uses PAM (Pluggable Authentication Modules), then PAM
477 must be configured for XScreenSaver. If it is not, then you might be
478 in a situation where you can't unlock. Probably the file you need is
479 /etc/pam.d/xscreensaver.
480 DON'T LOG IN AS ROOT
483 In order for it to be safe for XScreenSaver to be launched by xdm, cer‐
484 tain precautions had to be taken, among them that XScreenSaver never
485 runs as root. In particular, if it is launched as root (as xdm is
486 likely to do), XScreenSaver will disavow its privileges, and switch it‐
487 self to a safe user id (such as nobody).
488 An implication of this is that if you log in as root on the console,
490 XScreenSaver will refuse to lock the screen (because it can't tell the
491 difference between root being logged in on the console, and a normal
492 user being logged in on the console but XScreenSaver having been
493 launched by the xdm(1) Xsetup file).
494 Proper Unix hygiene dictates that you should log in as yourself, and
496 sudo(1) to root as necessary. People who spend their day logged in as
497 root are just begging for disaster.
498
501 For a single user, the proper way to configure XScreenSaver is to sim‐
502 ply run the xscreensaver-settings(1) program, and change the settings
503 through the GUI. The rest of this manual describes lower-level ways of
504 changing settings. You shouldn't need to know any of the stuff de‐
505 scribed below unless you are trying to do something complicated.
506 Options to XScreenSaver are stored in one of two places: in a file
508 called .xscreensaver in your home directory; or in the X resource
509 database. If the .xscreensaver file exists, it overrides any settings
510 in the resource database.
511 The syntax of the .xscreensaver file is similar to that of the .Xde‐
513 faults file; for example, to set the timeout parameter n the .xscreen‐
514 saver file, you would write the following:
515 timeout: 5
517 whereas, in the .Xdefaults file, you would write
519 xscreensaver.timeout: 5
521 If you change a setting in the .xscreensaver file while XScreenSaver is
523 already running, it will notice this, and reload the file as needed.
524 If you change a setting in your X resource database, or if you want
526 XScreenSaver to notice your changes immediately instead of the next
527 time it wakes up, then you will need to reload your .Xdefaults file,
528 and then tell the running xscreensaver process to restart itself, like
529 so:
530 xrdb < ~/.Xdefaults
532 xscreensaver-command --restart
533 If you want to set the system-wide defaults, then make your edits to
535 the XScreenSaver app-defaults file, which should have been installed
536 when XScreenSaver itself was installed. The app-defaults file will
537 usually be named /etc/X11/app-defaults/XScreenSaver, but different sys‐
538 tems might keep it in a different place.
539 When settings are changed in the Preferences dialog box, those settings
541 are written to the .xscreensaver file. The .Xdefaults file and the
542 app-defaults file will never be written by XScreenSaver itself.
543
546 These are the X resources use by XScreenSaver program. You probably
547 won't need to change these manually: that's what the xscreensaver-set‐
548 tings(1) program is for.
549 timeout (class Time)
552 The screensaver will activate (blank the screen) after the key‐
553 board and mouse have been idle for this many minutes. Default
554 10 minutes.
555 cycle (class Time)
558 After the screensaver has been running for this many minutes,
559 the currently running graphics-hack sub-process will be killed
560 (with SIGTERM), and a new one started. If this is 0, then the
561 graphics hack will never be changed: only one demo will run un‐
562 til the screensaver is deactivated by user activity. Default
563 10 minutes.
564 If there are multiple screens, the savers are staggered
566 slightly so that while they all change every cycle minutes,
567 they don't all change at the same time.
568 lock (class Boolean)
571 Enable locking: before the screensaver will turn off, it will
572 require you to type the password of the logged-in user.
573 lockTimeout (class Time)
576 If locking is enabled, this controls the length of the "grace
577 period" between when the screensaver activates, and when the
578 screen becomes locked. For example, if this is 5, and timeout
579 is 10, then after 10 minutes, the screen would blank. If there
580 was user activity at 12 minutes, no password would be required
581 to un-blank the screen. But, if there was user activity at 15
582 minutes or later (that is, lockTimeout minutes after activa‐
583 tion) then a password would be required. The default is 0,
584 meaning that if locking is enabled, then a password will be re‐
585 quired as soon as the screen blanks.
586 passwdTimeout (class Time)
589 If the screen is locked, then this is how many seconds the
590 password dialog box should be left on the screen before giving
591 up (default 30 seconds). A few seconds are added each time you
592 type a character.
593 dpmsEnabled (class Boolean)
596 Whether power management is enabled.
597 dpmsStandby (class Time)
600 If power management is enabled, how long until the monitor goes
601 solid black.
602 dpmsSuspend (class Time)
605 If power management is enabled, how long until the monitor goes
606 into power-saving mode.
607 dpmsOff (class Time)
610 If power management is enabled, how long until the monitor pow‐
611 ers down completely. Note that these settings will have no ef‐
612 fect unless both the X server and the display hardware support
613 power management; not all do. See the Power Management sec‐
614 tion, below, for more information.
615 dpmsQuickOff (class Boolean)
618 If mode is blank and this is true, then the screen will be pow‐
619 ered down immediately upon blanking, regardless of other power-
620 management settings.
621 verbose (class Boolean)
624 Whether to print diagnostics. Default false.
625 splash (class Boolean)
628 Whether to display a splash screen at startup. Default true.
629 splashDuration (class Time)
632 How long the splash screen should remain visible; default 5
633 seconds.
634 helpURL (class URL)
637 The splash screen has a Help button on it. When you press it,
638 it will display the web page indicated here in your web
639 browser.
640 loadURL (class LoadURL)
643 This is the shell command used to load a URL into your web
644 browser. The default setting will load it into Mozilla/Net‐
645 scape if it is already running, otherwise, will launch a new
646 browser looking at the helpURL.
647 demoCommand (class DemoCommand)
650 This is the shell command run when the Demo button on the
651 splash window is pressed. It defaults to xscreensaver-set‐
652 tings(1).
653 newLoginCommand (class NewLoginCommand)
656 If set, this is the shell command that is run when the "New Lo‐
657 gin" button is pressed on the unlock dialog box, in order to
658 create a new desktop session without logging out the user who
659 has locked the screen. Typically this will be some variant of
660 gdmflexiserver(1), kdmctl(1), lxdm(1) or dm-tool(1).
661 nice (class Nice)
664 The sub-processes launched by XScreenSaver will be "niced" to
665 this level, so that they are given lower priority than other
666 processes on the system, and don't increase the load unneces‐
667 sarily. The default is 10. (Higher numbers mean lower prior‐
668 ity; see nice(1) for details.)
669 fade (class Boolean)
672 If this is true, then when the screensaver activates, the cur‐
673 rent contents of the screen will fade to black instead of sim‐
674 ply winking out. Default: true.
675 unfade (class Boolean)
678 If this is true, then when the screensaver deactivates, the
679 original contents of the screen will fade in from black instead
680 of appearing immediately. This is only done if fade is true as
681 well. Default: true.
682 fadeSeconds (class Time)
685 If fade is true, this is how long the fade will be in seconds.
686 Default 3 seconds.
687 ignoreUninstalledPrograms (class Boolean)
690 There may be programs in the list that are not installed on the
691 system, yet are marked as "enabled". If this preference is
692 true, then such programs will simply be ignored. If false,
693 then a warning will be printed if an attempt is made to run the
694 nonexistent program. Also, the xscreensaver-settings(1) pro‐
695 gram will suppress the non-existent programs from the list if
696 this is true. Default: false.
697 authWarningSlack (class Integer)
700 After you successfully unlock the screen, a dialog may pop up
701 informing you of previous failed login attempts. If all of
702 those login attemps were within this amount of time, they are
703 ignored. The assumption is that incorrect passwords entered
704 within a few seconds of a correct one are user error, rather
705 than hostile action. Default 20 seconds.
706 mode (class Mode)
709 Controls the screen-saving behavior. Valid values are:
710 random When blanking the screen, select a random display mode
713 from among those that are enabled and applicable. This
714 is the default.
715 random-same
718 Like random, but if there are multiple screens, each
719 screen will run the same random display mode, instead
720 of each screen running a different one.
721 one When blanking the screen, only ever use one particular
724 display mode (the one indicated by the selected set‐
725 ting).
726 blank When blanking the screen, just go black: don't run any
729 graphics hacks.
730 off Don't ever blank the screen, and don't ever allow the
733 monitor to power down.
734 selected (class Integer)
737 When mode is set to one, this is the one, indicated by its in‐
738 dex in the programs list. You're crazy if you count them and
739 set this number by hand: let xscreensaver-settings(1) do it for
740 you!
741 programs (class Programs)
744 The graphics hacks which XScreenSaver runs when the user is
745 idle. The value of this resource is a multi-line string, one
746 sh-syntax command per line. Each line must contain exactly one
747 command: no semicolons, no ampersands.
748 When the screensaver starts up, one of these is selected (ac‐
750 cording to the mode setting), and run. After the cycle period
751 expires, it is killed, and another is selected and run.
752 If a line begins with a dash (-) then that particular program
754 is disabled: it won't be selected at random (though you can
755 still select it explicitly using the xscreensaver-settings(1)
756 program).
757 If all programs are disabled, then the screen will just be made
759 blank, as when mode is set to blank.
760 To disable a program, you must mark it as disabled with a dash
762 instead of removing it from the list. This is because the sys‐
763 tem-wide (app-defaults) and per-user (.xscreensaver) settings
764 are merged together, and if a user just deletes an entry from
765 their programs list, but that entry still exists in the system-
766 wide list, then it will come back. However, if the user dis‐
767 ables it, then their setting takes precedence.
768 If the display has multiple screens, then a different program
770 will be run for each screen. (All screens are blanked and un‐
771 blanked simultaneously.)
772 Note that you must escape the newlines; here is an example of
774 how you might set this in your ~/.xscreensaver file:
775 programs: \
777 qix -root \n\
778 ico -r -faces -sleep 1 -obj ico \n\
779 xdaliclock -builtin2 -root \n\
780 xv -root -rmode 5 image.gif -quit \n
781 The default XScreenSaver hacks directory (typically
783 /usr/libexec/xscreensaver/) is prepended to $PATH before
784 searching for these programs.
785 To use a program as a screensaver, it must be able to render
787 onto the window provided to it in the $XSCREENSAVER_WINDOW en‐
788 vironment variable. If it creates and maps its own window in‐
789 stead, it won't work. It must render onto the provided window.
790 Visuals:
792 Because XScreenSaver was created back when dinosaurs roamed the
794 earth, it still contains support for some things you've proba‐
795 bly never seen, such as 1-bit monochrome monitors, grayscale
796 monitors, and monitors capable of displaying only 8-bit col‐
797 ormapped images.
798 If there are some programs that you want to run only when using
800 a color display, and others that you want to run only when us‐
801 ing a monochrome display, you can specify that like this:
802 mono: mono-program -root \n\
804 color: color-program -root \n\
805 More generally, you can specify the kind of visual that should
807 be used for the window on which the program will be drawing.
808 For example, if one program works best if it has a colormap,
809 but another works best if it has a 24-bit visual, both can be
810 accommodated:
811 PseudoColor: cmap-program -root \n\
813 TrueColor: 24bit-program -root \n\
814 In addition to the symbolic visual names described above (in
816 the discussion of the visualID resource) one other visual name
817 is supported in the programs list:
818 default-n
820 This is like default, but also requests the use of the de‐
821 fault colormap, instead of a private colormap.
822 If you specify a particular visual for a program, and that vis‐
824 ual does not exist on the screen, then that program will not be
825 chosen to run. This means that on displays with multiple
826 screens of different depths, you can arrange for appropriate
827 hacks to be run on each. For example, if one screen is color
828 and the other is monochrome, hacks that look good in mono can
829 be run on one, and hacks that only look good in color will show
830 up on the other.
831 visualID (class VisualID)
834 This is an historical artifact left over from when 8-bit dis‐
835 plays were still common. You should probably ignore this.
836 Specify which X visual to use by default. (Note carefully that
838 this resource is called visualID, not merely visual; if you set
839 the visual resource instead, things will malfunction in obscure
840 ways for obscure reasons.)
841 Valid values for the VisualID resource are:
843 default Use the screen's default visual (the visual of the root
845 window). This is the default.
846 best Use the visual which supports the most colors. Note,
848 however, that the visual with the most colors might be
849 a TrueColor visual, which does not support colormap an‐
850 imation. Some programs have more interesting behavior
851 when run on PseudoColor visuals than on TrueColor.
852 mono Use a monochrome visual, if there is one.
854 gray Use a grayscale or staticgray visual, if there is one
856 and it has more than one plane (that is, it's not mono‐
857 chrome).
858 color Use the best of the color visuals, if there are any.
860 GL Use the visual that is best for OpenGL programs.
862 (OpenGL programs have somewhat different requirements
863 than other X programs.)
864 class where class is one of StaticGray, StaticColor, True‐
866 Color, GrayScale, PseudoColor, or DirectColor. Selects
867 the deepest visual of the given class.
868 N where number (decimal or hex) is interpreted as a vis‐
870 ual id number, as reported by the xdpyinfo(1) program;
871 in this way you can have finer control over exactly
872 which visual gets used, for example, to select a shal‐
873 lower one than would otherwise have been chosen.
874 Note that this option specifies only the default visual that
876 will be used: the visual used may be overridden on a program-
877 by-program basis. See the description of the programs re‐
878 source, above.
879 installColormap (class Boolean)
882 This is an historical artifact left over from when 8-bit dis‐
883 plays were still common. On PseudoColor (8-bit) displays, in‐
884 stall a private colormap while the screensaver is active, so
885 that the graphics hacks can get as many colors as possible.
886 This is the default. (This only applies when the screen's de‐
887 fault visual is being used, since non-default visuals get their
888 own colormaps automatically.) This can also be overridden on a
889 per-hack basis: see the discussion of the default-n name in the
890 section about the programs resource.
891 This does nothing if you have a TrueColor (16-bit or deeper)
893 display. (Which, in this century, you do.)
894 pointerHysteresis (class Integer)
897 If the mouse moves less than this-many pixels in a second, ig‐
898 nore it (do not consider that to be "activity"). This is so
899 that the screen doesn't un-blank (or fail to blank) just be‐
900 cause you bumped the desk. Default: 10 pixels.
901 A single pixel of motion will still cause the monitor to power
903 back on, but not un-blank. This is because the X11 server it‐
904 self unfortunately handles power-management-related activity
905 detection rather than XScreenSaver.
906
908 https://www.jwz.org/xscreensaver/bugs.html explains how to write the
909 most useful bug reports. If you find a bug, please let me know!
910
913 DISPLAY to get the default host and display number, and to inform the
914 sub-programs of the screen on which to draw.
915 XSCREENSAVER_WINDOW
917 Passed to sub-programs to indicate the ID of the window on
918 which they should draw. This is necessary on Xinerama/RANDR
919 systems where multiple physical monitors share a single X11
920 "Screen".
921 PATH to find the sub-programs to run, including the display modes.
923 HOME for the directory in which to read the .xscreensaver file.
925 XENVIRONMENT
927 to get the name of a resource file that overrides the global
928 resources stored in the RESOURCE_MANAGER property.
929
931 The latest version of XScreenSaver, an online version of this manual,
932 and a FAQ can always be found at https://www.jwz.org/xscreensaver/
933
935 X(1), Xsecurity(1), xauth(1), xdm(1), gdm(1), xhost(1), systemd(1), el‐
936 ogind(8), xscreensaver-settings(1), xscreensaver-command(1), xscreen‐
937 saver-systemd(6), xscreensaver-gl-helper(6), xscreensaver-getimage(6),
938 xscreensaver-text(6).
939
941 Copyright © 1991-2021 by Jamie Zawinski. Permission to use, copy, mod‐
942 ify, distribute, and sell this software and its documentation for any
943 purpose is hereby granted without fee, provided that the above copy‐
944 right notice appear in all copies and that both that copyright notice
945 and this permission notice appear in supporting documentation. No rep‐
946 resentations are made about the suitability of this software for any
947 purpose. It is provided "as is" without express or implied warranty.
948
950 Jamie Zawinski <jwz@jwz.org>. Written in late 1991; version 1.0 posted
951 to comp.sources.x on 17-Aug-1992.
952 Please let me know if you find any bugs or make any improvements.
954 And a huge thank you to the hundreds of people who have contributed, in
956 large ways and small, to the XScreenSaver collection over the past
957 three decades!
958X Version 11 6.02-4.fc35 (09-Nov-2021) XScreenSaver(1)