.if n .sp 1
.if t .sp .5
..
-.TH XScreenSaver 1 "16-Nov-98 (3.04)" "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
-[\-help] \
-[\-demo] \
-[\-prefs] \
-[\-activate] \
-[\-deactivate] \
-[\-cycle] \
-[\-next] \
-[\-prev] \
-[\-select \fIn\fP] \
-[\-exit] \
-[\-restart] \
-[\-lock] \
-[\-version] \
-[\-time]
+[\-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.
will notice, and deactivate.)
.TP 8
.B \-deactivate
-If the screensaver is active (the screen is blanked), this command will
-deactivate it just as if there had been keyboard or mouse 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
If the screensaver is active (the screen is blanked), then stop the current
element in the list is numbered 1, not 0.)
.TP 8
.B \-exit
-Causes the xscreensaver process to exit gracefully. This is roughly the same
-as killing the process with
-.BR kill (1),
-but it is easier, since you don't need to first figure out the pid.
+Causes the xscreensaver process to exit gracefully.
+This does nothing if the display is currently locked.
.B Warning:
never use \fIkill -9\fP with \fIxscreensaver\fP while the screensaver is
.TP 8
.B \-restart
Causes the screensaver process to exit and then restart with the same command
-line arguments as last time. Do this after you've changed the resource
-database, to cause xscreensaver to notice the changes.
+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.)
-.B Warning:
-if you have a \fI.xscreensaver\fP file, this might not do what you
-expect. You're probably better off killing the existing
-xscreensaver (with \fIxscreensaver\-command -exit\fP) and then
-launching it again.
+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
-The important point is, you need to make sure that the xscreensaver
-process is running as you. If it's not, it won't be reading the
-right \fI.xscreensaver\fP file.
+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
and related tools can always be found at http://www.jwz.org/xscreensaver/
.SH "SEE ALSO"
.BR X (1),
-.BR xscreensaver (1)
-.BR xscreensaver\-demo (1)
+.BR xscreensaver (1),
+.BR xscreensaver\-demo (1),
+.BR xset (1)
.SH COPYRIGHT
-Copyright \(co 1992, 1993, 1997, 1998
-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@jwz.org>, 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