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

FreeBSD Manual Pages

  
 
  

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  configu-
       ration 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 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.

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

       --verbose
	       Print diagnostics to stderr.

       --version
	       Print the version number	and exit.

       --log filename
	       Append all diagnostic output to the given file.	This also  im-
	       plies --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
       ~/.xscreensaver 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 sys-
       temd(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
       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.

   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
	      figure 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
	      controlled 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 set-
	      tings 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
	      laptop's	lid.   If that is happening, double-check the settings
	      above, but if those are correct, try the following.  First,  en-
	      sure  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).

       Copy the	file /usr/share/xscreensaver/xscreensaver.service into the di-
       rectory	~/.config/systemd/user/.   Create  that	 directory first if it
       doesn't exist.  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  up-
       start(7)	 instead  of systemd(1), launch	the "Startup Applications" ap-
       plet, 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 appropri-
       ate 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 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 --no-splash"
       into the	Background Program field.  That	will cause gdm to run XScreen-
       Saver 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:

	    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  information	 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 re-
       place  X11.  After 14+ 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-
	  turely.

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

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

	    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 suscep-
       tible to	foot-shooting.

   MAGIC BACKDOOR KEYSTROKES
       The Xorg	and XFree86 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.

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

       In  addition  to	 the kernel's OOM-killer, systemd(1) has its own.  The
       included	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 Xsecurity(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  situation	where you can't	unlock.	 Probably the file you need is
       /usr/local/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  nec-
       essary.	 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  sim-
       ply  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	 data-
       base or app-defaults file.

       If you change a setting in the .xscreensaver file while XScreenSaver is
       already	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-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
	       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.

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

       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 desk-
	       top 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.
	       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.

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

	       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.

	       Visuals:

	       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
	       accommodated:

		    PseudoColor: cmap-program  -root   \n\
		    TrueColor:	 24bit-program -root   \n\

	       In  addition  to	 the symbolic visual names described above (in
	       the discussion of the visualID resource)	one other visual  name
	       is supported in the programs list:

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

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

	       N       where number (decimal or	hex) is	interpreted as	a  vi-
		       sual 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
       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
	       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	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-2022  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.

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.09 (07-Jun-2024)	       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+14.3.quarterly>

home | help