1xscreensaver(1)               XScreenSaver manual              xscreensaver(1)
2
3
4

NAME

6       xscreensaver - extensible screen saver and screen locking framework
7

SYNOPSIS

9       xscreensaver  [-display  host:display.screen]  [-verbose]  [-no-splash]
10       [-no-capture-stderr] [-log filename]
11

DESCRIPTION

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
17       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
21       It also provides configuration and control of your monitor's power-sav‐
22       ing features.
23

GETTING STARTED

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
32       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

CONFIGURATION

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
42       I'll repeat that because it's important:
43
44           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
49       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
54       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
66       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
80       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

COMMAND-LINE OPTIONS

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
90       -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
95       -verbose
96               Same as setting the verbose resource to true: print diagnostics
97               on stderr and on the xscreensaver window.
98
99       -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
104       -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

HOW IT WORKS

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
118       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
124       You  can  control  a  running screensaver process by using the xscreen‐
125       saver-command(1) program (which see).
126

POWER MANAGEMENT

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
135       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
141       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
145       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
150       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
156       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

USING GNOME OR UNITY

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
169       To replace gnome-screensaver with xscreensaver:
170
171           1: Fully uninstall the gnome-screensaver package.
172              sudo apt-get remove gnome-screensaver
173              or possibly
174              sudo dpkg -P gnome-screensaver
175
176           2: Launch xscreensaver at login.
177              Select "Startup Applications" from the menu (or manually  launch
178              "gnome-session-properties") and add "xscreensaver".
179
180              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
184           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
194           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

USING KDE

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
204           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
208              Or possibly: Open "System Settings" and select "Screen Locking".
209              Un-check "Lock Screen Automatically".
210
211           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
216              If that doesn't work, then try this:
217
218              Open "System Settings / Startup/Shutdown / Autostart", and  then
219              add "/usr/bin/xscreensaver".
220
221              If you are lucky, that will create a "xscreensaver.desktop" file
222              for you in ~/.config/autostart/ or ~/.kde/Autostart/.
223
224           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
235           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
247       Now use xscreensaver normally, controlling it via  the  usual  xscreen‐
248       saver-demo(1) and xscreensaver-command(1) mechanisms.
249

USING SYSTEMD

251       If  the  above  didn't do it, and your system has systemd(1), then give
252       this a try:
253
254       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
264       2. Enable it.
265          systemctl --user enable xscreensaver
266          Then restart X11.
267

USING UPSTART

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

USING GDM

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
282       On the General page set the Local Greeter to Standard Greeter.
283
284       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
290       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
300       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
305       An  unfortunate  side effect of this (important) security precaution is
306       that it may conflict with cookie-based authentication.
307
308       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

LAPTOP LIDS

315       If you are running a system  with  systemd(1)  221  or  newer,  and  if
316       xscreensaver was compiled with libsystemd support, then closing the lid
317       of your laptop will cause the screen to lock immediately.
318
319       If not, then the screen might not lock until a few  seconds  after  you
320       re-open the lid. Which is less than ideal. So if you don't use systemd,
321       you might want to get in the habit of doing xscreensaver-command  -lock
322       before closing the lid.
323

BUGS

325       Bugs?   There  are  no bugs.  Ok, well, maybe.  If you find one, please
326       let me know.  https://www.jwz.org/xscreensaver/bugs.html  explains  how
327       to construct the most useful bug reports.
328
329       Locking and root logins
330           In  order for it to be safe for xscreensaver to be launched by xdm,
331           certain precautions had to be taken, among them  that  xscreensaver
332           never  runs  as root.  In particular, if it is launched as root (as
333           xdm is likely to do), xscreensaver will disavow its privileges, and
334           switch itself to a safe user id (such as nobody).
335
336           An  implication  of  this is that if you log in as root on the con‐
337           sole, xscreensaver will refuse to lock the screen (because it can't
338           tell  the  difference  between root being logged in on the console,
339           and a normal user being logged in on the console  but  xscreensaver
340           having been launched by the xdm(1) Xsetup file).
341
342           The  solution to this is simple: you shouldn't be logging in on the
343           console as root in the first place!  (What, are you crazy or  some‐
344           thing?)
345
346           Proper  Unix  hygiene  dictates that you should log in as yourself,
347           and su(1) to root as necessary.  People who spend their day  logged
348           in as root are just begging for disaster.
349
350       XAUTH and XDM
351           For  xscreensaver  to  work when launched by xdm(1) or gdm(1), pro‐
352           grams running on the local machine as user "nobody" must be able to
353           connect  to  the  X  server.   This  means  that if you want to run
354           xscreensaver on the console while nobody is logged in, you may need
355           to disable cookie-based access control (and allow all users who can
356           log in to the local machine to connect to the display).
357
358           You should be sure that this is an acceptable thing to do  in  your
359           environment  before  doing it.  See the "Using GDM" section, above,
360           for more details.
361
362       Passwords
363           If you get an error message at startup like "couldn't get  password
364           of  user" then this probably means that you're on a system in which
365           the getpwent(3) library routine can only  be  effectively  used  by
366           root.   If this is the case, then xscreensaver must be installed as
367           setuid to root in order for locking to work.  Care has  been  taken
368           to make this a safe thing to do.
369
370           It  also may mean that your system uses shadow passwords instead of
371           the standard getpwent(3) interface; in that case, you may  need  to
372           change some options with configure and recompile.
373
374           If  you  change your password after xscreensaver has been launched,
375           it will continue using your old password to unlock the screen until
376           xscreensaver  is  restarted.   On  some systems, it may accept both
377           your old and new passwords.  So, after you  change  your  password,
378           you'll have to do
379           xscreensaver-command -restart
380           to make xscreensaver notice.
381
382       PAM Passwords
383           If your system uses PAM (Pluggable Authentication Modules), then in
384           order for xscreensaver to use PAM properly, PAM must be told  about
385           xscreensaver.   The xscreensaver installation process should update
386           the PAM data (on Linux, by creating  the  file  /etc/pam.d/xscreen‐
387           saver  for you, and on Solaris, by telling you what lines to add to
388           the /etc/pam.conf file).
389
390           If the PAM configuration files do not know about xscreensaver, then
391           you  might be in a situation where xscreensaver will refuse to ever
392           unlock the screen.
393
394           This is a design flaw in PAM (there is no way for a client to  tell
395           the  difference  between PAM responding "I have never heard of your
396           module", and responding, "you typed the wrong password").   As  far
397           as  I  can  tell, there is no way for xscreensaver to automatically
398           work around this, or detect the problem in advance, so if you  have
399           PAM, make sure it is configured correctly!
400
401       Machine Load
402           Although  this  program  "nices"  the  subprocesses that it starts,
403           graphics-intensive subprograms can still overload  the  machine  by
404           causing  the X server process itself (which is not "niced") to con‐
405           sume many cycles.  Care has been taken in all the  modules  shipped
406           with  xscreensaver to sleep periodically, and not run full tilt, so
407           as not to cause appreciable load.
408
409           However, if you are running the OpenGL-based  screen  savers  on  a
410           machine  that does not have a video card with 3D acceleration, they
411           will make your machine slow, despite nice(1).
412
413           Your options are: don't use the OpenGL display modes;  or,  collect
414           the  spare  change hidden under the cushions of your couch, and use
415           it to buy a video card manufactured after 1998.  (It  doesn't  even
416           need  to be fast 3D hardware: the problem will be fixed if there is
417           any 3D hardware at all.)
418
419       Magic Backdoor Keystrokes
420           The XFree86 X server and the Linux kernel both trap  certain  magic
421           keystrokes  before  X11 client programs ever see them.  If you care
422           about keeping your screen locked, this is a big problem.
423
424           Ctrl+Alt+Backspace
425              This keystroke kills the X server, and on some  systems,  leaves
426              you  at a text console.  If the user launched X11 manually, that
427              text console will still be logged in.  To disable this keystroke
428              globally  and  permanently,  you need to set the DontZap flag in
429              your xorg.conf or XF86Config  or  XF86Config-4  file,  depending
430              which is in use on your system.  See XF86Config(5) for details.
431
432           Ctrl-Alt-F1, Ctrl-Alt-F2, etc.
433              These  keystrokes  will  switch  to a different virtual console,
434              while leaving the console that X11 is running on locked.  If you
435              left  a shell logged in on another virtual console, it is unpro‐
436              tected.  So don't leave yourself logged in  on  other  consoles.
437              You can disable VT switching globally and permanently by setting
438              DontVTSwitch in your xorg.conf, but that might make your  system
439              harder to use, since VT switching is an actual useful feature.
440
441              There  is no way to disable VT switching only when the screen is
442              locked.  It's all or nothing.
443
444           Ctrl-Alt-KP_Multiply
445              This keystroke kills any X11 app that holds a  lock,  so  typing
446              this  will  kill  xscreensaver  and unlock the screen.  This so-
447              called "feature" showed up in the X server in 2008,  and  as  of
448              2011,  some  vendors  are shipping it turned on by default.  How
449              nice.  You can disable it by turning off AllowClosedownGrabs  in
450              xorg.conf.
451
452           Alt-SysRq-F
453              This is the Linux kernel "OOM-killer" keystroke.  It shoots down
454              random long-running programs of its choosing, and so might might
455              target  and  kill  xscreensaver, and there's no way for xscreen‐
456              saver to protect itself from that.  You can disable it  globally
457              with:
458              echo 176 > /proc/sys/kernel/sysrq
459       There's  little  that  I  can do to make the screen locker be secure so
460       long as the kernel and X11  developers  are  actively  working  against
461       security  like  this.   The  strength  of  the  lock on your front door
462       doesn't matter much so long as someone else in  the  house  insists  on
463       leaving a key under the welcome mat.
464
465       Dangerous Backdoor Server Extensions
466           Many  distros  enable by default several X11 server extensions that
467           can be used to bypass grabs, and thus snoop  on  you  while  you're
468           typing your password.  These extensions are nominally for debugging
469           and automation, but they are also security-circumventing  keystroke
470           loggers.  If your server is configured to load the RECORD, XTRAP or
471           XTEST extensions, you absolutely should disable those, 100% of  the
472           time.  Look for them in xorg.conf or whatever it is called.
473

X RESOURCES

475       These  are the X resources use by the xscreensaver program.  You proba‐
476       bly won't need to change  these  manually  (that's  what  the  xscreen‐
477       saver-demo(1) program is for).
478
479       timeout (class Time)
480               The screensaver will activate (blank the screen) after the key‐
481               board and mouse have been idle for this many minutes.   Default
482               10 minutes.
483
484       cycle (class Time)
485               After  the  screensaver has been running for this many minutes,
486               the currently running graphics-hack sub-process will be  killed
487               (with  SIGTERM), and a new one started.  If this is 0, then the
488               graphics hack will never be changed: only  one  demo  will  run
489               until the screensaver is deactivated by user activity.  Default
490               10 minutes.
491
492               The running saver will be restarted every  cycle  minutes  even
493               when  mode  is  one,  since  some  savers tend to converge on a
494               steady state.
495
496       lock (class Boolean)
497               Enable locking: before the screensaver will turn off,  it  will
498               require you to type the password of the logged-in user (really,
499               the person who ran xscreensaver), or the root password.  (Note:
500               this  doesn't  work  if  the  screensaver is launched by xdm(1)
501               because it can't know the user-id of the logged-in  user.   See
502               the "Using XDM(1)" section, below.
503
504       lockTimeout (class Time)
505               If  locking  is enabled, this controls the length of the "grace
506               period" between when the screensaver activates,  and  when  the
507               screen becomes locked.  For example, if this is 5, and -timeout
508               is 10, then after 10 minutes, the screen would blank.  If there
509               was  user activity at 12 minutes, no password would be required
510               to un-blank the screen.  But, if there was user activity at  15
511               minutes  or later (that is, -lock-timeout minutes after activa‐
512               tion) then a password would be required.   The  default  is  0,
513               meaning  that  if  locking  is enabled, then a password will be
514               required as soon as the screen blanks.
515
516       passwdTimeout (class Time)
517               If the screen is locked, then this  is  how  many  seconds  the
518               password  dialog box should be left on the screen before giving
519               up (default 30 seconds).  This should not be too large:  the  X
520               server is grabbed for the duration that the password dialog box
521               is up (for security purposes) and leaving  the  server  grabbed
522               for too long can cause problems.
523
524       dpmsEnabled (class Boolean)
525               Whether power management is enabled.
526
527       dpmsStandby (class Time)
528               If power management is enabled, how long until the monitor goes
529               solid black.
530
531       dpmsSuspend (class Time)
532               If power management is enabled, how long until the monitor goes
533               into power-saving mode.
534
535       dpmsOff (class Time)
536               If power management is enabled, how long until the monitor pow‐
537               ers down completely.  Note that these  settings  will  have  no
538               effect  unless  both the X server and the display hardware sup‐
539               port power management; not all do.  See  the  Power  Management
540               section, below, for more information.
541
542       dpmsQuickOff (class Boolean)
543               If mode is blank and this is true, then the screen will be pow‐
544               ered down immediately upon blanking, regardless of other power-
545               management settings.
546
547       visualID (class VisualID)
548               This  is an historical artifacts left over from when 8-bit dis‐
549               plays were still common.  You should probably ignore this.
550
551               Specify which X visual to use by default.  (Note carefully that
552               this resource is called visualID, not merely visual; if you set
553               the visual resource instead, things will malfunction in obscure
554               ways for obscure reasons.)
555
556               Legal values for the VisualID resource are:
557
558               default Use the screen's default visual (the visual of the root
559                       window).  This is the default.
560
561               best    Use the visual which supports the most  colors.   Note,
562                       however,  that the visual with the most colors might be
563                       a TrueColor visual, which  does  not  support  colormap
564                       animation.   Some programs have more interesting behav‐
565                       ior when run on PseudoColor visuals than on TrueColor.
566
567               mono    Use a monochrome visual, if there is one.
568
569               gray    Use a grayscale or staticgray visual, if there  is  one
570                       and it has more than one plane (that is, it's not mono‐
571                       chrome).
572
573               color   Use the best of the color visuals, if there are any.
574
575               GL      Use the  visual  that  is  best  for  OpenGL  programs.
576                       (OpenGL  programs  have somewhat different requirements
577                       than other X programs.)
578
579               class   where class is one of  StaticGray,  StaticColor,  True‐
580                       Color, GrayScale, PseudoColor, or DirectColor.  Selects
581                       the deepest visual of the given class.
582
583               number  where number (decimal or hex) is interpreted as a  vis‐
584                       ual  id number, as reported by the xdpyinfo(1) program;
585                       in this way you can have  finer  control  over  exactly
586                       which  visual gets used, for example, to select a shal‐
587                       lower one than would otherwise have been chosen.
588
589               Note that this option specifies only the  default  visual  that
590               will  be  used: the visual used may be overridden on a program-
591               by-program  basis.   See  the  description  of   the   programs
592               resource, below.
593
594       installColormap (class Boolean)
595               On  PseudoColor  (8-bit)  displays,  install a private colormap
596               while the screensaver is active, so that the graphics hacks can
597               get  as  many  colors as possible.  This is the default.  (This
598               only applies when the screen's default visual  is  being  used,
599               since  non-default  visuals  get  their own colormaps automati‐
600               cally.)  This can also be overridden on a per-hack  basis:  see
601               the  discussion  of the default-n name in the section about the
602               programs resource.
603
604               This does nothing if you have a TrueColor  (16-bit  or  deeper)
605               display.  (Which, in this century, you do.)
606
607       verbose (class Boolean)
608               Whether to print diagnostics.  Default false.
609
610       timestamp (class Boolean)
611               Whether  to print the time of day along with any other diagnos‐
612               tic messages.  Default true.
613
614       splash (class Boolean)
615               Whether to display a splash screen at startup.  Default true.
616
617       splashDuration (class Time)
618               How long the splash screen should  remain  visible;  default  5
619               seconds.
620
621       helpURL (class URL)
622               The  splash screen has a Help button on it.  When you press it,
623               it will display  the  web  page  indicated  here  in  your  web
624               browser.
625
626       loadURL (class LoadURL)
627               This  is  the  shell  command  used to load a URL into your web
628               browser.  The default setting will load  it  into  Mozilla/Net‐
629               scape  if  it  is already running, otherwise, will launch a new
630               browser looking at the helpURL.
631
632       demoCommand (class DemoCommand)
633               This is the shell command run  when  the  Demo  button  on  the
634               splash window is pressed.  It defaults to xscreensaver-demo(1).
635
636       prefsCommand (class PrefsCommand)
637               This  is  the  shell  command  run when the Prefs button on the
638               splash  window   is   pressed.    It   defaults   to   xscreen‐
639               saver-demo -prefs.
640
641       newLoginCommand (class NewLoginCommand)
642               If  set,  this  is  the shell command that is run when the "New
643               Login" button is pressed on the unlock dialog box, in order  to
644               create  a  new desktop session without logging out the user who
645               has locked the screen.  Typically this will be some variant  of
646               gdmflexiserver(1), kdmctl(1), lxdm(1) or dm-tool(1).
647
648       nice (class Nice)
649               The  sub-processes  created  by xscreensaver will be "niced" to
650               this level, so that they are given lower  priority  than  other
651               processes  on  the system, and don't increase the load unneces‐
652               sarily.  The default is 10.  (Higher numbers mean lower  prior‐
653               ity; see nice(1) for details.)
654
655       fade (class Boolean)
656               If  this is true, then when the screensaver activates, the cur‐
657               rent contents of the screen will fade to black instead of  sim‐
658               ply  winking  out.  This only works on certain systems.  A fade
659               will also be done when switching graphics hacks (when the cycle
660               timer expires).  Default: true.
661
662       unfade (class Boolean)
663               If  this  is  true,  then when the screensaver deactivates, the
664               original contents of the screen will fade in from black instead
665               of  appearing immediately.  This only works on certain systems,
666               and if fade is true as well.  Default false.
667
668       fadeSeconds (class Time)
669               If fade is true, this is how long the fade will be  in  seconds
670               (default 3 seconds).
671
672       fadeTicks (class Integer)
673               If  fade  is true, this is how many times a second the colormap
674               will be  changed  to  effect  a  fade.   Higher  numbers  yield
675               smoother  fades,  but  may  make the fades take longer than the
676               specified fadeSeconds if your server isn't fast enough to  keep
677               up.  Default 20.
678
679       captureStderr (class Boolean)
680               Whether  xscreensaver  should  redirect  its  stdout and stderr
681               streams to the window itself.  Since its nature is to take over
682               the screen, you would not normally see error messages generated
683               by xscreensaver or the sub-programs it runs; this resource will
684               cause  the  output  of all relevant programs to be drawn on the
685               screensaver window itself, as well as being written to the con‐
686               trolling  terminal  of the screensaver driver process.  Default
687               true.
688
689       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-demo(1)  program
695               will  suppress  the non-existent programs from the list if this
696               is true.  Default: false.
697
698       authWarningSlack (class Integer)
699               If all failed unlock attempts (incorrect password entered) were
700               made  within  this  period of time, the usual dialog that warns
701               about such attempts after  a  successful  login  will  be  sup‐
702               pressed.  The  assumption  is  that incorrect passwords entered
703               within a few seconds of a correct one are  user  error,  rather
704               than hostile action.  Default 20 seconds.
705
706       GetViewPortIsFullOfLies (class Boolean)
707               Set  this  to true if the xscreensaver window doesn't cover the
708               whole screen.  This works around  a  longstanding  XFree86  bug
709               #421.  See the xscreensaver FAQ for details.
710
711       font (class Font)
712               The  font  used for the stdout/stderr text, if captureStderr is
713               true.  Default *-medium-r-*-140-*-m-* (a 14  point  fixed-width
714               font).
715
716       mode (class Mode)
717               Controls the behavior of xscreensaver.  Legal values are:
718
719               random  When  blanking the screen, select a random display mode
720                       from among those that are enabled and applicable.  This
721                       is the default.
722
723               random-same
724                       Like  random,  but  if there are multiple screens, each
725                       screen will run the same random display  mode,  instead
726                       of each screen running a different one.
727
728               one     When  blanking the screen, only ever use one particular
729                       display mode (the one indicated by  the  selected  set‐
730                       ting).
731
732               blank   When  blanking the screen, just go black: don't run any
733                       graphics hacks.
734
735               off     Don't ever blank the screen, and don't ever  allow  the
736                       monitor to power down.
737
738
739       selected (class Integer)
740               When  mode  is  set  to  one, this is the one, indicated by its
741               index in the programs list.  You're crazy if you count them and
742               set  this  number  by  hand: let xscreensaver-demo(1) do it for
743               you!
744
745       programs (class Programs)
746               The graphics hacks which xscreensaver runs  when  the  user  is
747               idle.   The  value of this resource is a multi-line string, one
748               sh-syntax command per line.  Each line must contain exactly one
749               command: no semicolons, no ampersands.
750
751               When  the  screensaver  starts  up,  one  of  these is selected
752               (according to the mode setting),  and  run.   After  the  cycle
753               period expires, it is killed, and another is selected and run.
754
755               If  a  line begins with a dash (-) then that particular program
756               is disabled: it won't be selected at  random  (though  you  can
757               still  select it explicitly using the xscreensaver-demo(1) pro‐
758               gram).
759
760               If all programs are disabled, then the screen will just be made
761               blank, as when mode is set to blank.
762
763               To  disable a program, you must mark it as disabled with a dash
764               instead of removing it from the list.  This is because the sys‐
765               tem-wide  (app-defaults)  and per-user (.xscreensaver) settings
766               are merged together, and if a user just deletes an  entry  from
767               their programs list, but that entry still exists in the system-
768               wide list, then it will come back.  However, if the  user  dis‐
769               ables it, then their setting takes precedence.
770
771               If  the  display has multiple screens, then a different program
772               will be run for each screen.   (All  screens  are  blanked  and
773               unblanked simultaneously.)
774
775               Note  that  you must escape the newlines; here is an example of
776               how you might set this in your ~/.xscreensaver file:
777
778               programs:  \
779                      qix -root                          \n\
780                      ico -r -faces -sleep 1 -obj ico    \n\
781                      xdaliclock -builtin2 -root         \n\
782                      xv -root -rmode 5 image.gif -quit  \n
783               Make sure your $PATH environment variable is set  up  correctly
784               before  xscreensaver  is  launched, or it won't be able to find
785               the programs listed in the programs resource.
786
787               To use a program as a screensaver,  two  things  are  required:
788               that  that  program  draw  on the root window (or be able to be
789               configured to draw on the root window); and that  that  program
790               understand  "virtual  root"  windows, as used by virtual window
791               managers such as tvtwm(1).  (Generally, this is accomplished by
792               just  including  the  "vroot.h"  header  file  in the program's
793               source.)
794
795               Visuals:
796
797               Because xscreensaver was created back when dinosaurs roamed the
798               earth,  it still contains support for some things you've proba‐
799               bly never seen, such as 1-bit  monochrome  monitors,  grayscale
800               monitors,  and  monitors  capable of displaying only 8-bit col‐
801               ormapped images.
802
803               If there are some programs that you want to run only when using
804               a  color  display,  and  others  that you want to run only when
805               using a monochrome display, you can specify that like this:
806                      mono:   mono-program  -root        \n\
807                      color:  color-program -root        \n\
808               More generally, you can specify the kind of visual that  should
809               be  used  for  the window on which the program will be drawing.
810               For example, if one program works best if it  has  a  colormap,
811               but  another  works best if it has a 24-bit visual, both can be
812               accommodated:
813                      PseudoColor: cmap-program  -root   \n\
814                      TrueColor:   24bit-program -root   \n\
815               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
819                default-n
820                    This is like default, but also requests  the  use  of  the
821                    default  colormap,  instead  of a private colormap.  (That
822                    is, it behaves as if the -no-install  command-line  option
823                    was  specified,  but only for this particular hack.)  This
824                    is provided because some third-party programs that draw on
825                    the  root  window  (notably:  xv(1),  and  xearth(1)) make
826                    assumptions about the visual and colormap of the root win‐
827                    dow: assumptions which xscreensaver can violate.
828
829               If you specify a particular visual for a program, and that vis‐
830               ual does not exist on the screen, then that program will not be
831               chosen  to  run.   This  means  that  on displays with multiple
832               screens of different depths, you can  arrange  for  appropriate
833               hacks  to  be run on each.  For example, if one screen is color
834               and the other is monochrome, hacks that look good in  mono  can
835               be run on one, and hacks that only look good in color will show
836               up on the other.
837
838       You shouldn't ever need to change the following resources:
839
840       pointerPollTime (class Time)
841               When server extensions are not in use, this controls  how  fre‐
842               quently  xscreensaver  checks  to  see if the mouse position or
843               buttons have changed.  Default 5 seconds.
844
845       pointerHysteresis (class Integer)
846               If the mouse moves less than  this-many  pixels  in  a  second,
847               ignore  it (do not consider that to be "activity").  This is so
848               that the screen  doesn't  un-blank  (or  fail  to  blank)  just
849               because you bumped the desk.  Default: 10 pixels.
850
851       windowCreationTimeout (class Time)
852               When  server extensions are not in use, this controls the delay
853               between when windows are created and when xscreensaver  selects
854               events on them.  Default 30 seconds.
855
856       initialDelay (class Time)
857               When  server  extensions are not in use, xscreensaver will wait
858               this many seconds before selecting events on existing  windows,
859               under  the  assumption that xscreensaver is started during your
860               login procedure, and the window state may be in flux.   Default
861               0.   (This used to default to 30, but that was back in the days
862               when slow machines and X terminals were more common...)
863
864       procInterrupts (class Boolean)
865               This resource controls whether the /proc/interrupts file should
866               be  consulted  to decide whether the user is idle.  This is the
867               default if xscreensaver has been compiled  on  a  system  which
868               supports this mechanism (i.e., Linux systems).
869
870               The  benefit  to  doing this is that xscreensaver can note that
871               the user is active even when the X console is  not  the  active
872               one: if the user is typing in another virtual console, xscreen‐
873               saver will notice that and will fail to activate.  For example,
874               if you're playing Quake in VGA-mode, xscreensaver won't wake up
875               in the middle of your game and start competing for CPU.
876
877               The drawback to doing this is that perhaps you really  do  want
878               idleness  on the X console to cause the X display to lock, even
879               if there is activity on other virtual consoles.   If  you  want
880               that,  then set this option to False.  (Or just lock the X con‐
881               sole manually.)
882
883               The default value for this resource is True, on  systems  where
884               it works.
885
886       overlayStderr (class Boolean)
887               If  captureStderr  is  True, and your server supports "overlay"
888               visuals, then the text will be written into one of  the  higher
889               layers  instead  of  into the same layer as the running screen‐
890               hack.  Set this to False to disable that (though you  shouldn't
891               need to).
892
893       overlayTextForeground (class Foreground)
894               The  foreground  color used for the stdout/stderr text, if cap‐
895               tureStderr is true.  Default: Yellow.
896
897       overlayTextBackground (class Background)
898               The background color used for the stdout/stderr text,  if  cap‐
899               tureStderr is true.  Default: Black.
900
901       bourneShell (class BourneShell)
902               The  pathname of the shell that xscreensaver uses to start sub‐
903               processes.  This must be whatever your local variant of /bin/sh
904               is: in particular, it must not be csh.
905

ENVIRONMENT

907       DISPLAY to  get  the default host and display number, and to inform the
908               sub-programs of the screen on which to draw.
909
910       XSCREENSAVER_WINDOW
911               Passed to sub-programs to indicate the  ID  of  the  window  on
912               which  they  should  draw.  This is necessary on Xinerama/RANDR
913               systems where multiple physical monitors  share  a  single  X11
914               "Screen".
915
916       PATH    to find the sub-programs to run.
917
918       HOME    for the directory in which to read the .xscreensaver file.
919
920       XENVIRONMENT
921               to  get  the  name of a resource file that overrides the global
922               resources stored in the RESOURCE_MANAGER property.
923

UPGRADES

925       The latest version of xscreensaver, an online version of  this  manual,
926       and a FAQ can always be found at https://www.jwz.org/xscreensaver/
927

SEE ALSO

929       X(1),   Xsecurity(1),  xauth(1),  xdm(1),  gdm(1),  xhost(1),  xscreen‐
930       saver-demo(1),   xscreensaver-command(1),    xscreensaver-gl-helper(1),
931       xscreensaver-getimage(1), xscreensaver-text(1).
932
934       Copyright © 1991-2019 by Jamie Zawinski.  Permission to use, copy, mod‐
935       ify, distribute, and sell this software and its documentation  for  any
936       purpose  is  hereby  granted without fee, provided that the above copy‐
937       right notice appear in all copies and that both that  copyright  notice
938       and this permission notice appear in supporting documentation.  No rep‐
939       resentations are made about the suitability of this  software  for  any
940       purpose.  It is provided "as is" without express or implied warranty.
941

AUTHOR

943       Jamie Zawinski <jwz@jwz.org>.  Written in late 1991; version 1.0 posted
944       to comp.sources.x on 17-Aug-1992.
945
946       Please let me know if you find any bugs or make any improvements.
947
948       And a huge thank you to the hundreds of people who have contributed, in
949       large  ways and small, to the xscreensaver collection over the past two
950       decades!
951
952
953
954X Version 11               5.43-2.fc31 (27-Aug-2019)           xscreensaver(1)
Impressum