Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
xscreensaver(1)		      XScreenSaver manual	       xscreensaver(1)

NAME
       xscreensaver - extensible screen	saver framework, plus locking

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

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

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

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

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

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

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

       I'll repeat that	because	it's important:

	   The easy way	to configure xscreensaver is to	run the	 xscreensaver-
	   demo(1)  program.   You shouldn't need to know any of the stuff de-
	   scribed 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 re-
       source 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  ac-
       tion,  such  as	blanking  or  unblanking  the screen, or picking a new
       graphics	mode.)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

USING GNOME
       For many	years, GNOME shipped xscreensaver as-is, and  everything  just
       worked  out  of	the box.  Recently, however, they've been re-inventing
       the wheel again in the form of "gnome-screensaver".

       To replace gnome-screensaver with xscreensaver:

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

	   2: Stop gnome-screensaver from launching at login.
	      Run the command:
	      gconftool-2 --type boolean -s \
	      /apps/gnome_settings_daemon/screensaver/start_screensaver	\
	      false
	      Or, just uninstall the "gnome-screensaver" package entirely.

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

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

	   5: Make ``System / Quit / Lock Screen'' use xscreensaver.
	      Run the command:
	      sudo ln -sf /usr/bin/xscreensaver-command	\
			  /usr/bin/gnome-screensaver-command

USING KDE
       KDE  also has invented their own	screen saver framework instead of sim-
       ply using xscreensaver.	To replace the KDE screen saver	with  xscreen-
       saver, do the following:

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

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

	   3: Make xscreensaver	be an Autostart	program.
	      Create a	.desktop  file	in  your  autostart  directory	called
	      xscreensaver.desktop that	contains the following five lines:
	      [Desktop Entry]
	      Exec=xscreensaver
	      Name=XScreenSaver
	      Type=Application
	      X-KDE-StartupNotify=false

	   4: Make the various "lock session" buttons call xscreensaver.
	      Replace  the file	kdesktop_lock or krunner_lock or kscreenlocker
	      in /usr/bin/ (or possibly	in /usr/kde/3.5/bin/  or  possibly  in
	      /usr/lib/kde4/libexec/  or  /usr/libexec/kde4/, depending	on the
	      distro and phase of the moon) with these two lines:
	      #!/bin/sh
	      xscreensaver-command -lock
	      Make sure	the file is executable (chmod a+x).

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

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

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

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

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

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

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

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

       Locking and XDM
	       If xscreensaver has been	launched from xdm(1) before anyone has
	       logged  in, you will need to kill and then restart the 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 ef-
	       fectively used by root.	If this	is the case, then xscreensaver
	       must be installed as setuid to root in  order  for  locking  to
	       work.  Care has been taken to make this a safe thing to do.

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

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

       PAM Passwords
	       If  your	 system	 uses  PAM (Pluggable Authentication Modules),
	       then in order for xscreensaver to use PAM properly, PAM must be
	       told about xscreensaver.	 The xscreensaver installation process
	       should update the PAM data (on  Linux,  by  creating  the  file
	       /usr/local/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!

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

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

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

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

       cycle (class Time)
	       After the screensaver has been running for this	many  minutes,
	       the  currently running graphics-hack sub-process	will be	killed
	       (with SIGTERM), and a new one started.  If this is 0, then  the
	       graphics	hack will never	be changed: only one demo will run un-
	       til 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)  be-
	       cause 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 re-
	       quired 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 ef-
	       fect unless both	the X server and the display hardware  support
	       power  management;  not	all do.	 See the Power Management sec-
	       tion, 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 an-
		       imation.	  Some programs	have more interesting behavior
		       when run	on PseudoColor visuals than on TrueColor.

	       mono    Use a monochrome	visual,	if there is one.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       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 in-
	       dex 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 (ac-
	       cording 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  un-
	       blanked simultaneously.)

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

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

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

	       If there	are some programs that you want	to run only when using
	       a  color	display, and others that you want to run only when us-
	       ing 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 de-
		    fault  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 as-
		    sumptions about the	visual and colormap of the  root  win-
		    dow: assumptions which xscreensaver	can violate.

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

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

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

       pointerHysteresis (class	Integer)
	       If the mouse moves less than this-many pixels in	a second,  ig-
	       nore  it	 (do  not consider that	to be "activity.")  This is so
	       that the	screen doesn't un-blank	(or fail to  blank)  just  be-
	       cause 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  ex-
	       tension	will be	used to	decide whether the user	is idle.  This
	       is the default if xscreensaver has been compiled	 with  support
	       for  this extension (which is the default on SGI	systems.).  If
	       it is available,	the SCREEN_SAVER method	is faster and more re-
	       liable  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 ex-
	       tension will be used to decide whether the user is idle.	  How-
	       ever,  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  de-
	       fault  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.

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

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

       PATH    to find the sub-programs	to run.

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

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

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

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

COPYRIGHT
       Copyright (C) 1991, 1992, 1993, 1994, 1995,  1996,  1997,  1998,	 1999,
       2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 by Jamie Za-
       winski.	Permission to use, copy, modify,  distribute,  and  sell  this
       software	 and its documentation for any purpose is hereby granted with-
       out fee,	provided that the above	copyright notice appear	in all	copies
       and  that  both that copyright notice and this permission notice	appear
       in supporting documentation.  No	representations	 are  made  about  the
       suitability  of	this software for any purpose.	It is provided "as is"
       without express or implied warranty.

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

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

ACKNOWLEDGEMENTS
       Thanks to Angela	Goodman	for the	XScreenSaver logo.

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

       Thanks to David Wojtowicz for implementing lockTimeout.

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

       Thanks to Patrick Moreau	for the	VMS port.

       Thanks to Nat Lanza for the Kerberos support.

       Thanks to Bill Nottingham for the initial PAM support.

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

X Version 11		      5.12 (15-Sep-2010)	       xscreensaver(1)

NAME | SYNOPSIS | DESCRIPTION | GETTING STARTED | CONFIGURATION | COMMAND-LINE OPTIONS | HOW IT WORKS | POWER MANAGEMENT | USING GNOME | USING KDE | USING GDM | BUGS | X RESOURCES | ENVIRONMENT | UPGRADES | SEE ALSO | COPYRIGHT | AUTHOR | ACKNOWLEDGEMENTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=xscreensaver&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help