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 | -version | -time | -watch]
12

DESCRIPTION

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

OPTIONS

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

STOPPING GRAPHICS

168       If xscreensaver is running, but you want  it  to  stop  running  screen
169       hacks (e.g., if you are logged in remotely, and you want the console to
170       remain locked but just be black, with no  graphics  processes  running)
171       you  can  accomplish that by simply powering down the monitor remotely.
172       In a minute or so, xscreensaver will notice that the  monitor  is  off,
173       and will stop running screen hacks.  You can power off the monitor like
174       so:
175       xset dpms force off
176       See the xset(1) manual for more info.
177
178       You can also use xscreensaver-demo(1) to make the  monitor  power  down
179       after a few hours, meaning that xscreensaver will run graphics until it
180       has been idle for the length of time you specified; and after that, the
181       monitor will power off, and screen hacks will stop being run.
182

DIAGNOSTICS

184       If an error occurs while communicating with the xscreensaver daemon, or
185       if the daemon reports an error, a diagnostic message will be printed to
186       stderr,  and  xscreensaver-command will exit with a non-zero value.  If
187       the command is accepted, an indication of this will be printed to  std‐
188       out, and the exit value will be zero.
189

ENVIRONMENT

191       DISPLAY to get the host and display number of the screen whose saver is
192               to be manipulated.
193
194       PATH    to find the executable to restart (for the  -restart  command).
195               Note  that this variable is consulted in the environment of the
196               xscreensaver process, not the xscreensaver-command process.
197

UPGRADES

199       The latest version of xscreensaver(1) and related tools can  always  be
200       found at https://www.jwz.org/xscreensaver/
201

SEE ALSO

203       X(1), xscreensaver(1), xscreensaver-demo(1), xset(1)
204
206       Copyright © 1992-2013 by Jamie Zawinski.  Permission to use, copy, mod‐
207       ify, distribute, and sell this software and its documentation  for  any
208       purpose  is  hereby  granted without fee, provided that the above copy‐
209       right notice appear in all copies and that both that  copyright  notice
210       and this permission notice appear in supporting documentation.  No rep‐
211       resentations are made about the suitability of this  software  for  any
212       purpose.  It is provided "as is" without express or implied warranty.
213

AUTHOR

215       Jamie Zawinski <jwz@jwz.org>, 13-aug-1992.
216
217       Please let me know if you find any bugs or make any improvements.
218
219
220
221X Version 11               5.42-1.fc29 (30-Dec-2018)   xscreensaver-command(1)
Impressum