1xscreensaver-command(1)       XScreenSaver manual      xscreensaver-command(1)
2
3
4

NAME

6       xscreensaver-command - control a running xscreensaver process
7

SYNOPSIS

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

DESCRIPTION

15       The  xscreensaver-command  program  controls  a  running   xscreensaver
16       process by sending it client-messages.
17
18       xscreensaver(1)  has a client-server model: the xscreensaver process is
19       a daemon that runs in the background; it is controlled by  other  fore‐
20       ground programs such as xscreensaver-command and xscreensaver-demo(1).
21
22       This  program,  xscreensaver-command,  is a command-line-oriented tool;
23       the xscreensaver-demo(1).  program is a graphical tool.
24

OPTIONS

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

STOPPING GRAPHICS

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

DIAGNOSTICS

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

ENVIRONMENT

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

UPGRADES

211       The latest version of xscreensaver(1) and related tools can  always  be
212       found at https://www.jwz.org/xscreensaver/
213

SEE ALSO

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

AUTHOR

227       Jamie Zawinski <jwz@jwz.org>, 13-aug-1992.
228
229       Please let me know if you find any bugs or make any improvements.
230
231
232
233X Version 11               5.45-1.fc33 (10-Dec-2020)   xscreensaver-command(1)
Impressum