14 .TH XScreenSaver 1 "12-May-94" "X Version 11"
16 xscreensaver - run graphics hacks after the user has been idle for a while
19 [\-display \fIhost:display.screen\fP] [\-timeout \fIint\fP] [\-cycle \fIint\fP] [\-nice \fIint\fP] [\-verbose] [\-silent] [\-xidle] [\-no-xidle] [\-lock] [\-no-lock] [\-lock\-timeout \fIint\fP] [\-demo] [\-visual \fIvisual\fP] [\-xrm \fIresources\fP]
21 The \fIxscreensaver\fP program waits until the keyboard and mouse have been
22 idle for a period, and then runs a graphics demo chosen at random. It
23 turns off as soon as there is any mouse or keyboard activity.
25 This program can lock your terminal in order to prevent others from using it,
26 though its default mode of operation is merely to display pretty pictures on
27 your screen when it is not in use.
29 The benefit that this program has over the combination of the
33 programs is the ease with which new graphics hacks can be installed. You
34 don't need to recompile (or even re-run) this program to add a new display
38 accepts the following options:
40 .B \-timeout \fIminutes\fP
41 The screensaver will activate after the keyboard and mouse have been idle
42 for this many minutes.
44 .B \-cycle \fIminutes\fP
45 After the screensaver has been running for this many minutes, the currently
46 running sub-process will be killed (with \fBSIGTERM\fP), and a new one
47 started. If this is 0, then the sub-process will not be killed; only one
48 demo will run until the screensaver is deactivated by user activity.
50 .B \-nice \fIinteger\fP
51 The sub-processes created by \fIxscreensaver\fP will be ``niced'' to this
52 level, so that they do not consume cycles that are needed elsewhere.
61 Use the \fIXIdle\fP server extension to decide whether the user is idle.
62 This is the default if \fIxscreensaver\fP has been compiled with support
63 for XIdle. The XIdle method is faster and more reliable than what will
64 be done otherwise, so use it if you can.
67 Don't use \fIXIdle\fP.
70 Enable locking: before the screensaver will turn off, it requires you to
71 type the password of the person who launched the screensaver, or the root
72 password. (Note: this doesn't work if the screensaver is launched
75 because it can't know the user-id of the logged-in user.)
78 Disable locking. This is the default.
80 .B \-lock\-timeout \fIminutes\fP
81 This is how long after the screensaver activates that locking is enabled.
82 For example, if this is 5, then any user activity within five minutes of
83 the time when the screensaver activated will cause the screen to unblank
84 without requiring a password. After 5 minutes, a password will be
85 required. The default is 0, meaning that if locking is enabled, then
86 a password will be required as soon as the screensaver activates.
88 .B \-visual \fIvisual\fP
89 Specify which visual to use. Legal values are:
93 Use the visual which supports the most writable color cells; this is
97 Use the screen's default visual (the visual of the root window.) This is
98 not necessarily the most colorful visual, which is why it is not the default.
101 One of \fBStaticGray\fP, \fBStaticColor\fP, \fBTrueColor\fP, \fBGrayScale\fP,
102 \fBPseudoColor\fP, or \fBDirectColor\fP. Selects the deepest visual of
106 A number (decimal or hex) is interpreted as a visual id number, as reported
109 program; in this way you can select a shallower visual if desired.
113 Enter the interactive demo mode immediately after startup. Normally
114 demo mode is invoked via the
115 .BR xscreensaver\-command (1)
118 \fIxscreensaver\fP understands the following resources:
121 .B timeout \fR(class \fBTime\fP)
122 Same as the \fI\-timeout\fP command-line option. Default 10 minutes.
124 .B cycle \fR(class \fBTime\fP)
125 Same as the \fI\-cycle\fP command-line option. Default 10 minutes.
127 .B nice \fR(class \fBNice\fP)
128 Same as the \fI\-nice\fP command-line option. Default 10.
130 .B verbose \fR(class \fBBoolean\fP)
131 Same as the \fI\-verbose\fP command-line option.
133 .B xidle \fR(class \fBBoolean\fP)
134 Same as the \fI\-xidle\fP command-line option.
136 .B lock \fR(class \fBBoolean\fP)
137 Same as the \fI\-lock\fP command-line option.
139 .B lockTimeout \fR(class \fBTime\fP)
140 Same as the \fI\-lock\-timeout\fP command-line option.
142 .B fade \fR(class \fBBoolean\fP)
143 If this is true, then when the screensaver activates, the current contents
144 of the screen will fade to black instead of simply winking out. This only
145 works on displays with writable colormaps. Default true. A fade will also
146 be done when switching graphics hacks (when the \fIcycle\fP timer expires.)
148 .B unfade \fR(class \fBBoolean\fP)
149 If this is true, then when the screensaver deactivates, the original contents
150 of the screen will fade in from black instead of appearing immediately. This
151 only works on displays with writable colormaps, and if \fIfade\fP is true
152 as well. Default false.
154 .B fadeSeconds \fR(class \fBTime\fP)
155 If \fIfade\fP is true, this is how long the fade will be in
158 .B fadeTicks \fR(class \fBInteger\fP)
159 If \fIfade\fP is true, this is how many times a second the colormap will
160 be changed to effect a fade. Higher numbers yield smoother fades, but
161 may make the fades take longer if your server isn't fast enough to keep
164 .B installColormap \fR(class \fBBoolean\fP)
165 Whether a new colormap should be installed while the screensaver is on,
166 so that the graphics hacks can get as many colors as possible. Default
169 .B passwdTimeout \fR(class \fBTime\fP)
170 If \fIlock\fP is true, this is how many seconds the password dialog box
171 should be left on the screen before giving up (default 30.) This should
172 not be too large: the X server is grabbed for the duration that the password
173 dialog box is up (for security purposes) and leaving the server grabbed for
174 too long can cause problems.
176 .B visualID \fR(class \fBVisualID\fP)
177 Same as the \fI\-visual\fP command-line option. Default \fBbest\fP.
180 .B programs \fR(class \fBPrograms\fP)
181 The graphics hacks which \fIxscreensaver\fP runs when the user is idle.
182 The value of this resource is a string, one \fIsh\fP command per line.
183 Each line must contain exactly one command -- no semicolons.
185 When the screensaver starts up, one of these is selected at random, and
186 run. After the \fIcycle\fP period expires, it is killed, and another
189 If the value of this resource (and the applicable one of \fBcolorPrograms\fP
190 or \fBmonoPrograms\fP) is empty, then no programs will be run; the screen
191 will simply be made black.
193 Note that you must escape the newlines; here is an example of how you
194 might set this in your \fI.Xdefaults\fP file:
196 xscreensaver.programs: \\
198 ico -r -faces -sleep 1 -obj ico \\n\\
199 xdaliclock -builtin2 -root \\n\\
202 To use a program as a screensaver, two things are required: that that
203 program draw on the root window (or be able to be configured to draw on
204 the root window); and that that program understand ``virtual root''
205 windows, as used by virtual window managers such as \fItvtwm\fP.
207 It is quite easy to make programs understand virtual roots if they
208 don't already: you merely need to include the file \fI"vroot.h"\fP in
209 them after the standard X includes, and recompile. This file is distributed
210 with X11r5, and is included with xscreensaver as well.
212 .B monoPrograms \fR(class \fBMonoPrograms\fP)
213 This resource is appended to the value of the \fIprograms\fP resource if
214 the display on which the screensaver is running is monochrome.
216 .B colorPrograms \fR(class \fBColorPrograms\fP)
217 This resource is appended to the value of the \fIprograms\fP resource if
218 the display on which the screensaver is running is not monochrome.
220 Normally you won't need to change the following resources:
222 .B bourneShell \fR(class \fBBourneShell\fP)
223 The pathname of the shell that \fIxscreensaver\fP uses to start subprocesses.
224 This must be whatever your local variant of \fB/bin/sh\fP is -- in particular,
225 it must not be \fBcsh\fP.
227 .B windowCreationTimeout \fR(class \fBTime\fP)
228 When \fIXIdle\fP is not in use, this controls the delay between when
229 windows are created and when \fIxscreensaver\fP selects events on them.
232 .B pointerPollTime \fR(class \fBTime\fP)
233 When \fIXIdle\fP is not in use, this controls how frequently \fIxscreensaver\fP
234 checks to see if the mouse position or buttons have changed. Default 5 seconds.
236 .B initialDelay \fR(class \fBTime\fP)
237 When \fIXIdle\fP is not in use, \fIxscreensaver\fP will wait this many seconds
238 before selecting events on existing windows, under the assumption that
239 \fIxscreensaver\fP is started during your login procedure, and the window
240 state may be in flux. Default 30 seconds.
242 When it is time to activate the screensaver, a full-screen black window is
243 created. This window is given the appropriate properties so that, to any
244 subsequently-created programs, it will appear to be a ``virtual root''
245 window. Because of this, any program which draws on the root window (and
246 which understands virtual roots) can be used as a screensaver.
248 When the user becomes active again, the screensaver window is unmapped and
249 the running subprocess is killed by sending it \fBSIGTERM\fP. This is also
250 how the subprocesses are killed when the screensaver decides that it's time
251 to run a different demo: the old one is killed and a new one is launched.
253 Before launching a subprocess, \fIxscreensaver\fP stores an appropriate value
254 for \fB$DISPLAY\fP in the environment that the child will recieve. (This is
255 so that if you start \fIxscreensaver\fP with a \fI-display\fP argument, the
256 programs which \fIxscreensaver\fP launches will draw on the same display.)
258 When the screensaver turns off, or is killed, care is taken to restore
259 the ``real'' virtual root window if there is one. Because of this, it is
260 important that you not kill the screensaver process with \fIkill -9\fP if
261 you are running a virtual-root window manager. If you kill it with \-9,
262 you may need to restart your window manager to repair the damage. This
263 isn't an issue if you aren't running a virtual-root window manager.
265 For all the gory details, see the commentary at the top of xscreensaver.c.
267 You can control a running screensaver process by using the
268 .BR xscreensaver\-command (1)
274 to get the default host and display number.
277 to get the name of a resource file that overrides the global resources
278 stored in the RESOURCE_MANAGER property.
280 You can run \fIxscreensaver\fP from your xdm session, so that the
281 screensaver will run even when nobody is logged in on the console.
282 Simply add \fB"xscreensaver &"\fP to your \fI/usr/lib/X11/xdm/Xsetup\fP
283 file. Because \fIxdm\fP grabs the keyboard, keypresses will not make
284 the screensaver deactivate, but any mouse activity will.
286 Users may want to add \fB"xscreensaver-command -restart"\fP to their
287 startup scripts, so that the screensaver will be reinitialized with
288 their private resource settings when they log in.
290 It is safe to run this program as root (as \fIxdm\fP is likely to do.) If
291 run as root, \fIxscreensaver\fP changes its effective user and group ids to
292 something safe (like \fI"nobody"\fP) before connecting to the X server
293 or launching user-specified programs.
295 Locking doesn't work if the screensaver is launched by \fIxdm\fP. To get
296 around this, you can run the screensaver from \fIxdm\fP without locking,
297 and kill and restart it from your personal X startup script to enable
300 If \fIxscreensaver\fP receives the \fBDEMO\fP ClientMessage, it pops up
301 a dialog box from which you can examine and experiment with the screensaver's
304 Clicking left on an element in the scrolling list will place the indicated
305 program and its args in the text field to be edited. Edit the arguments and
306 hit return to run the program with the parameters you have specified.
308 Double-clicking on an element in the scrolling list will run the indicated
311 When a client program is launched, the dialog box is hidden. Clicking
312 any mouse button will re-expose the dialog box (but will not kill the
316 Clicking this button will run the next program in the list after the
317 currently-selected one, and will scroll around to the top when it reaches
321 Opposite of Run Next; at the top, it scrolls around to the bottom.
324 This pops up a second dialog box, in which you have the option to
325 interactively change most of the screensaver's operational parameters,
326 such as its timeouts, and whether it should hack colormaps. Changing
327 these parameters here will affect only the running \fIxscreensaver\fP
328 process; to make the changes permanent, you need to edit your X resource
332 Returns to normal screensaver operation.
335 Causes the screensaver process to exit and then restart with the same
336 command-line arguments. This causes the X resource database to be
337 re-read. This is just like the \fI\-restart\fP argument to
338 .BR xscreensaver\-command (1)
339 except that when executed from this button, the screensaver will
340 automatically return to demo mode after restarting.
343 .BR xscreensaver\-command (1),
370 If you are not using \fIXIdle\fP, and an application does not
371 select \fBKeyPress\fP events on its non-leaf windows within the first
372 30 seconds of their existence, but selects them later, then it is
373 possible that \fIxscreensaver\fP could interfere with the propagation
374 of those events. This isn't very likely, but this is the reason that
375 it's a good idea to install the \fIXIdle\fP extension.
377 Although this program ``nices'' the subprocesses that it starts,
378 graphics-intensive subprograms can still overload the machine by causing
379 the X server process itself (which is not ``niced'') to suck a lot of
380 cycles. Care should be taken to slow down programs intended for use as
381 screensavers by inserting strategic calls to
387 Also, it will cause your X server to be pretty much permanently swapped in.
388 (but the same is true of any program that draws periodically, like xclock or
391 If the subprocess is drawing too quickly and the connection to the X
392 server is a slow one (such as an X terminal running over a phone line) then
393 the screensaver might not turn off right away when the user becomes active
396 demo has this problem if being run in full-speed mode). This can be
397 alleviated by inserting strategic calls to
399 in code intended for use as a screensaver. This prevents too much graphics
400 activity from being buffered up.
402 The screensaver only runs on the default screen of the display. If you have
403 more than one screen, you can run multiple screensaver processes, one for
404 each screen. This interacts poorly with locking. In an ideal world, the
405 screensaver would save (and lock) both screens simultaniously, and any activity
406 would restore both screens. It would be nice if one could run different hacks
407 on each screen simultaniously. However, I don't have access to a multi-headed
408 workstation, so it would be hard for me to implement something like this.
410 If you don't have Motif, you can't compile with support for locking or
413 When the \fBRun Next\fP and \fBRun Previous\fP buttons are used, the selected
414 item may not be visible in the window. It's a Motif bug that selecting a
415 different item doesn't scroll the list to show the new selected item.
417 Locking doesn't work if the screensaver is launched by \fIxdm\fP.
419 If you get an error message like ``couldn't get password of foo'' then
420 this probably means that you're on a system in which the
422 library routine can only be effectively used by root. If this is the case,
423 then \fIxscreensaver\fP must be installed as setuid to root. Care has
424 been taken to make this a safe thing to do.
426 There need to be a lot more graphics hacks. In particular, there should be
427 a simulation of a Lavalite (tm).
429 The \fBinstallColormap\fP option doesn't work very well with the
431 window manager and its descendants. There is a race condition between the
432 screensaver and this window manager, which can result in the screensaver's
433 colormap not getting installed properly, meaning the graphics hacks will
434 appear in essentially random colors. The
438 window managers don't seem to have this problem. The race condition exists
439 because X apparently does not provide a way for an OverrideRedirect window to
440 have its own colormap, short of grabbing the server (which is neither a good
441 idea, nor really possible with the current design.) What happens is that, as
442 soon as the screensaver installs its colormap, \fBtwm\fP responds to
443 the \fBColormapNotify\fP event that is generated by re-instaling the default
444 colormap. Apparently, \fBtwm\fP doesn't \fIalways\fP do this; it seems to do
445 it regularly if the screensaver is activated from a menu item, but seems to
446 not do it if the screensaver comes on of its own volition, or is activated
447 from another console. Any thoughts on this problem are welcome...
449 The \fBinstallColormap\fP option has no effect in "demo" mode, since the
450 dialog boxes allocate their colors out of the screen's default colormap
451 instead of the installed colormap.
453 For this same reason, locking doesn't work too well along
454 with \fBinstallColormap\fP; the dialog box's colors are random.
456 Apparently there are some problems with ``XView'' programs getting confused
457 and thinking that the screensaver window is the real root window even when
458 the screensaver is not active: ClientMessages intended for the window manager
459 are sent to the screensaver window instead. This could be solved by making
460 xscreensaver forward all unrecognised ClientMessages to the real root window,
461 but there may be other problems as well.
463 Copyright \(co 1992, 1993, 1994 by Jamie Zawinski. Permission to use, copy,
464 modify, distribute, and sell this software and its documentation for any
465 purpose is hereby granted without fee, provided that the above copyright
466 notice appear in all copies and that both that copyright notice and this
467 permission notice appear in supporting documentation. No representations are
468 made about the suitability of this software for any purpose. It is provided
469 "as is" without express or implied warranty.
471 Jamie Zawinski <jwz@mcom.com>, 13-aug-92.
472 Please let me know if you find any bugs or make any improvements.
474 Thanks to David Wojtowicz for implementing \fIlockTimeout\fP.
476 Thanks to Martin Kraemer for adding support for shadow passwords and
477 locking-disabled diagnostics.
projects / xscreensaver / blob