1 XScreenSaver(1)

1 XScreenSaver(1)

xrx Home Page User Commands Index xscreensaver-command


XScreenSaver(1)                                   XScreenSaver(1)

NAME
       xscreensaver  -  graphics hack and screen locker, launched
       when the user is idle

SYNOPSIS
       xscreensaver [-display host:display.screen] [-timeout int]
       [-cycle int] [-nice int] [-lock] [-no-lock] [-lock-timeout
       int] [-demo]  [-visual  visual]  [-install]  [-no-install]
       [-verbose]  [-silent] [-xidle-extension] [-no-xidle-exten-
       sion]  [-sgi-extension]  [-no-sgi-extension]  [-mit-exten-
       sion] [-no-mit-extension] [-xrm resources]

DESCRIPTION
       The  xscreensaver  program  waits  until  the keyboard and
       mouse have been idle for a period, and then runs a  graph-
       ics  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.

       The  benefit that this program has over the combination of
       the xlock(1) and xautolock(1) programs is  the  ease  with
       which new graphics hacks can be installed.  You don't need
       to recompile (or even re-run) this program to  add  a  new
       display mode.

GETTING STARTED
       For the impatient, try this:
               xscreensaver &
               xscreensaver-command -demo

       After  a  few  seconds,  the screen should go black, and a
       dialog box should appear in the upper right corner.   This
       is Demo Mode.

DEMO MODE
       If  xscreensaver receives the DEMO ClientMessage, which is
       done by running the xscreensaver-command(1)  program  with
       the  -demo  option,  the screensaver will black the screen
       and pop up a dialog box from which  you  can  examine  and
       experiment with the client programs.

       The  dialog  box  contains a scrolling list, a text field,
       and a number of buttons.

       Double-clicking on one of the programs in  the  list  will
       run  it.  The dialog box will disappear, allowing the pro-
       gram access to the full screen.  Clicking the mouse  again
       will bring the dialog box back.

X Version 11                16-Jan-98                           1

XScreenSaver(1)                                   XScreenSaver(1)

       Single-clicking  in the list will place the indicated pro-
       gram and its args in the text field to  be  edited.   Edit
       the  arguments  and hit return to run the program with the
       parameters you have specified.  (Note that these are  one-
       time  changes and won't be remembered; to make the changes
       permanent, you need to edit your X resource file.)

       The buttons are:

       Run Next
               Clicking this button will run the next program  in
               the  list  after  the  currently-selected one, and
               will scroll around to the top when it reaches  the
               bottom.

       Run Previous
               Opposite  of  Run  Next;  at  the  top, it scrolls
               around to the bottom.

       Edit Parameters
               This pops up a second dialog  box,  in  which  you
               have  the  option  to interactively change most of
               the screensaver's operational parameters, such  as
               its  timeouts,  and  whether  it  should  lock the
               screen.   Changing  these  parameters  here   will
               affect  only  the running xscreensaver process; to
               make the changes permanent, you need to edit  your
               X resource file.  (See below.)

       Exit Demo Mode
               Returns to normal screensaver operation.

       Reinitialize
               This causes the X resource database to be re-read,
               to pick up any changes you might have made.   This
               works  by  causing the screensaver process to exit
               and then restart itself with the same command-line
               arguments.   This  is just like the -restart argu-
               ment to xscreensaver-command(1) except  that  when
               executed  from  this  button, the screensaver will
               automatically return to demo mode  after  restart-
               ing.

OPTIONS
       xscreensaver accepts the following command line options:

       -timeout minutes
               The  screensaver  will activate after the keyboard
               and mouse have been idle for  this  many  minutes.
               Default 10.

       -cycle minutes
               After  the  screensaver  has been running for this
               many minutes, the currently running graphics  hack

X Version 11                16-Jan-98                           2

XScreenSaver(1)                                   XScreenSaver(1)
               sub-process  will  be killed (with SIGTERM), and a
               new one started.  If this is 0, then the  graphics
               hack  will  not be changed: only one demo will run
               until  the  screensaver  is  deactivated  by  user
               activity.  Default 10.

       -nice integer
               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 20.
               (Higher  numbers  mean lower priority; see nice(1)
               for details.)

       -lock   Enable locking: before the screensaver  will  turn
               off,  it  requires you to type the password of the
               person who launched the screensaver, or  the  root
               password.  (Note: this doesn't work if the screen-
               saver is launched by xdm(1) because it can't  know
               the user-id of the logged-in user.)

       -no-lock
               Disable locking.  This is the default.

       -lock-timeout minutes
               This  is  how long after the screensaver activates
               that locking is enabled.  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.  But,
               if there was user activity at 15 minutes or  later
               (-lock-timeout  minutes  after  activation) then a
               password would be required.   The  default  is  0,
               meaning  that  if locking is enabled, then a pass-
               word will be required as soon as  the  screensaver
               activates.

       -demo   Enter  the interactive demo mode immediately after
               startup.  Normally demo mode is  invoked  via  the
               xscreensaver-command(1)  program,  but  this  is a
               shortcut for new users.  See below for a  descrip-
               tion of how demo-mode works.

       -visual visual
               Specify  which  X visual to use by default.  Legal
               values 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

X Version 11                16-Jan-98                           3

XScreenSaver(1)                                   XScreenSaver(1)
                       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 inter-
                       esting  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.
               class   where class is one of StaticGray,  Static-
                       Color,  TrueColor, GrayScale, PseudoColor,
                       or  DirectColor.   Selects   the   deepest
                       visual of the given class.
               number  where  number  (decimal  or hex) is inter-
                       preted 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  other-
                       wise 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.

       -install
               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.

       -no-install
               Use the default colormap.

       -verbose
               Print diagnostics.

       -silent

X Version 11                16-Jan-98                           4

XScreenSaver(1)                                   XScreenSaver(1)

       -xidle-extension
               Use the XIDLE server extension to  decide  whether
               the user is idle.  This is the default if xscreen-
               saver has been  compiled  with  support  for  this
               extension.   On  X11R4 or X11R5 systems, the XIdle
               method is faster and more reliable than what  will
               be done otherwise, so use it if you can.

       -no-xidle-extension
               Don't use the XIDLE server extension.

       -sgi-extension
               Use  the  SGI  SCREEN_SAVER  server  extension  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.

       -no-sgi-extension
               Don't use the SGI SCREEN_SAVER server extension.

       -mit-extension
               Use  the  MIT-SCREEN-SAVER  server  extension   to
               decide  whether  the  user  is  idle.  This is the
               default if xscreensaver  has  been  compiled  with
               support  for this extension.  However, this exten-
               sion is flaky, so it's use is  not  really  recom-
               mended.   (It  also makes the fade option not work
               properly.)

       -no-mit-extension
               Don't use the MIT-SCREEN-SAVER server extension.

X RESOURCES
       xscreensaver understands the following resources:

       timeout (class Time)
               Same as the -timeout command-line option.  Default
               10 minutes.

       cycle (class Time)
               Same  as  the -cycle command-line option.  Default
               10 minutes.

       nice (class Nice)
               Same as the -nice  command-line  option.   Default
               10.

       lock (class Boolean)
               Same as the -lock command-line option.

X Version 11                16-Jan-98                           5

XScreenSaver(1)                                   XScreenSaver(1)

       lockTimeout (class Time)
               Same as the -lock-timeout command-line option.

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

       verbose (class Boolean)
               Same as the -verbose command-line option.

       xidle (class Boolean)
               Same as the -xidle command-line option.

       fade (class Boolean)
               If  this  is true, then when the screensaver acti-
               vates, the current contents  of  the  screen  will
               fade to black instead of simply winking out.  This
               only works on displays  with  writable  colormaps,
               that is, if the screen's default visual is a Pseu-
               doColor visual.  Default true.  A fade  will  also
               be  done  when  switching graphics hacks (when the
               cycle timer expires.)

       unfade (class Boolean)
               If this is true, then when the screensaver deacti-
               vates,  the  original  contents of the screen will
               fade in from black instead  of  appearing  immedi-
               ately.   This only works on displays with writable
               colormaps, 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.)

       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 fadeSec-
               onds if your server isn't fast enough to keep  up.
               Default 20.

       visualID (class VisualID)
               Same  as the -visual command-line option.  Default
               default.

       installColormap (class Boolean)
               Same as the -install command-line option.  Default

X Version 11                16-Jan-98                           6

XScreenSaver(1)                                   XScreenSaver(1)
               true.

       captureStderr (class Boolean)
               Whether xscreensaver should redirect its standard-
               error stream to  the  window  itself.   Since  its
               nature  is  to take over the screen, you would not
               normally  see  error  messages  generated  by  the
               screensaver or the programs it runs; this resource
               will cause the output of all relevant programs  to
               be  drawn on the screensaver window itself instead
               of written to  the  controlling  terminal  of  the
               screensaver driver process.  Default true.

       captureStdout (class Boolean)
               Like  captureStderr  but  for  the standard-output
               stream.  Default true.

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

       textForeground (class Foreground)
               The  foreground  color  used for the stdout/stderr
               text, if captureStdout or captureStderr are  true.
               Default: Yellow.

       textBackground (class Background)
               The  background  color  used for the stdout/stderr
               text, if captureStdout or captureStderr are  true.
               Default: Black.

       programs (class Programs)
               The  graphics  hacks  which xscreensaver runs when
               the user is idle.  The value of this resource is a
               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 at random,  and  run.   After  the  cycle
               period  expires,  it  is  killed,  and  another is
               selected and run.
               If the value of this resource is  empty,  then  no
               programs  will  be  run; the screen will simply be
               made black.
               If the display has multiple screens, then  a  dif-
               ferent program will be run for each screen.
               Note that you must escape the newlines; here is an
               example  of  how  you  might  set  this  in   your

X Version 11                16-Jan-98                           7

XScreenSaver(1)                                   XScreenSaver(1)
               .Xdefaults file:
               xscreensaver.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 win-
               dow (or be able to be configured to  draw  on  the
               root  window);  and  that  that program understand
               ``virtual root'' windows, as used by virtual  win-
               dow  managers  such as tvtwm.  (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 dis-
               play, 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 pro-
               gram  works best if it has a colormap, but another
               works best if it has a 24-bit visual, both can  be
               accomidated:
                       PseudoColor: cmap-program  -root   \n\
                       TrueColor:   24bit-program -root   \n\
               (This  sort  of thing used to be accomplished with
               the colorPrograms and monoPrograms resources,  but
               those  resources  have now been removed; a warning
               will be issued if they are used.)
               In addition to the symbolic visual names described
               above  (in  the section about the -visual command-
               line option) 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

X Version 11                16-Jan-98                           8

XScreenSaver(1)                                   XScreenSaver(1)
                       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  make  assumptions
                       about the visual and colormap of that 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.

       Normally you won't need to change the following resources:

       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.

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

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

       initialDelay (class Time)
               When server extensions are not  in  use,  xscreen-
               saver 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 30 seconds.

       overlayStderr (class Boolean)
               If  captureStderr  or  captureStdout are 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

X Version 11                16-Jan-98                           9

XScreenSaver(1)                                   XScreenSaver(1)
               screenhack.   Set  this  to  False to disable that
               (though you shouldn't need to.)

HOW IT WORKS
       When it is time to activate the screensaver, a full-screen
       black  window  is  created  on each screen of the display.
       The window or windows is given the appropriate  properties
       so  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  win-
       dows  are unmapped and the running subprocesses are killed
       by sending them SIGTERM.  This is  also  how  the  subpro-
       cesses  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.

       Before  launching  a  subprocess,  xscreensaver  stores an
       appropriate value for $DISPLAY in the environment that the
       child  will  recieve.   (This  is  so  that  if  you start
       xscreensaver with a -display argument, the programs  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  run-
       ning  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
       xscreensaver.c.

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

USING XDM(1)
       You can run xscreensaver from your xdm  session,  so  that
       the  screensaver will run even when nobody is logged in on
       the  console.   Simply  add  "xscreensaver  &"   to   your
       /usr/lib/X11/xdm/Xsetup  file.  Because xdm grabs the key-
       board, keypresses will not make  the  screensaver  deacti-
       vate, but any mouse activity will.

       Make  sure  you  have $PATH set up correctly in the Xsetup
       script, or xdm won't be able to find xscreensaver,  and/or
       xscreensaver won't be able to find its graphics hacks.

X Version 11                16-Jan-98                          10

XScreenSaver(1)                                   XScreenSaver(1)

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

       Users  may  want to add "xscreensaver-command -restart" to
       their startup scripts, so that  the  screensaver  will  be
       reinitialized  with  their  private resource settings when
       they log in.

       It is safe to run this program as root (as xdm  is  likely
       to  do.)   If run as root, xscreensaver changes its effec-
       tive user and group ids to something safe (like  "nobody")
       before connecting to the X server or launching user-speci-
       fied programs.

       Locking doesn't work if the  screensaver  is  launched  by
       xdm.  To get around this, you can run the screensaver from
       xdm without locking, and kill and  restart  it  from  your
       personal  X startup script to enable locking; for example,
       by using this pair of commands:
               xscreensaver-command -exit ; xscreensaver

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 CDE's 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 &
              This  will  cause  xscreensaver to be launched when
              you log in.  (As always, make  sure  that  xscreen-
              saver 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 following contents:

X Version 11                16-Jan-98                          11

XScreenSaver(1)                                   XScreenSaver(1)
                  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 contents:
                  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/error-
              log for error messages.

BUGS
       (This is not a bug, but) note that as of release 1.32, the
       colorPrograms  and  monoPrograms  resources  are no longer
       used: they have been supplanted by the extended syntax  of
       the  programs  resource  (which is described above, in the
       resources section.)

       Extensions
               If you are not making use of  one  of  the  server
               extensions   (XIDLE,  SGI  SCREEN_SAVER,  or  MIT-
               SCREEN-SAVER), then it is possible, in rare situa-
               tions,  for  xscreensaver  to interfere with event
               propagation and make another  X  program  malfunc-
               tion.   For  this to occur, that other application
               would need to not select KeyPress  events  on  its

X Version 11                16-Jan-98                          12

XScreenSaver(1)                                   XScreenSaver(1)
               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  pro-
               grams  generally  select  a constant 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.

       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 suck a
               lot of cycles.  Care should be taken to slow  down
               programs  intended  for  use  as  screensavers  by
               inserting strategic calls to sleep(3) or usleep(3)
               (or making liberal use of any -delay options which
               the programs may provide.)
               Also, an active  screensaver  will  cause  your  X
               server  to  be pretty much permanently swapped in;
               but the same is true of  any  program  that  draws
               periodically, like xclock(1) or xload(1).

       Latency and Responsiveness
               If  the  subprocess is drawing too quickly and the
               connection to the X server is a slow one (such  as
               an  X terminal running over a phone line) then the
               screensaver might not turn off right away when the
               user  becomes  active  again  (the ico(1) demo has
               this problem if being  run  in  full-speed  mode).
               This  can  be  alleviated  by  inserting strategic
               calls to XSync(3) in code intended for  use  as  a
               screensaver.   This  prevents  too  much  graphics
               activity from being buffered up.

       Locking and XDM
               Locking  doesn't  work  if  the   screensaver   is
               launched by xdm.  The reason for this is that when
               it is launched by xdm, the screensaver process  is
               owned  by  some  standard user id (such as root or
               daemon) instead of the user who is  logged  in  on
               the  console:  because the screensaver was started
               before anyone was logged in.   In  order  for  the
               screensaver to prompt for the password of the per-
               son who had logged in from xdm, it would  need  to
               know  who  that user was, and there is no reliable
               and safe way to figure that  out.   (And  even  if
               there  was,  there  would  be  some other security
               issues here as well.)

X Version 11                16-Jan-98                          13

XScreenSaver(1)                                   XScreenSaver(1)
               So if you want to use it as  a  locker,  you  must
               start  it  with  your  user id.  If it has already
               been started by xdm, you can kill it with xscreen-
               saver-command  -exit,  and  then start it again as
               you.

       Passwords
               If you get an error message  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.  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 inter-
               face; 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.  This turns out to be kind  of  hard
               to  fix.   (But  remember,  kids!   Unix  security
               doesn't do much more than keep honest people  hon-
               est...)

       Colormap lossage: TWM
               The  installColormap option doesn't work very well
               with the twm(1) window  manager  and  its  descen-
               dants.
               There  is a race condition between the screensaver
               and this window manager, which can result  in  the
               screensaver's colormap not getting installed prop-
               erly, 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  seem
               to  have  this problem.  The race condition exists
               because X does not provide a way for  an  Overrid-
               eRedirect  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 happens is that,  as  soon  as  the
               screensaver installs its colormap, twm responds to
               the ColormapNotify event that is generated by  re-
               instaling  the  default colormap.  Apparently, twm
               doesn't always do this; it seems to  do  it  regu-
               larly  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

X Version 11                16-Jan-98                          14

XScreenSaver(1)                                   XScreenSaver(1)
               another console.  Any thoughts on this problem are
               welcome...

       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  section
               about  the  programs resource.  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 altogether, but that would deny extra  col-
               ors  to  those programs that can take advantage of
               them.

       XView Clients
               Apparently there are some problems with XView pro-
               grams  getting  confused  and  thinking  that  the
               screensaver window is the real  root  window  even
               when the screensaver is not active: ClientMessages
               intended for the window manager are  sent  to  the
               screensaver  window instead.  This could be solved
               by making xscreensaver  forward  all  unrecognised
               ClientMessages  to the real root window, but there
               may be other problems as well.  If anyone has  any
               insight  on  the cause of this problem, please let
               me know.  (XView is an X11 toolkit that implements
               the  (quite  abominable)  Sun  OpenLook  look-and-
               feel.)

       MIT Extension and Fading
               When using the MIT-SCREEN-SAVER extension in  con-
               junction  with  the fade option, you may 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.

       LessTif (Motif Clone)
               Demo  mode  is  buggy if XScreenSaver was compiled
               against really old versions LessTif;  if  you  use
               LessTif, use version 0.82 or newer.

       Athena Widgets
               If you compiled against the Athena widget toolkit,

X Version 11                16-Jan-98                          15

XScreenSaver(1)                                   XScreenSaver(1)
               the dialog boxes are pretty ugly,  especially  the
               password  dialog.   Use  Motif!  If you don't have
               OSF   Motif,   use   GNU   LessTif,   it's   free:
               http://www.lesstif.org/

       SGI Power Saver
               If  you're  running  Irix 6.3, you might find that
               your monitor is powering down after an hour or two
               even  if  you've told it not to.  This is fixed by
               SGI patches 2447 and 2537.

       Red Hot Lava
               There need to be a lot more  graphics  hacks.   In
               particular,  there  should  be  a  simulation of a
               Lavalite (tm).

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.

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

UPGRADES
       The latest version can  always  be  found  at  http://peo-
       ple.netscape.com/jwz/xscreensaver/

SEE ALSO
       X(1) xscreensaver-command(1) xdm(1) ant(1) attrac- 
       tion(1) blitspin(1) bouboule(1) braid(1) bubbles(1) 
       cage(1) coral(1) cynosure(1) decayscreen(1) deco(1) 
       drift(1) fadeplot(1) flag(1) flame(1) forest(1) 
       galaxy(1) gears(1) goop(1) grav(1) greynetic(1) 
       halo(1) helix(1) hopalong(1) hypercube(1) ifs(1) 
       imsmap(1) julia(1) kaleidescope(1) laser(1) light- 
       ning(1) lisa(1) lissie(1) lmorph(1) maze(1) moe- 
       bius(1) moire(1) moire2(1) morph3d(1) mountain(1) 
       munch(1) noseguy(1) pedal(1) penrose(1) pipes(1) puz- 
       zle(1) pyro(1) qix(1) rd-bomb(1) rocks(1) 
       rorschach(1) rotor(1) rubik(1) sierpinski(1) 
       slidescreen(1) slip(1) sphere(1) spiral(1) sproin- 
       gies(1) stairs(1) starfish(1) strange(1) 
       superquadrics(1) swirl(1) triangle(1) vines(1) 
       worm(1) xjack(1) xlyap(1) xroger(1) bongo(1) ico(1) 
       xaos(1) xbouncebits(1) xcthugha(1) xdaliclock(1) 
       xfishtank(1) xmountains(1) xsplinefun(1) xswarm(1) 
       xtacy(1) xv(1) xwave(1). 

X Version 11                16-Jan-98                          16

XScreenSaver(1)                                   XScreenSaver(1)

COPYRIGHT
       Copyright  (C)  1991,  1992, 1993, 1994, 1995, 1996, 1997,
       1998 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 lt;jwz@netscape.com.  Written in late  1991;
       first posted to comp.sources.x on 13-Aug-1992.

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

ACKNOWLEDGEMENTS
       Thanks to David Wojtowicz for implementing lockTimeout.

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

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

       Thanks to Patrick Moreau for the VMS port.

       Thanks to Mark Bowyer for figuring out how to hook  it  up
       to CDE.

       And huge thanks to Jon A. Christopher for implementing the
       Athena dialog support, so that locking and demo-mode  work
       even if you don't have Motif.

xrx Home Page User Commands Index xscreensaver-command