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

  
 
  

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

NAME
     xscreensaver - extensible screen saver and screen locking framework

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

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

     XScreenSaver is also available on macOS, iOS and Android.

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

	  xscreensaver &
	  xscreensaver-settings

HOW IT WORKS
     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 pro-
     grams that do that.

     When the user becomes active again, the screensaver windows  are  unmapped,
     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 significant
     system resources.

COMMAND-LINE OPTIONS
     --display host:display.screen
	     The X display to use.  For displays with multiple screens, XScreen-
	     Saver will manage all screens on the display simultaneously.

     --verbose
	     Print diagnostics to stderr.

     --version
	     Print the version number and exit.

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

     --no-splash
	     Don't display the splash screen at startup.

POWER MANAGEMENT
     The  xscreensaver-settings(1)  program  is  where you configure if and when
     your monitor should power off.  It saves the settings in  your  ~/.xscreen-
     saver  file.   Do	not  use xset(1) to manually change the power management
     settings, that won't work.

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

LAPTOP LIDS
     If  your system uses systemd(1) 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 do not have systemd(1),
     you  might  want to get in the habit of manually locking your screen before
     closing the lid (xscreensaver-command --lock).

PLAYING VIDEOS
     Likewise, if you have systemd(1) 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 D-Bus.

INSTALLATION
     Each desktop environment has its own system for launching long-running dae-
     mons 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.

   INSTALLING XSCREENSAVER ON GNOME OR UNITY
     For  many	years,	GNOME  included  XScreenSaver as-is, and everything just
     worked.  Not any more!

	 1: Fully uninstall the other screen saver packages:

		 sudo apt remove gnome-screensaver
		 sudo apt remove mate-screensaver
		 sudo apt remove cinnamon-screensaver
		 sudo apt remove light-locker
	    or
		 sudo rpm -e gnome-screensaver
		 sudo rpm -e mate-screensaver
		 sudo rpm -e cinnamon-screensaver
		 sudo rpm -e light-locker

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

	 2: Turn off GNOME's built-in blanking.
	    Set all of the following settings to "Never" or "Off", as these  are
	    all controlled by xscreensaver-settings(1) now:

	    "Settings / Privacy / Screen Lock / Blank Screen Delay"
	    "Settings / Privacy / Screen Lock / Automatic Screen Lock"
	    "Settings / Power / Blank Screen"
	    "Settings / Power / Automatic Suspend"

	 3: Launch XScreenSaver at login.
	    Launch "Tweaks", select "Startup Applications", click the plus sign,
	    and  select  "XScreenSaver"  (not  "XScreenSaver Settings") from the
	    (very long) menu.

	    Or, see the "LAUNCHING XSCREENSAVER  FROM  SYSTEMD"  section  below.
	    That works too.

	 4: Make GNOME's "Lock" icon use XScreenSaver.
	    This  used to work, but no longer does with GNOME 3.38.  If you fig-
	    ure it out, let me know!  This still works for Cinnamon 4.8 and MATE
	    1.24:

		 sudo ln -sf /usr/bin/xscreensaver-command \
			/usr/bin/gnome-screensaver-command
		 sudo ln -sf /usr/bin/xscreensaver-command \
		     /usr/bin/cinnamon-screensaver-command
		 sudo ln -sf /usr/bin/xscreensaver-command \
			 /usr/bin/mate-screensaver-command
		 sudo ln -sf /usr/bin/xscreensaver-command \
			/usr/bin/xfce4-screensaver-command
		 sudo ln -sf /usr/bin/xscreensaver-command \
			     /usr/bin/light-locker-command

	    This change will get blown away when you upgrade.

   INSTALLING XSCREENSAVER ON KDE
     Like GNOME, KDE also decided to re-invent the wheel.  To  replace	the  KDE
     screen saver with XScreenSaver, do the following:

	 1: Turn off KDE's built-in blanking.
	    In	System Settings, un-check the following items, as these are con-
	    trolled by xscreensaver-settings(1) now:

	    "Workspace Behavior / Screen Locking / Lock automatically"
	    "Workspace Behavior / Screen Locking / After waking from sleep"
	    "Workspace Behavior / Screen Locking / Keyboard shortcut"
	    "Hardware / Power Management / Screen Energy Saving"
	    "Hardware / Power Management / Suspend session"
	    "Hardware / Power Management / Laptop lid closed" = Do Nothing

	    If there are multiple tabs, you may need to change these settings on
	    all three of them: "On AC power", "Battery" and "Low Battery".

	 2: Launch XScreenSaver at login.
	    Copy the file /usr/share/applications/xscreensaver.desktop into  the
	    directory ~/.config/autostart/

	 3: Make KDE's "Lock" icon use XScreenSaver.
	    Find   the	 "kscreenlocker_greet"	 program.    It   might   be  in
	    "/usr/lib/*/libexec/", or it might be somewhere else.   Delete  that
	    file and replace it with a file containing these two lines.  Make it
	    executable (chmod a+x).

		 #!/bin/sh
		 xscreensaver-command --lock &

	    This change will get blown away when you upgrade.

	 4: Turn off KDE's built-in locking on suspend, even harder.
	    Even  after  disabling  KDE's  screen locking, above, it is possible
	    that KDE will still use its built-in locker when you close your lap-
	    top's lid.	If that is happening, double-check the	settings  above,
	    but  if those are correct, try the following.  First, ensure you are
	    running KDE 5.21 or newer.	Next, enable "systemd user sessions" for
	    KDE so that you can edit the parameters for ksmserver:

		 kwriteconfig5 --file startkderc --group General \
		   --key systemdBoot true

	    Log out and back in.

	    Next, edit the plasma-ksmserver service to change how  ksmserver  is
	    launched:

		 systemctl edit --user plasma-ksmserver.service

	    Replace the contents of the file that lets you edit with this:

		 [Service]
		 ExecStart=
		 ExecStart=/usr/bin/ksmserver --no-lockscreen

	    Then log out and back in again.

   LAUNCHING XSCREENSAVER FROM LXDE
     Add   the	 line	@xscreensaver  to  /etc/xdg/lxsession/LXDE/autostart  or
     /etc/xdg/lxsession/LXDE-pi/autostart.

   LAUNCHING XSCREENSAVER FROM SYSTEMD
     If you are not using GNOME, KDE or LXDE, the way to launch XScreenSaver  at
     login is probably systemd(1).

     If the file /usr/lib/systemd/user/xscreensaver.service does not already ex-
     ist, copy the file /usr/share/xscreensaver/xscreensaver.service to there or
     to ~/.config/systemd/user/.

     Then enable it with:

	  systemctl --user enable xscreensaver

   LAUNCHING XSCREENAVER FROM UPSTART
     If  you  are  not using GNOME, KDE or LXDE, and your system uses upstart(7)
     instead of systemd(1), launch  the  "Startup  Applications"  applet,  click
     "Add", and enter these lines:

	  Name: XScreenSaver
	  Command: xscreensaver
	  Comment: XScreenSaver

   LAPTOP LIDS WITHOUT SYSTEMD
     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/handler.sh, if those files exist.

   LAUNCHING XSCREENSAVER FROM GDM
     You can run xscreensaver from your gdm(1) session, so that the  screensaver
     will  run	even  when  nobody is logged in on the console.  To do this, run
     gdmconfig(1).

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

     On the Background page, type the command  "xscreensaver  --no-splash"  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 or maybe /etc/gdm3/custom.conf to include:

	  Greeter=/usr/bin/gdmlogin
	  BackgroundProgram=xscreensaver --no-splash
	  RunBackgroundProgramAlways=true

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

     If  you get "connection refused" errors when running xscreensaver from gdm,
     then this probably means that you are having xauth(1) problems.  For infor-
     mation on the X server's access control mechanisms, see the man  pages  for
     X(1), Xsecurity(1), xauth(1), and xhost(1).

     There  might be a way to accomplish this with other display managers.  It's
     a mystery!

THE WAYLAND PROBLEM
     Wayland is a completely different window system that is intended to replace
     X11.  After 16+ years of trying, some Linux distros have finally begun  en-
     abling  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 Wayland, XScreenSaver will malfunction in a few
     ways, some small but one quite serious:

     1: 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.

     2: It won't work at all under GNOME.

	This is because the GNOME compositor does not support either of the Way-
	land protocols that allow us to tell when the user is  idle.   It  works
	with KDE and most other compositors, however.

     2: No mouse hystersis.

	Even a single pixel of mouse motion will cause the screen to un-blank.

     3: Fading and screenshots might not work.

	Under Wayland, Fading in and out, and allowing hacks to grab and manipu-
	late a desktop screenshot, depend on the program grim(1) being installed
	to grab screenshots for us.  And grim(1) doesn't work under the GNOME or
	KDE compositors.

     For  XScreenSaver	to  be able to lock, you will need to switch off Wayland
     and use the X Window System like in the "good old days".

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

     Alternately,  edit  /etc/X11/gdm/gdm.conf or maybe /etc/gdm3/custom.conf to
     include:

	  WaylandEnable=false

   TO DISABLE WAYLAND UNDER KDE
     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:

	  SessionDir=/dev/null

SECURITY CONCERNS
     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  susceptible  to
     foot-shooting.

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

     Ctrl+Alt+Backspace
	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(5) or XF86Config(5)
	file.

     Ctrl-Alt-F1, Ctrl-Alt-F2, etc.
	These keystrokes will switch to a different virtual console, while leav-
	ing 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(5),
	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.

     Ctrl-Alt-KP_Multiply
	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(5).

     Alt-SysRq-F
	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 with:

	     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.

   THE OOM-KILLER
     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  se-
     tuid,  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

     In  addition  to  the kernel's OOM-killer, systemd(1) has its own.  The in-
     cluded xscreensaver.service file attempts to evade it, but you may want  to
     just turn it off anyway:

	  sudo systemctl disable --now systemd-oomd
	  sudo systemctl mask systemd-oomd

   X SERVER ACCESS IS GAME OVER
     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  Xsecu-
     rity(1) and xauth(1).

   PAM PASSWORDS
     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 situ-
     ation where you can't unlock.  Probably  the  file  you  need  is	/usr/lo-
     cal/etc/pam.d/xscreensaver.

   DON'T LOG IN AS ROOT
     Never  log  in  as root.  Log in as a normal user and use sudo(1) as neces-
     sary.  If you are logged in as root, XScreenSaver will not lock your screen
     or run display modes, for numerous good and proper reasons.

MULTI-USER OR SITE-WIDE CONFIGURATION
     For a single user, the proper way to configure XScreenSaver  is  to  simply
     run  the  xscreensaver-settings(1) program, and change the settings through
     the GUI.  Changes are written to the ~/.xscreensaver file.

     If you want to set the  system-wide  defaults,  then  make  your  edits  to
     /etc/X11/app-defaults/XScreenSaver  instead.   The  two  files have similar
     (but not identical) syntax.

     You can also make changes via the X Resource Database and xrdb(1), but that
     can be very confusing and is not really recommended.

     Options in ~/.xscreensaver override any settings in the  resource	database
     or app-defaults file.

     If you change a setting in the .xscreensaver file while XScreenSaver is al-
     ready  running, it will notice this, and reload the file as needed.  But if
     you change a setting in the X Resource Database, you will need  to  restart
     XScreenSaver for those changes to take effect:

	  xrdb < ~/.Xdefaults
	  xscreensaver-command --restart

X RESOURCES
     These  are the X resources use by XScreenSaver program.  You probably won't
     need to change these manually:  that's  what  the	xscreensaver-settings(1)
     program is for.

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

     cycle (class Time)
	     After the screensaver has been running for this many  minutes,  the
	     currently	running  graphics-hack	sub-process will be killed (with
	     SIGTERM), and a new one started.  If this is 0, then  the	graphics
	     hack  will  never	be  changed:  only  one  demo will run until the
	     screensaver is deactivated by user activity.  Default 10 minutes.

	     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 re-
	     quire you to type the password of the logged-in user.

     lockTimeout (class Time)
	     If locking is enabled, this controls the length of the  "grace  pe-
	     riod"  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 activ-
	     ity 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  activation)  then  a	password
	     would  be	required.   The default is 0, meaning that if locking is
	     enabled, then a password will be required as  soon  as  the  screen
	     blanks.

     passwdTimeout (class Time)
	     If the screen is locked, then this is how many seconds the password
	     dialog  box  should be left on the screen before giving up (default
	     30 seconds).  A few seconds are added each time you type a  charac-
	     ter.

     dpmsEnabled (class Boolean)
	     Whether power management is enabled.

     dpmsStandby (class Time)
	     If  power	management  is	enabled, how long until the monitor goes
	     solid black.

     dpmsSuspend (class Time)
	     If power management is enabled, how long  until  the  monitor  goes
	     into power-saving mode.

     dpmsOff (class Time)
	     If  power	management is enabled, how long until the monitor powers
	     down completely.  Note that these settings will have no effect  un-
	     less  both the X server and the display hardware support power man-
	     agement; not all do.  See the Power Management section, below,  for
	     more information.

     dpmsQuickOff (class Boolean)
	     If  mode is blank and this is true, then the screen will be powered
	     down immediately upon blanking, regardless of  other  power-manage-
	     ment 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 sec-
	     onds.

     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.

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

     newLoginCommand (class NewLoginCommand)
	     If set, this is the shell command that is run when the "New  Login"
	     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 unnecessarily.  The de-
	     fault 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 desktop
	     will fade to black instead of simply winking out.	Default: true.

     unfade (class Boolean)
	     If this is true, then when  the  screensaver  deactivates,  desktop
	     will  fade  back  ininstead 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.  De-
	     fault 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 warn-
	     ing will be printed if an attempt is made to  run	the  nonexistent
	     program.	Also, the xscreensaver-settings(1) program 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 in-
	     forming you of previous failed login attempts.  If all of those lo-
	     gin 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.   De-
	     fault 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.

	     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 dis-
		     play mode (the one indicated by the selected setting).

	     blank   When  blanking  the  screen,  just  go black: don't run any
		     graphics hacks.

	     off     Don't ever blank the screen, and don't ever allow the moni-
		     tor to power down.

     selected (class Integer)
	     When mode is set to one, this is the one, indicated by its index in
	     the programs list.  You're crazy if you count  them  and  set  this
	     number by hand: let xscreensaver-settings(1) do it for you!

     programs (class Programs)
	     The  graphics  hacks which XScreenSaver runs when the user is idle.
	     The value of this resource is a multi-line  string,  one  sh-syntax
	     command  per  line.  Each line must contain exactly one command: no
	     semicolons, no ampersands.

	     When the screensaver starts up, one of these is selected (according
	     to the mode setting), and run.  After the cycle period expires,  it
	     is killed, and another is selected and run.

	     If  a  line  begins with a dash (-) then that particular program is
	     disabled: it won't be selected at random (though you can still  se-
	     lect it explicitly using the xscreensaver-settings(1) program).

	     If  all  programs	are  disabled, then the screen will just be made
	     blank, as when mode is set to blank.

	     To disable a program, you must mark it as disabled with a dash  in-
	     stead  of	removing  it from the list.  This is because the system-
	     wide  (app-defaults)  and	per-user  (.xscreensaver)  settings  are
	     merged  together,	and  if  a user just deletes an entry from their
	     programs list, but that entry still exists in the system-wide list,
	     then it will come back.  However, if the  user  disables  it,  then
	     their setting takes precedence.

	     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  environment
	     variable.	 If it creates and maps its own window instead, it won't
	     work.  It must render onto the provided window.

	     Visuals:

	     Because XScreenSaver was created back  when  dinosaurs  roamed  the
	     earth,  it  still	contains support for some things you've probably
	     never seen, such as 1-bit monochrome monitors, grayscale  monitors,
	     and monitors capable of displaying only 8-bit colormapped 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	using  a
	     monochrome display, you can specify that like this:

		  mono:   mono-program	-root	     \n\
		  color:  color-program -root	     \n\

	     More  generally,  you can specify the kind of visual that should be
	     used for the window on which the program will be drawing.	For  ex-
	     ample,  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 sup-
	     ported in the programs list:

      default-n
	  This is like default, but also requests the use of  the  default  col-
	  ormap, instead of a private colormap.

     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.

     visualID (class VisualID)
	     This  is  an historical artifact left over from when 8-bit displays
	     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, how-
		     ever, that the visual with the most colors might be a True-
		     Color visual, which does not  support  colormap  animation.
		     Some  programs  have  more interesting behavior when run on
		     PseudoColor visuals than on TrueColor.

	     mono    Use a monochrome visual, if there is one.

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

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

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

	     class   where  class  is one of StaticGray, StaticColor, TrueColor,
		     GrayScale, PseudoColor, or DirectColor.  Selects the  deep-
		     est visual of the given class.

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

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

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

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

     pointerHysteresis (class Integer)
	     If the mouse moves less than this-many pixels in a  second,  ignore
	     it  (do  not  consider that to be "activity").  This is so that the
	     screen doesn't un-blank (or fail to blank) just because you  bumped
	     the desk.	Default: 10 pixels.

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

BUGS
     https://www.jwz.org/xscreensaver/bugs.html explains how to write  the  most
     useful bug reports.  If you find a bug, please let me know!

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.

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

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

     XENVIRONMENT
	     to  get  the  name of a resource file that overrides the global re-
	     sources 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 https://www.jwz.org/xscreensaver/

SEE ALSO
     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),
     xscreensaver-text(6).

COPYRIGHT
     Copyright	(C)  1991-2026 by Jamie Zawinski.  Permission to use, copy, mod-
     ify, distribute, and sell this software and its documentation for any  pur-
     pose  is  hereby granted without fee, provided that the above copyright no-
     tice appear in all copies and that both that copyright notice and this per-
     mission notice appear in supporting documentation.  No representations  are
     made  about  the  suitability of this software for any purpose.  It is pro-
     vided "as is" without express or implied warranty.

AUTHOR
     Jamie Zawinski <jwz@jwz.org>

     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.15 (30-Mar-2026)		 XScreenSaver(1)

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

home | help