xscreensaver



XScreenSaver(1)                                                XScreenSaver(1)




NAME

       xscreensaver - extensible screen saver framework, plus locking


SYNOPSIS

       xscreensaver   [-display   host:display.screen]   [-verbose]  [-no-cap-
       ture-stderr] [-no-splash]


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:  unlike  xlock(1),  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-com-
       mand(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 paramter 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.)


       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.

       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
                       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, True-
                       Color, 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)  pro-
                       gram;  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 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.

       quad (class Boolean)
               If  true,  then  four screensavers will be run on each monitor.
               Use at your own risk!

       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   xscreen-
               saver-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 unneces-
               sarily.  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 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.

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

               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 win-
                    dow: 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  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...)

       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 sup-
               port 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, 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.


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
               Same  as  setting  the  captureStderr resource to false: 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.


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.

       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.

       Before launching a subprocess, xscreensaver stores an appropriate value
       for $DISPLAY in the environment that the child will receive.  (This  is
       so  that  if  you start xscreensaver with a -display argument, the pro-
       grams which xscreensaver launches will draw on the same display; and so
       that  the  child  will  end  up  drawing on the appropriate screen of a
       multi-headed display.)

       When the screensaver turns off, or is killed, care is taken to  restore
       the  ‘‘real’’ virtual root window if there is one.  Because of this, it
       is important that you not kill the screensaver process with kill -9  if
       you are running a virtual-root window manager.  If you kill it with -9,
       you may need to restart your window manager to repair the damage.  This
       isn’t an issue if you aren’t running a virtual-root window manager.

       For  all  the  gory  details, see the commentary at the top of xscreen-
       saver.c.

       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.

       As of version 3.28 (Feb 2001), 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  xscreen-
       saver  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 XDM(1)

       You can run xscreensaver from your xdm(1) session, so that the  screen-
       saver will run even when nobody is logged in on the console.

       The  trick to using xscreensaver with xdm is this: keep in mind the two
       very different states in which xscreensaver will be running:

           1: Nobody logged in.

              If you’re thinking of running xscreensaver from XDM at all, then
              it’s  probably  because you want graphics demos to be running on
              the console when nobody is  logged  in  there.   In  this  case,
              xscreensaver  will function only as a screen saver, not a screen
              locker: it doesn’t make  sense  for  xscreensaver  to  lock  the
              screen,  since  nobody  is logged in yet!  The only thing on the
              screen is the XDM login prompt.

           2: Somebody logged in.

              Once someone has logged in through the  XDM  login  window,  the
              situation is very different.  For example: now it makes sense to
              lock the screen (and prompt for the logged in user’s  password);
              and  now xscreensaver should consult that user’s ~/.xscreensaver
              file; and so on.

       The difference between these two states comes down to  a  question  of,
       which  user  is  the  xscreensaver  process  running as?  For the first
       state, it doesn’t matter.  If you start xscreensaver in the  usual  XDM
       way,  then  xscreensaver will probably end up running as root, which is
       fine for the first case (the ‘‘nobody logged in’’ case.)

       However, once someone is logged in, running as root is no longer  fine:
       because  xscreensaver  will  be  consulting  root’s  .xscreensaver file
       instead of that of the logged in user, and won’t be prompting  for  the
       logged in user’s password, and so on.  (This is not a security problem,
       it’s just not what you want.)

       So, once someone has logged in, you want xscreensaver to be running  as
       that  user.  The way to accomplish this is to kill the old xscreensaver
       process and start a new one (as the new user.)

       The simplest way to accomplish all of this is as follows:

           1: Launch xscreensaver before anyone logs in.

              To the file /usr/lib/X11/xdm/Xsetup, add the lines

                   xhost +localhost
                   xscreensaver-command -exit
                   xscreensaver &

              This will run xscreensaver as root, over the XDM  login  window.
              Moving  the  mouse  will cause the screen to un-blank, and allow
              the user to type their password at XDM to log in.

           2: Restart xscreensaver when someone logs in.

              Near the top of the file  /usr/lib/X11/xdm/Xsession,  add  those
              same lines:

                   xscreensaver-command -exit
                   xscreensaver &

              When  someone  logs  in,  this will kill off the existing (root)
              xscreensaver process, and start a new one, running as  the  user
              who  has  just  logged  in.   If  the  user’s .xscreensaver file
              requests locking, they’ll get it.  They will also get their  own
              choice of timeouts, and graphics demos, and so on.

              Alternately,  each user could just put those lines in their per-
              sonal ~/.xsession files.

       Make sure you have $PATH set up correctly in the  Xsetup  and  Xsession
       scripts, or xdm won’t be able to find xscreensaver, and/or xscreensaver
       won’t be able to find its graphics demos.

       (If your system does not seem to be executing the Xsetup file, you  may
       need  to  configure  it  to do so: the traditional way to do this is to
       make that file the value of the DisplayManager*setup  resource  in  the
       /usr/lib/X11/xdm/xdm-config file.  See the man page for xdm(1) for more
       details.)

       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
       xdm,  then  this  probably  means  that you have xauth(1) or some other
       security  mechanism  turned  on.   One  way  around  this  is  to   add
       "xhost +localhost" to Xsetup, just before xscreensaver is launched.

       Note  that  this  will give access to the X server to anyone capable of
       logging in to the local machine, so in some  environments,  this  might
       not be appropriate.  If turning off file-system-based access control is
       not acceptable, then running xscreensaver from the  Xsetup  file  might
       not be possible, and xscreensaver will only work when running as a nor-
       mal, unprivileged user.

       For more information on the X server’s access control  mechanisms,  see
       the man pages for X(1), Xsecurity(1), xauth(1), and xhost(1).


USING GDM(1)

       Using xscreensaver with gdm(1) is easy, because gdm has a configuration
       tool.  Just fire up gdmconfig(1)  and  on  the  Background  page,  type
       "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".


USING KDE (K DESKTOP ENVIRONMENT)

       I  understand  that  KDE has invented their own wrapper around xscreen-
       saver, that is inferior to xscreensaver-demo(1) in any number of  ways.
       I’ve never actually seen it, but I’m told that this is the way you dis-
       able it:

           1: Switch off KDEs screen saver.
              Open the ‘‘Control Center’’ and select the  ‘‘Look  and  Feel  /
              Screensaver’’  page.  Turn off the ‘‘Enable Screensaver’’ check-
              box.

           2: Find your Autostart directory.
              Open the ‘‘Look and Feel / Desktop / Paths’’ page, and see  what
              your  ‘‘Autostart’’  directory  is  set  to: it will probably be
              ~/.kde3/Autostart/ or something similar.

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

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


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


USING CDE (COMMON DESKTOP ENVIRONMENT)

       The easiest way to use xscreensaver on a system with CDE is  to  simply
       switch  off the built-in CDE screensaver, and use xscreensaver instead;
       and second, to tell the front panel to run xscreensaver-command(1) with
       the -lock option when the Lock icon is clicked.

       To accomplish this involves five steps:

           1: Switch off CDEs locker
              Do  this  by turning off ‘‘Screen Saver and Screen Lock’’ in the
              Screen section of the Style Manager.

           2: Edit sessionetc
              Edit the file ~/.dt/sessions/sessionetc and add to it the line

                   xscreensaver &

              And make sure the sessionetc  file  is  executable.   This  will
              cause  xscreensaver to be launched when you log in.  (As always,
              make sure that xscreensaver and the graphics demos are  on  your
              $PATH; the path needs to be set in .cshrc and/or .dtprofile, not
              .login.)

           3: Create XScreenSaver.dt
              Create a file called ~/.dt/types/XScreenSaver.dt with  the  fol-
              lowing contents:

                   ACTION XScreenSaver
                   {
                     LABEL         XScreenSaver
                     TYPE          COMMAND
                     EXEC_STRING   xscreensaver-command -lock
                     ICON          Dtkey
                     WINDOW_TYPE   NO_STDIO
                   }

              This  defines  a  ‘‘lock’’ command for the CDE front panel, that
              knows how to talk to xscreensaver.

           4: Create Lock.fp
              Create a file called ~/.dt/types/Lock.fp with the following con-
              tents:

                   CONTROL Lock
                   {
                     TYPE             icon
                     CONTAINER_NAME   Switch
                     CONTAINER_TYPE   SWITCH
                     POSITION_HINTS   1
                     ICON             Fplock
                     LABEL            Lock
                     PUSH_ACTION      XScreenSaver
                     HELP_TOPIC       FPOnItemLock
                     HELP_VOLUME      FPanel
                   }

              This  associates the CDE front panel ‘‘Lock’’ icon with the lock
              command we just defined in step 3.

           5: Restart
              Select ‘‘Restart Workspace Manager’’ from the popup menu to make
              your  changes  take  effect.   If things seem not to be working,
              check the file ~/.dt/errorlog for error messages.


USING HP VUE (VISUAL USER ENVIRONMENT)

       Since CDE is a descendant of VUE, the instructions for  using  xscreen-
       saver under VUE are similar to the above:

           1: Switch off VUEs locker
              Open  the  ‘‘Style  Manager’’  and  select ‘‘Screen.’’  Turn off
              ‘‘Screen Saver and Screen Lock’’ option.

           2: Make sure you have a Session
              Next, go to the Style Manager’s,  ‘‘Startup’’  page.   Click  on
              ‘‘Set  Home  Session’’  to create a session, then on ‘‘Return to
              Home Session’’ to select this session each time you log in.

           3: Edit vue.session
              Edit the file ~/.vue/sessions/home/vue.session and add to it the
              line

                   vuesmcmd -screen 0 -cmd "xscreensaver"

              This  will  cause  xscreensaver  to be launched when you log in.
              (As always, make sure that xscreensaver and the  graphics  demos
              are  on  your  $PATH;  the path needs to be set in .cshrc and/or
              .profile, not .login.)

           3: Edit vuewmrc
              Edit the file ~/.vue/vuewmrc and add (or change) the  Lock  con-
              trol:

                   CONTROL Lock
                   {
                     TYPE         button
                     IMAGE        lock
                     PUSH_ACTION  f.exec "xscreensaver-command -lock"
                     HELP_TOPIC   FPLock
                   }

              This  associates  the  VUE  front  panel  ‘‘Lock’’ icon with the
              xscreensaver lock command.



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 xscreen-
               saver 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 send-
               ing 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  your-
               self,  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 run-
               ning on the local machine as user "nobody" must be able to con-
               nect 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 xscreen-
               saver 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 pass-
               word.’’)  As far as I can tell, there is no  way  for  xscreen-
               saver  to automatically work around this, or detect the problem
               in advance, so if you have PAM, make sure it is configured cor-
               rectly!

       Colormap lossage: TWM
               The  installColormap  option  doesn’t  work  very well with the
               twm(1) window manager and its descendants, on 8-bit screens.

               There is a race condition between the screensaver and this win-
               dow manager, which can result in the screensaver’s colormap not
               getting installed properly, meaning  the  graphics  hacks  will
               appear in essentially random colors.  (If the screen goes white
               instead of black, this is probably why.)

               The mwm(1) and olwm(1) window managers don’t have this problem.
               The  race  condition  exists because X (really, ICCCM) does not
               provide a way for an OverrideRedirect window to  have  its  own
               colormap, short of grabbing the server (which is neither a good
               idea, nor really possible with the current design.)  What  hap-
               pens  is  that,  as soon as xscreensaver installs its colormap,
               twm responds to  the  resultant  ColormapNotify  event  by  re-
               instaling the default colormap.  Apparently, twm doesn’t always
               do this; it seems to do it  regularly  if  the  screensaver  is
               activated  from  a  menu  item,  but  seems to not do it if the
               screensaver comes on of its own volition, or is activated  from
               another console.

               Attention, window manager authors!
                   You  should  only  call  XInstallColormap(3) in response to
                   user events.  That is, it is appropriate to install a  col-
                   ormap  in  response  to FocusIn, FocusOut, EnterNotify, and
                   LeaveNotify events; but it is not appropriate to call it in
                   response  to  ColormapNotify  events.   If you install col-
                   ormaps in response to application actions  as  well  as  in
                   response  to  user  actions,  then you create the situation
                   where it is impossible for  override-redirect  applications
                   (such  as  xscreensaver)  to  display  their windows in the
                   proper colors.

       Colormap lossage: XV, XAnim, XEarth
               Some programs don’t operate properly on visuals other than  the
               default one, or with colormaps other than the default one.  See
               the discussion of the magic  "default-n"  visual  name  in  the
               description  of the programs resource in the Configuration sec-
               tion.  When programs only work with the default  colormap,  you
               need to use a syntax like this:

                       default-n: xv -root image-1.gif -quit  \n\
                       default-n: xearth -nostars -wait 0     \n\

               It would also work to turn off the installColormap option alto-
               gether, but that would deny extra colors to those programs that
               can take advantage of them.

       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,  col-
               lect  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 over-
               ride  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 XF86Con-
               fig(5) manual for details.

       MIT Extension and Fading
               The MIT-SCREEN-SAVER extension is junk.  Don’t use it.

               When  using  the MIT-SCREEN-SAVER extension in conjunction with
               the fade option, you’ll notice  an  unattractive  flicker  just
               before  the  fade  begins.   This  is because the server maps a
               black window just before it tells the xscreensaver  process  to
               activate.   The  xscreensaver  process  immediately unmaps that
               window, but this results in a flicker.  I haven’t figured a way
               to  get  around  this; it seems to be a fundamental property of
               the (mis-) design of this server extension.

               It sure would be  nice  if  someone  would  implement  the  SGI
               SCREEN_SAVER  extension in XFree86; it’s dead simple, and works
               far better than the overengineered and broken  MIT-SCREEN-SAVER
               extension.

       Keyboard LEDs
               If procInterrupts is on (which is the default on Linux systems)
               and you’re using some program that toggles the  state  of  your
               keyboard  LEDs,  xscreensaver  won’t  work right: turning those
               LEDs on or off causes a keyboard interrupt, which  xscreensaver
               will  interpret  as  user  activity.  So if you’re using such a
               program, set the procInterrupts resource to False.

       Extensions
               If you are not making use  of  one  of  the  server  extensions
               (XIDLE, SGI SCREEN_SAVER, or MIT-SCREEN-SAVER), then it is pos-
               sible, in rare situations, for xscreensaver to  interfere  with
               event  propagation and make another X program malfunction.  For
               this to occur, that other application would need to not  select
               KeyPress  events  on  its  non-leaf windows within the first 30
               seconds of their existence, but then select for them later.  In
               this  case,  that  client  might  fail to receive those events.
               This isn’t very likely, since programs generally select a  con-
               stant  set  of  events immediately after creating their windows
               and then don’t change them, but this is the reason that it’s  a
               good  idea  to  install  and  use  one of the server extensions
               instead, to work around this shortcoming in the X protocol.

               In all these years, I’ve not heard of even  a  single  case  of
               this  happening,  but it is theoretically possible, so I’m men-
               tioning it for completeness...


ENVIRONMENT

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

       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), xscreensaver-demo(1), xscreensaver-com-
       mand(1), xscreensaver-gl-helper(1),  xscreensaver-getimage(1),  xdm(1),
       gdm(1),   xset(1),   xhost(1).    anemone(1),   ant(1),  apollonian(1),
       atlantis(1),  attraction(1),   barcode(1),   blaster(1),   blitspin(1),
       bouboule(1),  boxed(1),  braid(1),  bsod(1),  bubble3d(1),  bubbles(1),
       bumps(1), cage(1), ccurve(1), circuit(1),  compass(1),  coral(1),  cos-
       mos(1),  critical(1),  crystal(1),  cubenetic(1),  cynosure(1), danger-
       ball(1), decayscreen(1),  deco(1),  deluxe(1),  demon(1),  discrete(1),
       distort(1),  drift(1),  electricsheep(1), endgame(1), engine(1), epicy-
       cle(1), eruption(1),* euler2d(1), extrusion(1),  fadeplot(1),  flag(1),
       flame(1),  flipscreen3d(1),  flow(1),  fluidballs(1),  flurry(1),  for-
       est(1),  galaxy(1),  gears(1),  gflux(1),  glblur(1),  glforestfire(1),
       glplanet(1),  glsnake(1),  gltext(1), goban(1), goop(1), grav(1), grey-
       netic(1), halftone(1), halo(1),  helix(1),  hopalong(1),  hyperball(1),
       hypercube(1), ifs(1), imsmap(1), interference(1), jigsaw(1), juggle(1),
       julia(1), kaleidescope(1), kumppa(1), lament(1), laser(1), lavalite(1),
       lightning(1),   lisa(1),   lissie(1),   lmorph(1),   loop(1),  maze(1),
       menger(1), metaballs(1), moebius(1), moire(1), moire2(1),  molecule(1),
       morph3d(1),  mountain(1),  munch(1), nerverot(1), noseguy(1), pedal(1),
       penetrate(1), penrose(1),  petri(1),  phosphor(1),  pipes(1),  polyomi-
       noes(1),  popsquares(1),  pulsar(1),  pyro(1),  qix(1),  queens(1), rd-
       bomb(1), ripples(1), rocks(1),  rorschach(1),  rotor(1),  rotzoomer(1),
       rubik(1),   sballs(1),  shadebobs(1),  sierpinski(1),  sierpinski3d(1),
       slidescreen(1), slip(1), sonar(1), speedmine(1), sphere(1), sphereEver-
       sion(1),   spheremonics(1),   spiral(1),  spotlight(1),  sproingies(1),
       squiral(1),  ssystem(1),  stairs(1),  starfish(1),  starwars(1),  ston-
       erview(1),   strange(1),  superquadrics(1),  swirl(1),  t3d(1),  thorn-
       bird(1),  triangle(1),  truchet(1),  twang(1),   vermiculate(1),   vid-
       whacker(1),   vines(1),   wander(1),  webcollage(1),  whirlwindwarp(1),
       whirlygig(1), worm(1), xaos(1), xdaliclock(1), xearth(1), xfishtank(1),
       xflame(1), xjack(1), xlyap(1), xmatrix(1), xmountains(1), xrayswarm(1),
       xsnow(1), xspirograph(1), xteevee(1), zoom(1)


COPYRIGHT

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


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  alterna-
       tives to Motif.



X Version 11                  20-Mar-2005 (4.21)               XScreenSaver(1)

Man(1) output converted with man2html