X-Git-Url: http://git.hungrycats.org/cgi-bin/gitweb.cgi?p=xscreensaver;a=blobdiff_plain;f=driver%2Fxscreensaver-command.man;h=0dee348fbdfdad605831f59c578a1d7139de6404;hp=06e88cbfce30d9547cc3ccc5a5c312353c209660;hb=019de959b265701cd0c3fccbb61f2b69f06bf9ee;hpb=ccbc9f87eb59497b23bd0424ee1ed20ad7c7db54 diff --git a/driver/xscreensaver-command.man b/driver/xscreensaver-command.man index 06e88cbf..0dee348f 100644 --- a/driver/xscreensaver-command.man +++ b/driver/xscreensaver-command.man @@ -11,100 +11,253 @@ .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 () { + 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 , 13-aug-92. +Jamie Zawinski , 13-aug-1992. + +Please let me know if you find any bugs or make any improvements.