X-Git-Url: http://git.hungrycats.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=driver%2Fxscreensaver.man;h=82cd7adfcedbb49207531c71a9ffdc3126fa611c;hb=1d7308dd9032b39a92fda86e8c2db04218b45fbf;hp=ac47595ade0da16c65a8280e22c64caf7d05b28f;hpb=2d04c4f22466851aedb6ed0f2919d148f726b889;p=xscreensaver diff --git a/driver/xscreensaver.man b/driver/xscreensaver.man index ac47595a..82cd7adf 100644 --- a/driver/xscreensaver.man +++ b/driver/xscreensaver.man @@ -11,15 +11,16 @@ .if n .sp 1 .if t .sp .5 .. -.TH XScreenSaver 1 "23-Feb-2005 (4.20)" "X Version 11" +.TH XScreenSaver 1 "20-Mar-2005 (4.21)" "X Version 11" .SH NAME xscreensaver - extensible screen saver framework, plus locking .SH SYNOPSIS .B xscreensaver [\-display \fIhost:display.screen\fP] \ [\-verbose] \ +[\-no\-splash] \ [\-no\-capture\-stderr] \ -[\-no\-splash] +[\-log \fIfilename\fP] .SH DESCRIPTION The \fIxscreensaver\fP program waits until the keyboard and mouse have been idle for a period, and then runs a graphics demo chosen at random. It @@ -42,11 +43,9 @@ The program pops up a dialog box that lets you configure the screen saver, and experiment with the various display modes. -.B Note: -unlike -.BR xlock (1), -xscreensaver has a client-server model: the \fIxscreensaver\fP program is a -daemon that runs in the background; it is controlled by the foreground +.B Note that xscreensaver has a client-server model: +the \fIxscreensaver\fP program is a daemon that runs in the background; +it is controlled by the foreground .BR xscreensaver-demo (1) and .BR xscreensaver-command (1) @@ -106,7 +105,348 @@ When settings are changed in the Preferences dialog box (see above) the current settings will be written to the \fI.xscreensaver\fP file. (The \fI.Xdefaults\fP file and the app-defaults file will never be written by xscreensaver itself.) +.SH COMMAND-LINE OPTIONS +.I xscreensaver +also accepts a few command-line options, mostly for use when debugging: +for normal operation, you should configure things via the \fI~/.xscreensaver\fP +file. +.TP 8 +.B \-display \fIhost:display.screen\fP +The X display to use. For displays with multiple screens, XScreenSaver +will manage all screens on the display simultaniously. +.TP 8 +.B \-verbose +Same as setting the \fIverbose\fP resource to \fItrue\fP: print diagnostics +on stderr and on the xscreensaver window. +.TP 8 +.B \-no-capture-stderr +Do not redirect the stdout and stderr streams to the xscreensaver window +itself. If xscreensaver is crashing, you might need to do this in order +to see the error message. +.TP 8 +.B \-log \fIfilename\fP +This is exactly the same as redirecting stdout and stderr to the given +file (for append). This is useful when reporting bugs. +.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. 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. +The various graphics demos are, in fact, just standalone programs that +know how to draw on the provided window. + +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. + +You can control a running screensaver process by using the +.BR xscreensaver\-command (1) +program (which see.) +.SH POWER MANAGEMENT +Modern X servers contain support to power down the monitor after an idle +period. If the monitor has powered down, then \fIxscreensaver\fP will +notice this (after a few minutes), and will not waste CPU by drawing +graphics demos on a black screen. An attempt will also be made to +explicitly power the monitor back up as soon as user activity is detected. + +The \fI~/.xscreensaver\fP file controls the configuration of your +display's power management settings: if you have used +.BR xset (1) +to change your power management settings, then xscreensaver will +override those changes with the values specified +in \fI~/.xscreensaver\fP (or with its built-in defaults, if there +is no \fI~/.xscreensaver\fP file yet.) + +To change your power management settings, run +.BR xscreensaver\-demo (1) +and change the various timeouts through the user interface. +Alternately, you can edit the \fI~/.xscreensaver\fP file directly. + +If the power management section is grayed out in the +.BR xscreensaver\-demo (1) +window, then that means that your X server does not support +the XDPMS extension, and so control over the monitor's power state +is not available. + +If you're using a laptop, don't be surprised if changing the DPMS +settings has no effect: many laptops have monitor power-saving behavior +built in at a very low level that is invisible to Unix and X. On such +systems, you can typically adjust the power-saving delays only by +changing settings in the BIOS in some hardware-specific way. + +If DPMS seems not to be working with XFree86, make sure the "DPMS" +option is set in your \fI/etc/X11/XF86Config\fP file. See the +.BR XF86Config (5) +manual for details. +.SH USING GNOME +For many years, GNOME shipped \fIxscreensaver\fP as-is, and +everything just worked out of the box. Recently, however, they've +been re-inventing the wheel again in the form of "gnome-screensaver". + +To replace gnome-screensaver with xscreensaver: +.RS 4 +.TP 3 +\fB1: Turn off gnome-screensaver.\fP +Open ``System / Preferences / Screensaver'' and uncheck both boxes. +.TP 3 +\fB2: Stop gnome-screensaver from launching at login.\fP +Run the command: +.EX +gconftool-2 --type boolean -s \\ +/apps/gnome_settings_daemon/screensaver/start_screensaver \\ +false +.EE +Or, just uninstall the "gnome-screensaver" package entirely. +.TP 3 +\fB3: Launch xscreensaver at login.\fP +Open ``System / Preferences / Sessions / Startup Programs''. +Click ``Add'' and type ``xscreensaver''. +.TP 3 +\fB4: Tell Preferences to use the xscreensaver configurator.\fP +Edit \fI/usr/share/applications/gnome-screensaver-preferences.desktop\fP +and change the \fIExec=\fP line to say + Exec=xscreensaver-demo +.TP 3 +\fB5: Make ``System / Quit / Lock Screen'' use xscreensaver.\fP +Run the command: +.EX +sudo ln -sf /usr/bin/xscreensaver-command \\ + /usr/bin/gnome-screensaver-command +.EE +.SH USING KDE +KDE also has invented their own screen saver framework instead of +simply using xscreensaver. To replace the KDE screen saver with +xscreensaver, do the following: +.RS 4 +.TP 3 +\fB1: Turn off KDE's screen saver.\fP +Open the ``\fIControl Center\fP'' and +select the ``\fIAppearance & Themes / Screensaver\fP'' page. +Un-check ``\fIStart Automatically\fP''. +.TP 3 +\fB2: Find your Autostart directory.\fP +Open the ``\fISystem Administration -> Paths\fP'' page, +and see what your ``Autostart path'' is set to: it will +probably be \fI~/.kde/Autostart/\fP or something similar. +.TP 3 +\fB3: Make xscreensaver be an Autostart program.\fP +Create a .desktop file in your autostart directory +called \fIxscreensaver.desktop\fP that contains the following five lines: +.EX +[Desktop Entry] +Exec=xscreensaver +Name=XScreenSaver +Type=Application +X-KDE-StartupNotify=false +.EE +.TP 3 +\fB4: Make the various "lock session" buttons call xscreensaver.\fP +Replace the file \fIkdesktop_lock\fP or \fIkrunner_lock\fP +or \fIkscreenlocker\fP +in \fI/usr/bin/\fP (or possibly in \fI/usr/kde/3.5/bin/\fP +or possibly in \fI/usr/lib/kde4/libexec/\fP +or \fI/usr/libexec/kde4/\fP, depending on the distro and +phase of the moon) with these two lines: +.EX +#!/bin/sh +xscreensaver-command -lock +.EE +Make sure the file is executable (chmod a+x). +.RE .PP +Now use xscreensaver normally, controlling it via the usual +.BR xscreensaver-demo (1) +and +.BR xscreensaver-command (1) +mechanisms. +.SH USING GDM +You can run \fIxscreensaver\fP from your +.BR gdm (1) +session, so that the screensaver will run even when nobody is logged +in on the console. To do this, run +.BR gdmconfig (1) +and on the \fIBackground\fP page, type the +command \fB"xscreensaver -nosplash"\fP into the \fIBackground Program\fP +field. That will cause gdm to run xscreensaver while nobody is logged +in, and kill it as soon as someone does log in. (The user will then +be responsible for starting xscreensaver on their own, if they want.) + +Another way to accomplish the same thing is to edit the +file \fI/etc/X11/gdm/gdm.conf\fP to include: +.EX +BackgroundProgram=xscreensaver -nosplash +RunBackgroundProgramAlways=true +.EE +In this situation, the \fIxscreensaver\fP process will probably be running +as user \fIgdm\fP instead of \fIroot\fP. You can configure the settings +for this nobody-logged-in state (timeouts, DPMS, etc.) by editing +the \fI~gdm/.xscreensaver\fP file. + +To get gdm to run the BackgroundProgram, you may need to switch it from +the "Graphical Greeter" to the "Standard Greeter". + +It is safe to run \fIxscreensaver\fP as root (as \fIxdm\fP is likely to do.) +If run as root, \fIxscreensaver\fP changes its effective user and group ids +to something safe (like \fI"nobody"\fP) before connecting to the X server +or launching user-specified programs. + +An unfortunate side effect of this (important) security precaution is that +it may conflict with cookie-based authentication. + +If you get "connection refused" errors when running \fIxscreensaver\fP +from \fIgdm\fP, then this probably means that you have +.BR xauth (1) +or some other security mechanism turned on. For information on the +X server's access control mechanisms, see the man pages for +.BR X (1), +.BR Xsecurity (1), +.BR xauth (1), +and +.BR xhost (1). +.SH BUGS +Bugs? There are no bugs. Ok, well, maybe. If you find one, please let +me know. http://www.jwz.org/xscreensaver/bugs.html explains how to +construct the most useful bug reports. +.TP 8 +.B Locking and XDM +If xscreensaver has been launched from +.BR xdm (1) +before anyone has logged in, you will need to kill and then restart the +xscreensaver daemon after you have logged in, or you will be confused by +the results. (For example, locking won't work, and your \fI~/.xscreensaver\fP +file will be ignored.) + +When you are logged in, you want the \fIxscreensaver\fP daemon to be +running under \fIyour\fP user id, not as root or some other user. + +If it has already been started by \fIxdm\fP, you can kill it by sending +it the \fBexit\fP command, and then re-launching it as you, by putting +something like the following in your personal X startup script: +.EX +xscreensaver-command -exit +xscreensaver & +.EE +The ``\fIUsing XDM(1)\fP'' section, above, goes into more detail, and explains +how to configure the system to do this for all users automatically. +.TP 8 +.B Locking and root logins +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 +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 +the difference between \fIroot\fP being logged in on the console, and a +normal user being logged in on the console but xscreensaver having been +launched by the +.BR xdm (1) +.I Xsetup +file.) + +The solution to this is simple: you shouldn't be logging in on the console +as \fIroot\fP in the first place! (What, are you crazy or something?) + +Proper Unix hygiene dictates that you should log in as yourself, and +.BR su (1) +to \fIroot\fP as necessary. People who spend their day logged in +as \fIroot\fP are just begging for disaster. +.TP 8 +.B XAUTH and XDM +For xscreensaver to work when launched by +.BR xdm (1), +programs running on the local machine as user \fI"nobody"\fP must be +able to connect to the X server. This means that if you want to run +xscreensaver on the console while nobody is logged in, you may need +to disable cookie-based access control (and allow all users who can log +in to the local machine to connect to the display.) + +You should be sure that this is an acceptable thing to do in your +environment before doing it. See the ``\fIUsing XDM(1)\fP'' section, +above, for more details. +.TP 8 +.B Passwords +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 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) +interface; in that case, you may need to change some options +with \fIconfigure\fP and recompile. + +If you change your password after xscreensaver has been launched, it will +continue using your old password to unlock the screen until xscreensaver +is restarted. On some systems, it may accept \fIboth\fP your old and new +passwords. So, after you change your password, you'll have to do +.EX +xscreensaver-command -restart +.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 Machine Load +Although this program ``nices'' the subprocesses that it starts, +graphics-intensive subprograms can still overload the machine by causing +the X server process itself (which is not ``niced'') to consume many +cycles. Care has been taken in all the modules shipped with xscreensaver +to sleep periodically, and not run full tilt, so as not to cause +appreciable load. + +However, if you are running the OpenGL-based screen savers on a machine +that does not have a video card with 3D acceleration, they \fIwill\fP +make your machine slow, despite +.BR nice (1). + +Your options are: don't use the OpenGL display modes; or, collect the +spare change hidden under the cushions of your couch, and use it to +buy a video card manufactured after 1998. (It doesn't even need to be +\fIfast\fP 3D hardware: the problem will be fixed if there is any +3D hardware \fIat all.\fP) +.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. To globally disable VT switching, +you can set the \fIDontVTSwitch\fP flag. See the +.BR XF86Config (5) +manual for details. +.SH X RESOURCES +These are the X resources use by the \fIxscreensaver\fP program. +You probably won't need to change these manually (that's what the +.BR xscreensaver\-demo (1) +program is for). .TP 8 .B timeout\fP (class \fBTime\fP) The screensaver will activate (blank the screen) after the keyboard and @@ -163,6 +503,11 @@ the X server and the display hardware support power management; not all do. See the \fIPower Management\fP section, below, for more information. .TP 8 +.B dpmsQuickOff\fP (class \fBBoolean\fP) +If \fImode\fP is \fIblank\fP and this is true, then the screen will be +powered down immediately upon blanking, regardless of other +power-management settings. +.TP 8 .B visualID\fP (class \fBVisualID\fP) Specify which X visual to use by default. (Note carefully that this resource is called \fBvisualID\fP, not merely \fBvisual\fP; if you set the \fBvisual\fP @@ -239,10 +584,6 @@ Whether to display a splash screen at startup. Default true. .B splashDuration\fP (class \fBTime\fP) How long the splash screen should remain visible; default 5 seconds. .TP 8 -.B quad\fP (class \fBBoolean\fP) -If true, then \fIfour\fP screensavers will be run on each monitor. -Use at your own risk! -.TP 8 .B helpURL\fP (class \fBURL\fP) The splash screen has a \fIHelp\fP button on it. When you press it, it will display the web page indicated here in your web browser. @@ -309,820 +650,211 @@ if an attempt is made to run the nonexistent program. Also, the program will suppress the non-existent programs from the list if this is true. Default: false. .TP 8 -.B font\fP (class \fBFont\fP) -The font used for the stdout/stderr text, if \fBcaptureStderr\fP is true. -Default \fB*\-medium\-r\-*\-140\-*\-m\-*\fP (a 14 point fixed-width font.) -.TP 8 -.B mode\fP (class \fBMode\fP) -Controls the behavior of xscreensaver. Legal values are: -.RS 8 -.TP 8 -.B random -When blanking the screen, select a random display mode from among those -that are enabled and applicable. This is the default. -.TP 8 -.B one -When blanking the screen, only ever use one particular display mode (the -one indicated by the \fIselected\fP setting.) -.TP 8 -.B blank -When blanking the screen, just go black: don't run any graphics hacks. -.TP 8 -.B off -Don't ever blank the screen, and don't ever allow the monitor to power down. - -.RE -.TP 8 -.B selected\fP (class \fBInteger\fP) -When \fImode\fP is set to \fIone\fP, this is the one, indicated by its -index in the \fIprograms\fP list. You're crazy if you count them and -set this number by hand: let -.BR xscreensaver\-demo (1) -do it for you! -.TP 8 -.B programs\fP (class \fBPrograms\fP) -The graphics hacks which \fIxscreensaver\fP runs when the user is idle. -The value of this resource is a multi-line string, one \fIsh\fP-syntax -command per line. Each line must contain exactly one command: no -semicolons, no ampersands. - -When the screensaver starts up, one of these is selected (according to -the \fBmode\fP setting), and run. After the \fIcycle\fP 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 -.BR xscreensaver\-demo (1) -program.) - -If all programs are disabled, then the screen will just be made blank, -as when \fImode\fP is set to \fIblank\fP. - -To disable a program, you must mark it as disabled with a dash instead -of removing it from the list. This is because the system-wide (app-defaults) -and per-user (.xscreensaver) settings are merged together, and if a user -just \fIdeletes\fP 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 \fIdisables\fP it, then their setting takes precedence. - -If the display has multiple screens, then a different program will be run -for each screen. (All screens are blanked and unblanked simultaniously.) - -Note that you must escape the newlines; here is an example of how you -might set this in your \fI~/.xscreensaver\fP file: - -.RS 8 -.EX -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 -Make sure your \fB$PATH\fP environment variable is set up correctly -\fIbefore\fP xscreensaver is launched, or it won't be able to find the -programs listed in the \fIprograms\fP resource. - -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 -.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\\ -.EE -.RE -.RS 8 -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: -.EX - PseudoColor: cmap-program -root \\n\\ - TrueColor: 24bit-program -root \\n\\ -.EE -.RE -.RS 8 -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: -.RS 1 -.TP 4 -.B default-n -This is like \fBdefault\fP, but also requests the use of the default colormap, -instead of a private colormap. (That is, it behaves as if -the \fI\-no\-install\fP command-line option was specified, but only for -this particular hack.) This is provided because some third-party programs -that draw on the root window (notably: -.BR xv (1), -and -.BR xearth (1)) -make assumptions about the visual and colormap of the root window: -assumptions which xscreensaver can violate. - -.RE -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. -.RE -.PP -.PP -You shouldn't ever need to change the following resources: -.PP -.TP 8 -.B pointerPollTime\fP (class \fBTime\fP) -When server extensions are not in use, this controls how -frequently \fIxscreensaver\fP checks to see if the mouse position or buttons -have changed. Default 5 seconds. -.TP 8 -.B windowCreationTimeout\fP (class \fBTime\fP) -When server extensions are not in use, this controls the delay between when -windows are created and when \fIxscreensaver\fP selects events on them. -Default 30 seconds. -.TP 8 -.B initialDelay\fP (class \fBTime\fP) -When server extensions are not in use, \fIxscreensaver\fP will wait this many -seconds before selecting events on existing windows, under the assumption that -\fIxscreensaver\fP is started during your login procedure, and the window -state may be in flux. Default 0. (This used to default to 30, but that was -back in the days when slow machines and X terminals were more common...) -.RE -.PP -There are a number of different X server extensions which can make -xscreensaver's job easier. The next few resources specify whether these -extensions should be utilized if they are available. -.TP 8 -.B sgiSaverExtension\fP (class \fBBoolean\fP) -This resource controls whether the SGI \fBSCREEN_SAVER\fP server extension -will be used to decide whether the user is idle. This is the default -if \fIxscreensaver\fP has been compiled with support for this -extension (which is the default on SGI systems.). If it is available, -the \fBSCREEN_SAVER\fP method is faster and more reliable than what will -be done otherwise, so use it if you can. (This extension is only available -on Silicon Graphics systems, unfortunately.) -.TP 8 -.B mitSaverExtension\fP (class \fBBoolean\fP) -This resource controls whether the \fBMIT\-SCREEN\-SAVER\fP server extension -will be used to decide whether the user is idle. However, the default for -this resource is \fIfalse\fP, because even if this extension is available, -it is flaky (and it also makes the \fBfade\fP option not work properly.) -Use of this extension is not recommended. -.TP 8 -.B xidleExtension\fP (class \fBBoolean\fP) -This resource controls whether the \fBXIDLE\fP server extension will be -used to decide whether the user is idle. This is the default -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. +.B GetViewPortIsFullOfLies\fP (class \fBBoolean\fP) +Set this to true if the xscreensaver window doesn't cover the whole screen. +This works around a longstanding XFree86 bug #421. See the +xscreensaver FAQ for details. .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 -the same layer as the running screenhack. Set this to False to disable -that (though you shouldn't need to.) +.B font\fP (class \fBFont\fP) +The font used for the stdout/stderr text, if \fBcaptureStderr\fP is true. +Default \fB*\-medium\-r\-*\-140\-*\-m\-*\fP (a 14 point fixed-width font.) .TP 8 -.B overlayTextForeground\fP (class \fBForeground\fP) -The foreground color used for the stdout/stderr text, if \fBcaptureStderr\fP -is true. Default: Yellow. +.B mode\fP (class \fBMode\fP) +Controls the behavior of xscreensaver. Legal values are: +.RS 8 .TP 8 -.B overlayTextBackground\fP (class \fBBackground\fP) -The background color used for the stdout/stderr text, if \fBcaptureStderr\fP -is true. Default: Black. +.B random +When blanking the screen, select a random display mode from among those +that are enabled and applicable. This is the default. .TP 8 -.B bourneShell\fP (class \fBBourneShell\fP) -The pathname of the shell that \fIxscreensaver\fP uses to start subprocesses. -This must be whatever your local variant of \fB/bin/sh\fP is: in particular, -it must not be \fBcsh\fP. -.SH COMMAND-LINE OPTIONS -.I xscreensaver -also accepts a few command-line options, mostly for use when debugging: -for normal operation, you should configure things via the \fI~/.xscreensaver\fP -file. +.B random-same +Like \fIrandom\fP, but if there are multiple screens, each screen +will run the \fIsame\fP random display mode, instead of each screen +running a different one. .TP 8 -.B \-display \fIhost:display.screen\fP -The X display to use. For displays with multiple screens, XScreenSaver -will manage all screens on the display simultaniously. +.B one +When blanking the screen, only ever use one particular display mode (the +one indicated by the \fIselected\fP setting.) .TP 8 -.B \-verbose -Same as setting the \fIverbose\fP resource to \fItrue\fP: print diagnostics -on stderr and on the xscreensaver window. +.B blank +When blanking the screen, just go black: don't run any graphics hacks. .TP 8 -.B \-no-capture-stderr -Same as setting the \fIcaptureStderr\fP resource to \fIfalse\fP: do not -redirect the stdout and stderr streams to the xscreensaver window itself. -If xscreensaver is crashing, you might need to do this in order to see -the error message. -.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. 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 -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. - -Before launching a subprocess, \fIxscreensaver\fP stores an appropriate value -for \fB$DISPLAY\fP in the environment that the child will receive. (This is -so that if you start \fIxscreensaver\fP with a \fI-display\fP argument, the -programs which \fIxscreensaver\fP launches will draw on the same display; -and so that the child will end up drawing on the appropriate screen of a -multi-headed display.) - -When the screensaver turns off, or is killed, care is taken to restore -the ``real'' virtual root window if there is one. Because of this, it is -important that you not kill the screensaver process with \fIkill -9\fP if -you are running a virtual-root window manager. If you kill it with \-9, -you may need to restart your window manager to repair the damage. This -isn't an issue if you aren't running a virtual-root window manager. - -For all the gory details, see the commentary at the top of xscreensaver.c. - -You can control a running screensaver process by using the -.BR xscreensaver\-command (1) -program (which see.) -.SH POWER MANAGEMENT -Modern X servers contain support to power down the monitor after an idle -period. If the monitor has powered down, then \fIxscreensaver\fP will -notice this (after a few minutes), and will not waste CPU by drawing -graphics demos on a black screen. An attempt will also be made to -explicitly power the monitor back up as soon as user activity is detected. - -As of version 3.28 (Feb 2001), the \fI~/.xscreensaver\fP file controls the -configuration of your display's power management settings: if you have -used -.BR xset (1) -to change your power management settings, then xscreensaver will -override those changes with the values specified -in \fI~/.xscreensaver\fP (or with its built-in defaults, if there -is no \fI~/.xscreensaver\fP file yet.) - -To change your power management settings, run -.BR xscreensaver\-demo (1) -and change the various timeouts through the user interface. -Alternately, you can edit the \fI~/.xscreensaver\fP file directly. - -If the power management section is grayed out in the -.BR xscreensaver\-demo (1) -window, then that means that your X server does not support -the XDPMS extension, and so control over the monitor's power state -is not available. - -If you're using a laptop, don't be surprised if changing the DPMS -settings has no effect: many laptops have monitor power-saving behavior -built in at a very low level that is invisible to Unix and X. On such -systems, you can typically adjust the power-saving delays only by -changing settings in the BIOS in some hardware-specific way. - -If DPMS seems not to be working with XFree86, make sure the "DPMS" -option is set in your \fI/etc/X11/XF86Config\fP file. See the -.BR XF86Config (5) -manual for details. -.SH USING XDM(1) -You can run \fIxscreensaver\fP from your -.BR xdm (1) -session, so that the screensaver will run even when nobody is logged -in on the console. - -The trick to using xscreensaver with \fIxdm\fP is this: keep in mind the -two very different states in which xscreensaver will be running: -.RS 4 -.TP 3 -.B 1: Nobody logged in. - -If you're thinking of running xscreensaver from XDM at all, then it's -probably because you want graphics demos to be running on the console -when nobody is logged in there. In this case, xscreensaver will function -only as a screen saver, not a screen locker: it doesn't make sense -for xscreensaver to lock the screen, since nobody is logged in yet! -The only thing on the screen is the XDM login prompt. -.TP 3 -.B 2: Somebody logged in. - -Once someone has logged in through the XDM login window, the situation is -very different. For example: now it makes sense to lock the screen (and -prompt for the logged in user's password); and now xscreensaver should -consult that user's \fI~/.xscreensaver\fP file; and so on. -.RE - -The difference between these two states comes down to a question of, -which user is the \fIxscreensaver\fP process running as? For the first -state, it doesn't matter. If you start \fIxscreensaver\fP in the usual -XDM way, then xscreensaver will probably end up running as root, which -is fine for the first case (the ``nobody logged in'' case.) - -However, once someone is logged in, running as root is no longer fine: -because xscreensaver will be consulting root's \fI.xscreensaver\fP file -instead of that of the logged in user, and won't be prompting for the -logged in user's password, and so on. (This is not a security problem, -it's just not what you want.) - -So, once someone has logged in, you want xscreensaver to be running as that -user. The way to accomplish this is to kill the old xscreensaver process -and start a new one (as the new user.) - -The simplest way to accomplish all of this is as follows: -.RS 4 -.TP 3 -.B 1: Launch xscreensaver before anyone logs in. - -To the file \fI/usr/lib/X11/xdm/Xsetup\fP, add the lines -.EX -xhost +localhost -xscreensaver-command -exit -xscreensaver & -.EE -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. -.TP 3 -.B 2: Restart xscreensaver when someone logs in. - -Near the top of the file \fI/usr/lib/X11/xdm/Xsession\fP, add those same lines: -.EX -xscreensaver-command -exit -xscreensaver & -.EE -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. - -Alternately, each user could just put those lines in their -personal \fI~/.xsession\fP files. -.RE - -Make sure you have \fB$PATH\fP set up correctly in the \fIXsetup\fP -and \fIXsession\fP scripts, or \fIxdm\fP won't be able to -find \fIxscreensaver\fP, and/or \fIxscreensaver\fP won't be able to -find its graphics demos. - -(If your system does not seem to be executing the \fIXsetup\fP file, you -may need to configure it to do so: the traditional way to do this is -to make that file the value of the \fIDisplayManager*setup\fP resource -in the \fI/usr/lib/X11/xdm/xdm-config\fP file. See the man page for -.BR xdm (1) -for more details.) - -It is safe to run \fIxscreensaver\fP as root (as \fIxdm\fP is likely to do.) -If run as root, \fIxscreensaver\fP changes its effective user and group ids -to something safe (like \fI"nobody"\fP) before connecting to the X server -or launching user-specified programs. - -An unfortunate side effect of this (important) security precaution is that -it may conflict with cookie-based authentication. - -If you get "connection refused" errors when running \fIxscreensaver\fP -from \fIxdm\fP, then this probably means that you have -.BR xauth (1) -or some other security mechanism turned on. One way around this is to -add \fB"xhost\ +localhost"\fP to \fIXsetup\fP, just before \fIxscreensaver\fP -is launched. - -Note that this will give access to the X server to anyone capable of logging -in to the local machine, so in some environments, this might not be -appropriate. If turning off file-system-based access control is not -acceptable, then running \fIxscreensaver\fP from the \fIXsetup\fP file -might not be possible, and xscreensaver will only work when running as -a normal, unprivileged user. - -For more information on the X server's access control mechanisms, see the -man pages for -.BR X (1), -.BR Xsecurity (1), -.BR xauth (1), -and -.BR xhost (1). -.SH USING GDM(1) -Using xscreensaver with -.BR gdm (1) -is easy, because gdm has a configuration tool. Just fire up -.BR gdmconfig (1) -and on the \fIBackground\fP page, type \fB"xscreensaver -nosplash"\fP into -the \fIBackground Program\fP field. That will cause gdm to run xscreensaver -while nobody is logged in, and kill it as soon as someone does log in. -(The user will then be responsible for starting xscreensaver on their -own, if they want.) - -Another way to accomplish the same thing is to edit the -file \fI/etc/X11/gdm/gdm.conf\fP to include: -.EX -BackgroundProgram=xscreensaver -nosplash -RunBackgroundProgramAlways=true -.EE -In this situation, the \fIxscreensaver\fP process will probably be running -as user \fIgdm\fP instead of \fIroot\fP. You can configure the settings -for this nobody-logged-in state (timeouts, DPMS, etc.) by editing -the \fI~gdm/.xscreensaver\fP file. - -To get gdm to run the BackgroundProgram, you may need to switch it from -the "Graphical Greeter" to the "Standard Greeter". -.SH USING KDE (K DESKTOP ENVIRONMENT) -I understand that KDE has invented their own wrapper around xscreensaver, -that is inferior to -.BR xscreensaver-demo (1) -in any number of ways. I've never actually seen it, but I'm told that -this is the way you disable it: -.RS 4 -.TP 3 -\fB1: Switch off KDE's screen saver.\fP -Open the ``\fIControl Center\fP'' and -select the ``\fILook and Feel / Screensaver\fP'' page. -Turn off the ``\fIEnable Screensaver\fP'' checkbox. -.TP 3 -\fB2: Find your Autostart directory.\fP -Open the ``\fILook and Feel / Desktop / Paths\fP'' page, -and see what your ``Autostart'' directory is set to: it will -probably be \fI~/.kde3/Autostart/\fP or something similar. -.TP 3 -\fB3: Make xscreensaver be an Autostart program.\fP -Create a file in your autostart directory -called \fIxscreensaver.desktop\fP that contains the following five lines: -.EX -[Desktop Entry] -Exec=xscreensaver -Name=XScreensaver -Type=Application -X-KDE-StartupNotify=false -.EE -.RE -.PP -Now use xscreensaver normally, controlling it via the usual -.BR xscreensaver-demo (1) -and -.BR xscreensaver-command (1) -mechanisms. -.SH USING CDE (COMMON DESKTOP ENVIRONMENT) -The easiest way to use \fIxscreensaver\fP on a system with CDE is to simply -switch off the built-in CDE screensaver, and use \fIxscreensaver\fP instead; -and second, to tell the front panel to run -.BR xscreensaver\-command (1) -with the \fI\-lock\fP option when the \fILock\fP icon is clicked. +.B off +Don't ever blank the screen, and don't ever allow the monitor to power down. -To accomplish this involves five steps: -.RS 4 -.TP 3 -\fB1: Switch off CDE's locker\fP -Do this by turning off ``\fIScreen Saver and Screen Lock\fP'' in the -Screen section of the Style Manager. -.TP 3 -\fB2: Edit sessionetc\fP -Edit the file \fI~/.dt/sessions/sessionetc\fP and add to it the line -.EX -xscreensaver & -.EE -And make sure the sessionetc file is executable. -This will cause \fIxscreensaver\fP to be launched when you log in. -(As always, make sure that xscreensaver and the graphics demos are on -your \fB$PATH\fP; the path needs to be set in \fI.cshrc\fP -and/or \fI.dtprofile\fP, not \fI.login\fP.) -.TP 3 -\fB3: Create XScreenSaver.dt\fP -Create a file called \fI~/.dt/types/XScreenSaver.dt\fP with the following -contents: -.EX -ACTION XScreenSaver -{ - LABEL XScreenSaver - TYPE COMMAND - EXEC_STRING xscreensaver-command -lock - ICON Dtkey - WINDOW_TYPE NO_STDIO -} -.EE -This defines a ``lock'' command for the CDE front panel, that knows how -to talk to \fIxscreensaver\fP. -.TP 3 -\fB4: Create Lock.fp\fP -Create a file called \fI~/.dt/types/Lock.fp\fP with the following -contents: -.EX -CONTROL Lock -{ - TYPE icon - CONTAINER_NAME Switch - CONTAINER_TYPE SWITCH - POSITION_HINTS 1 - ICON Fplock - LABEL Lock - PUSH_ACTION XScreenSaver - HELP_TOPIC FPOnItemLock - HELP_VOLUME FPanel -} -.EE -This associates the CDE front panel ``Lock'' icon with the lock command -we just defined in step 3. -.TP 3 -\fB5: Restart\fP -Select ``\fIRestart Workspace Manager\fP'' from the popup menu to make -your changes take effect. If things seem not to be working, check the -file \fI~/.dt/errorlog\fP for error messages. -.RE -.SH USING HP VUE (VISUAL USER ENVIRONMENT) -Since CDE is a descendant of VUE, the instructions for using xscreensaver -under VUE are similar to the above: -.RS 4 -.TP 3 -\fB1: Switch off VUE's locker\fP -Open the ``\fIStyle Manager\fP'' and select ``\fIScreen\fP.'' -Turn off ``\fIScreen Saver and Screen Lock\fP'' option. -.TP 3 -\fB2: Make sure you have a Session\fP -Next, go to the Style Manager's, ``\fIStartup\fP'' page. -Click on ``\fISet Home Session\fP'' to create a session, then -on ``\fIReturn to Home Session\fP'' to select this session each -time you log in. -.TP 3 -\fB3: Edit vue.session\fP -Edit the file \fI~/.vue/sessions/home/vue.session\fP and add to it -the line -.EX -vuesmcmd -screen 0 -cmd "xscreensaver" -.EE -This will cause \fIxscreensaver\fP to be launched when you log in. -(As always, make sure that xscreensaver and the graphics demos are on -your \fB$PATH\fP; the path needs to be set in \fI.cshrc\fP -and/or \fI.profile\fP, not \fI.login\fP.) -.TP 3 -\fB3: Edit vuewmrc\fP -Edit the file \fI~/.vue/vuewmrc\fP and add (or change) the Lock control: -.EX -CONTROL Lock -{ - TYPE button - IMAGE lock - PUSH_ACTION f.exec "xscreensaver-command -lock" - HELP_TOPIC FPLock -} -.EE -This associates the VUE front panel ``Lock'' icon with the xscreensaver -lock command. .RE -.PP -.SH BUGS -Bugs? There are no bugs. Ok, well, maybe. If you find one, please let -me know. http://www.jwz.org/xscreensaver/bugs.html explains how to -construct the most useful bug reports. .TP 8 -.B Locking and XDM -If xscreensaver has been launched from -.BR xdm (1) -before anyone has logged in, you will need to kill and then restart the -xscreensaver daemon after you have logged in, or you will be confused by -the results. (For example, locking won't work, and your \fI~/.xscreensaver\fP -file will be ignored.) - -When you are logged in, you want the \fIxscreensaver\fP daemon to be -running under \fIyour\fP user id, not as root or some other user. - -If it has already been started by \fIxdm\fP, you can kill it by sending -it the \fBexit\fP command, and then re-launching it as you, by putting -something like the following in your personal X startup script: -.EX -xscreensaver-command -exit -xscreensaver & -.EE -The ``\fIUsing XDM(1)\fP'' section, above, goes into more detail, and explains -how to configure the system to do this for all users automatically. +.B selected\fP (class \fBInteger\fP) +When \fImode\fP is set to \fIone\fP, this is the one, indicated by its +index in the \fIprograms\fP list. You're crazy if you count them and +set this number by hand: let +.BR xscreensaver\-demo (1) +do it for you! .TP 8 -.B Locking and root logins -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 -itself to a safe user id (such as \fInobody\fP.) +.B programs\fP (class \fBPrograms\fP) +The graphics hacks which \fIxscreensaver\fP runs when the user is idle. +The value of this resource is a multi-line string, one \fIsh\fP-syntax +command per line. Each line must contain exactly one command: no +semicolons, no ampersands. -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 -the difference between \fIroot\fP being logged in on the console, and a -normal user being logged in on the console but xscreensaver having been -launched by the -.BR xdm (1) -.I Xsetup -file.) +When the screensaver starts up, one of these is selected (according to +the \fBmode\fP setting), and run. After the \fIcycle\fP period +expires, it is killed, and another is selected and run. -The solution to this is simple: you shouldn't be logging in on the console -as \fIroot\fP in the first place! (What, are you crazy or something?) +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 +.BR xscreensaver\-demo (1) +program.) -Proper Unix hygiene dictates that you should log in as yourself, and -.BR su (1) -to \fIroot\fP as necessary. People who spend their day logged in -as \fIroot\fP are just begging for disaster. -.TP 8 -.B XAUTH and XDM -For xscreensaver to work when launched by -.BR xdm (1), -programs running on the local machine as user \fI"nobody"\fP must be -able to connect to the X server. This means that if you want to run -xscreensaver on the console while nobody is logged in, you may need -to disable cookie-based access control (and allow all users who can log -in to the local machine to connect to the display.) +If all programs are disabled, then the screen will just be made blank, +as when \fImode\fP is set to \fIblank\fP. -You should be sure that this is an acceptable thing to do in your -environment before doing it. See the ``\fIUsing XDM(1)\fP'' section, -above, for more details. -.TP 8 -.B Passwords -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 in order for -locking to work. Care has been taken to make this a safe thing to do. +To disable a program, you must mark it as disabled with a dash instead +of removing it from the list. This is because the system-wide (app-defaults) +and per-user (.xscreensaver) settings are merged together, and if a user +just \fIdeletes\fP 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 \fIdisables\fP it, then their setting takes precedence. -It also may mean that your system uses shadow passwords instead of the standard -.BR getpwent (3) -interface; in that case, you may need to change some options -with \fIconfigure\fP and recompile. +If the display has multiple screens, then a different program will be run +for each screen. (All screens are blanked and unblanked simultaneously.) -If you change your password after xscreensaver has been launched, it will -continue using your old password to unlock the screen until xscreensaver -is restarted. On some systems, it may accept \fIboth\fP your old and new -passwords. So, after you change your password, you'll have to do +Note that you must escape the newlines; here is an example of how you +might set this in your \fI~/.xscreensaver\fP file: + +.RS 8 .EX -xscreensaver-command -restart +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 -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) -window manager and its descendants, on 8-bit screens. +.RE +.RS 8 +Make sure your \fB$PATH\fP environment variable is set up correctly +\fIbefore\fP xscreensaver is launched, or it won't be able to find the +programs listed in the \fIprograms\fP resource. -There is a race condition between the screensaver and this window manager, -which can result in the screensaver's colormap not getting installed -properly, meaning the graphics hacks will appear in essentially random -colors. (If the screen goes white instead of black, this is probably why.) +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 +.BR tvtwm (1). +(Generally, this is accomplished by just including the \fI"vroot.h"\fP +header file in the program's source.) -The -.BR mwm (1) -and -.BR olwm (1) -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. +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\\ +.EE +.RE +.RS 8 +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: +.EX + PseudoColor: cmap-program -root \\n\\ + TrueColor: 24bit-program -root \\n\\ +.EE +.RE .RS 8 +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: +.RS 1 .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. +.B default-n +This is like \fBdefault\fP, but also requests the use of the default colormap, +instead of a private colormap. (That is, it behaves as if +the \fI\-no\-install\fP command-line option was specified, but only for +this particular hack.) This is provided because some third-party programs +that draw on the root window (notably: +.BR xv (1), +and +.BR xearth (1)) +make assumptions about the visual and colormap of the root window: +assumptions which xscreensaver can violate. + +.RE +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. .RE +.PP +.PP +You shouldn't ever need to change the following resources: +.PP .TP 8 -.B Colormap lossage: XV, XAnim, XEarth -Some programs don't operate properly on visuals other than the default one, -or with colormaps other than the default one. See the discussion of the -magic "default-n" visual name in the description of the \fBprograms\fP -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\\ -.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 -advantage of them. +.B pointerPollTime\fP (class \fBTime\fP) +When server extensions are not in use, this controls how +frequently \fIxscreensaver\fP checks to see if the mouse position or buttons +have changed. Default 5 seconds. .TP 8 -.B Machine Load -Although this program ``nices'' the subprocesses that it starts, -graphics-intensive subprograms can still overload the machine by causing -the X server process itself (which is not ``niced'') to consume many -cycles. Care has been taken in all the modules shipped with xscreensaver -to sleep periodically, and not run full tilt, so as not to cause -appreciable load. - -However, if you are running the OpenGL-based screen savers on a machine -that does not have a video card with 3D acceleration, they \fIwill\fP -make your machine slow, despite -.BR nice (1). - -Your options are: don't use the OpenGL display modes; or, collect the -spare change hidden under the cushions of your couch, and use it to -buy a video card manufactured after 1998. (It doesn't even need to be -\fIfast\fP 3D hardware: the problem will be fixed if there is any -3D hardware \fIat all.\fP) +.B pointerHysteresis\fP (class \fBInteger\fP) +If the mouse moves less than this-many pixels in a second, ignore it +(do not consider that to be "activity.") This is so that the screen +doesn't un-blank (or fail to blank) just because you bumped the desk. +Default: 10 pixels. .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. To globally disable VT switching, -you can set the \fIDontVTSwitch\fP flag. See the -.BR XF86Config (5) -manual for details. +.B windowCreationTimeout\fP (class \fBTime\fP) +When server extensions are not in use, this controls the delay between when +windows are created and when \fIxscreensaver\fP selects events on them. +Default 30 seconds. +.TP 8 +.B initialDelay\fP (class \fBTime\fP) +When server extensions are not in use, \fIxscreensaver\fP will wait this many +seconds before selecting events on existing windows, under the assumption that +\fIxscreensaver\fP is started during your login procedure, and the window +state may be in flux. Default 0. (This used to default to 30, but that was +back in the days when slow machines and X terminals were more common...) .TP 8 -.B MIT Extension and Fading -The \fBMIT-SCREEN-SAVER\fP extension is junk. Don't use it. +.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.) -When using the \fBMIT-SCREEN-SAVER\fP extension in conjunction with -the \fBfade\fP option, you'll notice an unattractive flicker just before -the fade begins. This is because the server maps a black window just before -it tells the \fIxscreensaver\fP process to activate. The \fIxscreensaver\fP -process immediately unmaps that window, but this results in a flicker. I -haven't figured a way to get around this; it seems to be a fundamental -property of the (mis-) design of this server extension. +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. -It sure would be nice if someone would implement the \fBSGI SCREEN_SAVER\fP -extension in XFree86; it's dead simple, and works far better than the -overengineered and broken \fBMIT-SCREEN-SAVER\fP extension. -.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, -\fBSGI SCREEN_SAVER\fP, or \fBMIT-SCREEN-SAVER\fP), then it is possible, in -rare situations, for \fIxscreensaver\fP to interfere with event propagation -and make another X program malfunction. For this to occur, that other -application would need to \fInot\fP select \fBKeyPress\fP events on its -non-leaf windows within the first 30 seconds of their existence, but then -select for them later. In this case, that client \fImight\fP fail to receive -those events. This isn't very likely, since programs generally select a -constant set of events immediately after creating their windows and then -don't change them, but this is the reason that it's a good idea to install -and use one of the server extensions instead, to work around this shortcoming -in the X protocol. +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.) -In all these years, I've not heard of even a single case of this happening, -but it is theoretically possible, so I'm mentioning it for completeness... +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 +the same layer as the running screenhack. Set this to False to disable +that (though you shouldn't need to.) +.TP 8 +.B overlayTextForeground\fP (class \fBForeground\fP) +The foreground color used for the stdout/stderr text, if \fBcaptureStderr\fP +is true. Default: Yellow. +.TP 8 +.B overlayTextBackground\fP (class \fBBackground\fP) +The background color used for the stdout/stderr text, if \fBcaptureStderr\fP +is true. Default: Black. +.TP 8 +.B bourneShell\fP (class \fBBourneShell\fP) +The pathname of the shell that \fIxscreensaver\fP uses to start subprocesses. +This must be whatever your local variant of \fB/bin/sh\fP is: in particular, +it must not be \fBcsh\fP. .SH ENVIRONMENT .PP .TP 8 @@ -1130,6 +862,11 @@ but it is theoretically possible, so I'm mentioning it for completeness... to get the default host and display number, and to inform the sub-programs of the screen on which to draw. .TP 8 +.B XSCREENSAVER_WINDOW +Passed to sub-programs to indicate the ID of the window on which they +should draw on. This is necessary on Xinerama/RANDR systems where +multiple physical monitors share a single X11 "Screen". +.TP 8 .B PATH to find the sub-programs to run. .TP 8 @@ -1146,207 +883,29 @@ and a FAQ can always be found at http://www.jwz.org/xscreensaver/ .BR X (1), .BR Xsecurity (1), .BR xauth (1), +.BR xdm (1), +.BR gdm (1), +.BR xhost (1), .BR xscreensaver\-demo (1), .BR xscreensaver\-command (1), .BR xscreensaver\-gl\-helper (1), .BR xscreensaver\-getimage (1), -.BR xdm (1), -.BR gdm (1), -.BR xset (1), -.BR xhost (1). -.BR anemone (1), -.BR ant (1), -.BR apollonian (1), -.BR atlantis (1), -.BR attraction (1), -.BR barcode (1), -.BR blaster (1), -.BR blitspin (1), -.BR bouboule (1), -.BR boxed (1), -.BR braid (1), -.BR bsod (1), -.BR bubble3d (1), -.BR bubbles (1), -.BR bumps (1), -.BR cage (1), -.BR ccurve (1), -.BR circuit (1), -.BR compass (1), -.BR coral (1), -.BR cosmos (1), -.BR critical (1), -.BR crystal (1), -.BR cubenetic (1), -.BR cynosure (1), -.BR dangerball (1), -.BR decayscreen (1), -.BR deco (1), -.BR deluxe (1), -.BR demon (1), -.BR discrete (1), -.BR distort (1), -.BR drift (1), -.BR electricsheep (1), -.BR endgame (1), -.BR engine (1), -.BR epicycle (1), -.BR eruption (1),* -.BR euler2d (1), -.BR extrusion (1), -.BR fadeplot (1), -.BR flag (1), -.BR flame (1), -.BR flipscreen3d (1), -.BR flow (1), -.BR fluidballs (1), -.BR flurry (1), -.BR forest (1), -.BR galaxy (1), -.BR gears (1), -.BR gflux (1), -.BR glblur (1), -.BR glforestfire (1), -.BR glplanet (1), -.BR glsnake (1), -.BR gltext (1), -.BR goban (1), -.BR goop (1), -.BR grav (1), -.BR greynetic (1), -.BR halftone (1), -.BR halo (1), -.BR helix (1), -.BR hopalong (1), -.BR hyperball (1), -.BR hypercube (1), -.BR ifs (1), -.BR imsmap (1), -.BR interference (1), -.BR jigsaw (1), -.BR juggle (1), -.BR julia (1), -.BR kaleidescope (1), -.BR kumppa (1), -.BR lament (1), -.BR laser (1), -.BR lavalite (1), -.BR lightning (1), -.BR lisa (1), -.BR lissie (1), -.BR lmorph (1), -.BR loop (1), -.BR maze (1), -.BR menger (1), -.BR metaballs (1), -.BR moebius (1), -.BR moire (1), -.BR moire2 (1), -.BR molecule (1), -.BR morph3d (1), -.BR mountain (1), -.BR munch (1), -.BR nerverot (1), -.BR noseguy (1), -.BR pedal (1), -.BR penetrate (1), -.BR penrose (1), -.BR petri (1), -.BR phosphor (1), -.BR pipes (1), -.BR polyominoes (1), -.BR popsquares (1), -.BR pulsar (1), -.BR pyro (1), -.BR qix (1), -.BR queens (1), -.BR rd-bomb (1), -.BR ripples (1), -.BR rocks (1), -.BR rorschach (1), -.BR rotor (1), -.BR rotzoomer (1), -.BR rubik (1), -.BR sballs (1), -.BR shadebobs (1), -.BR sierpinski (1), -.BR sierpinski3d (1), -.BR slidescreen (1), -.BR slip (1), -.BR sonar (1), -.BR speedmine (1), -.BR sphere (1), -.BR sphereEversion (1), -.BR spheremonics (1), -.BR spiral (1), -.BR spotlight (1), -.BR sproingies (1), -.BR squiral (1), -.BR ssystem (1), -.BR stairs (1), -.BR starfish (1), -.BR starwars (1), -.BR stonerview (1), -.BR strange (1), -.BR superquadrics (1), -.BR swirl (1), -.BR t3d (1), -.BR thornbird (1), -.BR triangle (1), -.BR truchet (1), -.BR twang (1), -.BR vermiculate (1), -.BR vidwhacker (1), -.BR vines (1), -.BR wander (1), -.BR webcollage (1), -.BR whirlwindwarp (1), -.BR whirlygig (1), -.BR worm (1), -.BR xaos (1), -.BR xdaliclock (1), -.BR xearth (1), -.BR xfishtank (1), -.BR xflame (1), -.BR xjack (1), -.BR xlyap (1), -.BR xmatrix (1), -.BR xmountains (1), -.BR xrayswarm (1), -.BR xsnow (1), -.BR xspirograph (1), -.BR xteevee (1), -.BR zoom (1) +.BR xscreensaver\-text (1). .SH COPYRIGHT -Copyright \(co 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, -2000, 2001, 2002, 2003, 2004, 2005 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 notice 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. +Copyright \(co 1991-2011 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 notice 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. .SH AUTHOR Jamie Zawinski . Written in late 1991; version 1.0 posted to comp.sources.x on 17-Aug-1992. Please let me know if you find any bugs or make any improvements. -.SH ACKNOWLEDGEMENTS -Thanks to Angela Goodman for the XScreenSaver logo. - -Thanks to the many people who have contributed graphics demos to the package. - -Thanks to David Wojtowicz for implementing \fIlockTimeout\fP. - -Thanks to Martin Kraemer for adding support for shadow passwords and -locking-disabled diagnostics. - -Thanks to Patrick Moreau for the VMS port. - -Thanks to Nat Lanza for the Kerberos support. - -Thanks to Bill Nottingham for the initial PAM support. -And thanks to Jon A. Christopher for implementing the Athena dialog -support, back in the days before Lesstif or Gtk were viable alternatives -to Motif. +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 +two decades!