1XScreenSaver(1)             General Commands Manual            XScreenSaver(1)
2
3
4

NAME

6       xscreensaver-command - control a running xscreensaver process
7

SYNOPSIS

9       xscreensaver-command  [--display host:display.screen] [--help | --quiet
10       | --verbose | --activate | --deactivate | --cycle | --next |  --prev  |
11       --select n | --lock | --suspend | --exit | --restart | --time | --watch
12       | --version]
13

DESCRIPTION

15       The xscreensaver-command program  controls  a  running  xscreensaver(1)
16       daemon.
17
18

OPTIONS

20       xscreensaver-command accepts the following command-line options:
21
22
23       --help  Prints a brief summary of command-line options.
24
25
26       --quiet Only print output if an error occurs.
27
28
29       --verbose
30               Opposite of --quiet. Default.
31
32
33       --activate
34               Tell  xscreensaver  to  turn on immediately (that is, blank the
35               screen, as if the user had been idle  for  long  enough.)   The
36               screensaver will deactivate as soon as there is any user activ‐
37               ity, as usual.
38
39               It is useful to run this from a menu; you may wish to run it as
40
41                    sleep 5 ; xscreensaver-command -activate
42
43               to be sure that you have time to take your hand off  the  mouse
44               before  the  screensaver  comes on.  (Because if you jiggle the
45               mouse, xscreensaver will notice, and deactivate.)
46
47
48       --deactivate
49               This tells xscreensaver to pretend that  there  has  just  been
50               user  activity.   This  means that if the screensaver is active
51               (the screen is blanked),  then  this  command  will  cause  the
52               screen  to  un-blank as if there had been keyboard or mouse ac‐
53               tivity.  If the screen is locked, then the password dialog will
54               pop  up  first,  as  usual.  If the screen is not blanked, then
55               this simulated user activity will re-start the  countdown  (so,
56               issuing  the  --deactivate  command  periodically is one way to
57               prevent the screen from blanking.)
58
59
60       --cycle If the screensaver is active (the screen is blanked), then stop
61               the current graphics demo and run a new one (chosen randomly.)
62
63
64       --next  This  is  like either --activate or --cycle, depending on which
65               is more appropriate, except that the graphics hack that will be
66               run  is  the next one in the list, instead of a randomly-chosen
67               one.  In other words, repeatedly executing -next will cause the
68               xscreensaver process to invoke each graphics demo sequentially.
69               (Though using the --settings option is probably an  easier  way
70               to accomplish that.)
71
72
73       --prev  This is like --next, but cycles in the other direction.
74
75
76       --select number
77               Like --activate, but runs the Nth element in the list of hacks.
78               By knowing what is in the programs list, and in what order, you
79               can  use  this  to  activate  the screensaver with a particular
80               graphics demo.  (The first element in the list is  numbered  1,
81               not 0.)
82
83
84       --lock  Tells the running xscreensaver process to lock the screen imme‐
85               diately.  This is like --activate, but forces locking as  well,
86               even  if  locking is not the default (that is, even if xscreen‐
87               saver's lock resource is false, and even if the lockTimeout re‐
88               source is non-zero.)
89
90               Note  that locking doesn't work unless the xscreensaver process
91               is running as you.  See xscreensaver(1) for details.
92
93
94       --suspend
95               Like --activate, but ignores lockTimeout and immediately powers
96               off  the screen without fading out.  This is intended to be run
97               just after your laptop's lid is closed, and just before the CPU
98               halts, to lock things down quickly.
99
100
101       --exit  Causes  the xscreensaver process to exit gracefully.  This does
102               nothing if the display is currently locked.
103
104               Warning: never use kill -9 with xscreensaver while the  screen‐
105               saver  is  active.  If you are using a virtual root window man‐
106               ager, that can leave things in an inconsistent state,  and  you
107               may need to restart your window manager to repair the damage.
108
109
110       --restart
111               Causes  the  screensaver  process to exit and then restart with
112               the same command line arguments as last  time.   You  shouldn't
113               really  need  to  do  this, since xscreensaver notices when the
114               .xscreensaver file has changed and re-reads it as needed.
115
116
117       --time  Prints the time at which the screensaver last activated or  de‐
118               activated  (roughly,  how  long  the user has been idle or non-
119               idle: but not quite, since it only tells you  when  the  screen
120               became blanked or un-blanked.)
121
122
123       --watch Prints a line each time the screensaver changes state: when the
124               screen blanks, locks, unblanks, or when  the  running  hack  is
125               changed.   This option never returns; it is intended for use by
126               shell scripts that want to react to  the  screensaver  in  some
127               way.  An example of its output would be:
128
129                    BLANK Fri Nov  5 01:57:22 1999
130                    RUN 34
131                    RUN 79
132                    RUN 16
133                    LOCK Fri Nov  5 01:57:22 1999
134                    RUN 76
135                    RUN 12
136                    UNBLANK Fri Nov  5 02:05:59 1999
137
138               The  above shows the screensaver activating, running three dif‐
139               ferent hacks, then locking (perhaps  because  the  lock-timeout
140               went  off) then unblanking (because the user became active, and
141               typed the correct password.)  The hack numbers are their  index
142               in  the  `programs'  list  (starting  with 1, not 0, as for the
143               --select command.)
144
145               For example, suppose you want to run a program that turns  down
146               the volume on your machine when the screen blanks, and turns it
147               back up when the screen un-blanks.  You could do that  by  run‐
148               ning  a Perl program like the following in the background.  The
149               following program tracks the output of the --watch command  and
150               reacts accordingly:
151
152                    #!/usr/bin/perl
153
154                    my $blanked = 0;
155                    open (my $in, "xscreensaver-command -watch |") || die;
156                    while (<$in>) {
157                      if (m/^(BLANK|LOCK)/) {
158                        if (!$blanked) {
159                          system ("sound-off");
160                          $blanked = 1;
161                        }
162                      } elsif (m/^UNBLANK/) {
163                        system ("sound-on");
164                        $blanked = 0;
165                      }
166                    }
167
168               Note  that  LOCK  might come either with or without a preceding
169               BLANK (depending on whether the lock-timeout is  non-zero),  so
170               the above program keeps track of both of them.
171
172
173       --version
174               Prints the version of xscreensaver that is currently running on
175               the display: that is, the actual version number of the  running
176               xscreensaver background process, rather than the version number
177               of  xscreensaver-command.   (To  see  the  version  number   of
178               xscreensaver-command itself, use the --help option.)
179
180

STOPPING GRAPHICS

182       If  xscreensaver  is  running,  but  you want it to stop running screen
183       hacks (e.g., if you are logged in remotely, and you want the console to
184       remain  locked  but  just be black, with no graphics processes running)
185       you can accomplish that by simply powering down the  monitor  remotely.
186       In  a  minute  or so, xscreensaver will notice that the monitor is off,
187       and will stop running screen hacks.  You can power off the monitor like
188       so:
189
190            xset dpms force off
191
192       See the xset(1) manual for more info.
193
194       You  can  also  use  xscreensaver-settings(1) to make the monitor power
195       down after a few hours, meaning that xscreensaver will run graphics un‐
196       til  it  has  been idle for the length of time you specified; and after
197       that, the monitor will power off, and screen hacks will stop being run.
198

DIAGNOSTICS

200       If an error occurs while communicating with the xscreensaver daemon, or
201       if the daemon reports an error, a diagnostic message will be printed to
202       stderr, and xscreensaver-command will exit with a non-zero  value.   If
203       the  command is accepted, an indication of this will be printed to std‐
204       out, and the exit value will be zero.
205

ENVIRONMENT

207       DISPLAY to get the host and display number of the screen whose saver is
208               to be manipulated.
209
210       PATH    to  find the executable to restart (for the --restart command).
211               Note that this variable is consulted in the environment of  the
212               xscreensaver process, not the xscreensaver-command process.
213

UPGRADES

215       The  latest  version of xscreensaver(1) and related tools can always be
216       found at https://www.jwz.org/xscreensaver/
217

SEE ALSO

219       X(1), xscreensaver(1), xscreensaver-settings(1), xset(1)
220
222       Copyright © 1992-2021 by Jamie Zawinski.  Permission to use, copy, mod‐
223       ify,  distribute,  and sell this software and its documentation for any
224       purpose is hereby granted without fee, provided that  the  above  copy‐
225       right  notice  appear in all copies and that both that copyright notice
226       and this permission notice appear in supporting documentation.  No rep‐
227       resentations  are  made  about the suitability of this software for any
228       purpose.  It is provided "as is" without express or implied warranty.
229

AUTHOR

231       Jamie Zawinski <jwz@jwz.org>, 13-aug-1992.
232
233       Please let me know if you find any bugs or make any improvements.
234
235
236
237X Version 11               6.02-4.fc35 (09-Nov-2021)           XScreenSaver(1)
Impressum