.if n .sp 1
.if t .sp .5
..
-.TH XScreenSaver 1 "22-mar-93" "X Version 11"
+.TH XScreenSaver 1 "09-Nov-2013 (5.23)" "X Version 11"
.SH NAME
xscreensaver-command - control a running xscreensaver process
.SH SYNOPSIS
.B xscreensaver-command
-[\-activate] [\-deactivate] [\-cycle] [\-next] [\-prev] [\-exit] [\-restart] [\-demo] [\-lock]
+[\-display \fIhost:display.screen\fP] \
+[\-help | \
+\-demo | \
+\-prefs | \
+\-activate | \
+\-deactivate | \
+\-cycle | \
+\-next | \
+\-prev | \
+\-select \fIn\fP | \
+\-exit | \
+\-restart | \
+\-lock | \
+\-version | \
+\-time | \
+\-watch]
.SH DESCRIPTION
The \fIxscreensaver\-command\fP program controls a running \fIxscreensaver\fP
process by sending it client-messages.
+
+.BR xscreensaver (1)
+has a client-server model: the xscreensaver process is a
+daemon that runs in the background; it is controlled by other
+foreground programs such as \fIxscreensaver-command\fP and
+.BR xscreensaver\-demo (1).
+
+This program, \fIxscreensaver-command\fP, is a command-line-oriented tool; the
+.BR xscreensaver\-demo (1).
+program is a graphical tool.
.SH OPTIONS
.I xscreensaver-command
-accepts the following options:
+accepts the following command-line options:
+.TP 8
+.B \-help
+Prints a brief summary of command-line options.
+.TP 8
+.B \-demo
+This just launches the
+.BR xscreensaver\-demo (1)
+program, in which one can experiment with the various graphics hacks
+available, and edit parameters.
+.TP 8
+.B \-demo \fP\fInumber\fP
+When the \fI\-demo\fP option is followed by an integer, it instructs
+the \fIxscreensaver\fP daemon to run that hack, and wait for the user
+to click the mouse before deactivating (i.e., mouse motion does not
+deactivate.) This is the mechanism by which
+.BR xscreensaver\-demo (1)
+communicates with the
+.BR xscreensaver (1)
+daemon. (The first hack in the list is numbered 1, not 0.)
+.TP 8
+.B \-prefs
+Like the no-argument form of \fI\-demo\fP, but brings up that program's
+Preferences panel by default.
.TP 8
.B \-activate
-Tell the screensaver to turn on immediately (that is, pretend that the
-user been idle for long enough.) It will turn off as soon as there is
-any user activity, as usual.
+Tell xscreensaver to turn on immediately (that is, blank the screen, as if
+the user had been idle for long enough.) The screensaver will deactivate as
+soon as there is any user activity, as usual.
It is useful to run this from a menu; you may wish to run it as
.EX
sleep 5 ; xscreensaver-command -activate
.EE
-to be sure that you have time to remove your hand from the mouse before
-the screensaver comes on.
+to be sure that you have time to take your hand off the mouse before
+the screensaver comes on. (Because if you jiggle the mouse, xscreensaver
+will notice, and deactivate.)
.TP 8
.B \-deactivate
-Tell the screensaver to turn off, as if there had been user activity.
-If locking is enabled, then the screensaver will prompt for a password
-as usual.
+This tells xscreensaver to pretend that there has just been user activity.
+This means that if the screensaver is active (the screen is blanked),
+then this command will cause the screen to un-blank as if there had been
+keyboard or mouse activity. If the screen is locked, then the password
+dialog will pop up first, as usual. If the screen is not blanked, then
+this simulated user activity will re-start the countdown (so, issuing
+the \fI\-deactivate\fP command periodically is \fIone\fP way to prevent
+the screen from blanking.)
.TP 8
.B \-cycle
-Tell the screensaver to change which graphics hack it is running, just
-as if the ``cycle'' timer had expired.
+If the screensaver is active (the screen is blanked), then stop the current
+graphics demo and run a new one (chosen randomly.)
.TP 8
.B \-next
This is like either \fI\-activate\fP or \fI\-cycle\fP, depending on which is
-more appropriate, except that the screenhack that will be run is the next
-one in the list of programs, instead of a randomly-chosen one. This option
-is good for looking at a demo of each of the screensavers currently available.
-You might want to put this on a menu.
+more appropriate, except that the graphics hack that will be run is the next
+one in the list, instead of a randomly-chosen one. In other words,
+repeatedly executing -next will cause the xscreensaver process to invoke each
+graphics demo sequentially. (Though using the \fI\-demo\fP option is probably
+an easier way to accomplish that.)
.TP 8
.B \-prev
This is like \fI\-next\fP, but cycles in the other direction.
.TP 8
-.B \-demo
-Cause the screensaver to enter its interactive demo mode, if it has been
-compiled with support for it.
-.TP 8
-.B \-lock
-Like \fI\-activate\fP, but a password will be required before the screensaver
-turns off, even if the screensaver's \fIlock\fP resource is false. The
-display will be locked immediately even if the screensaver's \fIlockTimeout\fP
-resource is non-zero.
+.B \-select \fInumber\fP
+Like \fI\-activate\fP, but runs the \fIN\fPth element in the list of hacks.
+By knowing what is in the \fIprograms\fP list, and in what order, you can use
+this to activate the screensaver with a particular graphics demo. (The first
+element in the list is numbered 1, not 0.)
.TP 8
.B \-exit
-Causes the screensaver process to exit gracefully. This is a slightly
-safer way to kill the screensaver than by using \fIkill\fP.
+Causes the xscreensaver process to exit gracefully.
+This does nothing if the display is currently locked.
-Never use \fIkill -9\fP with \fIxscreensaver\fP while the screensaver is
+.B Warning:
+never use \fIkill -9\fP with \fIxscreensaver\fP while the screensaver is
active. If you are using a virtual root window manager, that can leave
things in an inconsistent state, and you may need to restart your window
manager to repair the damage.
.TP 8
+.B \-lock
+Tells the running xscreensaver process to lock the screen immediately.
+This is like \fI\-activate\fP, but forces locking as well, even if locking
+is not the default (that is, even if xscreensaver's \fIlock\fP resource is
+false, and even if the \fIlockTimeout\fP resource is non-zero.)
+
+Note that locking doesn't work unless the \fIxscreensaver\fP process is
+running as you. See
+.BR xscreensaver (1)
+for details.
+.TP 8
+.B \-version
+Prints the version of xscreensaver that is currently running on the display:
+that is, the actual version number of the running xscreensaver background
+process, rather than the version number of xscreensaver-command. (To see
+the version number of \fIxscreensaver-command\fP itself, use
+the \fI\-help\fP option.)
+.TP 8
+.B \-time
+Prints the time at which the screensaver last activated or
+deactivated (roughly, how long the user has been idle or non-idle: but
+not quite, since it only tells you when the screen became blanked or
+un-blanked.)
+.TP 8
.B \-restart
Causes the screensaver process to exit and then restart with the same command
-line arguments. This is a good way of causing the screensaver to re-read the
-resource database.
+line arguments as last time. You shouldn't really need to do this,
+since xscreensaver notices when the \fI.xscreensaver\fP file has
+changed and re-reads it as needed.
+.TP 8
+.B \-watch
+Prints a line each time the screensaver changes state: when the screen
+blanks, locks, unblanks, or when the running hack is changed. This option
+never returns; it is intended for use by shell scripts that want to react to
+the screensaver in some way. An example of its output would be:
+.EX
+BLANK Fri Nov 5 01:57:22 1999
+RUN 34
+RUN 79
+RUN 16
+LOCK Fri Nov 5 01:57:22 1999
+RUN 76
+RUN 12
+UNBLANK Fri Nov 5 02:05:59 1999
+.EE
+The above shows the screensaver activating, running three different
+hacks, then locking (perhaps because the lock-timeout went off) then
+unblanking (because the user became active, and typed the correct
+password.) The hack numbers are their index in the `programs'
+list (starting with 1, not 0, as for the \fI\-select\fP command.)
+
+For example, suppose you want to run a program that turns down the volume
+on your machine when the screen blanks, and turns it back up when the screen
+un-blanks. You could do that by running a Perl program like the following
+in the background. The following program tracks the output of
+the \fI\-watch\fP command and reacts accordingly:
+.EX
+#!/usr/bin/perl
-If the screensaver is run from \fIxdm(1)\fP (that is, it is already running
-before you log in) then you may want to issue the ``restart'' command from
-one of your startup scripts, so that the screensaver gets your resource
-settings instead of the default ones.
+my $blanked = 0;
+open (IN, "xscreensaver-command -watch |");
+while (<IN>) {
+ if (m/^(BLANK|LOCK)/) {
+ if (!$blanked) {
+ system "sound-off";
+ $blanked = 1;
+ }
+ } elsif (m/^UNBLANK/) {
+ system "sound-on";
+ $blanked = 0;
+ }
+}
+.EE
+Note that LOCK might come either with or without a preceding BLANK
+(depending on whether the lock-timeout is non-zero), so the above program
+keeps track of both of them.
+.SH STOPPING GRAPHICS
+If xscreensaver is running, but you want it to stop running screen hacks
+(e.g., if you are logged in remotely, and you want the console to remain
+locked but just be black, with no graphics processes running) you can
+accomplish that by simply powering down the monitor remotely. In a
+minute or so, xscreensaver will notice that the monitor is off, and
+will stop running screen hacks. You can power off the monitor like so:
+.EX
+xset dpms force off
+.EE
+See the
+.BR xset (1)
+manual for more info.
+
+You can also use
+.BR xscreensaver-demo (1)
+to make the monitor power down after a few hours, meaning that xscreensaver
+will run graphics until it has been idle for the length of time you
+specified; and after that, the monitor will power off, and screen hacks
+will stop being run.
+.SH DIAGNOSTICS
+If an error occurs while communicating with the \fIxscreensaver\fP daemon, or
+if the daemon reports an error, a diagnostic message will be printed to
+stderr, and \fIxscreensaver-command\fP will exit with a non-zero value. If
+the command is accepted, an indication of this will be printed to stdout, and
+the exit value will be zero.
.SH ENVIRONMENT
.PP
.TP 8
.B DISPLAY
-to get the default host and display number.
+to get the host and display number of the screen whose saver is
+to be manipulated.
.TP 8
.B PATH
-to find the executable to restart.
+to find the executable to restart (for the \fI\-restart\fP command).
+Note that this variable is consulted in the environment of
+the \fIxscreensaver\fP process, not the \fIxscreensaver-command\fP process.
+.SH UPGRADES
+The latest version of
+.BR xscreensaver (1)
+and related tools can always be found at http://www.jwz.org/xscreensaver/
.SH "SEE ALSO"
.BR X (1),
-.BR xscreensaver (1)
-.SH BUGS
-Diagnostics are reported on the \fBstderr\fP of the \fIxscreensaver\fP
-process, not this process, so the caller of \fIxscreensaver-command\fP
-may not see the error messages.
+.BR xscreensaver (1),
+.BR xscreensaver\-demo (1),
+.BR xset (1)
.SH COPYRIGHT
-Copyright \(co 1992, 1993 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 1992-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
+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 <jwz@mcom.com>, 13-aug-92.
+Jamie Zawinski <jwz@jwz.org>, 13-aug-1992.
+
+Please let me know if you find any bugs or make any improvements.
projects / xscreensaver / blobdiff