X-Git-Url: http://git.hungrycats.org/cgi-bin/gitweb.cgi?p=xscreensaver;a=blobdiff_plain;f=driver%2Fxscreensaver-command.man;h=0dee348fbdfdad605831f59c578a1d7139de6404;hp=352de640aef1fa925d851452c716983888e42aaa;hb=019de959b265701cd0c3fccbb61f2b69f06bf9ee;hpb=df7adbee81405e2849728a24b498ad2117784b1f diff --git a/driver/xscreensaver-command.man b/driver/xscreensaver-command.man index 352de640..0dee348f 100644 --- a/driver/xscreensaver-command.man +++ b/driver/xscreensaver-command.man @@ -11,27 +11,27 @@ .if n .sp 1 .if t .sp .5 .. -.TH XScreenSaver 1 "23-Jun-99 (3.16)" "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] \ -[\-throttle] \ -[\-unthrottle] \ -[\-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. @@ -86,10 +86,14 @@ the screensaver comes on. (Because if you jiggle the mouse, xscreensaver 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 @@ -113,10 +117,8 @@ 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 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 @@ -135,21 +137,6 @@ running as you. See .BR xscreensaver (1) for details. .TP 8 -.B \-throttle -Temporarily switch to ``blank screen'' mode, and don't run any display modes -at all, until the screensaver is next de-activated. This is useful if you're -using a machine remotely, and you find that some display modes are using too -much CPU. - -(If you want to do this \fIpermanently\fP, that is, you want the screen saver -to only blank the screen and not run demos at all, then set the \fIprograms\fP -resource to an empty list: See -.BR xscreensaver (1) -for details.) -.TP 8 -.B \-unthrottle -Turn `-throttle' mode off and resume normal behavior. -.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 @@ -165,18 +152,76 @@ un-blanked.) .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 () { + 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 @@ -200,18 +245,19 @@ The latest version of 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, 1999 -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 , 13-aug-92. +Jamie Zawinski , 13-aug-1992. Please let me know if you find any bugs or make any improvements.