xscreensaver(1)               XScreenSaver manual              xscreensaver(1)



NAME
       xscreensaver - extensible screen saver and screen locking framework

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

DESCRIPTION
       The xscreensaver program waits until the keyboard and mouse  have  been
       idle  for a period, and then runs a graphics demo chosen at random.  It
       turns off as soon as there is any mouse or keyboard activity.

       This program can lock your terminal in order  to  prevent  others  from
       using  it,  though  its  default mode of operation is merely to display
       pretty pictures on your screen when it is not in use.

       It also provides configuration and control of your monitor's power-sav-
       ing features.

GETTING STARTED
       For the impatient, try this:
       xscreensaver &
       xscreensaver-demo
       The  xscreensaver-demo(1)  program  pops  up a dialog box that lets you
       configure the screen saver, and experiment  with  the  various  display
       modes.

       Note that xscreensaver has a client-server model: the xscreensaver pro-
       gram is a daemon that runs in the background; it is controlled  by  the
       foreground xscreensaver-demo(1) and xscreensaver-command(1) programs.

CONFIGURATION
       The easiest way to configure xscreensaver is to simply run the xscreen-
       saver-demo(1) program, and change the settings through  the  GUI.   The
       rest  of  this  manual page describes lower level ways of changing set-
       tings.

       I'll repeat that because it's important:

           The easy way to configure xscreensaver is to run the  xscreensaver-
           demo(1)  program.   You  shouldn't  need  to  know any of the stuff
           described in this manual unless you  are  trying  to  do  something
           tricky, like customize xscreensaver for site-wide use or something.

       Options to xscreensaver are stored in one of two places: in a .xscreen-
       saver file in your home directory; or in the X resource  database.   If
       the  .xscreensaver  file  exists,  it  overrides  any  settings  in the
       resource database.

       The syntax of the .xscreensaver file is similar to that  of  the  .Xde-
       faults file; for example, to set the timeout parameter in the .xscreen-
       saver file, you would write the following:
       timeout: 5
       whereas, in the .Xdefaults file, you would write
       xscreensaver.timeout: 5
       If you change a setting in the .xscreensaver file while xscreensaver is
       already  running,  it will notice this, and reload the file.  (The file
       will be reloaded the next time the screen  saver  needs  to  take  some
       action,  such  as  blanking  or unblanking the screen, or picking a new
       graphics mode.)

       If you change a setting in your X resource database,  or  if  you  want
       xscreensaver  to  notice  your  changes immediately instead of the next
       time it wakes up, then you will need to reload  your  .Xdefaults  file,
       and  then tell the running xscreensaver process to restart itself, like
       so:
       xrdb < ~/.Xdefaults
       xscreensaver-command -restart
       If you want to set the system-wide defaults, then make  your  edits  to
       the  xscreensaver  app-defaults  file, which should have been installed
       when xscreensaver itself was installed.   The  app-defaults  file  will
       usually  be named /usr/lib/X11/app-defaults/XScreenSaver, but different
       systems might keep it in a different  place  (for  example,  /usr/open-
       win/lib/app-defaults/XScreenSaver on Solaris.)

       When settings are changed in the Preferences dialog box (see above) the
       current settings will be written to the .xscreensaver file.  (The .Xde-
       faults file and the app-defaults file will never be written by xscreen-
       saver itself.)

COMMAND-LINE OPTIONS
       xscreensaver also accepts a few command-line options,  mostly  for  use
       when  debugging:  for normal operation, you should configure things via
       the ~/.xscreensaver file.

       -display host:display.screen
               The X display to use.   For  displays  with  multiple  screens,
               XScreenSaver  will  manage all screens on the display simultan-
               iously.

       -verbose
               Same as setting the verbose resource to true: print diagnostics
               on stderr and on the xscreensaver window.

       -no-capture-stderr
               Do  not  redirect the stdout and stderr streams to the xscreen-
               saver window itself.  If xscreensaver is  crashing,  you  might
               need to do this in order to see the error message.

       -log filename
               This  is  exactly  the same as redirecting stdout and stderr to
               the given file (for append).  This  is  useful  when  reporting
               bugs.

HOW IT WORKS
       When it is time to activate the screensaver, a full-screen black window
       is created on each screen of the display.  Each window  is  created  in
       such  a  way that, to any subsequently-created programs, it will appear
       to be a "virtual root" window.  Because  of  this,  any  program  which
       draws  on  the root window (and which understands virtual roots) can be
       used as a screensaver.  The various graphics demos are, in  fact,  just
       standalone programs that know how to draw on the provided window.

       When  the  user  becomes  active  again,  the  screensaver  windows are
       unmapped, and the running  subprocesses  are  killed  by  sending  them
       SIGTERM.  This is also how the subprocesses are killed when the screen-
       saver decides that it's time to run a different demo: the  old  one  is
       killed and a new one is launched.

       You  can  control  a  running screensaver process by using the xscreen-
       saver-command(1) program (which see.)

POWER MANAGEMENT
       Modern X servers contain support to power down  the  monitor  after  an
       idle  period.   If the monitor has powered down, then xscreensaver will
       notice this (after a few minutes), and will not waste  CPU  by  drawing
       graphics  demos  on  a  black  screen.  An attempt will also be made to
       explicitly power the monitor back  up  as  soon  as  user  activity  is
       detected.

       The  ~/.xscreensaver  file controls the configuration of your display's
       power management settings: if you have  used  xset(1)  to  change  your
       power  management  settings,  then  xscreensaver  will  override  those
       changes with the values  specified  in  ~/.xscreensaver  (or  with  its
       built-in defaults, if there is no ~/.xscreensaver file yet.)

       To  change your power management settings, run xscreensaver-demo(1) and
       change the various timeouts through the user  interface.   Alternately,
       you can edit the ~/.xscreensaver file directly.

       If  the  power  management  section  is  grayed  out  in  the  xscreen-
       saver-demo(1) window,  then that means that your X server does not sup-
       port the XDPMS extension, and so control over the monitor's power state
       is not available.

       If you're using a laptop, don't be surprised if changing the DPMS  set-
       tings  has  no  effect: many laptops have monitor power-saving behavior
       built in at a very low level that is invisible to Unix and X.  On  such
       systems,  you  can  typically  adjust  the  power-saving delays only by
       changing settings in the BIOS in some hardware-specific way.

       If DPMS seems not to be working with  XFree86,  make  sure  the  "DPMS"
       option  is set in your /etc/X11/XF86Config file.  See the XF86Config(5)
       manual for details.

USING GNOME
       For the better part of a decade, GNOME shipped xscreensaver as-is,  and
       everything  just worked out of the box.  In 2005, however, they decided
       to re-invent the wheel and ship their own replacement for the  xscreen-
       saver daemon called "gnome-screensaver", rather than improving xscreen-
       saver and contributing their changes back.  As a  result,  the  "gnome-
       screensaver" program is insecure, bug-ridden, and missing many features
       of xscreensaver.  You shouldn't use it.

       To replace gnome-screensaver with xscreensaver:

           1: Fully uninstall the gnome-screensaver package.
              sudo apt-get remove gnome-screensaver

           2: Launch xscreensaver at login.
              Select "Startup Applications" from the menu (or manually  launch
              "gnome-session-properties") and add "xscreensaver".

           3: Make "Lock Screen" use xscreensaver.
              sudo ln -sf /usr/bin/xscreensaver-command \
                          /usr/bin/gnome-screensaver-command

USING KDE
       Like GNOME, KDE also decided to invent their own screen saver framework
       from scratch instead of simply using xscreensaver.  To replace the  KDE
       screen saver with xscreensaver, do the following:

           1: Turn off KDE's screen saver.
              Open  the "Control Center" and select the "Appearance & Themes /
              Screensaver" page.  Un-check "Start Automatically".

           2: Find your Autostart directory.
              Open the "System Administration / Paths" page, and see what your
              "Autostart    path"   is   set   to:   it   will   probably   be
              ~/.kde/Autostart/ or something similar.

           3: Make xscreensaver be an Autostart program.
              Create a  .desktop  file  in  your  autostart  directory  called
              xscreensaver.desktop that contains the following five lines:

              [Desktop Entry]
              Exec=xscreensaver
              Name=XScreenSaver
              Type=Application
              X-KDE-StartupNotify=false

           4: Make the various "lock session" buttons call xscreensaver.
              The  file  you  want  to  replace next has moved around over the
              years. It might be called /usr/libexec/kde4/kscreenlocker, or it
              might  be  called "kdesktop_lock" or "krunner_lock" or "kscreen-
              locker_greet", and it might be in /usr/lib/kde4/libexec/  or  in
              /usr/kde/3.5/bin/  or even in /usr/bin/, depending on the distro
              and phase of the moon.  Replace the contents of that  file  with
              these two lines:

              #!/bin/sh
              xscreensaver-command -lock

              Make sure the file is executable (chmod a+x).

       Now  use  xscreensaver  normally, controlling it via the usual xscreen-
       saver-demo(1) and xscreensaver-command(1) mechanisms.

USING UNITY
       Guess what, they did it again!  Ubuntu Unity's screen-locking framework
       is  yet  another  rewrite,  and it is completely broken, bug-ridden and
       insecure. At this time I don't have any information on how to  turn  it
       off and use xscreensaver instead.  If you do, let me know.

USING GDM
       You  can run xscreensaver from your gdm(1) session, so that the screen-
       saver will run even when nobody is logged in on  the  console.   To  do
       this,  run  gdmconfig(1)  and  on the Background page, type the command
       "xscreensaver -nosplash" into the Background Program field.  That  will
       cause gdm to run xscreensaver while nobody is logged in, and kill it as
       soon as someone does log in.  (The user will then  be  responsible  for
       starting xscreensaver on their own, if they want.)

       Another  way  to  accomplish  the  same  thing  is  to  edit  the  file
       /etc/X11/gdm/gdm.conf to include:
       BackgroundProgram=xscreensaver -nosplash
       RunBackgroundProgramAlways=true
       In this situation, the xscreensaver process will probably be running as
       user  gdm  instead  of  root.   You can configure the settings for this
       nobody-logged-in  state  (timeouts,  DPMS,   etc.)   by   editing   the
       ~gdm/.xscreensaver file.

       To get gdm to run the BackgroundProgram, you may need to switch it from
       the "Graphical Greeter" to the "Standard Greeter".

       It is safe to run xscreensaver as root (as xdm or gdm may do.)  If  run
       as root, xscreensaver changes its effective user and group ids to some-
       thing safe (like "nobody") before connecting to the X server or launch-
       ing user-specified programs.

       An  unfortunate  side effect of this (important) security precaution is
       that it may conflict with cookie-based authentication.

       If you get "connection refused" errors when running  xscreensaver  from
       gdm,  then  this  probably  means  that you have xauth(1) or some other
       security mechanism turned on.  For information on the X server's access
       control mechanisms, see the man pages for X(1), Xsecurity(1), xauth(1),
       and xhost(1).

BUGS
       Bugs?  There are no bugs.  Ok, well, maybe.  If you  find  one,  please
       let me know.  http://www.jwz.org/xscreensaver/bugs.html explains how to
       construct the most useful bug reports.

       Locking and root logins
           In order for it to be safe for xscreensaver to be launched by  xdm,
           certain  precautions  had to be taken, among them that xscreensaver
           never runs as root.  In particular, if it is launched as  root  (as
           xdm is likely to do), xscreensaver will disavow its privileges, and
           switch itself to a safe user id (such as nobody.)

           An implication of this is that if you log in as root  on  the  con-
           sole, xscreensaver will refuse to lock the screen (because it can't
           tell the difference between root being logged in  on  the  console,
           and  a  normal user being logged in on the console but xscreensaver
           having been launched by the xdm(1) Xsetup file.)

           The solution to this is simple: you shouldn't be logging in on  the
           console  as root in the first place!  (What, are you crazy or some-
           thing?)

           Proper Unix hygiene dictates that you should log  in  as  yourself,
           and  su(1) to root as necessary.  People who spend their day logged
           in as root are just begging for disaster.

       XAUTH and XDM
           For xscreensaver to work when launched by xdm(1)  or  gdm(1),  pro-
           grams running on the local machine as user "nobody" must be able to
           connect to the X server.  This  means  that  if  you  want  to  run
           xscreensaver on the console while nobody is logged in, you may need
           to disable cookie-based access control (and allow all users who can
           log in to the local machine to connect to the display.)

           You  should  be sure that this is an acceptable thing to do in your
           environment before doing it.  See the "Using GDM"  section,  above,
           for more details.

       Passwords
           If  you get an error message at startup like "couldn't get password
           of user" then this probably means that you're on a system in  which
           the  getpwent(3)  library  routine  can only be effectively used by
           root.  If this is the case, then xscreensaver must be installed  as
           setuid  to  root in order for locking to work.  Care has been taken
           to make this a safe thing to do.

           It also may mean that your system uses shadow passwords instead  of
           the  standard  getpwent(3) interface; in that case, you may need to
           change some options with configure and recompile.

           If you change your password after xscreensaver has  been  launched,
           it will continue using your old password to unlock the screen until
           xscreensaver is restarted.  On some systems,  it  may  accept  both
           your  old  and  new passwords.  So, after you change your password,
           you'll have to do
           xscreensaver-command -restart
           to make xscreensaver notice.

       PAM Passwords
           If your system uses PAM (Pluggable Authentication Modules), then in
           order  for xscreensaver to use PAM properly, PAM must be told about
           xscreensaver.  The xscreensaver installation process should  update
           the  PAM  data  (on Linux, by creating the file /etc/pam.d/xscreen-
           saver for you, and on Solaris, by telling you what lines to add  to
           the /etc/pam.conf file.)

           If the PAM configuration files do not know about xscreensaver, then
           you might be in a situation where xscreensaver will refuse to  ever
           unlock the screen.

           This  is a design flaw in PAM (there is no way for a client to tell
           the difference between PAM responding "I have never heard  of  your
           module",  and  responding, "you typed the wrong password".)  As far
           as I can tell, there is no way for  xscreensaver  to  automatically
           work  around this, or detect the problem in advance, so if you have
           PAM, make sure it is configured correctly!

       Machine Load
           Although this program "nices"  the  subprocesses  that  it  starts,
           graphics-intensive  subprograms  can  still overload the machine by
           causing the X server process itself (which is not "niced") to  con-
           sume  many  cycles.  Care has been taken in all the modules shipped
           with xscreensaver to sleep periodically, and not run full tilt,  so
           as not to cause appreciable load.

           However,  if  you  are  running the OpenGL-based screen savers on a
           machine that does not have a video card with 3D acceleration,  they
           will make your machine slow, despite nice(1).

           Your  options  are: don't use the OpenGL display modes; or, collect
           the spare change hidden under the cushions of your couch,  and  use
           it  to  buy a video card manufactured after 1998.  (It doesn't even
           need to be fast 3D hardware: the problem will be fixed if there  is
           any 3D hardware at all.)

       XFree86's Magic Keystrokes
           The  XFree86  X server traps certain magic keystrokes before client
           programs   ever   see   them.    Two   that   are   of   note   are
           Ctrl+Alt+Backspace,   which  causes  the  X  server  to  exit;  and
           Ctrl+Alt+Fn, which switches virtual consoles.  The  X  server  will
           respond  to  these  keystrokes  even if xscreensaver has the screen
           locked.  Depending on your setup, you might consider this  a  prob-
           lem.

           Unfortunately,  there is no way for xscreensaver itself to override
           the  interpretation  of  these  keys.   If  you  want  to   disable
           Ctrl+Alt+Backspace  globally,  you  need to set the DontZap flag in
           your /etc/X11/XF86Config file.  To globally disable  VT  switching,
           you  can  set  the DontVTSwitch flag.  See the XF86Config(5) manual
           for details.

X RESOURCES
       These are the X resources use by the xscreensaver program.  You  proba-
       bly  won't  need  to  change  these  manually (that's what the xscreen-
       saver-demo(1) program is for).

       timeout (class Time)
               The screensaver will activate (blank the screen) after the key-
               board  and mouse have been idle for this many minutes.  Default
               10 minutes.

       cycle (class Time)
               After the screensaver has been running for this  many  minutes,
               the  currently running graphics-hack sub-process will be killed
               (with SIGTERM), and a new one started.  If this is 0, then  the
               graphics  hack  will  never  be changed: only one demo will run
               until the screensaver is deactivated by user activity.  Default
               10 minutes.

       lock (class Boolean)
               Enable  locking:  before the screensaver will turn off, it will
               require you to type the password of the logged-in user (really,
               the person who ran xscreensaver), or the root password.  (Note:
               this doesn't work if the  screensaver  is  launched  by  xdm(1)
               because  it  can't know the user-id of the logged-in user.  See
               the "Using XDM(1)" section, below.

       lockTimeout (class Time)
               If locking is enabled, this controls the length of  the  "grace
               period"  between  when  the screensaver activates, and when the
               screen becomes locked.  For example, if this is 5, and -timeout
               is 10, then after 10 minutes, the screen would blank.  If there
               was user activity at 12 minutes, no password would be  required
               to  un-blank the screen.  But, if there was user activity at 15
               minutes or later (that is, -lock-timeout minutes after  activa-
               tion)  then  a  password  would be required.  The default is 0,
               meaning that if locking is enabled, then  a  password  will  be
               required as soon as the screen blanks.

       passwdTimeout (class Time)
               If  the  screen  is  locked,  then this is how many seconds the
               password dialog box should be left on the screen before  giving
               up  (default  30 seconds.)  This should not be too large: the X
               server is grabbed for the duration that the password dialog box
               is  up  (for  security purposes) and leaving the server grabbed
               for too long can cause problems.

       dpmsEnabled (class Boolean)
               Whether power management is enabled.

       dpmsStandby (class Time)
               If power management is enabled, how long until the monitor goes
               solid black.

       dpmsSuspend (class Time)
               If power management is enabled, how long until the monitor goes
               into power-saving mode.

       dpmsOff (class Time)
               If power management is enabled, how long until the monitor pow-
               ers  down  completely.   Note  that these settings will have no
               effect unless both the X server and the display  hardware  sup-
               port  power  management;  not all do.  See the Power Management
               section, below, for more information.

       dpmsQuickOff (class Boolean)
               If mode is blank and this is true, then the screen will be pow-
               ered down immediately upon blanking, regardless of other power-
               management settings.

       visualID (class VisualID)
               Specify which X visual to use by default.  (Note carefully that
               this resource is called visualID, not merely visual; if you set
               the visual resource instead, things will malfunction in obscure
               ways for obscure reasons.)

               Legal values for the VisualID resource are:

               default Use the screen's default visual (the visual of the root
                       window.)  This is the default.

               best    Use the visual which supports the most  colors.   Note,
                       however,  that the visual with the most colors might be
                       a TrueColor visual, which  does  not  support  colormap
                       animation.   Some programs have more interesting behav-
                       ior when run on PseudoColor visuals than on TrueColor.

               mono    Use a monochrome visual, if there is one.

               gray    Use a grayscale or staticgray visual, if there  is  one
                       and it has more than one plane (that is, it's not mono-
                       chrome.)

               color   Use the best of the color visuals, if there are any.

               GL      Use the  visual  that  is  best  for  OpenGL  programs.
                       (OpenGL  programs  have somewhat different requirements
                       than other X programs.)

               class   where class is one of  StaticGray,  StaticColor,  True-
                       Color, GrayScale, PseudoColor, or DirectColor.  Selects
                       the deepest visual of the given class.

               number  where number (decimal or hex) is interpreted as a  vis-
                       ual  id number, as reported by the xdpyinfo(1) program;
                       in this way you can have  finer  control  over  exactly
                       which  visual gets used, for example, to select a shal-
                       lower one than would otherwise have been chosen.

               Note that this option specifies only the  default  visual  that
               will  be  used: the visual used may be overridden on a program-
               by-program  basis.   See  the  description  of   the   programs
               resource, below.

       installColormap (class Boolean)
               On  PseudoColor  (8-bit)  displays,  install a private colormap
               while the screensaver is active, so that the graphics hacks can
               get  as  many  colors as possible.  This is the default.  (This
               only applies when the screen's default visual  is  being  used,
               since  non-default  visuals  get  their own colormaps automati-
               cally.)  This can also be overridden on a per-hack  basis:  see
               the  discussion  of the default-n name in the section about the
               programs resource.

               This does nothing if you have a TrueColor  (16-bit  or  deeper)
               display.

       verbose (class Boolean)
               Whether to print diagnostics.  Default false.

       timestamp (class Boolean)
               Whether  to print the time of day along with any other diagnos-
               tic messages.  Default true.

       splash (class Boolean)
               Whether to display a splash screen at startup.  Default true.

       splashDuration (class Time)
               How long the splash screen should  remain  visible;  default  5
               seconds.

       helpURL (class URL)
               The  splash screen has a Help button on it.  When you press it,
               it will display  the  web  page  indicated  here  in  your  web
               browser.

       loadURL (class LoadURL)
               This  is  the  shell  command  used to load a URL into your web
               browser.  The default setting will load  it  into  Mozilla/Net-
               scape  if  it  is already running, otherwise, will launch a new
               browser looking at the helpURL.

       demoCommand (class DemoCommand)
               This is the shell command run  when  the  Demo  button  on  the
               splash window is pressed.  It defaults to xscreensaver-demo(1).

       prefsCommand (class PrefsCommand)
               This  is  the  shell  command  run when the Prefs button on the
               splash  window   is   pressed.    It   defaults   to   xscreen-
               saver-demo -prefs.

       newLoginCommand (class NewLoginCommand)
               If  set,  this  is  the shell command that is run when the "New
               Login" button is pressed on the unlock dialog box, in order  to
               create  a  new desktop session without logging out the user who
               has locked the screen.  Typically this will be some variant  of
               gdmflexiserver(1) or kdmctl(1).

       nice (class Nice)
               The  sub-processes  created  by xscreensaver will be "niced" to
               this level, so that they are given lower  priority  than  other
               processes  on  the system, and don't increase the load unneces-
               sarily.  The default is 10.  (Higher numbers mean lower  prior-
               ity; see nice(1) for details.)

       fade (class Boolean)
               If  this is true, then when the screensaver activates, the cur-
               rent contents of the screen will fade to black instead of  sim-
               ply  winking  out.  This only works on certain systems.  A fade
               will also be done when switching graphics hacks (when the cycle
               timer expires.)  Default: true.

       unfade (class Boolean)
               If  this  is  true,  then when the screensaver deactivates, the
               original contents of the screen will fade in from black instead
               of  appearing immediately.  This only works on certain systems,
               and if fade is true as well.  Default false.

       fadeSeconds (class Time)
               If fade is true, this is how long the fade will be  in  seconds
               (default 3 seconds.)

       fadeTicks (class Integer)
               If  fade  is true, this is how many times a second the colormap
               will be  changed  to  effect  a  fade.   Higher  numbers  yield
               smoother  fades,  but  may  make the fades take longer than the
               specified fadeSeconds if your server isn't fast enough to  keep
               up.  Default 20.

       captureStderr (class Boolean)
               Whether  xscreensaver  should  redirect  its  stdout and stderr
               streams to the window itself.  Since its nature is to take over
               the screen, you would not normally see error messages generated
               by xscreensaver or the sub-programs it runs; this resource will
               cause  the  output  of all relevant programs to be drawn on the
               screensaver window itself, as well as being written to the con-
               trolling  terminal  of the screensaver driver process.  Default
               true.

       ignoreUninstalledPrograms (class Boolean)
               There may be programs in the list that are not installed on the
               system,  yet  are  marked  as "enabled."  If this preference is
               true, then such programs will simply  be  ignored.   If  false,
               then a warning will be printed if an attempt is made to run the
               nonexistent program.  Also,  the  xscreensaver-demo(1)  program
               will  suppress  the non-existent programs from the list if this
               is true.  Default: false.

       authWarningSlack (class Integer)
               If all failed unlock attempts (incorrect password entered) were
               made  within  this  period of time, the usual dialog that warns
               about such attempts after  a  successful  login  will  be  sup-
               pressed.  The  assumption  is  that incorrect passwords entered
               within a few seconds of a correct one are  user  error,  rather
               than hostile action.  Default 20 seconds.

       GetViewPortIsFullOfLies (class Boolean)
               Set  this  to true if the xscreensaver window doesn't cover the
               whole screen.  This works around  a  longstanding  XFree86  bug
               #421.  See the xscreensaver FAQ for details.

       font (class Font)
               The  font  used for the stdout/stderr text, if captureStderr is
               true.  Default *-medium-r-*-140-*-m-* (a 14  point  fixed-width
               font.)

       mode (class Mode)
               Controls the behavior of xscreensaver.  Legal values are:

               random  When  blanking the screen, select a random display mode
                       from among those that are enabled and applicable.  This
                       is the default.

               random-same
                       Like  random,  but  if there are multiple screens, each
                       screen will run the same random display  mode,  instead
                       of each screen running a different one.

               one     When  blanking the screen, only ever use one particular
                       display mode (the one indicated by  the  selected  set-
                       ting.)

               blank   When  blanking the screen, just go black: don't run any
                       graphics hacks.

               off     Don't ever blank the screen, and don't ever  allow  the
                       monitor to power down.


       selected (class Integer)
               When  mode  is  set  to  one, this is the one, indicated by its
               index in the programs list.  You're crazy if you count them and
               set  this  number  by  hand: let xscreensaver-demo(1) do it for
               you!

       programs (class Programs)
               The graphics hacks which xscreensaver runs  when  the  user  is
               idle.   The  value of this resource is a multi-line string, one
               sh-syntax command per line.  Each line must contain exactly one
               command: no semicolons, no ampersands.

               When  the  screensaver  starts  up,  one  of  these is selected
               (according to the mode setting),  and  run.   After  the  cycle
               period expires, it is killed, and another is selected and run.

               If  a  line begins with a dash (-) then that particular program
               is disabled: it won't be selected at  random  (though  you  can
               still  select it explicitly using the xscreensaver-demo(1) pro-
               gram.)

               If all programs are disabled, then the screen will just be made
               blank, as when mode is set to blank.

               To  disable a program, you must mark it as disabled with a dash
               instead of removing it from the list.  This is because the sys-
               tem-wide  (app-defaults)  and per-user (.xscreensaver) settings
               are merged together, and if a user just deletes an  entry  from
               their programs list, but that entry still exists in the system-
               wide list, then it will come back.  However, if the  user  dis-
               ables it, then their setting takes precedence.

               If  the  display has multiple screens, then a different program
               will be run for each screen.   (All  screens  are  blanked  and
               unblanked simultaneously.)

               Note  that  you must escape the newlines; here is an example of
               how you might set this in your ~/.xscreensaver file:

               programs:  \
                      qix -root                          \n\
                      ico -r -faces -sleep 1 -obj ico    \n\
                      xdaliclock -builtin2 -root         \n\
                      xv -root -rmode 5 image.gif -quit  \n
               Make sure your $PATH environment variable is set  up  correctly
               before  xscreensaver  is  launched, or it won't be able to find
               the programs listed in the programs resource.

               To use a program as a screensaver,  two  things  are  required:
               that  that  program  draw  on the root window (or be able to be
               configured to draw on the root window); and that  that  program
               understand  "virtual  root"  windows, as used by virtual window
               managers such as tvtwm(1).  (Generally, this is accomplished by
               just  including  the  "vroot.h"  header  file  in the program's
               source.)

               Visuals:

               Because xscreensaver was created back when dinosaurs roamed the
               earth,  it still contains support for some things you've proba-
               bly never seen, such as 1-bit  monochrome  monitors,  grayscale
               monitors,  and  monitors  capable of displaying only 8-bit col-
               ormapped images.

               If there are some programs that you want to run only when using
               a  color  display,  and  others  that you want to run only when
               using a monochrome display, you can specify that like this:
                      mono:   mono-program  -root        \n\
                      color:  color-program -root        \n\
               More generally, you can specify the kind of visual that  should
               be  used  for  the window on which the program will be drawing.
               For example, if one program works best if it  has  a  colormap,
               but  another  works best if it has a 24-bit visual, both can be
               accommodated:
                      PseudoColor: cmap-program  -root   \n\
                      TrueColor:   24bit-program -root   \n\
               In addition to the symbolic visual names  described  above  (in
               the  discussion of the visualID resource) one other visual name
               is supported in the programs list:

                default-n
                    This is like default, but also requests  the  use  of  the
                    default  colormap,  instead  of a private colormap.  (That
                    is, it behaves as if the -no-install  command-line  option
                    was  specified,  but only for this particular hack.)  This
                    is provided because some third-party programs that draw on
                    the  root  window  (notably:  xv(1),  and  xearth(1)) make
                    assumptions about the visual and colormap of the root win-
                    dow: assumptions which xscreensaver can violate.

               If you specify a particular visual for a program, and that vis-
               ual does not exist on the screen, then that program will not be
               chosen  to  run.   This  means  that  on displays with multiple
               screens of different depths, you can  arrange  for  appropriate
               hacks  to  be run on each.  For example, if one screen is color
               and the other is monochrome, hacks that look good in  mono  can
               be run on one, and hacks that only look good in color will show
               up on the other.

       You shouldn't ever need to change the following resources:

       pointerPollTime (class Time)
               When server extensions are not in use, this controls  how  fre-
               quently  xscreensaver  checks  to  see if the mouse position or
               buttons have changed.  Default 5 seconds.

       pointerHysteresis (class Integer)
               If the mouse moves less than  this-many  pixels  in  a  second,
               ignore  it (do not consider that to be "activity.")  This is so
               that the screen  doesn't  un-blank  (or  fail  to  blank)  just
               because you bumped the desk.  Default: 10 pixels.

       windowCreationTimeout (class Time)
               When  server extensions are not in use, this controls the delay
               between when windows are created and when xscreensaver  selects
               events on them.  Default 30 seconds.

       initialDelay (class Time)
               When  server  extensions are not in use, xscreensaver will wait
               this many seconds before selecting events on existing  windows,
               under  the  assumption that xscreensaver is started during your
               login procedure, and the window state may be in flux.   Default
               0.   (This used to default to 30, but that was back in the days
               when slow machines and X terminals were more common...)

       procInterrupts (class Boolean)
               This resource controls whether the /proc/interrupts file should
               be  consulted  to decide whether the user is idle.  This is the
               default if xscreensaver has been compiled  on  a  system  which
               supports this mechanism (i.e., Linux systems.)

               The  benefit  to  doing this is that xscreensaver can note that
               the user is active even when the X console is  not  the  active
               one: if the user is typing in another virtual console, xscreen-
               saver will notice that and will fail to activate.  For example,
               if you're playing Quake in VGA-mode, xscreensaver won't wake up
               in the middle of your game and start competing for CPU.

               The drawback to doing this is that perhaps you really  do  want
               idleness  on the X console to cause the X display to lock, even
               if there is activity on other virtual consoles.   If  you  want
               that,  then set this option to False.  (Or just lock the X con-
               sole manually.)

               The default value for this resource is True, on  systems  where
               it works.

       overlayStderr (class Boolean)
               If  captureStderr  is  True, and your server supports "overlay"
               visuals, then the text will be written into one of  the  higher
               layers  instead  of  into the same layer as the running screen-
               hack.  Set this to False to disable that (though you  shouldn't
               need to.)

       overlayTextForeground (class Foreground)
               The  foreground  color used for the stdout/stderr text, if cap-
               tureStderr is true.  Default: Yellow.

       overlayTextBackground (class Background)
               The background color used for the stdout/stderr text,  if  cap-
               tureStderr is true.  Default: Black.

       bourneShell (class BourneShell)
               The  pathname of the shell that xscreensaver uses to start sub-
               processes.  This must be whatever your local variant of /bin/sh
               is: in particular, it must not be csh.

ENVIRONMENT
       DISPLAY to  get  the default host and display number, and to inform the
               sub-programs of the screen on which to draw.

       XSCREENSAVER_WINDOW
               Passed to sub-programs to indicate the  ID  of  the  window  on
               which  they  should  draw.  This is necessary on Xinerama/RANDR
               systems where multiple physical monitors  share  a  single  X11
               "Screen".

       PATH    to find the sub-programs to run.

       HOME    for the directory in which to read the .xscreensaver file.

       XENVIRONMENT
               to  get  the  name of a resource file that overrides the global
               resources stored in the RESOURCE_MANAGER property.

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

SEE ALSO
       X(1),   Xsecurity(1),  xauth(1),  xdm(1),  gdm(1),  xhost(1),  xscreen-
       saver-demo(1),   xscreensaver-command(1),    xscreensaver-gl-helper(1),
       xscreensaver-getimage(1), xscreensaver-text(1).

COPYRIGHT
       Copyright  (C)  1991-2014  by Jamie Zawinski.  Permission to use, copy,
       modify, distribute, and sell this software and  its  documentation  for
       any  purpose  is  hereby  granted  without fee, provided that the above
       copyright notice appear in all copies  and  that  both  that  copyright
       notice  and  this permission notice appear in supporting documentation.
       No representations are made about the suitability of this software  for
       any  purpose.   It  is provided "as is" without express or implied war-
       ranty.

AUTHOR
       Jamie Zawinski <jwz@jwz.org>.  Written in late 1991; version 1.0 posted
       to comp.sources.x on 17-Aug-1992.

       Please let me know if you find any bugs or make any improvements.

       And a huge thank you to the hundreds of people who have contributed, in
       large ways and small, to the xscreensaver collection over the past  two
       decades!



X Version 11                  5.30 (11-Sep-2014)               xscreensaver(1)
