.if n .sp 1
.if t .sp .5
..
-.TH XScreenSaver 1 "24-Oct-98 (3.01)" "X Version 11"
+.TH XScreenSaver 1 "27-Apr-99 (3.10)" "X Version 11"
.SH NAME
xscreensaver - graphics hack and screen locker, launched when the user is idle
.SH SYNOPSIS
[\-no\-sgi\-extension] \
[\-xidle\-extension] \
[\-no\-xidle\-extension] \
+[\-proc\-interrupts] \
+[\-no\-proc\-interrupts] \
[\-xrm \fIresources\fP]
.SH DESCRIPTION
The \fIxscreensaver\fP program waits until the keyboard and mouse have been
xscreensaver &
xscreensaver-demo
.EE
-The \fIxscreensaver\-demo\fP program should pop up a dialog box
-that lets you experiment with the xscreensaver settings and graphics
-modes.
+The
+.BR xscreensaver-demo (1)
+program should pop up a dialog box that lets you experiment with the
+xscreensaver settings and graphics modes.
.B Note:
unlike
.SH CONFIGURATION
Options to \fIxscreensaver\fP are specified in one of two places: in
a \fI.xscreensaver\fP file in your home directory; or in the X resource
-database. If a \fI.xscreensaver\fP file exists, it overrides any settings
+database. If the \fI.xscreensaver\fP file exists, it overrides any settings
in the resource database.
The syntax of the \fI.xscreensaver\fP file is similar to that of
for each screen. (All screens are blanked and unblanked simultaniously.)
Note that you must escape the newlines; here is an example of how you
-might set this in your \fI~/.Xdefaults\fP file:
+might set this in your \fI~/.xscreensaver\fP file:
.RS 8
.EX
-xscreensaver.programs: \\
- qix -root \\n\\
- ico -r -faces -sleep 1 -obj ico \\n\\
- xdaliclock -builtin2 -root \\n\\
- xv -root -rmode 5 image.gif -quit \\n
+programs: \\
+ qix -root \\n\\
+ ico -r -faces -sleep 1 -obj ico \\n\\
+ xdaliclock -builtin2 -root \\n\\
+ xv -root -rmode 5 image.gif -quit \\n
.EE
.RE
.RS 8
To use a program as a screensaver, two things are required: that that
program draw on the root window (or be able to be configured to draw on
the root window); and that that program understand ``virtual root''
-windows, as used by virtual window managers such as \fItvtwm\fP. (Generally,
-this is accomplished by just including the \fI"vroot.h"\fP header file in
-the program's source.)
+windows, as used by virtual window managers such as
+.BR tvtwm (1).
+(Generally, this is accomplished by just including the \fI"vroot.h"\fP
+header file in the program's source.)
If there are some programs that you want to run only when using a color
display, and others that you want to run only when using a monochrome
display, you can specify that like this:
-
.EX
- mono: mono-program -root \\n\\
- color: color-program -root \\n\\
+ mono: mono-program -root \\n\\
+ color: color-program -root \\n\\
.EE
.RE
.RS 8
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:
-
.EX
- PseudoColor: cmap-program -root \\n\\
- TrueColor: 24bit-program -root \\n\\
+ PseudoColor: cmap-program -root \\n\\
+ TrueColor: 24bit-program -root \\n\\
.EE
.RE
.RS 8
-(This sort of thing used to be accomplished with the \fIcolorPrograms\fP
-and \fImonoPrograms\fP resources, but those resources have now been removed;
-a warning will be issued if they are used.)
-
In addition to the symbolic visual names described above (in the discussion
of the \fIvisualID\fP resource) one other visual name is supported in
the \fIprograms\fP list:
if \fIxscreensaver\fP has been compiled with support for this extension.
(This extension is only available for X11R4 and X11R5 systems, unfortunately.)
.TP 8
+.B procInterrupts\fP (class \fBBoolean\fP)
+This resource controls whether the \fB/proc/interrupts\fP file should be
+consulted to decide whether the user is idle. This is the default
+if \fIxscreensaver\fP has been compiled on a system which supports this
+mechanism (i.e., Linux systems.)
+
+The benefit to doing this is that \fIxscreensaver\fP can note that the user
+is active even when the X console is not the active one: if the user is
+typing in another virtual console, xscreensaver will notice that and will
+fail to activate. For example, if you're playing Quake in VGA-mode,
+xscreensaver won't wake up in the middle of your game and start competing
+for CPU.
+
+The drawback to doing this is that perhaps you \fIreally do\fP want idleness
+on the X console to cause the X display to lock, even if there is activity
+on other virtual consoles. If you want that, then set this option to False.
+(Or just lock the X console manually.)
+
+The default value for this resource is True, on systems where it works.
+.TP 8
.B overlayStderr\fP (class \fBBoolean\fP)
If \fBcaptureStderr\fP is True, and your server supports ``overlay'' visuals,
then the text will be written into one of the higher layers instead of into
.B \-no\-xidle\-extension
Same as setting the \fIxidleExtension\fP resource to \fIfalse\fP.
.TP 8
+.B \-proc\-interrupts
+Same as setting the \fIprocInterrupts\fP resource to \fItrue\fP.
+.TP 8
+.B \-no\-proc\-interrupts
+Same as setting the \fIprocInterrupts\fP resource to \fIfalse\fP.
+.TP 8
.B \-xrm \fIresource-specification\fP
As with all other Xt programs, you can specify X resources on the command-line
using the \fI\-xrm\fP argument. Most of the interesting resources have
command-line equivalents, however.
.SH HOW IT WORKS
When it is time to activate the screensaver, a full-screen black window is
-created on each screen of the display. The window or windows is given the
-appropriate properties so that, to any subsequently-created programs, it
-will appear to be a ``virtual root'' window. Because of this, any program
-which draws on the root window (and which understands virtual roots) can be
-used as a screensaver.
+created on each screen of the display. Each window is created in such a way
+that, to any subsequently-created programs, it will appear to be a ``virtual
+root'' window. Because of this, any program which draws on the root
+window (and which understands virtual roots) can be used as a screensaver.
-When the user becomes active again, the screensaver windows are unmapped and
+When the user becomes active again, the screensaver windows are unmapped, and
the running subprocesses are killed by sending them \fBSIGTERM\fP. This is
also how the subprocesses are killed when the screensaver decides that it's
time to run a different demo: the old one is killed and a new one is launched.
In order for it to be safe for xscreensaver to be launched by \fIxdm\fP,
certain precautions had to be taken, among them that xscreensaver never
runs as \fIroot\fP. In particular, if it is launched as root (as \fIxdm\fP
-is likely to do), xscreensaver will disavow its privileges, and switch to
-a safe user id (such as \fInobody\fP.)
+is likely to do), xscreensaver will disavow its privileges, and switch
+itself to a safe user id (such as \fInobody\fP.)
An implication of this is that if you log in as \fIroot\fP on the console,
xscreensaver will refuse to lock the screen (because it can't tell
let me know.
.TP 8
.B Passwords
-If you get an error message like ``couldn't get password of \fIuser\fP''
-then this probably means that you're on a system in which the
+If you get an error message at startup like ``couldn't get password
+of \fIuser\fP'' then this probably means that you're on a system in which
+the
.BR getpwent (3)
library routine can only be effectively used by root. If this is the case,
-then \fIxscreensaver\fP must be installed as setuid to root. Care has
-been taken to make this a safe thing to do.
+then \fIxscreensaver\fP must be installed as setuid to root in order for
+locking to work. Care has been taken to make this a safe thing to do.
It also may mean that your system uses shadow passwords instead of the standard
.BR getpwent (3)
.EE
to make \fIxscreensaver\fP notice.
.TP 8
+.B PAM Passwords
+If your system uses PAM (Pluggable Authentication Modules), then in order
+for xscreensaver to use PAM properly, PAM must be told about xscreensaver.
+The xscreensaver installation process should update the PAM data (on Linux,
+by creating the file \fI/etc/pam.d/xscreensaver\fP for you, and on Solaris,
+by telling you what lines to add to the \fI/etc/pam.conf\fP file.)
+
+If the PAM configuration files do not know about xscreensaver, then
+you \fImight\fP be in a situation where xscreensaver will refuse to ever
+unlock the screen.
+
+This is a design flaw in PAM (there is no way for a client to tell the
+difference between PAM responding ``I have never heard of your module,''
+and responding, ``you typed the wrong password.'') As far as I can tell,
+there is no way for xscreensaver to automatically work around this, or
+detect the problem in advance, so if you have PAM, make sure it is
+configured correctly!
+.TP 8
.B Colormap lossage: TWM
The \fBinstallColormap\fP option doesn't work very well with the
.BR twm (1)
.BR mwm (1)
and
.BR olwm (1)
-window managers don't seem to have this problem. The race condition exists
-because X does not provide a way for an OverrideRedirect window to have its
-own colormap, short of grabbing the server (which is neither a good idea, nor
-really possible with the current design.) What happens is that, as soon as
-the screensaver installs its colormap, \fBtwm\fP responds to
-the \fBColormapNotify\fP event that is generated by re-instaling the default
-colormap. Apparently, \fBtwm\fP doesn't \fIalways\fP do this; it seems to do
-it regularly if the screensaver is activated from a menu item, but seems to
-not do it if the screensaver comes on of its own volition, or is activated
-from another console. Any thoughts on this problem are welcome...
+window managers don't have this problem. The race condition exists
+because X (really, ICCCM) does not provide a way for an OverrideRedirect
+window to have its own colormap, short of grabbing the server (which is
+neither a good idea, nor really possible with the current design.) What
+happens is that, as soon as xscreensaver installs its colormap, \fBtwm\fP
+responds to the resultant \fBColormapNotify\fP event by re-instaling the
+default colormap. Apparently, \fBtwm\fP doesn't \fIalways\fP do this; it
+seems to do it regularly if the screensaver is activated from a menu item,
+but seems to not do it if the screensaver comes on of its own volition, or
+is activated from another console.
+.RS 8
+.TP 4
+.B Attention, window manager authors!
+You should only call
+.BR XInstallColormap (3)
+in response to user events. That is, it is appropriate to install a colormap
+in response to \fBFocusIn\fP, \fBFocusOut\fP, \fBEnterNotify\fP,
+and \fBLeaveNotify\fP events; but it is not appropriate to call it in
+response to \fBColormapNotify\fP events. If you install colormaps in
+response to \fIapplication\fP actions as well as in response to \fIuser\fP
+actions, then you create the situation where it is impossible for
+override-redirect applications (such as xscreensaver) to display their
+windows in the proper colors.
+.RE
.TP 8
.B Colormap lossage: XV, XAnim, XEarth
Some programs don't operate properly on visuals other than the default one,
resource in the \fIConfiguration\fP section. When programs only work with
the default colormap, you need to use a syntax like this:
.EX
- default-n: xv -root image-1.gif -quit \\n\\
- default-n: xearth -nostars -wait 0 \\n\\
+ default-n: xv -root image-1.gif -quit \\n\\
+ default-n: xearth -nostars -wait 0 \\n\\
.EE
It would also work to turn off the \fBinstallColormap\fP option altogether,
but that would deny extra colors to those programs that \fIcan\fP take
or
.BR xload (1).
.TP 8
-.B Doom and Quake
-On some systems, Doom, Quake, and other games intercept the keyboard in
-ways that X programs can never detect. Therefore, when running these games,
-xscreensaver might think the console is idle, and activate. In the worst
-case, xscreensaver might blank the screen and mess up the game. Alternately,
-xscreensaver might activate on the X display while leaving the game visible,
-and merely cause the game to slow down.
-
-I don't know how to fix this, because I don't know how to detect the kind
-of keyboard activity that occurs during these games. Suggestions are welcome.
-.TP 8
.B Latency and Responsiveness
If the subprocess is drawing too quickly and the connection to the X
server is a slow one (such as an X terminal running over a phone line) then
in code intended for use as a screensaver. This prevents too much graphics
activity from being buffered up.
.TP 8
+.B XFree86's Magic Keystrokes
+The XFree86 X server traps certain magic keystrokes before client programs ever
+see them. Two that are of note are Ctrl+Alt+Backspace, which causes
+the X server to exit; and Ctrl+Alt+F\fIn\fP, which switches virtual consoles.
+The X server will respond to these keystrokes even if xscreensaver has the
+screen locked. Depending on your setup, you might consider this a problem.
+
+Unfortunately, there is no way for xscreensaver itself to override the
+interpretation of these keys. If you want to disable Ctrl+Alt+Backspace
+globally, you need to set the \fIDontZap\fP flag in
+your \fI/etc/X11/XF86Config\fP file. See the
+.BR XF86Config (5)
+manual for details.
+
+There is no way (as far as I can tell) to disable the VT-switching keystrokes.
+
+Some Linux systems come with a VT_LOCKSWITCH ioctl, that one could
+theoretically use to prevent VT-switching while the screen is locked;
+but unfortunately, this ioctl can only be used by root, which means
+that xscreensaver can't use it (since xscreensaver disavows its privileges
+shortly after startup, for security reasons.)
+
+Any suggestions for other solutions to this problem are welcome.
+.TP 8
.B XView Clients
Apparently there are some problems with XView programs getting confused
and thinking that the screensaver window is the real root window even when
Your mileage, therefore, may vary dramatically.
.TP 8
.B MesaGL and Voodoo Cards
-If you have a 3Dfx/Voodoo card, the default settings for xscreensaver will run
-the GL-based graphics demos in such a way that they will not take advantage
-of the 3D acceleration hardware. The solution is to change the \fBprograms\fP
-entries for the GL hacks from this:
+If you have a 3Dfx/Voodoo card, the default settings for xscreensaver will
+run the GL-based graphics demos in such a way that they will not take
+advantage of the 3D acceleration hardware. The solution is to change
+the \fBprograms\fP entries for the GL hacks from this:
.EX
- gears -root \\n\\
+ gears -root \\n\\
.EE
to this:
.EX
- MESA_GLX_FX=fullscreen gears \\n\\
+ MESA_GLX_FX=fullscreen gears \\n\\
.EE
That is, make sure that \fB$MESA_GLX_FX\fP is set to \fIfullscreen\fP, and
don't tell the program to draw on the root window. This may seem strange,
For those who don't know, these cards work by sitting between your normal
video card and the monitor, and seizing control of the monitor when it's
time to do 3D. But this means that accelerated 3D only happens in full-screen
-mode (you can't do it in a window) and that 3D will probably drive your
-monitor at a lower resolution, as well. It's bizarre.
+mode (you can't do it in a window, and you can't see the output of 3D and 2D
+programs simultaniously), and that 3D will probably drive your monitor at a
+lower resolution, as well. It's bizarre.
+
+If you find that GL programs only work properly when run as root, and not
+as normal users, then the problem is that your \fI/dev/3dfx\fP file is not
+configured properly. Check the Linux 3Dfx FAQ.
+.TP 8
+.B Keyboard LEDs
+If \fIprocInterrupts\fP is on (which is the default on Linux systems) and
+you're using some program that toggles the state of your keyboard LEDs,
+xscreensaver won't work right: turning those LEDs on or off causes a
+keyboard interrupt, which xscreensaver will interpret as user activity.
+So if you're using such a program, set the \fIprocInterrupts\fP resource
+to False.
.TP 8
.B Extensions
If you are not making use of one of the server extensions (\fBXIDLE\fP,
.BR xv (1),
.BR xwave (1).
.SH COPYRIGHT
-Copyright \(co 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998
+Copyright \(co 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999
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
projects / xscreensaver / blobdiff