14 .TH XScreenSaver 1 "6-Jan-95" "X Version 11"
16 xscreensaver - graphics hack and screen locker, launched when the user is idle
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] [\-install] [\-no-install] [\-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 \fBXIDLE\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 this extension. On X11R4 or X11R5 systems, the XIdle method is faster
64 and more reliable than what will be done otherwise, so use it if you can.
66 .B \-no\-xidle\-extension
67 Don't use the \fBXIDLE\fP server extension.
70 Use the \fBMIT\-SCREEN\-SAVER\fP server extension to decide whether the user
71 is idle. This is the default if \fIxscreensaver\fP has been compiled with
72 support for this extension. On X11R6 systems, the \fBMIT\-SCREEN\-SAVER\fP
73 method is faster and more reliable than what will be done otherwise, so use
76 .B \-no\-ss\-extension
77 Don't use the \fBMIT\-SCREEN\-SAVER\fP server extension.
80 Enable locking: before the screensaver will turn off, it requires you to
81 type the password of the person who launched the screensaver, or the root
82 password. (Note: this doesn't work if the screensaver is launched
85 because it can't know the user-id of the logged-in user.)
88 Disable locking. This is the default.
90 .B \-lock\-timeout \fIminutes\fP
91 This is how long after the screensaver activates that locking is enabled.
92 For example, if this is 5, then any user activity within five minutes of
93 the time when the screensaver activated will cause the screen to unblank
94 without requiring a password. After 5 minutes, a password will be
95 required. The default is 0, meaning that if locking is enabled, then
96 a password will be required as soon as the screensaver activates.
98 .B \-visual \fIvisual\fP
99 Specify which visual to use. Legal values are:
103 Use the visual which supports the most writable color cells; this is
107 Use the screen's default visual (the visual of the root window.) This is
108 not necessarily the most colorful visual, which is why it is not the default.
111 One of \fBStaticGray\fP, \fBStaticColor\fP, \fBTrueColor\fP, \fBGrayScale\fP,
112 \fBPseudoColor\fP, or \fBDirectColor\fP. Selects the deepest visual of
116 A number (decimal or hex) is interpreted as a visual id number, as reported
119 program; in this way you can select a shallower visual if desired.
123 Use the default colormap. This is the default.
126 Install a private colormap while the screensaver is on, so that the graphics
127 hacks can get as many colors as possible.
130 Enter the interactive demo mode immediately after startup. Normally
131 demo mode is invoked via the
132 .BR xscreensaver\-command (1)
135 \fIxscreensaver\fP understands the following resources:
138 .B timeout \fR(class \fBTime\fP)
139 Same as the \fI\-timeout\fP command-line option. Default 10 minutes.
141 .B cycle \fR(class \fBTime\fP)
142 Same as the \fI\-cycle\fP command-line option. Default 10 minutes.
144 .B nice \fR(class \fBNice\fP)
145 Same as the \fI\-nice\fP command-line option. Default 10.
147 .B verbose \fR(class \fBBoolean\fP)
148 Same as the \fI\-verbose\fP command-line option.
150 .B xidle \fR(class \fBBoolean\fP)
151 Same as the \fI\-xidle\fP command-line option.
153 .B lock \fR(class \fBBoolean\fP)
154 Same as the \fI\-lock\fP command-line option.
156 .B lockTimeout \fR(class \fBTime\fP)
157 Same as the \fI\-lock\-timeout\fP command-line option.
159 .B fade \fR(class \fBBoolean\fP)
160 If this is true, then when the screensaver activates, the current contents
161 of the screen will fade to black instead of simply winking out. This only
162 works on displays with writable colormaps. Default true. A fade will also
163 be done when switching graphics hacks (when the \fIcycle\fP timer expires.)
165 .B unfade \fR(class \fBBoolean\fP)
166 If this is true, then when the screensaver deactivates, the original contents
167 of the screen will fade in from black instead of appearing immediately. This
168 only works on displays with writable colormaps, and if \fIfade\fP is true
169 as well. Default false.
171 .B fadeSeconds \fR(class \fBTime\fP)
172 If \fIfade\fP is true, this is how long the fade will be in
175 .B fadeTicks \fR(class \fBInteger\fP)
176 If \fIfade\fP is true, this is how many times a second the colormap will
177 be changed to effect a fade. Higher numbers yield smoother fades, but
178 may make the fades take longer if your server isn't fast enough to keep
181 .B installColormap \fR(class \fBBoolean\fP)
182 Same as the \fI\-install\fP command-line option. Default false.
184 .B passwdTimeout \fR(class \fBTime\fP)
185 If \fIlock\fP is true, this is how many seconds the password dialog box
186 should be left on the screen before giving up (default 30.) This should
187 not be too large: the X server is grabbed for the duration that the password
188 dialog box is up (for security purposes) and leaving the server grabbed for
189 too long can cause problems.
191 .B visualID \fR(class \fBVisualID\fP)
192 Same as the \fI\-visual\fP command-line option. Default \fBbest\fP.
194 .B captureStderr \fR(class \fBBoolean\fP)
195 Whether \fIxscreensaver\fP should redirect its standard-error stream to the
196 window itself. Since its nature is to take over the screen, you would not
197 normally see error messages generated by the screensaver or the programs it
198 runs; this resource will cause the output of all relevant programs to be
199 drawn on the screensaver window itself instead of written to the controlling
200 terminal of the screensaver driver process. Default: True.
202 .B captureStdout \fR(class \fBBoolean\fP)
203 Like \fBcaptureStderr\fP but for the standard-output stream. Default: True.
205 .B font \fR(class \fBFont\fP)
206 The font used for the stdout/stderr text, if \fBcaptureStdout\fP or
207 \fBcaptureStderr\fP are true. Default \fB*\-medium\-r\-*\-140\-*\-m\-*\fP
208 (a 14 point fixed-width font.)
210 .B textForeground \fR(class \fBForeground\fP)
211 The foreground color used for the stdout/stderr text, if \fBcaptureStdout\fP
212 or \fBcaptureStderr\fP are true. Default: Yellow.
214 .B textBackground \fR(class \fBBackground\fP)
215 The background color used for the stdout/stderr text, if \fBcaptureStdout\fP
216 or \fBcaptureStderr\fP are true. Default: Black.
218 .B programs \fR(class \fBPrograms\fP)
219 The graphics hacks which \fIxscreensaver\fP runs when the user is idle.
220 The value of this resource is a string, one \fIsh\fP command per line.
221 Each line must contain exactly one command -- no semicolons.
223 When the screensaver starts up, one of these is selected at random, and
224 run. After the \fIcycle\fP period expires, it is killed, and another
227 If the value of this resource (and the applicable one of \fBcolorPrograms\fP
228 or \fBmonoPrograms\fP) is empty, then no programs will be run; the screen
229 will simply be made black.
231 Note that you must escape the newlines; here is an example of how you
232 might set this in your \fI.Xdefaults\fP file:
234 xscreensaver.programs: \\
236 ico -r -faces -sleep 1 -obj ico \\n\\
237 xdaliclock -builtin2 -root \\n\\
240 To use a program as a screensaver, two things are required: that that
241 program draw on the root window (or be able to be configured to draw on
242 the root window); and that that program understand ``virtual root''
243 windows, as used by virtual window managers such as \fItvtwm\fP.
245 It is quite easy to make programs understand virtual roots if they
246 don't already: you merely need to include the file \fI"vroot.h"\fP in
247 them after the standard X includes, and recompile. This file is distributed
248 with X11r5, and is included with xscreensaver as well.
250 .B monoPrograms \fR(class \fBMonoPrograms\fP)
251 This resource is appended to the value of the \fIprograms\fP resource if
252 the display on which the screensaver is running is monochrome.
254 .B colorPrograms \fR(class \fBColorPrograms\fP)
255 This resource is appended to the value of the \fIprograms\fP resource if
256 the display on which the screensaver is running is not monochrome.
259 \fBNOTE: this means that if you want to completely replace the list of
260 programs which xscreensaver runs, you must set at least \fItwo\fP,
261 possibly \fIthree\fP resources. It is not enough to just set
262 the \fBprograms\fP resource -- you must also set \fBcolorPrograms\fP
263 or \fBmonoPrograms\fP or both.\fP
266 Normally you won't need to change the following resources:
268 .B bourneShell \fR(class \fBBourneShell\fP)
269 The pathname of the shell that \fIxscreensaver\fP uses to start subprocesses.
270 This must be whatever your local variant of \fB/bin/sh\fP is -- in particular,
271 it must not be \fBcsh\fP.
273 .B windowCreationTimeout \fR(class \fBTime\fP)
274 When \fIXIdle\fP is not in use, this controls the delay between when
275 windows are created and when \fIxscreensaver\fP selects events on them.
278 .B pointerPollTime \fR(class \fBTime\fP)
279 When \fIXIdle\fP is not in use, this controls how frequently \fIxscreensaver\fP
280 checks to see if the mouse position or buttons have changed. Default 5 seconds.
282 .B initialDelay \fR(class \fBTime\fP)
283 When \fIXIdle\fP is not in use, \fIxscreensaver\fP will wait this many seconds
284 before selecting events on existing windows, under the assumption that
285 \fIxscreensaver\fP is started during your login procedure, and the window
286 state may be in flux. Default 30 seconds.
288 When it is time to activate the screensaver, a full-screen black window is
289 created. This window is given the appropriate properties so that, to any
290 subsequently-created programs, it will appear to be a ``virtual root''
291 window. Because of this, any program which draws on the root window (and
292 which understands virtual roots) can be used as a screensaver.
294 When the user becomes active again, the screensaver window is unmapped and
295 the running subprocess is killed by sending it \fBSIGTERM\fP. This is also
296 how the subprocesses are killed when the screensaver decides that it's time
297 to run a different demo: the old one is killed and a new one is launched.
299 Before launching a subprocess, \fIxscreensaver\fP stores an appropriate value
300 for \fB$DISPLAY\fP in the environment that the child will recieve. (This is
301 so that if you start \fIxscreensaver\fP with a \fI-display\fP argument, the
302 programs which \fIxscreensaver\fP launches will draw on the same display.)
304 When the screensaver turns off, or is killed, care is taken to restore
305 the ``real'' virtual root window if there is one. Because of this, it is
306 important that you not kill the screensaver process with \fIkill -9\fP if
307 you are running a virtual-root window manager. If you kill it with \-9,
308 you may need to restart your window manager to repair the damage. This
309 isn't an issue if you aren't running a virtual-root window manager.
311 For all the gory details, see the commentary at the top of xscreensaver.c.
313 You can control a running screensaver process by using the
314 .BR xscreensaver\-command (1)
320 to get the default host and display number.
323 to get the name of a resource file that overrides the global resources
324 stored in the RESOURCE_MANAGER property.
326 You can run \fIxscreensaver\fP from your xdm session, so that the
327 screensaver will run even when nobody is logged in on the console.
328 Simply add \fB"xscreensaver &"\fP to your \fI/usr/lib/X11/xdm/Xsetup\fP
329 file. Because \fIxdm\fP grabs the keyboard, keypresses will not make
330 the screensaver deactivate, but any mouse activity will.
332 Users may want to add \fB"xscreensaver-command -restart"\fP to their
333 startup scripts, so that the screensaver will be reinitialized with
334 their private resource settings when they log in.
336 It is safe to run this program as root (as \fIxdm\fP is likely to do.) If
337 run as root, \fIxscreensaver\fP changes its effective user and group ids to
338 something safe (like \fI"nobody"\fP) before connecting to the X server
339 or launching user-specified programs.
341 Locking doesn't work if the screensaver is launched by \fIxdm\fP. To get
342 around this, you can run the screensaver from \fIxdm\fP without locking,
343 and kill and restart it from your personal X startup script to enable
346 If \fIxscreensaver\fP receives the \fBDEMO\fP ClientMessage, it pops up
347 a dialog box from which you can examine and experiment with the screensaver's
350 Clicking left on an element in the scrolling list will place the indicated
351 program and its args in the text field to be edited. Edit the arguments and
352 hit return to run the program with the parameters you have specified.
354 Double-clicking on an element in the scrolling list will run the indicated
357 When a client program is launched, the dialog box is hidden. Clicking
358 any mouse button will re-expose the dialog box (but will not kill the
362 Clicking this button will run the next program in the list after the
363 currently-selected one, and will scroll around to the top when it reaches
367 Opposite of Run Next; at the top, it scrolls around to the bottom.
370 This pops up a second dialog box, in which you have the option to
371 interactively change most of the screensaver's operational parameters,
372 such as its timeouts, and whether it should hack colormaps. Changing
373 these parameters here will affect only the running \fIxscreensaver\fP
374 process; to make the changes permanent, you need to edit your X resource
378 Returns to normal screensaver operation.
381 Causes the screensaver process to exit and then restart with the same
382 command-line arguments. This causes the X resource database to be
383 re-read. This is just like the \fI\-restart\fP argument to
384 .BR xscreensaver\-command (1)
385 except that when executed from this button, the screensaver will
386 automatically return to demo mode after restarting.
389 .BR xscreensaver\-command (1),
417 If you think you have changed the \fBprograms\fP resource but the
418 screensaver is ignoring it, you are confused -- you need to set
419 the \fBcolorPrograms\fP and/or \fBmonoPrograms\fP resources as well.
420 (This is not a bug, but I mention it here because people think that
421 it is with great regularity.)
423 If you are not making use of one of the server extensions (\fBXIDLE\fP
424 or \fBMIT-SCREEN-SAVER\fP), then it is possible, in rare situations,
425 for \fIxscreensaver\fP to interfere with event propagation and make
426 another X program malfunction. For this to occur, that other application
427 would need to \fInot\fP select \fBKeyPress\fP events on its non-leaf windows
428 within the first 30 seconds of their existence, but then select for them later.
429 In this case, that client \fImight\fP fail to receive those events.
430 This isn't very likely, since programs generally select a constant set
431 of events immediately after creating their windows and then don't change
432 them, but this is the reason that it's a good idea to install and use one
433 of the server extensions instead, to work around this shortcoming in the
436 Although this program ``nices'' the subprocesses that it starts,
437 graphics-intensive subprograms can still overload the machine by causing
438 the X server process itself (which is not ``niced'') to suck a lot of
439 cycles. Care should be taken to slow down programs intended for use as
440 screensavers by inserting strategic calls to
446 Also, it will cause your X server to be pretty much permanently swapped in.
447 (but the same is true of any program that draws periodically, like xclock or
450 If the subprocess is drawing too quickly and the connection to the X
451 server is a slow one (such as an X terminal running over a phone line) then
452 the screensaver might not turn off right away when the user becomes active
455 demo has this problem if being run in full-speed mode). This can be
456 alleviated by inserting strategic calls to
458 in code intended for use as a screensaver. This prevents too much graphics
459 activity from being buffered up.
461 The screensaver only runs on the default screen of the display. If you have
462 more than one screen, you can run multiple screensaver processes, one for
463 each screen. This interacts poorly with locking. In an ideal world, the
464 screensaver would save (and lock) both screens simultaniously, and any activity
465 would restore both screens. It would be nice if one could run different hacks
466 on each screen simultaniously. However, I don't have access to a multi-headed
467 workstation, so it would be hard for me to implement something like this.
469 If you don't have Motif, you can't compile with support for locking or
472 Locking doesn't work if the screensaver is launched by \fIxdm\fP.
473 The reason for this is that when it is launched by \fIxdm\fP, the
474 screensaver process is owned by some standard user id (such as \fIroot\fP
475 or \fIdaemon\fP) instead of the user who is logged in on the console.
476 In order for the screensaver to prompt for the password of the person
477 who had logged in from \fIxdm\fP, it would need to know who that user was,
478 and there is no reliable and safe way to figure that out. (And even if
479 there was, there would be some other security issues here as well.)
481 So if you want to use it as a locker, you must start it with your user id.
482 If it has already been started by \fIxdm\fP, you can kill it with
483 \fBxscreensaver-command -exit\fP, and then start it again as you.
485 If you get an error message like ``couldn't get password of foo'' then
486 this probably means that you're on a system in which the
488 library routine can only be effectively used by root. If this is the case,
489 then \fIxscreensaver\fP must be installed as setuid to root. Care has
490 been taken to make this a safe thing to do.
492 The \fBinstallColormap\fP option doesn't work very well with the
494 window manager and its descendants. There is a race condition between the
495 screensaver and this window manager, which can result in the screensaver's
496 colormap not getting installed properly, meaning the graphics hacks will
497 appear in essentially random colors. The
501 window managers don't seem to have this problem. The race condition exists
502 because X apparently does not provide a way for an OverrideRedirect window to
503 have its own colormap, short of grabbing the server (which is neither a good
504 idea, nor really possible with the current design.) What happens is that, as
505 soon as the screensaver installs its colormap, \fBtwm\fP responds to
506 the \fBColormapNotify\fP event that is generated by re-instaling the default
507 colormap. Apparently, \fBtwm\fP doesn't \fIalways\fP do this; it seems to do
508 it regularly if the screensaver is activated from a menu item, but seems to
509 not do it if the screensaver comes on of its own volition, or is activated
510 from another console. Any thoughts on this problem are welcome...
512 Apparently there are some problems with ``XView'' programs getting confused
513 and thinking that the screensaver window is the real root window even when
514 the screensaver is not active: ClientMessages intended for the window manager
515 are sent to the screensaver window instead. This could be solved by making
516 xscreensaver forward all unrecognised ClientMessages to the real root window,
517 but there may be other problems as well.
519 When using the \fBMIT-SCREEN-SAVER\fP extension in conjunction with
520 the \fBfade\fP option, you may notice an unattractive flicker just before
521 the fade begins. This is because the server maps a black window just before
522 it tells the \fIxscreensaver\fP process to activate. The \fIxscreensaver\fP
523 process immediately unmaps that window, but this results in a flicker. I
524 haven't figured out how to get around this yet.
526 There need to be a lot more graphics hacks. In particular, there should be
527 a simulation of a Lavalite (tm).
529 Copyright \(co 1992, 1993, 1994, 1995 by Jamie Zawinski. Permission to use,
530 copy, modify, distribute, and sell this software and its documentation for
531 any purpose is hereby granted without fee, provided that the above copyright
532 notice appear in all copies and that both that copyright notice and this
533 permission notice appear in supporting documentation. No representations are
534 made about the suitability of this software for any purpose. It is provided
535 "as is" without express or implied warranty.
537 Jamie Zawinski <jwz@mcom.com>, 13-aug-92.
538 Please let me know if you find any bugs or make any improvements.
540 Thanks to David Wojtowicz for implementing \fIlockTimeout\fP.
542 Thanks to Martin Kraemer for adding support for shadow passwords and
543 locking-disabled diagnostics.
projects / xscreensaver / blob