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

FreeBSD Manual Pages


home | help
XScreenSaver(1)		    General Commands Manual	       XScreenSaver(1)

       xscreensaver - extensible screen	saver and screen locking framework

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

       XScreenSaver waits until	the user is idle, and then runs	graphics demos
       chosen  at random.  It can also lock your screen, and provides configu-
       ration and control of display power management.

       XScreenSaver is also available on macOS,	iOS and	Android.

       XScreenSaver is a daemon	that runs in the background.  You configure it
       with the	xscreensaver-settings(1) program.

	    xscreensaver &

       When it is time to activate the screensaver, a full-screen black	window
       is created that covers each monitor.  A	sub-process  is	 launched  for
       each  one  running  a graphics demo, pointed at the appropriate window.
       Because of this,	any program which can draw on a	provided window	can be
       used  as	 a screensaver.	 The various graphics demos are, in fact, just
       standalone programs that	do that.

       When the	user becomes active again, the	screensaver  windows  are  un-
       mapped, and the running subprocesses are	killed.

       The  display modes are run at a low process priority, and spend most of
       their time sleeping/idle	by default, so they should not consume signif-
       icant system resources.

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

	       Print diagnostics to stderr.

       --log filename
	       Append  all diagnostic output to	the given file.	 This also im-
	       plies --verbose.	 Use this when reporting bugs.

	       Don't display the splash	screen at startup.

       The xscreensaver-settings(1) program is where you configure if and when
       your  monitor  should  power  off.   It	saves  the  settings  in  your
       ~/.xscreensaver file.

       If the power management section is grayed out in	the  xscreensaver-set-
       tings(1)	 window,   then	that means that	your X server does not support
       the XDPMS extension, and	so control over	the monitor's power  state  is
       not available.

       When the	monitor	is powered down, the display hacks are stopped (though
       it may take a minute or two for XScreenSaver to notice).

       Note: if	you use	xset(1)	 to  change  the  power	 management  settings,
       XScreenSaver   will   override  those  changes.	 Whatever  is  in  the
       ~/.xscreensaver file takes precedence.

       If your system has systemd(1) 221 or newer, or elogind(8), then closing
       the lid of your laptop will cause the screen to lock immediately.

       If  not,	 then  the screen might	not lock until a few seconds after you
       re-open the lid.	 Which is less than ideal.  So if you don't  use  sys-
       temd,  you might	want to	get in the habit of doing xscreensaver-command
       --lock before closing the lid.

       Likewise, if you	have systemd(1)	221 or newer, or elogind(8), then  all
       of the popular video players and	web browsers will prevent XScreenSaver
       from blanking the screen	while video is playing.

       Both of these features require  that  xscreensaver-systemd(6)  be  able
       connect to the systemd bus.  Parts of KDE and GNOME may need to be dis-
       abled first for that to work; see below.

       Each desktop environment	has its	own system for launching  long-running
       daemons	like  XScreenSaver,  and  since	many of	them come bundled with
       their own (buggy, insecure, inferior) screen-locking frameworks,	it  is
       also  necessary	to  disable those other	frameworks before XScreenSaver
       can work.

       For many	years, GNOME shipped XScreenSaver as-is, and  everything  just
       worked.	 In  2005,  however,  they decided to needlessly re-invent the
       wheel and ship their own	replacement for	the xscreensaver daemon	called
       gnome-screensaver(1)  rather than improving XScreenSaver	and contribut-
       ing their changes back.	As a result, the gnome-screensaver program  is
       insecure,  bug-ridden,  and  missing many features of XScreenSaver.  In
       fact, in	2011 it	lost the ability to run	display	modes at all.

       In 2012 some distros forked and renamed it as both  mate-screensaver(1)
       and cinnamon-screensaver(1), which seem to be basically the same.

       To replace gnome-screensaver with XScreenSaver:

	   1: Fully uninstall the other	screen saver packages:

		   sudo	apt-get	remove gnome-screensaver
		   sudo	apt-get	remove mate-screensaver
		   sudo	apt-get	remove cinnamon-screensaver
		   sudo	rpm -e gnome-screensaver
		   sudo	rpm -e mate-screensaver
		   sudo	rpm -e cinnamon-screensaver

	      Be careful that it doesn't try to	uninstall all of GNOME.

	   2: Launch XScreenSaver at login.

	      Select  "Startup Applications" from the menu (or manually	launch
	      "gnome-session-properties") and add "xscreensaver".  Do this  as
	      your normal user account,	not as root.

	   3: Make GNOME's "Lock Screen" use XScreenSaver.

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

	   4: Turn off Unity's built-in	blanking.

	      Open "System Settings / Brightness _ Lock";
	      Un-check "Start Automatically";
	      Set "Turn	screen off when	inactive for" to "Never".

	      Or possibly that has been	randomly renamed again:
	      Set "Settings / Power / Power Settings" to "Never".

	   5: Stop GNOME from blocking XScreenSaver's "systemd"	integration:

		   sudo	systemctl --user mask gsd-screensaver-proxy.service
		   sudo	systemctl --user mask \

	      Without  the  above,  video  players  will  not  be able to tell
	      XScreenSaver not to blank	the screen while videos	 are  playing,
	      and  the	screen will not	auto-lock when you close your laptop's

	      After running those commands, reboot.  Yes, you have to  reboot;
	      it  won't	let you	simply stop the	service.  Logging out won't do
	      it either.

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

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

	      Or possibly: Open	"System	Settings" and select "Screen Locking".
	      Un-check "Lock Screen 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	something like
	      ~/.kde/Autostart/	or ~/.config/autostart/

	      If that doesn't work, then try this:

	      Open "System Settings / Startup/Shutdown / Autostart", and  then
	      add "/usr/bin/xscreensaver".

	      If  you  are  lucky,  that will create an	"xscreensaver.desktop"
	      file for you in ~/.config/autostart/ or ~/.kde/Autostart/.

	   3: Make XScreenSaver	be an Autostart	program.
	      If it does not already exist, create a file  in  your  autostart
	      directory	 called	xscreensaver.desktop that contains the follow-
	      ing six lines:

		   [Desktop Entry]

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

		   xscreensaver-command	--lock

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

	      This change will probably	get blown away the next	time your sys-
	      tem upgrades KDE.

	   5: Stop KDE from blocking XScreenSaver's "systemd" integration:
	      You  must	 arrange  for KDE's ksmserver(1) daemon	to be launched
	      with the command line option --no-lockscreen.

	      Under KDE	5.00 through 5.16, you can accomplish that by  editing
	      the  startkde(1)	script	in /usr/bin/ by	hand, then logging out
	      and back in again.

	      Under KDE	5.17 through 5.20, you must wrap ksmserver(1) instead:

		   mv /usr/bin/ksmserver /usr/bin/ksmserver-orig

	      and replace /usr/bin/ksmserver with:

		   ksmserver-orig --no-lockscreen

	      Either change will, of course, get blown away the	next time your
	      system upgrades KDE.

	      Instead of being in /usr/bin/, the ksmserver program might be in
	      /usr/lib/	or /usr/lib*/libexec/ or usr/lib/*/libexec/  or	 some-
	      where else, depending on your distro.

	      Under  KDE  5.21+	 this  might  work  instead, and might persist
	      through upgrades:

		   systemctl edit plasma-ksmserver.service

	      and then put this	in the file you	get to edit:

		   ExecStart=/usr/bin/ksmserver	--no-lockscreen

	      Regardless of which approach you need to	use,  if  you  do  not
	      force ksmserver(1) to stop squatting on the DBus endpoint, video
	      players will not be able to tell XScreenSaver not	to  blank  the
	      screen  while  videos are	playing, and the screen	will not auto-
	      lock when	you close your laptop's	lid.

       If the above didn't do it, and your system has systemd(1),  maybe  this
       is how it works:

	   1: Create a service.
	      Create the file ~/.config/systemd/user/xscreensaver.service con-


	   2. Enable it.

		   systemctl --user enable xscreensaver

       Then restart X11.

       If your system has upstart(7) instead of	systemd(1),  maybe  this  will
       work:  launch  the  "Startup  Applications"  applet, click "Add", enter
       these lines, then restart X11:

	    Name: XScreenSaver
	    Command: xscreensaver
	    Comment: XScreenSaver

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

       On the General page set the Local Greeter to Standard Greeter.

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

       If that doesn't work, you can  edit  the	 config	 file  directly.  Edit
       /etc/X11/gdm/gdm.conf to	include:

	    BackgroundProgram=xscreensaver --nosplash

       In this situation, the xscreensaver process will	probably be running as
       user gdm	instead	of as root.  You can configure the settings  for  this
       nobody-logged-in	  state	  (timeouts,   DPMS,   etc.)  by  editing  the
       ~gdm/.xscreensaver file.

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

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

       If you get "connection refused" errors when running  xscreensaver  from
       gdm,  then this probably	means that you have xauth(1) or	some other 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).

       BSD systems or other systems without  systemd(1)	 or  elogind(8)	 might
       have  luck by adding xscreensaver-command --suspend to some appropriate
       spot in /etc/acpi/events/anything or in /etc/acpi/, if	 those
       files exist.

       Wayland is a completely different window	system that is intended	to re-
       place X11.  After 13+ years of trying, some Linux distros have  finally
       begun  enabling	it  by	default.   Most	deployments of it also include
       XWayland, which is a compatibility layer	that allows some X11  programs
       to continue to work within a Wayland environment.

       Unfortunately, XScreenSaver is not one of those programs.

       If  your	 system	 is running XWayland, XScreenSaver will	malfunction in
       two ways:

       1: It will be unable to detect user activity in non-X11 programs.

	  This means that while	a native Wayland program is selected, XScreen-
	  Saver	 will think that you are idle, and may blank the screen	prema-

       2: It will be unable to lock the	screen.

	  This is because X11 grabs don't work	properly  under	 XWayland,  so
	  there	 is no way for XScreenSaver to prevent the user	from switching
	  away from the	screen locker to another application.

       In short, for XScreenSaver to work properly, you	will  need  to	switch
       off Wayland and use the X Window	System like in the "good old days".

       The  login screen should	have a gear-icon menu that lets	you change the
       session type from "GNOME" (the Wayland session) to "GNOME on Xorg" (the
       X11 session).

       Alternately,  edit  /etc/gdm/custom.conf	and make sure it includes this


       The login screen	should have a menu that	lets you  change  the  session
       type to "Plasma (X11)".

       Alternately,  edit  /etc/sddm.conf and change the SessionDir line under
       the [Wayland] section to	say:


       XScreenSaver has	a decades-long track record of securely	 locking  your
       screen.	 However,  there  are many things that can go wrong.  X11 is a
       very old	system,	and has	a number of design flaws that make it  suscep-
       tible to	foot-shooting.

       The  XFree86 and	Xorg X servers,	as well	as the Linux kernel, both trap
       certain magic keystrokes	before X11 client programs ever	see them.   If
       you care	about keeping your screen locked, this is a big	problem.

	  This	keystroke  kills the X server, and on some systems, leaves you
	  at a text console.  If the user launched  X11	 manually,  that  text
	  console will still be	logged in.  To disable this keystroke globally
	  and permanently, you need to set the DontZap flag in your  xorg.conf
	  or  XF86Config  or  XF86Config-4  file, depending which is in	use on
	  your system.	See XF86Config(5) for details.

       Ctrl-Alt-F1, Ctrl-Alt-F2, etc.
	  These	keystrokes will	switch to a different virtual  console,	 while
	  leaving  the	console	 that X11 is running on	locked.	 If you	left a
	  shell	logged in on another virtual console, it is  unprotected.   So
	  don't	 leave	yourself logged	in on other consoles.  You can disable
	  VT switching globally	and permanently	 by  setting  DontVTSwitch  in
	  your xorg.conf, but that might make your system harder to use, since
	  VT switching is an actual useful feature.

	  There	is no way to disable VT	switching  only	 when  the  screen  is
	  locked.  It's	all or nothing.

	  This	keystroke  kills any X11 app that holds	a lock,	so typing this
	  will kill XScreenSaver and unlock the	screen.	 You can disable it by
	  turning off AllowClosedownGrabs in xorg.conf.

	  This	is  the	 Linux	kernel "OOM-killer" keystroke.	It shoots down
	  random long-running programs of its choosing,	and  so	 might	target
	  and  kill  XScreenSaver.   You  can  disable this keystroke globally

	       echo 176	> /proc/sys/kernel/sysrq

	  There's little that I	can do to make the screen locker be secure  so
	  long	as  the	kernel and X11 developers are actively working against
	  security like	this.  The strength of the lock	 on  your  front  door
	  doesn't  matter much so long as someone else in the house insists on
	  leaving a key	under the welcome mat.

       Even if you have	disabled the  Alt-SysRq-F  OOM-killer  keystroke,  the
       OOM-killer  might  still	 decide	to assassinate XScreenSaver at random,
       which will unlock your screen.  If the xscreensaver-auth(6) program  is
       installed  setuid,  it  attempts	 to  tell  the OOM-killer to leave the
       XScreenSaver daemon alone, but that may or may not work.

       You would think that the	OOM-killer would pick the  process  using  the
       most  memory,  but  most	 of the	time it	seems to pick the process that
       would be	most comically inconvenient, such as your  screen  locker,  or
       crond(8).  You can disable the OOM-killer entirely with:

	    echo 2 > /proc/sys/vm/overcommit_memory
	    echo vm.overcommit_memory =	2 >> /etc/sysctl.conf

       X11's  security	model  is all-or-nothing.  If a	program	can connect to
       your X server at	all, either locally or over the	network,  it  can  log
       all of your keystrokes, simulate	keystrokes, launch arbitrary programs,
       and change the settings of other	programs.  Assume that	anything  that
       can  connect to your X server can execute arbitrary code	as the logged-
       in user.	 See Xsecurity(1) and xauth(1).

       If your system uses PAM (Pluggable Authentication  Modules),  then  PAM
       must  be	 configured for	XScreenSaver.  If it is	not, then you might be
       in a situation where you	can't unlock.  Probably	the file you  need  is

       In order	for it to be safe for XScreenSaver to be launched by xdm, cer-
       tain 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 it-
       self 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).

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

       For  a single user, the proper way to configure XScreenSaver is to sim-
       ply run the xscreensaver-settings(1) program, and change	 the  settings
       through the GUI.	 The rest of this manual describes lower-level ways of
       changing	settings.  You shouldn't need to know any  of  the  stuff  de-
       scribed below unless you	are trying to do something complicated.

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

       The syntax of the .xscreensaver file is similar to that	of  the	 .Xde-
       faults  file; for example, to set the timeout parameter n 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 as needed.

       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

	    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	/etc/X11/app-defaults/XScreenSaver, but	different sys-
       tems might keep it in a different place.

       When settings are changed in the	Preferences dialog box,	those settings
       are written to the .xscreensaver	file.  The  .Xdefaults	file  and  the
       app-defaults file will never be written by XScreenSaver itself.

       These  are  the	X resources use	by XScreenSaver	program.  You probably
       won't need to change these manually: that's what	the  xscreensaver-set-
       tings(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.

	       If  there  are  multiple	 screens,  the	savers	are  staggered
	       slightly	 so  that  while  they all change every	cycle minutes,
	       they don't all change at	the same time.

       lock (class Boolean)
	       Enable locking: before the screensaver will turn	off,  it  will
	       require you to type the password	of the logged-in user.

       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, lockTimeout 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).	 A few seconds are added each time you
	       type a character.

       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.

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

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

       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

       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

       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-set-

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

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

       fade (class Boolean)
	       If  this	is true, then when the screensaver activates, the cur-
	       rent contents of	the screen will	fade to	black instead of  sim-
	       ply winking out.	 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 is only done if fade is true as
	       well.  Default: true.

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

       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-settings(1) pro-
	       gram will suppress the non-existent programs from the  list  if
	       this is true.  Default: false.

       authWarningSlack	(class Integer)
	       After  you  successfully	unlock the screen, a dialog may	pop up
	       informing you of	previous failed	login  attempts.   If  all  of
	       those  login  attemps were within this amount of	time, they are
	       ignored.	 The assumption	is that	 incorrect  passwords  entered
	       within  a  few  seconds of a correct one	are user error,	rather
	       than hostile action.  Default 20	seconds.

       mode (class Mode)
	       Controls	the screen-saving behavior.  Valid values are:

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

		       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-

	       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-settings(1) do	it for

       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-settings(1)

	       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

	       The    default	 XScreenSaver	hacks	directory   (typically
	       /usr/libexec/xscreensaver/)  is	prepended  to	$PATH	before
	       searching for these programs.

	       To  use	a  program as a	screensaver, it	must be	able to	render
	       onto the	window provided	to it in the $XSCREENSAVER_WINDOW  en-
	       vironment  variable.  If	it creates and maps its	own window in-
	       stead, it won't work.  It must render onto the provided window.


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

	       If there	are some programs that you want	to run only when using
	       a  color	display, and others that you want to run only when 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

		    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:

		    This is like default, but also requests the	use of the de-
		    fault colormap, instead of a private colormap.

	       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.

       visualID	(class VisualID)
	       This is an historical artifact left over	from when  8-bit  dis-
	       plays were still	common.	 You should probably ignore this.

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

	       Valid 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-

	       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.

	       N       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, above.

       installColormap (class Boolean)
	       This is an historical artifact left over	from when  8-bit  dis-
	       plays  were still common.  On PseudoColor (8-bit) displays, in-
	       stall 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  de-
	       fault visual is being used, since non-default visuals get their
	       own colormaps automatically.)  This can also be overridden on a
	       per-hack	basis: see the discussion of the default-n name	in the
	       section about the programs resource.

	       This does nothing if you	have a TrueColor  (16-bit  or  deeper)
	       display.	 (Which, in this century, you do.)

       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.

	       A single	pixel of motion	will still cause the monitor to	 power
	       back  on,  but not un-blank. This is because the	X11 server it-
	       self unfortunately  handles  power-management-related  activity
	       detection rather	than XScreenSaver.

BUGS  explains  how  to write the
       most useful bug reports.	 If you	find a bug, please let me know!

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

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

       PATH    to find the sub-programs	to run,	including the display modes.

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

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

       The  latest  version of XScreenSaver, an	online version of this manual,
       and a FAQ can always be found at

       X(1), Xsecurity(1), xauth(1), xdm(1), gdm(1), xhost(1), systemd(1), el-
       ogind(8),  xscreensaver-settings(1),  xscreensaver-command(1), xscreen-
       saver-systemd(6), xscreensaver-gl-helper(6),  xscreensaver-getimage(6),

       Copyright  (C)  1991-2021  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  no-
       tice 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.

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

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

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

X Version 11		      6.02 (11-Oct-2021)	       XScreenSaver(1)


Want to link to this manual page? Use this URL:

home | help