Provided by: xscreensaver_5.10-3ubuntu4_i386 bug

NAME

       xscreensaver - extensible screen saver framework, plus locking

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-
       saving 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
       program 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
       xscreensaver-demo(1)  program, and change the settings through the GUI.
       The rest of this manual page describes lower  level  ways  of  changing
       settings.

       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
       .xscreensaver 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
       .Xdefaults  file;  for  example,  to  set  the  timeout paramter in the
       .xscreensaver 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/openwin/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
       .Xdefaults  file  and  the  app-defaults  file will never be written by
       xscreensaver 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
               simultaniously.

       -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
               xscreensaver 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
       screensaver 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
       xscreensaver-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
       xscreensaver-demo(1) window,  then that means that your X  server  does
       not  support  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
       settings 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 many years, GNOME shipped xscreensaver as-is, and  everything  just
       worked  out  of  the box.  Recently, however, they’ve been re-inventing
       the wheel again in the form of "gnome-screensaver".

       To replace gnome-screensaver with xscreensaver:

           1: Turn off gnome-screensaver.
              Open ‘‘System / Preferences /  Screensaver’’  and  uncheck  both
              boxes.

           2: Stop gnome-screensaver from launching at login.
              Run the command:

                   gconftool-2 --type boolean -s \
                   /apps/gnome_settings_daemon/screensaver/start_screensaver \
                   false

              Or, just uninstall the "gnome-screensaver" package entirely.

           3: Launch xscreensaver at login.
              Open  ‘‘System  /  Preferences  / Sessions / Startup Programs’’.
              Click ‘‘Add’’ and type ‘‘xscreensaver’’.

           4: Tell Preferences to use the xscreensaver configurator.
              Edit                  /usr/share/applications/gnome-screensaver-
              preferences.desktop and change the Exec= line to say
                  Exec=xscreensaver-demo

           5: Make ‘‘System / Quit / Lock Screen’’ use xscreensaver.
              Run the command:

                   sudo ln -sf /usr/bin/xscreensaver-command \
                               /usr/bin/gnome-screensaver-command

USING KDE

       KDE  also  has  invented  their  own  screen saver framework instead of
       simply using xscreensaver.   To  replace  the  KDE  screen  saver  with
       xscreensaver, do the following:

           1: Turn off KDEs 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.
              Replace  the file kdesktop_lock or krunner_lock in /usr/bin/ (or
              possibly /usr/kde/3.5/bin/ or /usr/lib/kde4/libexec/) 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
       xscreensaver-demo(1) and xscreensaver-command(1) mechanisms.

USING GDM

       You can  run  xscreensaver  from  your  gdm(1)  session,  so  that  the
       screensaver  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 is likely to do.)  If
       run as root, xscreensaver changes its effective user and group  ids  to
       something  safe  (like  "nobody")  before connecting to the X server or
       launching 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 XDM
               If xscreensaver has been launched from xdm(1) before anyone has
               logged  in,  you  will  need  to  kill  and  then  restart  the
               xscreensaver  daemon  after  you have logged in, or you will be
               confused by the results.  (For example, locking won’t work, and
               your ~/.xscreensaver file will be ignored.)

               When  you are logged in, you want the xscreensaver daemon to be
               running under your user id, not as root or some other user.

               If it has already been started by  xdm,  you  can  kill  it  by
               sending  it  the exit command, and then re-launching it as you,
               by putting something like the  following  in  your  personal  X
               startup script:

                    xscreensaver-command -exit
                    xscreensaver &

               The ‘‘Using XDM(1)’’ section, above, goes into more detail, and
               explains how to configure the system to do this for  all  users
               automatically.

       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
               console,  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 something?)

               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), programs
               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  XDM(1)’’
               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/xscreensaver 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 consume 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.)

       XFree86s 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 problem.

               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
       probably   won’t  need  to  change  these  manually  (that’s  what  the
       xscreensaver-demo(1) program is for).

       timeout (class Time)
               The screensaver will activate  (blank  the  screen)  after  the
               keyboard  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
               activation)  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
               powers  down completely.  Note that these settings will have no
               effect unless both  the  X  server  and  the  display  hardware
               support power management; not all do.  See the Power Management
               section, below, for more information.

       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
                       behavior  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
                       monochrome.)

               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,
                       TrueColor,  GrayScale,  PseudoColor,  or   DirectColor.
                       Selects the deepest visual of the given class.

               number  where  number  (decimal  or  hex)  is  interpreted as a
                       visual  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  shallower 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
               automatically.)  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
               diagnostic 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/Netscape  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
               xscreensaver-demo -prefs.

       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
               unnecessarily.  The default is 10.

               (Higher  numbers mean lower priority; see nice(1) for details.)

       fade (class Boolean)
               If this is true,  then  when  the  screensaver  activates,  the
               current  contents  of  the screen will fade to black instead of
               simply 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
               controlling  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.

       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
                       setting.)

               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)
               program.)

               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
               system-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 disables 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.)

               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
                    window: assumptions which xscreensaver can violate.

               If you specify a particular visual  for  a  program,  and  that
               visual 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
               frequently 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...)

       There  are  a  number  of  different X server extensions which can make
       xscreensaver’s job easier.  The  next  few  resources  specify  whether
       these extensions should be utilized if they are available.

       sgiSaverExtension (class Boolean)
               This  resource  controls  whether  the  SGI SCREEN_SAVER server
               extension will be used to decide  whether  the  user  is  idle.
               This  is  the  default  if  xscreensaver has been compiled with
               support for  this  extension  (which  is  the  default  on  SGI
               systems.).   If  it  is  available,  the SCREEN_SAVER method is
               faster and more reliable than what will be done  otherwise,  so
               use  it  if  you  can.   (This  extension  is only available on
               Silicon Graphics systems, unfortunately.)

       mitSaverExtension (class Boolean)
               This resource  controls  whether  the  MIT-SCREEN-SAVER  server
               extension  will  be  used  to  decide whether the user is idle.
               However, the default for this resource is false,  because  even
               if  this extension is available, it is flaky (and it also makes
               the fade option not work properly.)  Use of this  extension  is
               strongly  discouraged.  Support for it will probably be removed
               eventually.

       xidleExtension (class Boolean)
               This resource controls whether the XIDLE server extension  will
               be  used  to  decide  whether  the  user  is idle.  This is the
               default if xscreensaver has been compiled with support for this
               extension.   (This  extension  is  only available for X11R4 and
               X11R5 systems, unfortunately.)

       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,
               xscreensaver 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
               console 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
               screenhack.   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
               captureStderr is true.  Default: Yellow.

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

       bourneShell (class BourneShell)
               The pathname of the  shell  that  xscreensaver  uses  to  start
               subprocesses.   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 on.  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),
       xscreensaver-demo(1),                          xscreensaver-command(1),
       xscreensaver-gl-helper(1),                    xscreensaver-getimage(1),
       xscreensaver-text(1).

COPYRIGHT

       Copyright © 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
       2001, 2002, 2003, 2004, 2005,  2006,  2007,  2008  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 warranty.

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.

ACKNOWLEDGEMENTS

       Thanks to Angela Goodman for the XScreenSaver logo.

       Thanks to the many people who have contributed graphics  demos  to  the
       package.

       Thanks to David Wojtowicz for implementing lockTimeout.

       Thanks  to  Martin  Kraemer for adding support for shadow passwords and
       locking-disabled diagnostics.

       Thanks to Patrick Moreau for the VMS port.

       Thanks to Nat Lanza for the Kerberos support.

       Thanks to Bill Nottingham for the initial PAM support.

       And thanks to Jon A. Christopher for  implementing  the  Athena  dialog
       support,   back   in  the  days  before  Lesstif  or  Gtk  were  viable
       alternatives to Motif.