git.hungrycats.org Git - xscreensaver/blob - driver/xscreensaver-command.man

   1 .de EX          \"Begin example
   2 .ne 5
   3 .if n .sp 1
   4 .if t .sp .5
   5 .nf
   6 .in +.5i
   7 ..
   8 .de EE
   9 .fi
  10 .in -.5i
  11 .if n .sp 1
  12 .if t .sp .5
  13 ..
  14 .TH XScreenSaver 1 "31-May-97" "X Version 11"
  15 .SH NAME
  16 xscreensaver-command - control a running xscreensaver process
  17 .SH SYNOPSIS
  18 .B xscreensaver-command
  19 [\-help] [\-demo] [\-activate] [\-deactivate] [\-lock] [\-cycle] [\-next] [\-prev] [\-exit] [\-restart] [\-version] [\-time]
  20 .SH DESCRIPTION
  21 The \fIxscreensaver\-command\fP program controls a running \fIxscreensaver\fP
  22 process by sending it client-messages.
  23 .SH OPTIONS
  24 .I xscreensaver-command
  25 accepts the following options:
  26 .TP 8
  27 .B \-help
  28 Prints a brief summary of command-line options.
  29 .TP 8
  30 .B \-demo
  31 Cause the screensaver to enter its interactive demo mode, in which one
  32 can experiment with the various graphics hacks available.  See
  33 .BR xscreensaver (1)
  34 for details.
  35 .TP 8
  36 .B \-activate
  37 Tell the screensaver to turn on immediately (that is, pretend that the
  38 user been idle for long enough.)  It will turn off as soon as there is
  39 any user activity, as usual.
  40
  41 It is useful to run this from a menu; you may wish to run it as
  42 .EX
  43 sleep 5 ; xscreensaver-command -activate
  44 .EE
  45 to be sure that you have time to remove your hand from the mouse before
  46 the screensaver comes on.
  47 .TP 8
  48 .B \-deactivate
  49 Tell the screensaver to turn off, as if there had been user activity.
  50 If locking is enabled, then the screensaver will prompt for a password
  51 as usual.
  52 .TP 8
  53 .B \-lock
  54 Like \fI\-activate\fP, but a password will be required before the screensaver
  55 turns off, even if the screensaver's \fIlock\fP resource is false.  The
  56 display will be locked immediately even if the screensaver's \fIlockTimeout\fP
  57 resource is non-zero.
  58 .TP 8
  59 .B \-cycle
  60 Tell the screensaver to change which graphics hack it is running, just
  61 as if the ``cycle'' timer had expired.  A new hack will be chosen randomly.
  62 .TP 8
  63 .B \-next
  64 This is like either \fI\-activate\fP or \fI\-cycle\fP, depending on which is
  65 more appropriate, except that the screenhack that will be run is the next
  66 one in the list of programs, instead of a randomly-chosen one.  Repeatedly
  67 executing this will cycle through each hack in turn (though using
  68 the \fI\-demo\fP option is probably an easier way to accomplish that.)
  69 .TP 8
  70 .B \-prev
  71 This is like \fI\-next\fP, but cycles in the other direction.
  72 .TP 8
  73 .B \-exit
  74 Causes the screensaver process to exit gracefully.  This is a safer and
  75 easier way to kill the screensaver than by using \fIkill\fP.
  76
  77 .B Warning:
  78 never use \fIkill -9\fP with \fIxscreensaver\fP while the screensaver is
  79 active.  If you are using a virtual root window manager, that can leave
  80 things in an inconsistent state, and you may need to restart your window
  81 manager to repair the damage.
  82 .TP 8
  83 .B \-restart
  84 Causes the screensaver process to exit and then restart with the same command
  85 line arguments.  This is a good way of causing the screensaver to re-read the
  86 resource database.
  87
  88 If the screensaver is run from \fIxdm(1)\fP (that is, it is already running
  89 before you log in) then you may want to issue the ``restart'' command from
  90 one of your startup scripts, so that the screensaver gets your resource
  91 settings instead of the default ones.
  92 .TP 8
  93 .B \-version
  94 Print (on stdout) the version number of the xscreensaver program that is
  95 running on $DISPLAY.  (To see the version number of \fIxscreensaver-command\fP
  96 itself, use the \fI\-help\fP option.)
  97 .TP 8
  98 .B \-time
  99 This option prints on stdout the time at which the screensaver last activated
 100 (blanked the screen) or deactivated (restored the screen.)  Note that the
 101 activation-time is not the last time at which the user was active, but is
 102 some time later (it is the time at which either: xscreensaver decided that
 103 the user has been idle long enough; or, the user explicitly activated the
 104 screensaver or locker.)
 105 .SH ENVIRONMENT
 106 .PP
 107 .TP 8
 108 .B DISPLAY
 109 to get the host and display number of the screen whose saver is
 110 to be manipulated.
 111 .TP 8
 112 .B PATH
 113 to find the executable to restart (for the \fI\-restart\fP command).
 114 Note that this variable is consulted in the environment of
 115 the \fIxscreensaver\fP process, not the \fIxscreensaver-command\fP process.
 116 .SH "SEE ALSO"
 117 .BR X (1),
 118 .BR xscreensaver (1)
 119 .SH BUGS
 120 Some diagnostics are reported on the stderr of the \fIxscreensaver\fP
 121 process, not this process, so the caller of \fIxscreensaver-command\fP
 122 may not see the error messages.
 123 .SH COPYRIGHT
 124 Copyright \(co 1992, 1993, 1997 by Jamie Zawinski.
 125 Permission to use, copy, modify, distribute, and sell this software and its
 126 documentation for any purpose is hereby granted without fee, provided that
 127 the above copyright notice appear in all copies and that both that copyright
 128 notice and this permission notice appear in supporting documentation.  No
 129 representations are made about the suitability of this software for any
 130 purpose.  It is provided "as is" without express or implied warranty.
 131 .SH AUTHOR
 132 Jamie Zawinski <jwz@netscape.com>, 13-aug-92.