EditPageHistoryDiffInfoLikePages

Annotated edit history of xscreensaver(1) version 5, including all changes. View license author blame.

Rev	Author	#	Line
1	perry	1	XScreenSaver
		2	!!!XScreenSaver
		3	NAME
		4	SYNOPSIS
		5	DESCRIPTION
		6	GETTING STARTED
		7	CONFIGURATION
		8	COMMAND-LINE OPTIONS
		9	HOW IT WORKS
		10	POWER MANAGEMENT
		11	USING XDM(1)
		12	USING GDM(1)
		13	USING CDE (COMMON DESKTOP ENVIRONMENT)
		14	USING HP VUE (VISUAL USER ENVIRONMENT)
		15	ADDING TO MENUS
		16	BUGS
		17	ENVIRONMENT
		18	UPGRADES
		19	SEE ALSO
		20	COPYRIGHT
		21	AUTHOR
		22	ACKNOWLEDGEMENTS
		23	----
		24	!!NAME
		25
		26
		27	xscreensaver - graphics hack and screen locker, launched when the user is idle
		28	!!SYNOPSIS
		29
		30
		31	__xscreensaver__ [[-display ''host:display.screen'']
		32	[[-timeout ''int''] [[-cycle ''int''] [[-lock-mode]
		33	[[-no-lock-mode] [[-lock-timeout ''int''] [[-visual
		34	''visual''] [[-install] [[-no-install] [[-verbose] [[-silent]
		35	[[-timestamp] [[-capture-stderr] [[-no-capture-stderr]
		36	[[-splash] [[-no-splash] [[-nice ''int''] [[-mit-extension]
		37	[[-no-mit-extension] [[-sgi-extension] [[-no-sgi-extension]
		38	[[-xidle-extension] [[-no-xidle-extension] [[-proc-interrupts]
		39	[[-no-proc-interrupts] [[-xrm ''resources'']
		40	!!DESCRIPTION
		41
		42
		43	The ''xscreensaver'' program waits until the keyboard and
		44	mouse have been idle for a period, and then runs a graphics
		45	demo chosen at random. It turns off as soon as there is any
		46	mouse or keyboard activity.
		47
		48
		49	This program can lock your terminal in order to prevent
		50	others from using it, though its default mode of operation
		51	is merely to display pretty pictures on your screen when it
		52	is not in use.
		53
		54
		55	The benefit that this program has over the combination of
		56	the xlock(1) and xautolock(1) programs is the
		57	ease with which new graphics hacks can be installed. You
		58	don't need to recompile (or even re-run) this program to add
		59	a new display mode.
		60	!!GETTING STARTED
		61
		62
		63	For the impatient, try this:
		64
		65
		66	xscreensaver
5	perry	67	The xscreensaver-demo(1) program should pop up a dialog box that lets you experiment with the xscreensaver settings and graphics modes.
1	perry	68
		69
		70	__Note:__ unlike xlock(1), xscreensaver has a
		71	client-server model: the ''xscreensaver'' program is a
		72	daemon that runs in the background; it is controlled by the
5	perry	73	foreground xscreensaver-demo(1) and
		74	xscreensaver-command(1) programs.
1	perry	75	!!CONFIGURATION
		76
		77
		78	The easiest way to configure ''xscreensaver'' is to
5	perry	79	simply run the xscreensaver-demo(1) program, and
1	perry	80	change the settings through the GUI. The rest of this manual
		81	page describes lower level ways of changing
		82	settings.
		83
		84
		85	Options to ''xscreensaver'' are stored in one of two
		86	places: in a ''.xscreensaver'' file in your home
		87	directory; or in the X resource database. If the
		88	''.xscreensaver'' file exists, it overrides any settings
		89	in the resource database.
		90
		91
		92	The syntax of the ''.xscreensaver'' file is similar to
		93	that of the ''.Xdefaults'' file; for example, to set the
		94	''timeout'' paramter in the ''.xscreensaver'' file,
		95	you would write the following:
		96
		97
		98	timeout: 5
		99	whereas, in the ''.Xdefaults'' file, you would write
		100
		101
		102	xscreensaver.timeout: 5
		103	If you change a setting in the ''.xscreensaver'' file while xscreensaver is already running, it will notice this, and reload the file. (The file will be reloaded the next time the screen saver needs to take some action, such as blanking or unblanking the screen, or picking a new graphics mode.)
		104
		105
		106	If you change a setting in your X resource database, or if
		107	you want xscreensaver to notice your changes immediately
		108	instead of the next time it wakes up, then you will need to
		109	tell the running xscreensaver process to re-initialize
		110	itself, like so:
		111
		112
		113	xscreensaver-command -restart
		114	Note that if you changed the ''.Xdefaults'' file, you might also need to run xrdb(1):
		115
		116
		117	xrdb
		118	If you want to set the system-wide defaults, then make your edits to the xscreensaver app-defaults file, which should have been installed when xscreensaver itself was installed. The app-defaults file will usually be named /usr/lib/X11/app-defaults/XScreenSaver, but different systems might keep it in a different place (for example, /usr/openwin/lib/app-defaults/XScreenSaver on Solaris.)
		119
		120
		121	When settings are changed in the Preferences dialog box (see
		122	above) the current settings will be written to the
		123	''.xscreensaver'' file. (The ''.Xdefaults'' file and
		124	the app-defaults file will never be written by xscreensaver
		125	itself.)
		126
		127
		128	__timeout__ (class __Time__)
		129
		130
		131	The screensaver will activate (blank the screen) after the
		132	keyboard and mouse have been idle for this many minutes.
		133	Default 10 minutes.
		134
		135
		136	__cycle__ (class __Time__)
		137
		138
		139	After the screensaver has been running for this many
		140	minutes, the currently running graphics-hack sub-process
		141	will be killed (with __SIGTERM__), and a new one started.
		142	If this is 0, then the graphics hack will never be changed:
		143	only one demo will run until the screensaver is deactivated
		144	by user activity. Default 10 minutes.
		145
		146
		147	__lock__ (class __Boolean__)
		148
		149
		150	Enable locking: before the screensaver will turn off, it
		151	will require you to type the password of the logged-in user
		152	(really, the person who ran xscreensaver), or the root
		153	password. (__Note:__ this doesn't work if the screensaver
		154	is launched by xdm(1) because it can't know the
		155	user-id of the logged-in user. See the ``''Using
		156	XDM(1)'''' section, below.
		157
		158
		159	__lockTimeout__ (class __Time__)
		160
		161
		162	If locking is enabled, this controls the length of the
		163	``grace period'' between when the screensaver activates, and
		164	when the screen becomes locked. For example, if this is 5,
		165	and ''-timeout'' is 10, then after 10 minutes, the screen
		166	would blank. If there was user activity at 12 minutes, no
		167	password would be required to un-blank the screen. But, if
		168	there was user activity at 15 minutes or later (that is,
		169	''-lock-timeout'' minutes after activation) then a
		170	password would be required. The default is 0, meaning that
		171	if locking is enabled, then a password will be required as
		172	soon as the screen blanks.
		173
		174
		175	__passwdTimeout__ (class __Time__)
		176
		177
		178	If the screen is locked, then this is how many seconds the
		179	password dialog box should be left on the screen before
		180	giving up (default 30 seconds.) This should not be too
		181	large: the X server is grabbed for the duration that the
		182	password dialog box is up (for security purposes) and
		183	leaving the server grabbed for too long can cause
		184	problems.
		185
		186
		187	__dpmsEnabled__ (class __Boolean__)
		188
		189
		190	Whether power management is enabled.
		191
		192
		193	__dpmsStandby__ (class __Time__)
		194
		195
		196	If power management is enabled, how long until the monitor
		197	goes solid black.
		198
		199
		200	__dpmsSuspend__ (class __Time__)
		201
		202
		203	If power management is enabled, how long until the monitor
		204	goes into power-saving mode.
		205
		206
		207	__dpmsOff__ (class __Time__)
		208
		209
		210	If power management is enabled, how long until the monitor
		211	powers down completely. Note that these settings will have
		212	no effect unless both the X server and the display hardware
		213	support power management; not all do. See the ''Power
		214	Management'' section, below, for more
		215	information.
		216
		217
		218	__visualID__ (class __VisualID__)
		219
		220
		221	Specify which X visual to use by default. (Note carefully
		222	that this resource is called __visualID__, not merely
		223	__visual__; if you set the __visual__ resource
		224	instead, things will malfunction in obscure ways for obscure
		225	reasons.)
		226
		227
		228	Legal values for the __VisualID__ resource
		229	are:
		230
		231
		232	__default__
		233
		234
		235	Use the screen's default visual (the visual of the root
		236	window.) This is the default.
		237
		238
		239	__best__
		240
		241
		242	Use the visual which supports the most colors. Note,
		243	however, that the visual with the most colors might be a
4	perry	244	!TrueColor visual, which does not support colormap animation.
1	perry	245	Some programs have more interesting behavior when run on
4	perry	246	!PseudoColor visuals than on !TrueColor.
1	perry	247
		248
		249	__mono__
		250
		251
		252	Use a monochrome visual, if there is one.
		253
		254
		255	__gray__
		256
		257
		258	Use a grayscale or staticgray visual, if there is one and it
		259	has more than one plane (that is, it's not
		260	monochrome.)
		261
		262
		263	__color__
		264
		265
		266	Use the best of the color visuals, if there are
		267	any.
		268
		269
		270	__GL__
		271
		272
		273	Use the visual that is best for OpenGL programs. (OpenGL
		274	programs have somewhat different requirements than other X
		275	programs.)
		276
		277
		278	''class''
		279
		280
4	perry	281	where ''class'' is one of __!StaticGray__,
		282	__!StaticColor__, __!TrueColor__, __!GrayScale__,
		283	__!PseudoColor__, or __!DirectColor__. Selects the
1	perry	284	deepest visual of the given class.
		285
		286
		287	''number''
		288
		289
		290	where ''number'' (decimal or hex) is interpreted as a
		291	visual id number, as reported by the xdpyinfo(1)
		292	program; in this way you can have finer control over exactly
		293	which visual gets used, for example, to select a shallower
		294	one than would otherwise have been chosen.
		295
		296
		297	Note that this option specifies only the ''default''
		298	visual that will be used: the visual used may be overridden
		299	on a program-by-program basis. See the description of the
		300	__programs__ resource, below.
		301
		302
		303	__installColormap__ (class __Boolean__)
		304
		305
		306	Install a private colormap while the screensaver is active,
		307	so that the graphics hacks can get as many colors as
		308	possible. This is the default. (This only applies when the
		309	screen's default visual is being used, since non-default
		310	visuals get their own colormaps automatically.) This can
		311	also be overridden on a per-hack basis: see the discussion
		312	of the __default-n__ name in the section about the
		313	__programs__ resource.
		314
		315
		316	__verbose__ (class __Boolean__)
		317
		318
		319	Whether to print diagnostics. Default false.
		320
		321
		322	__timestamp__ (class __Boolean__)
		323
		324
		325	Whether to print the time of day along with any other
		326	diagnostic messages. Default false.
		327
		328
		329	__splash__ (class __Boolean__)
		330
		331
		332	Whether to display a splash screen at startup. Default
		333	true.
		334
		335
		336	__splashDuration__ (class __Time__)
		337
		338
		339	How long the splash screen should remain visible; default 5
		340	seconds.
		341
		342
		343	__helpURL__ (class __URL__)
		344
		345
		346	The splash screen has a ''Help'' button on it. When you
		347	press it, it will display the web page indicated here in
		348	your web browser.
		349
		350
		351	__loadURL__ (class __LoadURL__)
		352
		353
		354	This is the shell command used to load a URL into your web
		355	browser. The default setting will load it into Netscape if
		356	it is already running, otherwise, will launch a new Netscape
		357	looking at the ''helpURL''.
		358
		359
4	perry	360	__demoCommand__ (class __!DemoCommand__)
1	perry	361
		362
		363	This is the shell command run when the ''Demo'' button on
		364	the splash window is pressed. It defaults to
		365	''xscreensaver-demo''.
		366
		367
4	perry	368	__prefsCommand__ (class __!PrefsCommand__)
1	perry	369
		370
		371	This is the shell command run when the ''Prefs'' button
		372	on the splash window is pressed. It defaults to
		373	''xscreensaver-demo -prefs''.
		374
		375
		376	__nice__ (class __Nice__)
		377
		378
		379	The sub-processes created by ''xscreensaver'' will be
		380	``niced'' to this level, so that they are given lower
		381	priority than other processes on the system, and don't
		382	increase the load unnecessarily. The default is
		383	10.
		384
		385
		386	(Higher numbers mean lower priority; see nice(1) for
		387	details.)
		388
		389
4	perry	390	__memoryLimit__ (class __!MemoryLimit__)
1	perry	391
		392
		393	The sub-processes created by ''xscreensaver'' will not be
		394	allowed to allocate more than this much memory (more
		395	accurately, this is the maximum size their address space may
		396	become.) If any sub-process tries to allocate more than
		397	this, malloc(3) will fail, and the process will
		398	likely exit (or safely crash) rather than going forth and
		399	hogging memory.
		400
		401
		402	The assumption here is that if one of the screenhacks is
		403	trying to use a lot of memory, then something has gone
		404	wrong, and it's better to kill that program than to overload
		405	the machine.
		406
		407
		408	Default: 50M.
		409
		410
		411	__fade__ (class __Boolean__)
		412
		413
		414	If this is true, then when the screensaver activates, the
		415	current contents of the screen will fade to black instead of
		416	simply winking out. This only works on displays with
		417	writable colormaps, that is, if the screen's default visual
4	perry	418	is a !PseudoColor visual. A fade will also be done when
1	perry	419	switching graphics hacks (when the ''cycle'' timer
		420	expires.) Default: true.
		421
		422
		423	__unfade__ (class __Boolean__)
		424
		425
		426	If this is true, then when the screensaver deactivates, the
		427	original contents of the screen will fade in from black
		428	instead of appearing immediately. This only works on
		429	displays with writable colormaps, and if ''fade'' is true
		430	as well. Default false.
		431
		432
		433	__fadeSeconds__ (class __Time__)
		434
		435
		436	If ''fade'' is true, this is how long the fade will be in
		437	seconds (default 3 seconds.)
		438
		439
		440	__fadeTicks__ (class __Integer__)
		441
		442
		443	If ''fade'' is true, this is how many times a second the
		444	colormap will be changed to effect a fade. Higher numbers
		445	yield smoother fades, but may make the fades take longer
		446	than the specified ''fadeSeconds'' if your server isn't
		447	fast enough to keep up. Default 20.
		448
		449
		450	__captureStderr__ (class __Boolean__)
		451
		452
		453	Whether ''xscreensaver'' should redirect its stdout and
		454	stderr streams to the window itself. Since its nature is to
		455	take over the screen, you would not normally see error
		456	messages generated by xscreensaver or the sub-programs it
		457	runs; this resource will cause the output of all relevant
		458	programs to be drawn on the screensaver window itself, as
		459	well as being written to the controlling terminal of the
		460	screensaver driver process. Default true.
		461
		462
		463	__font__ (class __Font__)
		464
		465
		466	The font used for the stdout/stderr text, if
		467	__captureStderr__ is true. Default
		468	__*-medium-r-*-140-*-m-*__ (a 14 point fixed-width
		469	font.)
		470
		471
		472	__programs__ (class __Programs__)
		473
		474
		475	The graphics hacks which ''xscreensaver'' runs when the
		476	user is idle. The value of this resource is a string, one
		477	''sh''-syntax command per line. Each line must contain
		478	exactly one command: no semicolons, no
		479	ampersands.
		480
		481
		482	When the screensaver starts up, one of these is selected at
		483	random, and run. After the ''cycle'' period expires, it
		484	is killed, and another is selected and run.
		485
		486
		487	If a line begins with a dash (-) then that particular
		488	program is disabled: it won't be selected at random (though
		489	you can still select it explicitly using the
5	perry	490	xscreensaver-demo(1) program.)
1	perry	491
		492
		493	If all programs are disabled, then the screen will just be
		494	made blank.
		495
		496
		497	To disable a program, it's better to mark it as disabled
		498	with a dash than to remove it from the list. This is because
		499	the system-wide (app-defaults) and per-user (.xscreensaver)
		500	settings are merged together, and if a user just
		501	''deletes'' an entry from their programs list, but that
		502	entry still exists in the system-wide list, then it will
		503	come back. However, if the user ''disables'' it, then
		504	their setting takes precedence.
		505
		506
		507	If the display has multiple screens, then a different
		508	program will be run for each screen. (All screens are
		509	blanked and unblanked simultaniously.)
		510
		511
		512	Note that you must escape the newlines; here is an example
		513	of how you might set this in your ''~/.xscreensaver''
		514	file:
		515
		516
		517	programs: \
		518	qix -root n\
		519	ico -r -faces -sleep 1 -obj ico n\
		520	xdaliclock -builtin2 -root n\
		521	xv -root -rmode 5 image.gif -quit n
		522
		523
		524	Make sure your __$PATH__ environment variable is set up
		525	correctly ''before'' xscreensaver is launched, or it
		526	won't be able to find the programs listed in the
		527	''programs'' resource.
		528
		529
		530	To use a program as a screensaver, two things are required:
		531	that that program draw on the root window (or be able to be
		532	configured to draw on the root window); and that that
		533	program understand ``virtual root'' windows, as used by
		534	virtual window managers such as tvtwm(1). (Generally,
		535	this is accomplished by just including the
		536	'''' header file in the program's
		537	source.)
		538
		539
		540	If there are some programs that you want to run only when
		541	using a color display, and others that you want to run only
		542	when using a monochrome display, you can specify that like
		543	this:
		544
		545
		546	mono: mono-program -root n\
		547	color: color-program -root n\
		548
		549
		550	More generally, you can specify the kind of visual that
		551	should be used for the window on which the program will be
		552	drawing. For example, if one program works best if it has a
		553	colormap, but another works best if it has a 24-bit visual,
		554	both can be accommodated:
		555
		556
4	perry	557	!PseudoColor: cmap-program -root n\
		558	!TrueColor: 24bit-program -root n\
1	perry	559
		560
		561	In addition to the symbolic visual names described above (in
		562	the discussion of the ''visualID'' resource) one other
		563	visual name is supported in the ''programs''
		564	list:
		565
		566
		567	__default-n__
		568
		569
		570	This is like __default__, but also requests the use of
		571	the default colormap, instead of a private colormap. (That
		572	is, it behaves as if the ''-no-install'' command-line
		573	option was specified, but only for this particular hack.)
		574	This is provided because some third-party programs that draw
		575	on the root window (notably: xv(1), and
		576	xearth(1)) make assumptions about the visual and
		577	colormap of the root window: assumptions which xscreensaver
		578	can violate.
		579
		580
		581	If you specify a particular visual for a program, and that
		582	visual does not exist on the screen, then that program will
		583	not be chosen to run. This means that on displays with
		584	multiple screens of different depths, you can arrange for
		585	appropriate hacks to be run on each. For example, if one
		586	screen is color and the other is monochrome, hacks that look
		587	good in mono can be run on one, and hacks that only look
		588	good in color will show up on the other.
		589
		590
		591	Normally you won't need to change the following
		592	resources:
		593
		594
		595	__pointerPollTime__ (class __Time__)
		596
		597
		598	When server extensions are not in use, this controls how
		599	frequently ''xscreensaver'' checks to see if the mouse
		600	position or buttons have changed. Default 5
		601	seconds.
		602
		603
		604	__windowCreationTimeout__ (class
		605	__Time__)
		606
		607
		608	When server extensions are not in use, this controls the
		609	delay between when windows are created and when
		610	''xscreensaver'' selects events on them. Default 30
		611	seconds.
		612
		613
		614	__initialDelay__ (class __Time__)
		615
		616
		617	When server extensions are not in use, ''xscreensaver''
		618	will wait this many seconds before selecting events on
		619	existing windows, under the assumption that
		620	''xscreensaver'' is started during your login procedure,
		621	and the window state may be in flux. Default 0. (This used
		622	to default to 30, but that was back in the days when slow
		623	machines and X terminals were more common...)
		624
		625
		626	__sgiSaverExtension__ (class __Boolean__)
		627
		628
		629	There are a number of different X server extensions which
		630	can make xscreensaver's job easier. The next few resources
		631	specify whether these extensions should be utilized if they
		632	are available.
		633
		634
		635	This resource controls whether the SGI __SCREEN_SAVER__
		636	server extension will be used to decide whether the user is
		637	idle. This is the default if ''xscreensaver'' has been
		638	compiled with support for this extension (which is the
		639	default on SGI systems.). If it is available, the
		640	__SCREEN_SAVER__ method is faster and more reliable than
		641	what will be done otherwise, so use it if you can. (This
		642	extension is only available on Silicon Graphics systems,
		643	unfortunately.)
		644
		645
		646	__mitSaverExtension__ (class __Boolean__)
		647
		648
		649	This resource controls whether the __MIT-SCREEN-SAVER__
		650	server extension will be used to decide whether the user is
		651	idle. However, the default for this resource is
		652	''false'', because even if this extension is available,
		653	it is flaky (and it also makes the __fade__ option not
		654	work properly.) Use of this extension is not
		655	recommended.
		656
		657
		658	__xidleExtension__ (class __Boolean__)
		659
		660
		661	This resource controls whether the __XIDLE__ server
		662	extension will be used to decide whether the user is idle.
		663	This is the default if ''xscreensaver'' has been compiled
		664	with support for this extension. (This extension is only
		665	available for X11R4 and X11R5 systems,
		666	unfortunately.)
		667
		668
		669	__procInterrupts__ (class __Boolean__)
		670
		671
		672	This resource controls whether the __/proc/interrupts__
		673	file should be consulted to decide whether the user is idle.
		674	This is the default if ''xscreensaver'' has been compiled
		675	on a system which supports this mechanism (i.e., Linux
		676	systems.)
		677
		678
		679	The benefit to doing this is that ''xscreensaver'' can
		680	note that the user is active even when the X console is not
		681	the active one: if the user is typing in another virtual
		682	console, xscreensaver will notice that and will fail to
		683	activate. For example, if you're playing Quake in VGA-mode,
		684	xscreensaver won't wake up in the middle of your game and
		685	start competing for CPU.
		686
		687
		688	The drawback to doing this is that perhaps you ''really
		689	do'' want idleness on the X console to cause the X display
		690	to lock, even if there is activity on other virtual
		691	consoles. If you want that, then set this option to False.
		692	(Or just lock the X console manually.)
		693
		694
		695	The default value for this resource is True, on systems
		696	where it works.
		697
		698
		699	__overlayStderr__ (class __Boolean__)
		700
		701
		702	If __captureStderr__ is True, and your server supports
		703	``overlay'' visuals, then the text will be written into one
		704	of the higher layers instead of into the same layer as the
		705	running screenhack. Set this to False to disable that
		706	(though you shouldn't need to.)
		707
		708
		709	__overlayTextForeground__ (class
		710	__Foreground__)
		711
		712
		713	The foreground color used for the stdout/stderr text, if
		714	__captureStderr__ is true. Default: Yellow.
		715
		716
		717	__overlayTextBackground__ (class
		718	__Background__)
		719
		720
		721	The background color used for the stdout/stderr text, if
		722	__captureStderr__ is true. Default: Black.
		723
		724
4	perry	725	__bourneShell__ (class __!BourneShell__)
1	perry	726
		727
		728	The pathname of the shell that ''xscreensaver'' uses to
		729	start subprocesses. This must be whatever your local variant
		730	of __/bin/sh__ is: in particular, it must not be
		731	__csh__.
		732	!!COMMAND-LINE OPTIONS
		733
		734
		735	''xscreensaver'' also accepts the following command line
		736	options. Except for the ''-display'' option, these
		737	command-line options are all simply shorthand for the X
		738	resources described in the ''Configuration'' section,
		739	above.
		740
		741
		742	__-display__ ''host:display.screen''
		743
		744
		745	The X display to use. For displays with multiple screens,
		746	XScreenSaver will manage all screens on the display
		747	simultaniously; the ''screen'' argument (the ``default''
		748	screen) says which screen should be used for dialog boxes
		749	(the password window, ''Demo Mode'', etc.)
		750
		751
		752	__-timeout__ ''minutes''
		753
		754
		755	Same as the ''timeout'' resource.
		756
		757
		758	__-cycle__ ''minutes''
		759
		760
		761	Same as the ''cycle'' resource.
		762
		763
		764	__-lock-mode__
		765
		766
		767	Same as setting the ''lock'' resource to
		768	''true''.
		769
		770
		771	__-no-lock-mode__
		772
		773
		774	Same as setting the ''lock'' resource to
		775	''false''.
		776
		777
		778	__-lock-timeout__ ''minutes''
		779
		780
		781	Same as the ''lockTimeout'' resource.
		782
		783
		784	__-visual__ ''visual''
		785
		786
		787	Same as the ''visualID'' resource.
		788
		789
		790	__-install__
		791
		792
		793	Same as setting the ''installColormap'' resource to
		794	''true''.
		795
		796
		797	__-no-install__
		798
		799
		800	Same as setting the ''installColormap'' resource to
		801	''false''.
		802
		803
		804	__-verbose__
		805
		806
		807	Same as setting the ''verbose'' resource to
		808	''true''.
		809
		810
		811	__-silent__
		812
		813
		814	Same as setting the ''verbose'' resource to
		815	''false''.
		816
		817
		818	__-timestamp__
		819
		820
		821	Same as setting the ''timestamp'' resource to
		822	''true''.
		823
		824
		825	__-capture-stderr__
		826
		827
		828	Same as setting the ''captureStderr'' resource to
		829	''true''.
		830
		831
		832	__-no-capture-stderr__
		833
		834
		835	Same as setting the ''captureStderr'' resource to
		836	''false''.
		837
		838
		839	__-splash__
		840
		841
		842	Same as setting the ''splash'' resource to
		843	''true''.
		844
		845
		846	__-no-splash__
		847
		848
		849	Same as setting the ''splash'' resource to
		850	''false''.
		851
		852
		853	__-nice__ ''integer''
		854
		855
		856	Same as the ''nice'' resource.
		857
		858
		859	__-sgi-extension__
		860
		861
		862	Same as setting the ''sgiSaverExtension'' resource to
		863	''true''.
		864
		865
		866	__-no-sgi-extension__
		867
		868
		869	Same as setting the ''sgiSaverExtension'' resource to
		870	''false''.
		871
		872
		873	__-mit-extension__
		874
		875
		876	Same as setting the ''mitSaverExtension'' resource to
		877	''true''.
		878
		879
		880	__-no-mit-extension__
		881
		882
		883	Same as setting the ''mitSaverExtension'' resource to
		884	''false''.
		885
		886
		887	__-xidle-extension__
		888
		889
		890	Same as setting the ''xidleExtension'' resource to
		891	''true''.
		892
		893
		894	__-no-xidle-extension__
		895
		896
		897	Same as setting the ''xidleExtension'' resource to
		898	''false''.
		899
		900
		901	__-proc-interrupts__
		902
		903
		904	Same as setting the ''procInterrupts'' resource to
		905	''true''.
		906
		907
		908	__-no-proc-interrupts__
		909
		910
		911	Same as setting the ''procInterrupts'' resource to
		912	''false''.
		913
		914
		915	__-xrm__ ''resource-specification''
		916
		917
		918	As with all other Xt programs, you can specify X resources
		919	on the command-line using the ''-xrm'' argument. Most of
		920	the interesting resources have command-line equivalents,
		921	however.
		922	!!HOW IT WORKS
		923
		924
		925	When it is time to activate the screensaver, a full-screen
		926	black window is created on each screen of the display. Each
		927	window is created in such a way that, to any
		928	subsequently-created programs, it will appear to be a
		929	``virtual root'' window. Because of this, any program which
		930	draws on the root window (and which understands virtual
		931	roots) can be used as a screensaver.
		932
		933
		934	When the user becomes active again, the screensaver windows
		935	are unmapped, and the running subprocesses are killed by
		936	sending them __SIGTERM__. This is also how the
		937	subprocesses are killed when the screensaver decides that
		938	it's time to run a different demo: the old one is killed and
		939	a new one is launched.
		940
		941
		942	Before launching a subprocess, ''xscreensaver'' stores an
		943	appropriate value for __$DISPLAY__ in the environment
		944	that the child will receive. (This is so that if you start
		945	''xscreensaver'' with a ''-display'' argument, the
		946	programs which ''xscreensaver'' launches will draw on the
		947	same display; and so that the child will end up drawing on
		948	the appropriate screen of a multi-headed
		949	display.)
		950
		951
		952	When the screensaver turns off, or is killed, care is taken
		953	to restore the ``real'' virtual root window if there is one.
		954	Because of this, it is important that you not kill the
		955	screensaver process with ''kill -9'' if you are running a
		956	virtual-root window manager. If you kill it with -9, you may
		957	need to restart your window manager to repair the damage.
		958	This isn't an issue if you aren't running a virtual-root
		959	window manager.
		960
		961
		962	For all the gory details, see the commentary at the top of
		963	xscreensaver.c.
		964
		965
		966	You can control a running screensaver process by using the
5	perry	967	xscreensaver-command(1) program (which
1	perry	968	see.)
		969	!!POWER MANAGEMENT
		970
		971
		972	Modern X servers contain support to power down the monitor
		973	after an idle period. If the monitor has powered down, then
		974	''xscreensaver'' will notice this (after a few minutes),
		975	and will not waste CPU by drawing graphics demos on a black
		976	screen. An attempt will also be made to explicitly power the
		977	monitor back up as soon as user activity is
		978	detected.
		979
		980
		981	As of version 3.28, the ''~/.xscreensaver'' file controls
		982	the configuration of your display's power management
		983	settings: if you have used xset(1) to change your
		984	power management settings, then xscreensaver will override
		985	those changes with the values specified in
		986	''~/.xscreensaver'' (or with its built-in defaults, if
		987	there is no ''~/.xscreensaver'' file yet.)
		988
		989
		990	To change your power management settings, run
5	perry	991	xscreensaver-demo(1) and change the various timeouts
1	perry	992	through the user interface. Alternately, you can edit the
		993	''~/.xscreensaver'' file directly.
		994
		995
		996	If the power management section is grayed out in the
5	perry	997	xscreensaver-demo(1) window, then that means that
1	perry	998	your X server does not support the XDPMS extension, and so
		999	control over the monitor's power state is not
		1000	available.
		1001
		1002
		1003	If you're using a laptop, don't be surprised if changing the
		1004	DPMS settings has no effect: many laptops have monitor
		1005	power-saving behavior built in at a very low level that is
		1006	invisible to Unix and X. On such systems, you can typically
		1007	only adjust the power-saving delays by changing settings in
		1008	the BIOS in some hardware-specific way.
		1009	!!USING XDM(1)
		1010
		1011
		1012	You can run ''xscreensaver'' from your xdm(1)
		1013	session, so that the screensaver will run even when nobody
		1014	is logged in on the console.
		1015
		1016
		1017	The trick to using xscreensaver with ''xdm'' is this:
		1018	keep in mind the two very different states in which
		1019	xscreensaver will be running:
		1020
		1021
		1022	__1: Nobody logged in.__
		1023
		1024
		1025	If you're thinking of running xscreensaver from XDM at all,
		1026	then it's probably because you want graphics demos to be
		1027	running on the console when nobody is logged in there. In
		1028	this case, xscreensaver will function only as a screen
		1029	saver, not a screen locker: it doesn't make sense for
		1030	xscreensaver to lock the screen, since nobody is logged in
		1031	yet! The only thing on the screen is the XDM login
		1032	prompt.
		1033
		1034
		1035	__2: Somebody logged in.__
		1036
		1037
		1038	Once someone has logged in through the XDM login window, the
		1039	situation is very different. For example: now it makes sense
		1040	to lock the screen (and prompt for the logged in user's
		1041	password); and now xscreensaver should consult that user's
		1042	''~/.xscreensaver'' file; and so on.
		1043
		1044
		1045	The difference between these two states comes down to a
		1046	question of, which user is the ''xscreensaver'' process
		1047	running as? For the first state, it doesn't matter. If you
		1048	start ''xscreensaver'' in the usual XDM way, then
		1049	xscreensaver will probably end up running as root, which is
		1050	fine for the first case (the ``nobody logged in''
		1051	case.)
		1052
		1053
		1054	However, once someone is logged in, running as root is no
		1055	longer fine: because xscreensaver will be consulting root's
		1056	''.xscreensaver'' file instead of that of the logged in
		1057	user, and won't be prompting for the logged in user's
		1058	password, and so on. (This is not a security problem, it's
		1059	just not what you want.)
		1060
		1061
		1062	So, once someone has logged in, you want xscreensaver to be
		1063	running as that user. The way to accomplish this is to kill
		1064	the old xscreensaver process and start a new one (as the new
		1065	user.)
		1066
		1067
		1068	The simplest way to accomplish all of this is as
		1069	follows:
		1070
		1071
		1072	__1: Launch xscreensaver before anyone logs
		1073	in.__
		1074
		1075
		1076	To the file ''/usr/lib/X11/xdm/Xsetup'', add the
		1077	lines
		1078
		1079
		1080	xhost +localhost
		1081	xscreensaver-command -exit
		1082	xscreensaver
		1083	This will run xscreensaver as root, over the XDM login window. Moving the mouse will cause the screen to un-blank, and allow the user to type their password at XDM to log in.
		1084
		1085
		1086	__2: Restart xscreensaver when someone logs
		1087	in.__
		1088
		1089
		1090	Near the top of the file ''/usr/lib/X11/xdm/Xsession'',
		1091	add those same lines:
		1092
		1093
		1094	xscreensaver-command -exit
		1095	xscreensaver
		1096	When someone logs in, this will kill off the existing (root) xscreensaver process, and start a new one, running as the user who has just logged in. If the user's .xscreensaver file requests locking, they'll get it. They will also get their own choice of timeouts, and graphics demos, and so on.
		1097
		1098
		1099	Alternately, each user could just put those lines in their
		1100	personal ''~/.xsession'' files.
		1101
		1102
		1103	Make sure you have __$PATH__ set up correctly in the
		1104	''Xsetup'' and ''Xsession'' scripts, or ''xdm''
		1105	won't be able to find ''xscreensaver'', and/or
		1106	''xscreensaver'' won't be able to find its graphics
		1107	demos.
		1108
		1109
		1110	(If your system does not seem to be executing the
		1111	''Xsetup'' file, you may need to configure it to do so:
		1112	the traditional way to do this is to make that file the
4	perry	1113	value of the ''!DisplayManager*setup'' resource in the
1	perry	1114	''/usr/lib/X11/xdm/xdm-config'' file. See the man page
		1115	for xdm(1) for more details.)
		1116
		1117
		1118	It is safe to run ''xscreensaver'' as root (as ''xdm''
		1119	is likely to do.) If run as root, ''xscreensaver''
		1120	changes its effective user and group ids to something safe
		1121	(like '''') before connecting to the X
		1122	server or launching user-specified programs.
		1123
		1124
		1125	An unfortunate side effect of this (important) security
		1126	precaution is that it may conflict with cookie-based
		1127	authentication.
		1128
		1129
		1130	If you get
		1131	xscreensaver'' from ''xdm'', then this
		1132	probably means that you have xauth(1) or some other
		1133	security mechanism turned on. One way around this is to add
		1134	____ to ''Xsetup'', just
		1135	before ''xscreensaver'' is launched.
		1136
		1137
		1138	Note that this will give access to the X server to anyone
		1139	capable of logging in to the local machine, so in some
		1140	environments, this might not be appropriate. If turning off
		1141	file-system-based access control is not acceptable, then
		1142	running ''xscreensaver'' from the ''Xsetup'' file
		1143	might not be possible, and xscreensaver will only work when
		1144	running as a normal, unprivileged user.
		1145
		1146
		1147	For more information on the X server's access control
5	perry	1148	mechanisms, see the man pages for X(1),
		1149	Xsecurity(1), xauth(1), and
1	perry	1150	xhost(1).
		1151	!!USING GDM(1)
		1152
		1153
		1154	The instructions for using ''xscreensaver'' with
		1155	gdm(1) are almost the same as for using
		1156	xdm(1), above. There are only two differences,
		1157	really: instead of editing ''/usr/lib/X11/xdm/Xsetup'',
		1158	edit the file ''/etc/X11/gdm/Init/Default''; and instead
		1159	of editing ''/usr/lib/X11/xdm/Xsession'', edit one or all
		1160	of the files in the ''/etc/X11/gdm/Sessions/'' directory.
		1161	(Note that the default session
		1162	(''/etc/X11/gdm/Sessions/Default'') usually simply
		1163	executes ''/usr/lib/X11/xdm/Xsession'', so be careful you
		1164	aren't initializing xscreensaver twice.)
		1165
		1166
		1167	All the same caveats apply for gdm(1) as for
		1168	xdm(1).
		1169	!!USING CDE (COMMON DESKTOP ENVIRONMENT)
		1170
		1171
		1172	The easiest way to use ''xscreensaver'' on a system with
		1173	CDE is to simply switch off the built-in CDE screensaver,
		1174	and use ''xscreensaver'' instead; and second, to tell the
5	perry	1175	front panel to run xscreensaver-command(1) with the
1	perry	1176	''-lock'' option when the ''Lock'' icon is
		1177	clicked.
		1178
		1179
		1180	To accomplish this involves five steps:
		1181
		1182
		1183	__1: Switch off CDE's locker__
		1184
		1185
		1186	Do this by turning off ``''Screen Saver and Screen
		1187	Lock'''' in the Screen section of the Style
		1188	Manager.
		1189
		1190
		1191	__2: Edit sessionetc__
		1192
		1193
		1194	Edit the file ''~/.dt/sessions/sessionetc'' and add to it
		1195	the line
		1196
		1197
		1198	xscreensaver
		1199	And make sure the sessionetc file is executable. This will cause ''xscreensaver'' to be launched when you log in. (As always, make sure that xscreensaver and the graphics demos are on your __$PATH__; the path needs to be set in ''.cshrc'' and/or ''.dtprofile'', not ''.login''.)
		1200
		1201
		1202	__3: Create XScreenSaver.dt__
		1203
		1204
		1205	Create a file called ''~/.dt/types/XScreenSaver.dt'' with
		1206	the following contents:
		1207
		1208
		1209	ACTION XScreenSaver
		1210	{
		1211	LABEL XScreenSaver
		1212	TYPE COMMAND
		1213	EXEC_STRING xscreensaver-command -lock
		1214	ICON Dtkey
		1215	WINDOW_TYPE NO_STDIO
		1216	}
		1217	This defines a ``lock'' command for the CDE front panel, that knows how to talk to ''xscreensaver''.
		1218
		1219
		1220	__4: Create Lock.fp__
		1221
		1222
		1223	Create a file called ''~/.dt/types/Lock.fp'' with the
		1224	following contents:
		1225
		1226
		1227	CONTROL Lock
		1228	{
		1229	TYPE icon
		1230	CONTAINER_NAME Switch
		1231	CONTAINER_TYPE SWITCH
		1232	POSITION_HINTS 1
		1233	ICON Fplock
		1234	LABEL Lock
		1235	PUSH_ACTION XScreenSaver
		1236	HELP_TOPIC FPOnItemLock
		1237	HELP_VOLUME FPanel
		1238	}
		1239	This associates the CDE front panel ``Lock'' icon with the lock command we just defined in step 3.
		1240
		1241
		1242	__5: Restart__
		1243
		1244
		1245	Select ``''Restart Workspace Manager'''' from the popup
		1246	menu to make your changes take effect. If things seem not to
		1247	be working, check the file ''~/.dt/errorlog'' for error
		1248	messages.
		1249	!!USING HP VUE (VISUAL USER ENVIRONMENT)
		1250
		1251
		1252	Since CDE is a descendant of VUE, the instructions for using
		1253	xscreensaver under VUE are similar to the
		1254	above:
		1255
		1256
		1257	__1: Switch off VUE's locker__
		1258
		1259
		1260	Open the ``''Style Manager'''' and select
		1261	``''Screen''.'' Turn off ``''Screen Saver and Screen
		1262	Lock'''' option.
		1263
		1264
		1265	__2: Make sure you have a Session__
		1266
		1267
		1268	Next, go to the Style Manager's, ``''Startup'''' page.
		1269	Click on ``''Set Home Session'''' to create a session,
		1270	then on ``''Return to Home Session'''' to select this
		1271	session each time you log in.
		1272
		1273
		1274	__3: Edit vue.session__
		1275
		1276
		1277	Edit the file ''~/.vue/sessions/home/vue.session'' and
		1278	add to it the line
		1279
		1280
		1281	vuesmcmd -screen 0 -cmd
		1282	This will cause ''xscreensaver'' to be launched when you log in. (As always, make sure that xscreensaver and the graphics demos are on your __$PATH__; the path needs to be set in ''.cshrc'' and/or ''.profile'', not ''.login''.)
		1283
		1284
		1285	__3: Edit vuewmrc__
		1286
		1287
		1288	Edit the file ''~/.vue/vuewmrc'' and add (or change) the
		1289	Lock control:
		1290
		1291
		1292	CONTROL Lock
		1293	{
		1294	TYPE button
		1295	IMAGE lock
		1296	PUSH_ACTION f.exec
		1297	This associates the VUE front panel ``Lock'' icon with the xscreensaver lock command.
		1298	!!ADDING TO MENUS
		1299
		1300
5	perry	1301	The xscreensaver-command(1) program is a perfect
1	perry	1302	candidate for something to add to your window manager's
5	perry	1303	popup menus. If you use mwm(1), 4Dwm(1),
1	perry	1304	twm(1), or (probably) any of ''twm'''s many
		1305	descendants, you can do it like this:
		1306
		1307
		1308	__1. Create ~/.mwmrc (or ~/.twmrc or ...)__
		1309
		1310
		1311	If you don't have a ''~/.mwmrc'' file (or, on SGIs, a
		1312	''~/.4Dwmrc'' file; or, with twm, a ''~/.twmrc'' file)
		1313	then create one by making a copy of the
		1314	''/usr/lib/X11/system.mwmrc'' file (or
		1315	''/usr/lib/X11/twm/system.twmrc'', and so
		1316	on.)
		1317
		1318
		1319	__2. Add a menu definition.__
		1320
		1321
		1322	Something like this:
		1323
		1324
		1325	menu XScreenSaver
		1326	{
		1327
		1328
		1329	__3. Add the menu__
		1330
		1331
5	perry	1332	For mwm(1) and 4Dwm(1), find the section of
4	perry	1333	the file that says ''Menu !DefaultRootMenu''. For
1	perry	1334	twm(1), it will probably be ''menu
		1335	''. If you add a line somewhere in that
		1336	menu definition that reads
		1337
		1338
		1339
		1340	then this will add an XScreenSaver sub-menu to your default root-window popup menu. Alternately, you could just put the xscreensaver menu items directly into the root menu.
		1341
		1342
		1343	For Fvwm2, the process is similar: first create a
		1344	''~/.fvwm2rc'' file if you don't already have one, by
		1345	making a copy of the ''/etc/X11/fvwm2/system.fvwm2rc''
		1346	file. Then, add a menu definition to it:
		1347
		1348
4	perry	1349	!AddToMenu XScreenSaver
1	perry	1350	The Enlightenment window manager keeps each of its menus in a separate file. So, you need to create a file named ''~/.enlightenment/xscreensaver.menu'' with the contents:
		1351
		1352
		1353
		1354	then add
		1355
		1356
		1357
		1358	to ''~/.enlightenment/file.menu'' to put the XScreenSaver submenu on your left-button root-window menu.
		1359
		1360
		1361	As you see, every window manager does this stuff
		1362	gratuitously differently, just to make your life difficult.
		1363	You are in a maze of twisty menu configuration languages,
		1364	all alike.
		1365	!!BUGS
		1366
		1367
		1368	Bugs? There are no bugs. Ok, well, maybe. If you find one,
		1369	please let me know.
		1370	http://www.jwz.org/xscreensaver/bugs.html explains how to
		1371	construct the most useful bug reports.
		1372
		1373
		1374	__Locking and XDM__
		1375
		1376
		1377	If xscreensaver has been launched from xdm(1) before
		1378	anyone has logged in, you will need to kill and then restart
		1379	the xscreensaver daemon after you have logged in, or you
		1380	will be confused by the results. (For example, locking won't
		1381	work, and your ''~/.xscreensaver'' file will be
		1382	ignored.)
		1383
		1384
		1385	When you are logged in, you want the ''xscreensaver''
		1386	daemon to be running under ''your'' user id, not as root
		1387	or some other user.
		1388
		1389
		1390	If it has already been started by ''xdm'', you can kill
		1391	it by sending it the __exit__ command, and then
		1392	re-launching it as you, by putting something like the
		1393	following in your personal X startup script:
		1394
		1395
		1396	xscreensaver-command -exit
		1397	xscreensaver
		1398	The ``''Using XDM(1)'''' section, above, goes into more detail, and explains how to configure the system to do this for all users automatically.
		1399
		1400
		1401	__Locking and root logins__
		1402
		1403
		1404	In order for it to be safe for xscreensaver to be launched
		1405	by ''xdm'', certain precautions had to be taken, among
		1406	them that xscreensaver never runs as ''root''. In
		1407	particular, if it is launched as root (as ''xdm'' is
		1408	likely to do), xscreensaver will disavow its privileges, and
		1409	switch itself to a safe user id (such as
		1410	''nobody''.)
		1411
		1412
		1413	An implication of this is that if you log in as ''root''
		1414	on the console, xscreensaver will refuse to lock the screen
		1415	(because it can't tell the difference between ''root''
		1416	being logged in on the console, and a normal user being
		1417	logged in on the console but xscreensaver having been
		1418	launched by the xdm(1) ''Xsetup''
		1419	file.)
		1420
		1421
		1422	The solution to this is simple: you shouldn't be logging in
		1423	on the console as ''root'' in the first place! (What, are
		1424	you crazy or something?)
		1425
		1426
		1427	Proper Unix hygiene dictates that you should log in as
		1428	yourself, and su(1) to ''root'' as necessary.
		1429	People who spend their day logged in as ''root'' are just
		1430	begging for disaster.
		1431
		1432
		1433	__XAUTH and XDM__
		1434
		1435
		1436	For xscreensaver to work when launched by xdm(1),
		1437	programs running on the local machine as user
		1438	'''' must be able to connect to the X
		1439	server. This means that if you want to run xscreensaver on
		1440	the console while nobody is logged in, you may need to
		1441	disable cookie-based access control (and allow all users who
		1442	can log in to the local machine to connect to the
		1443	display.)
		1444
		1445
		1446	You should be sure that this is an acceptable thing to do in
		1447	your environment before doing it. See the ``''Using
		1448	XDM(1)'''' section, above, for more details.
		1449
		1450
		1451	If anyone has suggestions on how xscreensaver could be made
		1452	to work with xdm(1) without first turning off
		1453	''.Xauthority''-based access control, please let me
		1454	know.
		1455
		1456
		1457	__Passwords__
		1458
		1459
		1460	If you get an error message at startup like ``couldn't get
		1461	password of ''user'''' then this probably means that
		1462	you're on a system in which the getpwent(3) library
		1463	routine can only be effectively used by root. If this is the
		1464	case, then ''xscreensaver'' must be installed as setuid
		1465	to root in order for locking to work. Care has been taken to
		1466	make this a safe thing to do.
		1467
		1468
		1469	It also may mean that your system uses shadow passwords
		1470	instead of the standard getpwent(3) interface; in
		1471	that case, you may need to change some options with
		1472	''configure'' and recompile.
		1473
		1474
		1475	If you change your password after xscreensaver has been
		1476	launched, it will continue using your old password to unlock
		1477	the screen until xscreensaver is restarted. So, after you
		1478	change your password, you'll have to do
		1479
		1480
		1481	xscreensaver-command -restart
		1482	to make ''xscreensaver'' notice.
		1483
		1484
		1485	__PAM Passwords__
		1486
		1487
		1488	If your system uses PAM (Pluggable Authentication Modules),
		1489	then in order for xscreensaver to use PAM properly, PAM must
		1490	be told about xscreensaver. The xscreensaver installation
		1491	process should update the PAM data (on Linux, by creating
		1492	the file ''/etc/pam.d/xscreensaver'' for you, and on
		1493	Solaris, by telling you what lines to add to the
		1494	''/etc/pam.conf'' file.)
		1495
		1496
		1497	If the PAM configuration files do not know about
		1498	xscreensaver, then you ''might'' be in a situation where
		1499	xscreensaver will refuse to ever unlock the
		1500	screen.
		1501
		1502
		1503	This is a design flaw in PAM (there is no way for a client
		1504	to tell the difference between PAM responding ``I have never
		1505	heard of your module,'' and responding, ``you typed the
		1506	wrong password.'') As far as I can tell, there is no way for
		1507	xscreensaver to automatically work around this, or detect
		1508	the problem in advance, so if you have PAM, make sure it is
		1509	configured correctly!
		1510
		1511
		1512	__Colormap lossage: TWM__
		1513
		1514
		1515	The __installColormap__ option doesn't work very well
		1516	with the twm(1) window manager and its
		1517	descendants.
		1518
		1519
		1520	There is a race condition between the screensaver and this
		1521	window manager, which can result in the screensaver's
		1522	colormap not getting installed properly, meaning the
		1523	graphics hacks will appear in essentially random colors. (If
		1524	the screen goes white instead of black, this is probably
		1525	why.)
		1526
		1527
		1528	The mwm(1) and olwm(1) window managers don't
		1529	have this problem. The race condition exists because X
		1530	(really, ICCCM) does not provide a way for an
4	perry	1531	!OverrideRedirect window to have its own colormap, short of
1	perry	1532	grabbing the server (which is neither a good idea, nor
		1533	really possible with the current design.) What happens is
		1534	that, as soon as xscreensaver installs its colormap,
4	perry	1535	__twm__ responds to the resultant __!ColormapNotify__
1	perry	1536	event by re-instaling the default colormap. Apparently,
		1537	__twm__ doesn't ''always'' do this; it seems to do it
		1538	regularly if the screensaver is activated from a menu item,
		1539	but seems to not do it if the screensaver comes on of its
		1540	own volition, or is activated from another
		1541	console.
		1542
		1543
		1544	__Attention, window manager authors!__
		1545
		1546
5	perry	1547	You should only call XInstallColormap(3) in response
1	perry	1548	to user events. That is, it is appropriate to install a
4	perry	1549	colormap in response to __!FocusIn__, __!FocusOut__,
		1550	__!EnterNotify__, and __!LeaveNotify__ events; but it is
1	perry	1551	not appropriate to call it in response to
4	perry	1552	__!ColormapNotify__ events. If you install colormaps in
1	perry	1553	response to ''application'' actions as well as in
		1554	response to ''user'' actions, then you create the
		1555	situation where it is impossible for override-redirect
		1556	applications (such as xscreensaver) to display their windows
		1557	in the proper colors.
		1558
		1559
		1560	__Colormap lossage: XV, XAnim, XEarth__
		1561
		1562
		1563	Some programs don't operate properly on visuals other than
		1564	the default one, or with colormaps other than the default
		1565	one. See the discussion of the magic
		1566	programs__
		1567	resource in the ''Configuration'' section. When programs
		1568	only work with the default colormap, you need to use a
		1569	syntax like this:
		1570
		1571
		1572	default-n: xv -root image-1.gif -quit n\
		1573	default-n: xearth -nostars -wait 0 n\
		1574	It would also work to turn off the __installColormap__ option altogether, but that would deny extra colors to those programs that ''can'' take advantage of them.
		1575
		1576
		1577	__Machine Load__
		1578
		1579
		1580	Although this program ``nices'' the subprocesses that it
		1581	starts, graphics-intensive subprograms can still overload
		1582	the machine by causing the X server process itself (which is
		1583	not ``niced'') to suck a lot of cycles. Care should be taken
		1584	to slow down programs intended for use as screensavers by
		1585	inserting strategic calls to sleep(3) or
		1586	usleep(3) (or making liberal use of any ''-delay''
		1587	options which the programs may provide.)
		1588
		1589
		1590	Note that the OpenGL-based graphics demos are real pigs on
		1591	machines that don't have texture hardware.
		1592
		1593
		1594	Also, an active screensaver will cause your X server to be
		1595	pretty much permanently swapped in; but the same is true of
		1596	any program that draws periodically, like xclock(1)
		1597	or xload(1).
		1598
		1599
		1600	__Latency and Responsiveness__
		1601
		1602
		1603	If the subprocess is drawing too quickly and the connection
		1604	to the X server is a slow one (such as an X terminal running
		1605	over a phone line) then the screensaver might not turn off
		1606	right away when the user becomes active again (the
		1607	ico(1) demo has this problem if being run in
		1608	full-speed mode). This can be alleviated by inserting
5	perry	1609	strategic calls to XSync(3) in code intended for use
1	perry	1610	as a screensaver. This prevents too much graphics activity
		1611	from being buffered up.
		1612
		1613
		1614	__XFree86's Magic Keystrokes__
		1615
		1616
		1617	The XFree86 X server traps certain magic keystrokes before
		1618	client programs ever see them. Two that are of note are
		1619	Ctrl+Alt+Backspace, which causes the X server to exit; and
		1620	Ctrl+Alt+F''n'', which switches virtual consoles. The X
		1621	server will respond to these keystrokes even if xscreensaver
		1622	has the screen locked. Depending on your setup, you might
		1623	consider this a problem.
		1624
		1625
		1626	Unfortunately, there is no way for xscreensaver itself to
		1627	override the interpretation of these keys. If you want to
		1628	disable Ctrl+Alt+Backspace globally, you need to set the
4	perry	1629	''!DontZap'' flag in your ''/etc/X11/XF86Config'' file.
5	perry	1630	See the XF86Config(5) manual for
1	perry	1631	details.
		1632
		1633
		1634	There is no way (as far as I can tell) to disable the
		1635	VT-switching keystrokes.
		1636
		1637
		1638	Some Linux systems come with a VT_LOCKSWITCH ioctl, that one
		1639	could theoretically use to prevent VT-switching while the
		1640	screen is locked; but unfortunately, this ioctl can only be
		1641	used by root, which means that xscreensaver can't use it
		1642	(since xscreensaver disavows its privileges shortly after
		1643	startup, for security reasons.)
		1644
		1645
		1646	Any suggestions for other solutions to this problem are
		1647	welcome.
		1648
		1649
		1650	__XView Clients__
		1651
		1652
		1653	Apparently there are some problems with XView programs
		1654	getting confused and thinking that the screensaver window is
		1655	the real root window even when the screensaver is not
4	perry	1656	active: !ClientMessages intended for the window manager are
1	perry	1657	sent to the screensaver window instead. This could be solved
		1658	by making xscreensaver forward all unrecognised
4	perry	1659	!ClientMessages to the real root window, but there may be
1	perry	1660	other problems as well. If anyone has any insight on the
		1661	cause of this problem, please let me know. (XView is an X11
4	perry	1662	toolkit that implements the (quite abominable) Sun !OpenLook
1	perry	1663	look-and-feel.)
		1664
		1665
		1666	__MIT Extension and Fading__
		1667
		1668
		1669	The __MIT-SCREEN-SAVER__ extension is junk. Don't use
		1670	it.
		1671
		1672
		1673	When using the __MIT-SCREEN-SAVER__ extension in
		1674	conjunction with the __fade__ option, you'll notice an
		1675	unattractive flicker just before the fade begins. This is
		1676	because the server maps a black window just before it tells
		1677	the ''xscreensaver'' process to activate. The
		1678	''xscreensaver'' process immediately unmaps that window,
		1679	but this results in a flicker. I haven't figured a way to
		1680	get around this; it seems to be a fundamental property of
		1681	the (mis-) design of this server extension.
		1682
		1683
		1684	It sure would be nice if someone would implement the __SGI
		1685	SCREEN_SAVER__ extension in XFree86; it's dead simple, and
		1686	works far better than the overengineered and broken
		1687	__MIT-SCREEN-SAVER__ extension.
		1688
		1689
		1690	__SGI Power Saver__
		1691
		1692
		1693	If you're running Irix 6.3, you might find that your monitor
		1694	is powering down after an hour or two even if you've told it
		1695	not to. This is fixed by SGI patches 2447 and
		1696	2537.
		1697
		1698
		1699	If you're running Irix 6.5, this bug is back. I don't know a
		1700	fix.
		1701
		1702
		1703	__MesaGL and Voodoo Cards__
		1704
		1705
		1706	If you have a 3Dfx/Voodoo card, the default settings for
		1707	xscreensaver will run the GL-based graphics demos in such a
		1708	way that they will not take advantage of the 3D acceleration
		1709	hardware. The solution is to change the __programs__
		1710	entries for the GL hacks from this:
		1711
		1712
		1713	gears -root n\
		1714	to this:
		1715
		1716
		1717	MESA_GLX_FX=fullscreen gears n\
		1718	That is, make sure that __$MESA_GLX_FX__ is set to ''fullscreen'', and don't tell the program to draw on the root window. This may seem strange, but the setup used by Mesa and these kinds of cards ''is'' strange!
		1719
		1720
		1721	For those who don't know, these cards work by sitting
		1722	between your normal video card and the monitor, and seizing
		1723	control of the monitor when it's time to do 3D. But this
		1724	means that accelerated 3D only happens in full-screen mode
		1725	(you can't do it in a window, and you can't see the output
		1726	of 3D and 2D programs simultaniously), and that 3D will
		1727	probably drive your monitor at a lower resolution, as well.
		1728	It's bizarre.
		1729
		1730
		1731	If you find that GL programs only work properly when run as
		1732	root, and not as normal users, then the problem is that your
		1733	''/dev/3dfx'' file is not configured properly. Check the
		1734	Linux 3Dfx FAQ.
		1735
		1736
		1737	__Keyboard LEDs__
		1738
		1739
		1740	If ''procInterrupts'' is on (which is the default on
		1741	Linux systems) and you're using some program that toggles
		1742	the state of your keyboard LEDs, xscreensaver won't work
		1743	right: turning those LEDs on or off causes a keyboard
		1744	interrupt, which xscreensaver will interpret as user
		1745	activity. So if you're using such a program, set the
		1746	''procInterrupts'' resource to False.
		1747
		1748
		1749	__Extensions__
		1750
		1751
		1752	If you are not making use of one of the server extensions
		1753	(__XIDLE__, __SGI SCREEN_SAVER__, or
		1754	__MIT-SCREEN-SAVER__), then it is possible, in rare
		1755	situations, for ''xscreensaver'' to interfere with event
		1756	propagation and make another X program malfunction. For this
		1757	to occur, that other application would need to ''not''
4	perry	1758	select __!KeyPress__ events on its non-leaf windows within
1	perry	1759	the first 30 seconds of their existence, but then select for
		1760	them later. In this case, that client ''might'' fail to
		1761	receive those events. This isn't very likely, since programs
		1762	generally select a constant set of events immediately after
		1763	creating their windows and then don't change them, but this
		1764	is the reason that it's a good idea to install and use one
		1765	of the server extensions instead, to work around this
		1766	shortcoming in the X protocol.
		1767
		1768
		1769	In all these years, I've not heard of even a single case of
		1770	this happening, but it is theoretically possible, so I'm
		1771	mentioning it for completeness...
		1772
		1773
		1774	__Red Hot Lava__
		1775
		1776
		1777	There need to be a lot more graphics hacks. In particular,
		1778	there should be a simulation of a Lavalite
		1779	(tm).
		1780	!!ENVIRONMENT
		1781
		1782
		1783	__DISPLAY__
		1784
		1785
		1786	to get the default host and display number, and to inform
		1787	the sub-programs of the screen on which to
		1788	draw.
		1789
		1790
		1791	__PATH__
		1792
		1793
		1794	to find the sub-programs to run.
		1795
		1796
		1797	__HOME__
		1798
		1799
		1800	for the directory in which to read and write the
		1801	''.xscreensaver'' file.
		1802
		1803
		1804	__XENVIRONMENT__
		1805
		1806
		1807	to get the name of a resource file that overrides the global
		1808	resources stored in the RESOURCE_MANAGER
		1809	property.
		1810	!!UPGRADES
		1811
		1812
		1813	The latest version can always be found at
		1814	http://www.jwz.org/xscreensaver/
		1815	!!SEE ALSO
		1816
		1817
5	perry	1818	X(1), __xscreensaver-demo__(1),
		1819	xscreensaver-command(1),
		1820	xscreensaver-gl-helper(1), xdm(1),
		1821	xset(1), Xsecurity(1), xauth(1),
1	perry	1822	xhost(1). ant(1), atlantis(1),
		1823	attraction(1), blitspin(1),
		1824	bouboule(1), braid(1), bsod(1),
5	perry	1825	bubble3d(1), bubbles(1), cage(1),
1	perry	1826	compass(1), coral(1), critical(1),
		1827	crystal(1), cynosure(1),
		1828	decayscreen(1), deco(1), deluxe(1),
		1829	demon(1), discrete(1), distort(1),
		1830	drift(1), epicycle(1), fadeplot(1),
		1831	flag(1), flame(1), flow(1),
		1832	forest(1), galaxy(1), gears(1),
		1833	glplanet(1), goop(1), grav(1),
		1834	greynetic(1), halo(1), helix(1),
		1835	hopalong(1), hypercube(1), ifs(1),
		1836	imsmap(1), interference(1), jigsaw(1),
		1837	julia(1), kaleidescope(1), kumppa(1),
		1838	lament(1), laser(1), lightning(1),
		1839	lisa(1), lissie(1), lmorph(1),
		1840	loop(1), maze(1), moebius(1),
5	perry	1841	moire(1), moire2(1), __morph3d__(1),
1	perry	1842	mountain(1), munch(1), noseguy(1),
		1843	pedal(1), penetrate(1), penrose(1),
		1844	petri(1), phosphor(1), pipes(1),
		1845	pulsar(1), pyro(1), qix(1),
5	perry	1846	rd-bomb(1), rocks(1), rorschach(1),
1	perry	1847	rotor(1), rubik(1), sierpinski(1),
		1848	slidescreen(1), slip(1), sonar(1),
		1849	sphere(1), spiral(1), spotlight(1),
		1850	sproingies(1), squiral(1), stairs(1),
		1851	starfish(1), strange(1),
5	perry	1852	superquadrics(1), swirl(1), t3d(1),
1	perry	1853	triangle(1), truchet(1), vines(1),
		1854	wander(1), worm(1), xflame(1),
		1855	xjack(1), xlyap(1), xmatrix(1),
		1856	bongo(1), ico(1), xaos(1),
		1857	xbouncebits(1), xcthugha(1),
		1858	xdaliclock(1), xfishtank(1),
		1859	xmountains(1), xsplinefun(1),
		1860	xswarm(1), xtacy(1), xv(1),
		1861	chbg(1), xwave(1).
		1862	!!COPYRIGHT
		1863
		1864
		1865	Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
		1866	1999, 2000, 2001 by Jamie Zawinski. Permission to use, copy,
		1867	modify, distribute, and sell this software and its
		1868	documentation for any purpose is hereby granted without fee,
		1869	provided that the above copyright notice appear in all
		1870	copies and that both that copyright notice and this
		1871	permission notice appear in supporting documentation. No
		1872	representations are made about the suitability of this
		1873	software for any purpose. It is provided
		1874	!!AUTHOR
		1875
		1876
		1877	Jamie Zawinski
		1878
		1879
		1880	Please let me know if you find any bugs or make any
		1881	improvements.
		1882	!!ACKNOWLEDGEMENTS
		1883
		1884
		1885	Thanks to Angela Goodman for the XScreenSaver
		1886	logo.
		1887
		1888
		1889	Thanks to the many people who have contributed graphics
		1890	demos to the package.
		1891
		1892
		1893	Thanks to David Wojtowicz for implementing
		1894	''lockTimeout''.
		1895
		1896
		1897	Thanks to Martin Kraemer for adding support for shadow
		1898	passwords and locking-disabled diagnostics.
		1899
		1900
		1901	Thanks to Patrick Moreau for the VMS port.
		1902
		1903
		1904	Thanks to Mark Bowyer for figuring out how to hook it up to
		1905	CDE.
		1906
		1907
		1908	Thanks to Nat Lanza for the Kerberos support.
		1909
		1910
		1911	Thanks to Bill Nottingham for the initial PAM
		1912	support.
		1913
		1914
		1915	And thanks to Jon A. Christopher for implementing the Athena
		1916	dialog support, back in the days before Lesstif or Gtk were
		1917	viable alternatives to Motif.
		1918	----