X-Git-Url: http://git.hungrycats.org/cgi-bin/gitweb.cgi?p=xscreensaver;a=blobdiff_plain;f=driver%2Fxscreensaver-command.man;h=0dee348fbdfdad605831f59c578a1d7139de6404;hp=835faa55283123b46a730abc6b5fff737883bdd7;hb=019de959b265701cd0c3fccbb61f2b69f06bf9ee;hpb=ce3185de9d9705e259f2b60dd4b5509007fa17d4 diff --git a/driver/xscreensaver-command.man b/driver/xscreensaver-command.man index 835faa55..0dee348f 100644 --- a/driver/xscreensaver-command.man +++ b/driver/xscreensaver-command.man @@ -11,32 +11,40 @@ .if n .sp 1 .if t .sp .5 .. -.TH XScreenSaver 1 "02-Oct-98 (2.31)" "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] \ -[\-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. .BR xscreensaver (1) has a client-server model: the xscreensaver process is a -daemon that runs in the background; it is controlled by the -foreground \fIxscreensaver-command\fP program. +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 command-line options: @@ -45,17 +53,24 @@ accepts the following command-line options: Prints a brief summary of command-line options. .TP 8 .B \-demo -Cause the screensaver to enter its interactive demo mode, in which one -can experiment with the various graphics hacks available. See +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) -for details. +daemon. (The first hack in the list is numbered 1, not 0.) .TP 8 .B \-prefs -Cause the screensaver to enter its interactive demo mode, and bring up -the Preferences control panel, in which one can change most of the settings -that control the xscreensaver daemon's behavior. See -.BR xscreensaver (1) -for details. +Like the no-argument form of \fI\-demo\fP, but brings up that program's +Preferences panel by default. .TP 8 .B \-activate Tell xscreensaver to turn on immediately (that is, blank the screen, as if @@ -66,15 +81,19 @@ 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 +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 -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 @@ -91,11 +110,15 @@ an easier way to accomplish that.) .B \-prev This is like \fI\-next\fP, but cycles in the other direction. .TP 8 +.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 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 @@ -103,21 +126,16 @@ 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 \-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. - -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 \fI\-restart\fP command from -one of your startup scripts, so that the screensaver gets your resource -settings instead of the default ones. -.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: @@ -131,6 +149,85 @@ 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 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 + +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 +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 @@ -145,25 +242,22 @@ the \fIxscreensaver\fP process, not the \fIxscreensaver-command\fP process. .SH UPGRADES The latest version of .BR xscreensaver (1) -and \fIxscreensaver\-command\fP can always be found at -http://www.jwz.org/xscreensaver/ +and related tools can always be found at http://www.jwz.org/xscreensaver/ .SH "SEE ALSO" .BR X (1), -.BR xscreensaver (1) -.SH BUGS -Some diagnostics are reported on the stderr 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, 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 , 13-aug-92. +Jamie Zawinski , 13-aug-1992. Please let me know if you find any bugs or make any improvements.