Penguin
Recent Changes
Blame: xscreensaver-command(1)
EditPageHistoryDiffInfoLikePages
Annotated edit history of xscreensaver-command(1) version 5, including all changes. View license author blame.
Rev Author # Line
1 perry 1 XScreenSaver
2 !!!XScreenSaver
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 OPTIONS
7 DIAGNOSTICS
8 ENVIRONMENT
9 UPGRADES
10 SEE ALSO
11 COPYRIGHT
12 AUTHOR
13 ----
14 !!NAME
15
16
17 xscreensaver-command - control a running xscreensaver process
18 !!SYNOPSIS
19
20
21 __xscreensaver-command__ [[-display
22 ''host:display.screen''] [[-help] [[-demo] [[-prefs]
23 [[-activate] [[-deactivate] [[-cycle] [[-next] [[-prev] [[-select
24 ''n''] [[-exit] [[-restart] [[-lock] [[-throttle]
25 [[-unthrottle] [[-version] [[-time] [[-watch]
26 !!DESCRIPTION
27
28
29 The ''xscreensaver-command'' program controls a running
30 ''xscreensaver'' process by sending it
31 client-messages.
32
33
34 xscreensaver(1) has a client-server model: the
35 xscreensaver process is a daemon that runs in the
36 background; it is controlled by other foreground programs
37 such as ''xscreensaver-command'' and
5 perry 38 xscreensaver-demo(1).
1 perry 39
40
41 This program, ''xscreensaver-command'', is a
5 perry 42 command-line-oriented tool; the xscreensaver-demo(1).
1 perry 43 program is a graphical tool.
44 !!OPTIONS
45
46
47 ''xscreensaver-command'' accepts the following
48 command-line options:
49
50
51 __-help__
52
53
54 Prints a brief summary of command-line options.
55
56
57 __-demo__
58
59
5 perry 60 This just launches the xscreensaver-demo(1) program,
1 perry 61 in which one can experiment with the various graphics hacks
62 available, and edit parameters.
63
64
65 __-demo__ ''number''
66
67
68 When the ''-demo'' option is followed by an integer, it
69 instructs the ''xscreensaver'' daemon to run that hack,
70 and wait for the user to click the mouse before deactivating
71 (i.e., mouse motion does not deactivate.) This is the
5 perry 72 mechanism by which xscreensaver-demo(1) communicates
1 perry 73 with the xscreensaver(1) daemon. (The first hack in
74 the list is numbered 1, not 0.)
75
76
77 __-prefs__
78
79
80 Like the no-argument form of ''-demo'', but brings up
81 that program's Preferences panel by default.
82
83
84 __-activate__
85
86
87 Tell xscreensaver to turn on immediately (that is, blank the
88 screen, as if the user had been idle for long enough.) The
89 screensaver will deactivate as soon as there is any user
90 activity, as usual.
91
92
93 It is useful to run this from a menu; you may wish to run it
94 as
95
96
97 sleep 5 ; xscreensaver-command -activate
98 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.)
99
100
101 __-deactivate__
102
103
104 If the screensaver is active (the screen is blanked), this
105 command will deactivate it just as if there had been
106 keyboard or mouse activity. If locking is enabled, then the
107 screensaver will prompt for a password as
108 usual.
109
110
111 __-cycle__
112
113
114 If the screensaver is active (the screen is blanked), then
115 stop the current graphics demo and run a new one (chosen
116 randomly.)
117
118
119 __-next__
120
121
122 This is like either ''-activate'' or ''-cycle'',
123 depending on which is more appropriate, except that the
124 graphics hack that will be run is the next one in the list,
125 instead of a randomly-chosen one. In other words, repeatedly
126 executing -next will cause the xscreensaver process to
127 invoke each graphics demo sequentially. (Though using the
128 ''-demo'' option is probably an easier way to accomplish
129 that.)
130
131
132 __-prev__
133
134
135 This is like ''-next'', but cycles in the other
136 direction.
137
138
139 __-select__ ''number''
140
141
142 Like ''-activate'', but runs the ''N''th element in
143 the list of hacks. By knowing what is in the ''programs''
144 list, and in what order, you can use this to activate the
145 screensaver with a particular graphics demo. (The first
146 element in the list is numbered 1, not 0.)
147
148
149 __-exit__
150
151
152 Causes the xscreensaver process to exit gracefully. This is
153 roughly the same as killing the process with kill(1),
154 but it is easier, since you don't need to first figure out
155 the pid.
156
157
158 __Warning:__ never use ''kill -9'' with
159 ''xscreensaver'' while the screensaver is active. If you
160 are using a virtual root window manager, that can leave
161 things in an inconsistent state, and you may need to restart
162 your window manager to repair the damage.
163
164
165 __-lock__
166
167
168 Tells the running xscreensaver process to lock the screen
169 immediately. This is like ''-activate'', but forces
170 locking as well, even if locking is not the default (that
171 is, even if xscreensaver's ''lock'' resource is false,
172 and even if the ''lockTimeout'' resource is
173 non-zero.)
174
175
176 Note that locking doesn't work unless the
177 ''xscreensaver'' process is running as you. See
178 xscreensaver(1) for details.
179
180
181 __-throttle__
182
183
184 Temporarily switch to ``blank screen'' mode, and don't run
185 any display modes at all, until the screensaver is next
186 de-activated. This is useful if you're using a machine
187 remotely, and you find that some display modes are using too
188 much CPU.
189
190
191 (If you want to do this ''permanently'', that is, you
192 want the screen saver to only blank the screen and not run
193 demos at all, then set the ''programs'' resource to an
194 empty list: See xscreensaver(1) for
195 details.)
196
197
198 __-unthrottle__
199
200
201 Turn `-throttle' mode off and resume normal
202 behavior.
203
204
205 __-version__
206
207
208 Prints the version of xscreensaver that is currently running
209 on the display: that is, the actual version number of the
210 running xscreensaver background process, rather than the
211 version number of xscreensaver-command. (To see the version
212 number of ''xscreensaver-command'' itself, use the
213 ''-help'' option.)
214
215
216 __-time__
217
218
219 Prints the time at which the screensaver last activated or
220 deactivated (roughly, how long the user has been idle or
221 non-idle: but not quite, since it only tells you when the
222 screen became blanked or un-blanked.)
223
224
225 __-restart__
226
227
228 Causes the screensaver process to exit and then restart with
229 the same command line arguments as last time. Do this after
230 you've changed the resource database, to cause xscreensaver
231 to notice the changes.
232
233
234 __Warning:__ if you have a ''.xscreensaver'' file,
235 this might not do what you expect. You're probably better
236 off killing the existing xscreensaver (with
237 ''xscreensaver-command -exit'') and then launching it
238 again.
239
240
241 The important point is, you need to make sure that the
242 xscreensaver process is running as you. If it's not, it
243 won't be reading the right ''.xscreensaver''
244 file.
245
246
247 __-watch__
248
249
250 Prints a line each time the screensaver changes state: when
251 the screen blanks, locks, unblanks, or when the running hack
252 is changed. This option never returns; it is intended for
253 use by shell scripts that want to react to the screensaver
254 in some way. An example of its output would be:
255
256
257 BLANK Fri Nov 5 01:57:22 1999
258 RUN 34
259 RUN 79
260 RUN 16
261 LOCK Fri Nov 5 01:57:22 1999
262 RUN 76
263 RUN 12
264 UNBLANK Fri Nov 5 02:05:59 1999
265 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 ''-select'' command.)
266
267
268 For example, suppose you want to run a program that turns
269 down the volume on your machine when the screen blanks, and
270 turns it back up when the screen un-blanks. You could do
271 that by running a Perl program like the following in the
272 background. The following program tracks the output of the
273 ''-watch'' command and reacts accordingly:
274
275
276 #!/usr/bin/perl
277 my $blanked = 0;
278 open (IN,
279 Note that LOCK might come either with or without a preceeding BLANK (depending on whether the lock-timeout is non-zero), so the above program keeps track of both of them.
280 !!DIAGNOSTICS
281
282
283 If an error occurs while communicating with the
284 ''xscreensaver'' daemon, or if the daemon reports an
285 error, a diagnostic message will be printed to stderr, and
286 ''xscreensaver-command'' will exit with a non-zero value.
287 If the command is accepted, an indication of this will be
288 printed to stdout, and the exit value will be
289 zero.
290 !!ENVIRONMENT
291
292
293 __DISPLAY__
294
295
296 to get the host and display number of the screen whose saver
297 is to be manipulated.
298
299
300 __PATH__
301
302
303 to find the executable to restart (for the ''-restart''
304 command). Note that this variable is consulted in the
305 environment of the ''xscreensaver'' process, not the
306 ''xscreensaver-command'' process.
307 !!UPGRADES
308
309
310 The latest version of xscreensaver(1) and related
311 tools can always be found at
312 http://www.jwz.org/xscreensaver/
313 !!SEE ALSO
314
315
5 perry 316 X(1), xscreensaver(1)
317 xscreensaver-demo(1)
1 perry 318 !!COPYRIGHT
319
320
321 Copyright 1992, 1993, 1997, 1998, 1999, 2000, 2001 by Jamie
322 Zawinski. Permission to use, copy, modify, distribute, and
323 sell this software and its documentation for any purpose is
324 hereby granted without fee, provided that the above
325 copyright notice appear in all copies and that both that
326 copyright notice and this permission notice appear in
327 supporting documentation. No representations are made about
328 the suitability of this software for any purpose. It is
329 provided
330 !!AUTHOR
331
332
333 Jamie Zawinski
334
335
336 Please let me know if you find any bugs or make any
337 improvements.
338 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.