.if n .sp 1
.if t .sp .5
..
-.TH XScreenSaver 1 "20-Mar-2005 (4.21)" "X Version 11"
+.TH XScreenSaver 1 "09-Nov-2013 (5.23)" "X Version 11"
.SH NAME
-xscreensaver - extensible screen saver framework, plus locking
+xscreensaver - extensible screen saver and screen locking framework
.SH SYNOPSIS
.B xscreensaver
[\-display \fIhost:display.screen\fP] \
in the resource database.
The syntax of the \fI.xscreensaver\fP file is similar to that of
-the \fI.Xdefaults\fP file; for example, to set the \fItimeout\fP paramter
+the \fI.Xdefaults\fP file; for example, to set the \fItimeout\fP parameter
in the \fI.xscreensaver\fP file, you would write the following:
.EX
timeout: 5
.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
+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.
.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".
+For the better part of a decade, GNOME shipped xscreensaver as-is,
+and everything just worked out of the box. In 2005, however, they
+decided to re-invent the wheel and ship their own replacement for
+the \fIxscreensaver\fP daemon called "\fIgnome-screensaver\fP",
+rather than improving xscreensaver and contributing their changes
+back. As a result, the "\fIgnome-screensaver\fP" program is insecure,
+bug-ridden, and missing many features of xscreensaver. You shouldn't
+use it.
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:
+\fB1: Fully uninstall the gnome-screensaver package.\fP
.EX
-gconftool-2 --type boolean -s \\
-/apps/gnome_settings_daemon/screensaver/start_screensaver \\
-false
+sudo apt-get remove gnome-screensaver
.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
+\fB2: Launch xscreensaver at login.\fP
+Open "\fIStartup Applications\fP" and add "\fIxscreensaver\fP".
.TP 3
-\fB5: Make ``System / Quit / Lock Screen'' use xscreensaver.\fP
-Run the command:
+\fB3: Make "Lock Screen" use xscreensaver.\fP
.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:
+Like GNOME, KDE also decided to invent their own screen saver framework
+from scratch 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''.
+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
+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
+Name=XScreenSaver
Type=Application
X-KDE-StartupNotify=false
.EE
.TP 3
\fB4: Make the various "lock session" buttons call xscreensaver.\fP
-Replace the file \fI/usr/bin/kdesktop_lock\fP (or
-possibly \fI/usr/kde/3.5/bin/kdesktop_lock\fP)
-with these two lines:
+The file you want to replace next has moved around over the years. It
+might be called \fI/usr/libexec/kde4/kscreenlocker\fP,
+or it might be called "\fIkdesktop_lock\fP" or "\fIkrunner_lock\fP", and
+it might be in \fI/usr/lib/kde4/libexec/\fP
+or in \fI/usr/kde/3.5/bin/\fP or even in \fI/usr/bin/\fP,
+depending on the distro and phase of the moon. Replace the contents
+of that file with these two lines:
.EX
+
#!/bin/sh
xscreensaver-command -lock
+
.EE
Make sure the file is executable (chmod a+x).
.RE
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.)
+It is safe to run \fIxscreensaver\fP as root (as \fIxdm\fP or \fIgdm\fP may 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.
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
+.PP
+.TP 4
.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
.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
+.TP 4
.B XAUTH and XDM
For xscreensaver to work when launched by
-.BR xdm (1),
+.BR xdm (1)
+or
+.BR gdm (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
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,
+environment before doing it. See the "\fIUsing GDM\fP" section,
above, for more details.
-.TP 8
+.TP 4
.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
+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,
xscreensaver-command -restart
.EE
to make \fIxscreensaver\fP notice.
-.TP 8
+.TP 4
.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.
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,
+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
+.TP 4
.B Machine Load
-Although this program ``nices'' the subprocesses that it starts,
+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
+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.
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
+.TP 4
.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
screensaver is launched by
.BR xdm (1)
because it can't know the user-id of the logged-in user. See
-the ``\fIUsing XDM(1)\fP'' section, below.
+the "\fIUsing XDM(1)\fP" section, below.
.TP 8
.B lockTimeout\fP (class \fBTime\fP)
-If locking is enabled, this controls the length of the ``grace period''
+If locking is enabled, this controls the length of the "grace period"
between when the screensaver activates, and when the screen becomes locked.
For example, if this is 5, and \fI\-timeout\fP is 10, then after 10 minutes,
the screen would blank. If there was user activity at 12 minutes, no password
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
This is the shell command run when the \fIPrefs\fP button on the splash window
is pressed. It defaults to \fIxscreensaver\-demo\ \-prefs\fP.
.TP 8
+.B newLoginCommand\fP (class \fBNewLoginCommand\fP)
+If set, this is the shell command that is run when the "New Login" button
+is pressed on the unlock dialog box, in order to create a new desktop
+session without logging out the user who has locked the screen.
+Typically this will be some variant of
+.BR gdmflexiserver (1)
+or
+.BR kdmctl (1).
+.TP 8
.B nice\fP (class \fBNice\fP)
-The sub-processes created by \fIxscreensaver\fP will be ``niced'' to this
+The sub-processes created by \fIxscreensaver\fP will be "niced" to this
level, so that they are given lower priority than other processes on the
system, and don't increase the load unnecessarily. The default is 10.
-
(Higher numbers mean lower priority; see
.BR nice (1)
for details.)
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''
+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.)
+.B Visuals:
+
+Because xscreensaver was created back when dinosaurs roamed the earth,
+it still contains support for some things you've probably never seen,
+such as 1-bit monochrome monitors, grayscale monitors, and monitors
+capable of displaying only 8-bit colormapped images.
+
If there are some programs that you want to run only when using a color
display, and others that you want to run only when using a monochrome
display, you can specify that like this:
\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 strongly discouraged. Support for it will
-probably be removed eventually.
-.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
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,
+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 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
+should draw. This is necessary on Xinerama/RANDR systems where
multiple physical monitors share a single X11 "Screen".
.TP 8
.B PATH
.BR xscreensaver\-getimage (1),
.BR xscreensaver\-text (1).
.SH COPYRIGHT
-Copyright \(co 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
-2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 by Jamie Zawinski.
+Copyright \(co 1991-2013 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
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!
projects / xscreensaver / blobdiff