aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--unsaver.1141
-rw-r--r--unsaver.c110
-rw-r--r--unsaver.html152
-rw-r--r--unsaver.rst137
4 files changed, 326 insertions, 214 deletions
diff --git a/unsaver.1 b/unsaver.1
index 5a69b40..3ed224e 100644
--- a/unsaver.1
+++ b/unsaver.1
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
-.TH UNSAVER 1 "2020-05-19" "0.3.0" "Urchlay"
+.TH UNSAVER 1 "2020-05-20" "0.3.0" "Urchlay"
.SH NAME
unsaver \- deactivate screensaver on joystick activity
.
@@ -36,38 +36,41 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.
.SH SYNOPSIS
.sp
-unsaver [\fB\-i interval[s|ms]\fP] [\fB\-m\fP | \fB\-k keycode\fP | \fB\-b button\fP | \fB\-c command\fP | \fB\-x\fP ] [\fB\-d dir\fP] [\fB\-j name\fP] [\fB\-f\fP] [\fB\-F\fP] [\fB\-D\fP] [\fBjoydev [joydev ...]\fP]
+unsaver [\fB\-i interval[s|ms]\fP] [\fB\-m\fP | \fB\-k keycode\fP | \fB\-b button\fP | \fB\-c command\fP | \fB\-x\fP ] [\fB\-j\fP | \fB\-f\fP] [\fB\-d\fP] [\fBjoydev [joydev ...]\fP]
.SH DESCRIPTION
.sp
unsaver lets you play games with your joysticks/gamepads without the screen
-saver activating due to lack of keyboard/mouse input. It can also prevent
+saver activating due to lack of keyboard/mouse input. It also prevents
the screensaver from activating when a fullscreen window is in use (e.g.
while watching a movie).
.sp
-Multiple joystick devices can be monitored. By default, unsaver
-monitors up to 16 devices, named /dev/input/js0 through js15.
-These devices don\(aqt have to actually exist: they can come and go
-as joysticks are plugged in and unplugged.
+unsaver should be started from your \fB\&.xinitrc\fP or whatever X startup
+script your window manager or desktop environment uses. By default, it
+will exit when the X server does. There\(aqs no PID file: use "pkill unsaver"
+if you need to kill the daemon.
.sp
Every \fIinterval\fP milliseconds (250, or whatever \fB\-i\fP is set to), unsaver
checks to see if there\(aqs been any activity on any of the devices it\(aqs
monitoring. If so, it sends a fake mouse movement, keystroke, or mouse
button click, which the screen saver will see as activity.
.sp
-It\(aqs recommended to let unsaver find the joysticks itself. However,
-you can pass one or more device names (or just numbers) if the default
-doesn\(aqt do the right thing for you. In this case, only these devices
-will be monitored (no search is done).
-.sp
-unsaver should be started from your \fB\&.xinitrc\fP or whatever X startup
-script your window manager or desktop environment uses. By default, it
-will exit when the X server does. There\(aqs no PID file: use "pkill unsaver"
-if you need to kill the daemon.
+Multiple joystick devices can be monitored. By default, unsaver
+monitors up to 16 devices, named /dev/input/js0 through js15.
+These devices don\(aqt have to actually exist: they can come and go
+as joysticks are plugged in and unplugged. See JOYSTICK DEVICES
+if the defaults don\(aqt work for you.
.SH OPTIONS
+.SS General options
.INDENT 0.0
.TP
.B \-\-help
-Print usage summary
+Print usage summary and exit.
+.TP
+.B \-d
+Debug mode: run in foreground and print verbose messages.
+.UNINDENT
+.SS Monitoring options
+.INDENT 0.0
.TP
.BI \-i \ <interval>
Interval to check for activity. Can be given in seconds
@@ -76,6 +79,20 @@ with \fIs\fP suffix (e.g. \fB1s\fP), or milliseconds with \fIm\fP
to be in seconds if it\(aqs under 100, otherwise it\(aqs treated
as milliseconds. Default: 250m.
.TP
+.B \-j
+Only monitor joysticks; don\(aqt try to detect fullscreen windows.
+\fB\-j\fP and \fB\-f\fP are mutually exclusive.
+.TP
+.B \-f
+Only detect fullscreen windows; don\(aqt monitor joysticks.
+\fB\-j\fP and \fB\-f\fP are mutually exclusive. Note that
+\fBjoydevs\fP are ignored with \fB\-f\fP\&.
+.UNINDENT
+.SS Deactivation mode options
+.sp
+Only one of \fB\-k\fP/\fB\-b\fP/\fB\-m\fP/\fB\-c\fP/\fB\-x\fP is accepted.
+.INDENT 0.0
+.TP
.BI \-k \ <keycode>
Send this keycode when activity is detected. Default
is to search the keymap for an unused code. If you set this
@@ -103,61 +120,25 @@ option, to avoid excess process\-spawning overhead.
.TP
.B \-x
Same as \fB\-c "xscreensaver\-command \-deactivate" \-i 1s\fP\&.
-.TP
-.B \-f
-Deactivate screensaver if a fullscreen window is detected.
-This isn\(aqt likely to be 100% reliable yet.
-.TP
-.B \-F
-Same as \fB\-f\fP, but also disables joystick monitoring entirely.
-Note that \fB\-j\fP, \fB\-d\fP, and \fBjoydev\fP are ignored
-with this option.
-.UNINDENT
-.sp
-These options are intended for developers and \fIreally\fP shouldn\(aqt be
-needed for normal use:
-.INDENT 0.0
-.TP
-.BI \-d \ <dir>
-Path to the directory containing joystick device nodes.
-Default is "/dev/input". This directory is monitored with
-inotify(7) so unsaver will be aware of hotplug events.
-.TP
-.BI \-j \ <name>
-Name of joystick device nodes, without any numeric
-suffix. Default is "js".
-.TP
-.B \-D
-Debug mode: run in foreground and print verbose messages.
.UNINDENT
.sp
A space is required between an option and its argument, as shown
above. Use e.g. \fB\-i 300\fP, not \fB\-i300\fP\&.
.SH NOTES
.sp
-unsaver was tested with xlock(1) and xscreensaver(1). All 3 modes
-(keycode, mouse click, and mouse motion) work with xscreensaver.
-xlock doesn\(aqt respond to mouse motion, so use the keycode or click
-modes with it.
+unsaver was tested with xlock(1), xscreensaver(1), and the built\-in
+Xorg screensaver (see xset(1)). All 4 modes (keycode, mouse click, mouse
+motion, command execution) work with xscreensaver. xlock doesn\(aqt have a
+disable command nor respond to mouse motion, so use the keycode or click
+modes with it. The "xset s" screen\-blanker works with keycodes, mouse
+clicks, and mouse motion. I didn\(aqt test with gnome\-screensaver, sorry.
.sp
unsaver can monitor up to MAX_STICKS joysticks. This is a compile time
constant, normally set to 16. See the \fB\-\-help\fP output to find out
the compiled\-in default.
.sp
-\fBjoydev\fP arguments can be either a path to a device node (e.g.
-\fI/dev/input/js0\fP or similar), or a number, which will have the default
-device basename prepended to it. This is normally "/dev/input/js", but
-can be changed via the \fB\-d\fP and \fB\-j\fP options. Note that (currently)
-all the joystick devices have to be in the same directory for unsaver
-to detect hotplug events!
-.sp
-Note that it\(aqs \fInot\fP an error to give nonexistent joystick device names.
-unsaver will wait for devices to come into existence (e.g. as created
-by \fBudev\fP).
-.sp
If the screensaver is configured to lock the screen, and it has already
-done so, pressing a joystick button/direction will just bring up the
-password dialog, same as pressing a key or mouse button would.
+done so, unsaver can\(aqt magically type your password for you.
.sp
unsaver depends on the XTest extension being present in the X server. If
you get a "X server doesn\(aqt support XTest extension" error, see your X
@@ -165,15 +146,43 @@ server documentation to find out how to enable XTest.
.sp
The fullscreen window monitoring has only been tested on a system with
a single monitor, and may not work properly in multi\-head environments.
+.SH JOYSTICK DEVICES
+.sp
+It\(aqs recommended to let unsaver find the joysticks itself. However, you
+can pass one or more joystick numbers if the default doesn\(aqt do the right
+thing for you. Remember that the first joystick is numbered 0, not 1.
+.sp
+When you manually set the list of devices, unsaver will only detect
+hotplug events on the devices you gave it. If you plug in more joysticks,
+they won\(aqt be monitored.
+.sp
+None of the joystick devices (whether autodetected or not) has to
+actually exist when unsaver starts up, although their directory does
+have to exist. This means unsaver can detect hotplug events, but you
+have to be careful not to typo the device names.
+.sp
+If your system doesn\(aqt keep its joystick device nodes in /dev/input, and/or
+if they\(aqre not named "js<num>", see ENVIRONMENT for a way to override
+the default names.
+.SH ENVIRONMENT
+.INDENT 0.0
+.TP
+.B UNSAVER_JS_DIR Path to joystick device nodes. If your OS keeps them
+somewhere besides "/dev/input", set this variable.
+.TP
+.B UNSAVER_JS_NODE Base name for joystick device nodes. "js" by default.
+\fIDon\(aqt\fP set this to "event", unsaver doesn\(aqt speak the
+full Linux event protocol.
+.UNINDENT
.SH EXIT STATUS
.sp
-Without the \-D option, the exit status is 0 (success) if unsaver
+Without the \-d option, the exit status is 0 (success) if unsaver
successfully forked into the background.
.sp
A non\-zero exit status means an error in the command line arguments,
or else fork() failed. No daemon will be running in this case.
.sp
-With the \-D option, unsaver never exits until it\(aqs killed.
+With the \-d option, unsaver never exits until it\(aqs killed.
.SH BUGS
.sp
There\(aqs no way to distinguish between an invalid device name and a
@@ -188,9 +197,15 @@ be a log file, or use syslog (or is that overkill?).
It should be (but currently isn\(aqt) possible to at least work in
mouse\-motion mode even without the XTest extension, via XWarpPointer().
.sp
+I \fIreally\fP need to use the XKB extension rather than the old & deprecated
+Xlib keyboard API. This mainly affects the default "find an unused
+keycode" mode.
+.sp
unsaver isn\(aqt portable. It only works on Linux, at least for now, for
three reasons:
.INDENT 0.0
+.INDENT 3.5
+.INDENT 0.0
.IP \(bu 2
It uses the Linux joystick API.
.IP \(bu 2
@@ -199,6 +214,8 @@ It uses inotify(7) to detect joystick hotplug events.
I haven\(aqt even looked at other OSes to see if it would be possible
to port the code.
.UNINDENT
+.UNINDENT
+.UNINDENT
.\" EXAMPLES
.
.\" ========
diff --git a/unsaver.c b/unsaver.c
index eceb4d3..a612ff2 100644
--- a/unsaver.c
+++ b/unsaver.c
@@ -47,16 +47,16 @@ typedef enum {
/* user options */
int interval = DEFAULT_INTERVAL; /* -i (always in millisec) */
-int debug = 0; /* -D */
+int debug = 0; /* -d */
int keycode = -1; /* -k */
int button = -1; /* -b */
-char *event_dir = EVENTDIR; /* -d */
+const char *event_dir = EVENTDIR; /* joydev args can change this */
char *js_node_name = JSNODE; /* -j */
int autodiscover = 1; /* cleared if user supplies joydev args */
fake_mode_t fake_mode = fm_auto_keycode; /* -k, -b, -m */
char *c_command = NULL; /* -c, -x */
-int monitor_joysticks = 1; /* -F */
-int monitor_fullscreen = 0; /* -f, -F */
+int monitor_joysticks = 1; /* -f clears this */
+int monitor_fullscreen = 1; /* -j clears this */
/* joystick stuff */
char *joynames[MAX_STICKS + 1];
@@ -77,8 +77,8 @@ struct inotify_event *inotify_ev = (struct inotify_event *)inotify_buf;
/* not going to include pages of usage info duplicating the man page */
void usage(void) {
printf(PROJ " v" VERSION " by B. Watson, WTFPL\n");
- printf("Usage: %s [-i interval] [-b button | -k keycode] [-j name]\n", self);
- printf(" [-d dir] [-D] [joystick [...]]\n");
+ printf("Usage: %s [-i interval] [-m | -b button | -k keycode | -c command | -x]\n", self);
+ printf(" [-j | -f ] [-d] [inputdir] [joystick [...]]\n");
printf("Built-in defaults: MAX_STICKS=%d, -d " EVENTDIR ", -j " JSNODE "\n", MAX_STICKS);
printf("See man page for details\n");
exit(0);
@@ -206,6 +206,39 @@ void send_fake_x_event(void) {
}
}
+/* wrapper for open(2), does an ioctl to make sure the thing it just
+ opened really is a joystick. also warns on 'permission denied'. */
+int js_open(const char *path, int mode) {
+ int fd, res, ver;
+
+ fd = open(path, mode);
+
+ if(fd < 0 && errno == EACCES)
+ fprintf(stderr, "%s: warning: %s exists, but: %s\n",
+ self, path, strerror(errno));
+
+ if(fd > -1) {
+ res = ioctl(fd, JSIOCGVERSION, &ver);
+
+ if(res < 0) {
+ if(errno == ENOTTY || errno == EINVAL) {
+ fprintf(stderr, "%s: file %s is not a joystick\n", self, path);
+ exit(1);
+ } else {
+ fprintf(stderr, "%s: %s: %s\n", self, path, strerror(errno));
+ exit(1);
+ }
+ }
+
+ /* don't really need this much detail:
+ if(debug)
+ fprintf(stderr, "joystick driver version 0x%x\n", ver);
+ */
+ }
+
+ return fd;
+}
+
void open_joysticks(void) {
int fdcount, i;
struct js_event e;
@@ -214,7 +247,7 @@ void open_joysticks(void) {
for(i = 0; i < last_joyname; i++) {
int synthev = 0;
if(joyfds[i] > -1) close(joyfds[i]);
- joyfds[i] = open(joynames[i], O_RDONLY | O_NONBLOCK);
+ joyfds[i] = js_open(joynames[i], O_RDONLY | O_NONBLOCK);
if(joyfds[i] > -1) {
fdcount++;
while( (read(joyfds[i], &e, sizeof(e)) > 0) && (e.type & JS_EVENT_INIT) )
@@ -389,7 +422,7 @@ void set_exe_name(const char *argv0) {
if(p[0] == '/' && p[1]) self = p + 1;
}
-char *make_joystick_name(int js) {
+char *joy_num_to_name(int js) {
static char buf[PATH_MAX + 1];
sprintf(buf, "%s/%s%d", event_dir, js_node_name, js);
return buf;
@@ -407,7 +440,7 @@ void add_joystick_name(const char *name) {
}
if(*name >= '0' && *name <= '9') {
- add_joystick_name(make_joystick_name(atoi(name)));
+ add_joystick_name(joy_num_to_name(atoi(name)));
return;
}
@@ -415,16 +448,30 @@ void add_joystick_name(const char *name) {
die(strerror(errno));
if(debug)
- fprintf(stderr, "added device name %d: %s\n", last_joyname, name);
+ fprintf(stderr, "added device %d: %s\n", last_joyname, joynames[last_joyname]);
last_joyname++;
}
+void add_joystick_num(char *arg) {
+ int i;
+ char *end;
+
+ i = strtol(arg, &end, 0);
+
+ if(end == arg || *end || i < 0) {
+ fprintf(stderr, "%s: invalid joystick number: %s\n", self, arg);
+ exit(1);
+ }
+
+ add_joystick_name(joy_num_to_name(i));
+}
+
void populate_joynames(void) {
int i;
for(i = 0; i < MAX_STICKS; i++) {
- add_joystick_name(make_joystick_name(i));
+ add_joystick_name(joy_num_to_name(i));
}
}
@@ -474,7 +521,7 @@ void parse_args(int argc, char **argv) {
while(++argv, --argc) {
if(argv[0][0] != '-') {
/* no dash, treat as a joystick device */
- add_joystick_name(*argv);
+ add_joystick_num(*argv);
autodiscover = 0;
} else {
if(argv[0][1] && argv[0][2])
@@ -516,22 +563,6 @@ void parse_args(int argc, char **argv) {
die("-i requires a positive integer argument in milliseconds");
break;
case 'd':
- if(nextarg) {
- event_dir = nextarg;
- argv++, argc--;
- } else {
- die("-d requires a directory argument");
- }
- break;
- case 'j':
- if(nextarg) {
- js_node_name = nextarg;
- argv++, argc--;
- } else {
- die("-j requires a string argument");
- }
- break;
- case 'D':
debug = 1;
break;
case 'c':
@@ -547,10 +578,11 @@ void parse_args(int argc, char **argv) {
set_fake_mode(fm_cmd);
c_command = X_COMMAND;
break;
- case 'F':
- monitor_joysticks = 0; /* and fall thru */
case 'f':
- monitor_fullscreen = 1;
+ monitor_joysticks = 0;
+ break;
+ case 'j':
+ monitor_fullscreen = 0;
break;
default:
die("unrecognized argument, try --help");
@@ -558,6 +590,9 @@ void parse_args(int argc, char **argv) {
}
}
}
+
+ if(!monitor_joysticks && !monitor_fullscreen)
+ die("nothing to monitor (can't use -f and -j together)");
}
/* make ourselves a daemon, double-fork technique.
@@ -731,9 +766,22 @@ void print_banner() {
self, VERSION, m, interval);
}
+void read_env_vars(void) {
+ char *tmp;
+
+ if( (tmp = getenv("UNSAVER_JS_DIR")) )
+ event_dir = tmp;
+
+ if( (tmp = getenv("UNSAVER_JS_NODE")) )
+ js_node_name = tmp;
+
+}
+
int main(int argc, char **argv) {
set_exe_name(argv[0]);
+ read_env_vars();
+
parse_args(argc, argv);
print_banner();
diff --git a/unsaver.html b/unsaver.html
index 7d3ce80..04e1e92 100644
--- a/unsaver.html
+++ b/unsaver.html
@@ -5,7 +5,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.14: http://docutils.sourceforge.net/" />
<title>unsaver</title>
-<meta name="date" content="2020-05-19" />
+<meta name="date" content="2020-05-20" />
<style type="text/css">
/*
@@ -373,7 +373,7 @@ ul.auto-toc {
<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Urchlay</td>
</tr>
<tr><th class="docinfo-name">Date:</th>
-<td>2020-05-19</td></tr>
+<td>2020-05-20</td></tr>
<tr><th class="docinfo-name">Version:</th>
<td>0.3.0</td></tr>
</tbody>
@@ -382,40 +382,51 @@ ul.auto-toc {
<!-- rst2man.py unsaver.rst > unsaver.1 -->
<div class="section" id="synopsis">
<h1>SYNOPSIS</h1>
-<p>unsaver [<strong>-i interval[s|ms]</strong>] [<strong>-m</strong> | <strong>-k keycode</strong> | <strong>-b button</strong> | <strong>-c command</strong> | <strong>-x</strong> ] [<strong>-d dir</strong>] [<strong>-j name</strong>] [<strong>-f</strong>] [<strong>-F</strong>] [<strong>-D</strong>] [<strong>joydev [joydev ...]</strong>]</p>
+<p>unsaver [<strong>-i interval[s|ms]</strong>] [<strong>-m</strong> | <strong>-k keycode</strong> | <strong>-b button</strong> | <strong>-c command</strong> | <strong>-x</strong> ] [<strong>-j</strong> | <strong>-f</strong>] [<strong>-d</strong>] [<strong>joydev [joydev ...]</strong>]</p>
</div>
<div class="section" id="description">
<h1>DESCRIPTION</h1>
<p>unsaver lets you play games with your joysticks/gamepads without the screen
-saver activating due to lack of keyboard/mouse input. It can also prevent
+saver activating due to lack of keyboard/mouse input. It also prevents
the screensaver from activating when a fullscreen window is in use (e.g.
while watching a movie).</p>
-<p>Multiple joystick devices can be monitored. By default, unsaver
-monitors up to 16 devices, named /dev/input/js0 through js15.
-These devices don't have to actually exist: they can come and go
-as joysticks are plugged in and unplugged.</p>
-<p>Every <em>interval</em> milliseconds (250, or whatever <strong>-i</strong> is set to), unsaver
-checks to see if there's been any activity on any of the devices it's
-monitoring. If so, it sends a fake mouse movement, keystroke, or mouse
-button click, which the screen saver will see as activity.</p>
-<p>It's recommended to let unsaver find the joysticks itself. However,
-you can pass one or more device names (or just numbers) if the default
-doesn't do the right thing for you. In this case, only these devices
-will be monitored (no search is done).</p>
<p>unsaver should be started from your <strong>.xinitrc</strong> or whatever X startup
script your window manager or desktop environment uses. By default, it
will exit when the X server does. There's no PID file: use &quot;pkill unsaver&quot;
if you need to kill the daemon.</p>
+<p>Every <em>interval</em> milliseconds (250, or whatever <strong>-i</strong> is set to), unsaver
+checks to see if there's been any activity on any of the devices it's
+monitoring. If so, it sends a fake mouse movement, keystroke, or mouse
+button click, which the screen saver will see as activity.</p>
+<p>Multiple joystick devices can be monitored. By default, unsaver
+monitors up to 16 devices, named /dev/input/js0 through js15.
+These devices don't have to actually exist: they can come and go
+as joysticks are plugged in and unplugged. See JOYSTICK DEVICES
+if the defaults don't work for you.</p>
</div>
<div class="section" id="options">
<h1>OPTIONS</h1>
+<div class="section" id="general-options">
+<h2>General options</h2>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">--help</span></kbd></td>
-<td>Print usage summary</td></tr>
+<td>Print usage summary and exit.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">-d</span></kbd></td>
+<td>Debug mode: run in foreground and print verbose messages.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="monitoring-options">
+<h2>Monitoring options</h2>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">-i <var>&lt;interval&gt;</var></span></kbd></td>
<td>Interval to check for activity. Can be given in seconds
@@ -424,6 +435,25 @@ with <em>s</em> suffix (e.g. <strong>1s</strong>), or milliseconds with <em>m</e
to be in seconds if it's under 100, otherwise it's treated
as milliseconds. Default: 250m.</td></tr>
<tr><td class="option-group">
+<kbd><span class="option">-j</span></kbd></td>
+<td>Only monitor joysticks; don't try to detect fullscreen windows.
+<strong>-j</strong> and <strong>-f</strong> are mutually exclusive.</td></tr>
+<tr><td class="option-group">
+<kbd><span class="option">-f</span></kbd></td>
+<td>Only detect fullscreen windows; don't monitor joysticks.
+<strong>-j</strong> and <strong>-f</strong> are mutually exclusive. Note that
+<strong>joydevs</strong> are ignored with <strong>-f</strong>.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="deactivation-mode-options">
+<h2>Deactivation mode options</h2>
+<p>Only one of <strong>-k</strong>/<strong>-b</strong>/<strong>-m</strong>/<strong>-c</strong>/<strong>-x</strong> is accepted.</p>
+<table class="docutils option-list" frame="void" rules="none">
+<col class="option" />
+<col class="description" />
+<tbody valign="top">
+<tr><td class="option-group">
<kbd><span class="option">-k <var>&lt;keycode&gt;</var></span></kbd></td>
<td>Send this keycode when activity is detected. Default
is to search the keymap for an unused code. If you set this
@@ -451,74 +481,65 @@ option, to avoid excess process-spawning overhead.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-x</span></kbd></td>
<td>Same as <strong>-c &quot;xscreensaver-command -deactivate&quot; -i 1s</strong>.</td></tr>
-<tr><td class="option-group">
-<kbd><span class="option">-f</span></kbd></td>
-<td>Deactivate screensaver if a fullscreen window is detected.
-This isn't likely to be 100% reliable yet.</td></tr>
-<tr><td class="option-group">
-<kbd><span class="option">-F</span></kbd></td>
-<td>Same as <strong>-f</strong>, but also disables joystick monitoring entirely.
-Note that <strong>-j</strong>, <strong>-d</strong>, and <strong>joydev</strong> are ignored
-with this option.</td></tr>
-</tbody>
-</table>
-<p>These options are intended for developers and <em>really</em> shouldn't be
-needed for normal use:</p>
-<table class="docutils option-list" frame="void" rules="none">
-<col class="option" />
-<col class="description" />
-<tbody valign="top">
-<tr><td class="option-group">
-<kbd><span class="option">-d <var>&lt;dir&gt;</var></span></kbd></td>
-<td>Path to the directory containing joystick device nodes.
-Default is &quot;/dev/input&quot;. This directory is monitored with
-inotify(7) so unsaver will be aware of hotplug events.</td></tr>
-<tr><td class="option-group">
-<kbd><span class="option">-j <var>&lt;name&gt;</var></span></kbd></td>
-<td>Name of joystick device nodes, without any numeric
-suffix. Default is &quot;js&quot;.</td></tr>
-<tr><td class="option-group">
-<kbd><span class="option">-D</span></kbd></td>
-<td>Debug mode: run in foreground and print verbose messages.</td></tr>
</tbody>
</table>
<p>A space is required between an option and its argument, as shown
above. Use e.g. <strong>-i 300</strong>, not <strong>-i300</strong>.</p>
</div>
+</div>
<div class="section" id="notes">
<h1>NOTES</h1>
-<p>unsaver was tested with xlock(1) and xscreensaver(1). All 3 modes
-(keycode, mouse click, and mouse motion) work with xscreensaver.
-xlock doesn't respond to mouse motion, so use the keycode or click
-modes with it.</p>
+<p>unsaver was tested with xlock(1), xscreensaver(1), and the built-in
+Xorg screensaver (see xset(1)). All 4 modes (keycode, mouse click, mouse
+motion, command execution) work with xscreensaver. xlock doesn't have a
+disable command nor respond to mouse motion, so use the keycode or click
+modes with it. The &quot;xset s&quot; screen-blanker works with keycodes, mouse
+clicks, and mouse motion. I didn't test with gnome-screensaver, sorry.</p>
<p>unsaver can monitor up to MAX_STICKS joysticks. This is a compile time
constant, normally set to 16. See the <strong>--help</strong> output to find out
the compiled-in default.</p>
-<p><strong>joydev</strong> arguments can be either a path to a device node (e.g.
-<em>/dev/input/js0</em> or similar), or a number, which will have the default
-device basename prepended to it. This is normally &quot;/dev/input/js&quot;, but
-can be changed via the <strong>-d</strong> and <strong>-j</strong> options. Note that (currently)
-all the joystick devices have to be in the same directory for unsaver
-to detect hotplug events!</p>
-<p>Note that it's <em>not</em> an error to give nonexistent joystick device names.
-unsaver will wait for devices to come into existence (e.g. as created
-by <strong>udev</strong>).</p>
<p>If the screensaver is configured to lock the screen, and it has already
-done so, pressing a joystick button/direction will just bring up the
-password dialog, same as pressing a key or mouse button would.</p>
+done so, unsaver can't magically type your password for you.</p>
<p>unsaver depends on the XTest extension being present in the X server. If
you get a &quot;X server doesn't support XTest extension&quot; error, see your X
server documentation to find out how to enable XTest.</p>
<p>The fullscreen window monitoring has only been tested on a system with
a single monitor, and may not work properly in multi-head environments.</p>
</div>
+<div class="section" id="joystick-devices">
+<h1>JOYSTICK DEVICES</h1>
+<p>It's recommended to let unsaver find the joysticks itself. However,
+you can pass one or more device names (or just numbers) if the default
+doesn't do the right thing for you.</p>
+<p>If you do use them, the <em>joydev</em> arguments can be one of 3 things:</p>
+<blockquote>
+<ul class="simple">
+<li>The first argument can optionally be a directory, which must exist.
+The default is &quot;/dev/input&quot;. unsaver will look for joystick devices here.
+If there are no more <em>joydev</em> arguments, unsaver will monitor devices
+and detect hotplug events on devices js0 through js15 in this directory.</li>
+<li>One or more numbers. unsaver will prepend the directory and &quot;js&quot; to each number,
+and monitor that device. Hotplug events will be detected <em>only</em> for
+the specified devices. You could use this e.g. to not monitor your
+2nd joystick, because it sometimes drifts and reports false events.</li>
+<li>One or more device nodes (e.g. js0). Use relative paths here (relative
+to the directory argument or &quot;/dev/input&quot;). This option only exists
+for future-proofing (in case the js name changes someday). Hotplug
+events will be detected <em>only</em> for the specified devices.</li>
+</ul>
+</blockquote>
+<p>None of the joystick devices (whether autodetected, named, or numbered)
+has to actually exist when unsaver starts up, although their directory
+does have to exist. This means unsaver can detect hotplug events, but
+you have to be careful not to typo the device names.</p>
+</div>
<div class="section" id="exit-status">
<h1>EXIT STATUS</h1>
-<p>Without the -D option, the exit status is 0 (success) if unsaver
+<p>Without the -d option, the exit status is 0 (success) if unsaver
successfully forked into the background.</p>
<p>A non-zero exit status means an error in the command line arguments,
or else fork() failed. No daemon will be running in this case.</p>
-<p>With the -D option, unsaver never exits until it's killed.</p>
+<p>With the -d option, unsaver never exits until it's killed.</p>
</div>
<div class="section" id="bugs">
<h1>BUGS</h1>
@@ -531,14 +552,19 @@ does go wrong, there's no way to find out what. Probably there should
be a log file, or use syslog (or is that overkill?).</p>
<p>It should be (but currently isn't) possible to at least work in
mouse-motion mode even without the XTest extension, via XWarpPointer().</p>
+<p>I <em>really</em> need to use the XKB extension rather than the old &amp; deprecated
+Xlib keyboard API. This mainly affects the default &quot;find an unused
+keycode&quot; mode.</p>
<p>unsaver isn't portable. It only works on Linux, at least for now, for
three reasons:</p>
+<blockquote>
<ul class="simple">
<li>It uses the Linux joystick API.</li>
<li>It uses inotify(7) to detect joystick hotplug events.</li>
<li>I haven't even looked at other OSes to see if it would be possible
to port the code.</li>
</ul>
+</blockquote>
<!-- EXAMPLES -->
<!-- ======== -->
</div>
diff --git a/unsaver.rst b/unsaver.rst
index 6e6f1dd..b66e2ad 100644
--- a/unsaver.rst
+++ b/unsaver.rst
@@ -20,40 +20,44 @@ deactivate screensaver on joystick activity
SYNOPSIS
========
-unsaver [**-i interval[s|ms]**] [**-m** | **-k keycode** | **-b button** | **-c command** | **-x** ] [**-d dir**] [**-j name**] [**-f**] [**-F**] [**-D**] [**joydev [joydev ...]**]
+unsaver [**-i interval[s|ms]**] [**-m** | **-k keycode** | **-b button** | **-c command** | **-x** ] [**-j** | **-f**] [**-d**] [**joydev [joydev ...]**]
DESCRIPTION
===========
unsaver lets you play games with your joysticks/gamepads without the screen
-saver activating due to lack of keyboard/mouse input. It can also prevent
+saver activating due to lack of keyboard/mouse input. It also prevents
the screensaver from activating when a fullscreen window is in use (e.g.
while watching a movie).
-Multiple joystick devices can be monitored. By default, unsaver
-monitors up to 16 devices, named /dev/input/js0 through js15.
-These devices don't have to actually exist: they can come and go
-as joysticks are plugged in and unplugged.
+unsaver should be started from your **.xinitrc** or whatever X startup
+script your window manager or desktop environment uses. By default, it
+will exit when the X server does. There's no PID file: use "pkill unsaver"
+if you need to kill the daemon.
Every *interval* milliseconds (250, or whatever **-i** is set to), unsaver
checks to see if there's been any activity on any of the devices it's
monitoring. If so, it sends a fake mouse movement, keystroke, or mouse
button click, which the screen saver will see as activity.
-It's recommended to let unsaver find the joysticks itself. However,
-you can pass one or more device names (or just numbers) if the default
-doesn't do the right thing for you. In this case, only these devices
-will be monitored (no search is done).
-
-unsaver should be started from your **.xinitrc** or whatever X startup
-script your window manager or desktop environment uses. By default, it
-will exit when the X server does. There's no PID file: use "pkill unsaver"
-if you need to kill the daemon.
+Multiple joystick devices can be monitored. By default, unsaver
+monitors up to 16 devices, named /dev/input/js0 through js15.
+These devices don't have to actually exist: they can come and go
+as joysticks are plugged in and unplugged. See JOYSTICK DEVICES
+if the defaults don't work for you.
OPTIONS
=======
---help Print usage summary
+General options
+---------------
+
+--help Print usage summary and exit.
+
+-d Debug mode: run in foreground and print verbose messages.
+
+Monitoring options
+------------------
-i <interval> Interval to check for activity. Can be given in seconds
with *s* suffix (e.g. **1s**), or milliseconds with *m*
@@ -61,6 +65,18 @@ OPTIONS
to be in seconds if it's under 100, otherwise it's treated
as milliseconds. Default: 250m.
+-j Only monitor joysticks; don't try to detect fullscreen windows.
+ **-j** and **-f** are mutually exclusive.
+
+-f Only detect fullscreen windows; don't monitor joysticks.
+ **-j** and **-f** are mutually exclusive. Note that
+ **joydevs** are ignored with **-f**.
+
+Deactivation mode options
+-------------------------
+
+Only one of **-k**/**-b**/**-m**/**-c**/**-x** is accepted.
+
-k <keycode> Send this keycode when activity is detected. Default
is to search the keymap for an unused code. If you set this
manually, it should be a keycode that *doesn't* map to a keysym
@@ -84,54 +100,25 @@ OPTIONS
-x Same as **-c "xscreensaver-command -deactivate" -i 1s**.
--f Deactivate screensaver if a fullscreen window is detected.
- This isn't likely to be 100% reliable yet.
-
--F Same as **-f**, but also disables joystick monitoring entirely.
- Note that **-j**, **-d**, and **joydev** are ignored
- with this option.
-
-These options are intended for developers and *really* shouldn't be
-needed for normal use:
-
--d <dir> Path to the directory containing joystick device nodes.
- Default is "/dev/input". This directory is monitored with
- inotify(7) so unsaver will be aware of hotplug events.
-
--j <name> Name of joystick device nodes, without any numeric
- suffix. Default is "js".
-
--D Debug mode: run in foreground and print verbose messages.
-
A space is required between an option and its argument, as shown
above. Use e.g. **-i 300**, not **-i300**.
NOTES
=====
-unsaver was tested with xlock(1) and xscreensaver(1). All 3 modes
-(keycode, mouse click, and mouse motion) work with xscreensaver.
-xlock doesn't respond to mouse motion, so use the keycode or click
-modes with it.
+unsaver was tested with xlock(1), xscreensaver(1), and the built-in
+Xorg screensaver (see xset(1)). All 4 modes (keycode, mouse click, mouse
+motion, command execution) work with xscreensaver. xlock doesn't have a
+disable command nor respond to mouse motion, so use the keycode or click
+modes with it. The "xset s" screen-blanker works with keycodes, mouse
+clicks, and mouse motion. I didn't test with gnome-screensaver, sorry.
unsaver can monitor up to MAX_STICKS joysticks. This is a compile time
constant, normally set to 16. See the **--help** output to find out
the compiled-in default.
-**joydev** arguments can be either a path to a device node (e.g.
-*/dev/input/js0* or similar), or a number, which will have the default
-device basename prepended to it. This is normally "/dev/input/js", but
-can be changed via the **-d** and **-j** options. Note that (currently)
-all the joystick devices have to be in the same directory for unsaver
-to detect hotplug events!
-
-Note that it's *not* an error to give nonexistent joystick device names.
-unsaver will wait for devices to come into existence (e.g. as created
-by **udev**).
-
If the screensaver is configured to lock the screen, and it has already
-done so, pressing a joystick button/direction will just bring up the
-password dialog, same as pressing a key or mouse button would.
+done so, unsaver can't magically type your password for you.
unsaver depends on the XTest extension being present in the X server. If
you get a "X server doesn't support XTest extension" error, see your X
@@ -140,16 +127,46 @@ server documentation to find out how to enable XTest.
The fullscreen window monitoring has only been tested on a system with
a single monitor, and may not work properly in multi-head environments.
+JOYSTICK DEVICES
+================
+
+It's recommended to let unsaver find the joysticks itself. However, you
+can pass one or more joystick numbers if the default doesn't do the right
+thing for you. Remember that the first joystick is numbered 0, not 1.
+
+When you manually set the list of devices, unsaver will only detect
+hotplug events on the devices you gave it. If you plug in more joysticks,
+they won't be monitored.
+
+None of the joystick devices (whether autodetected or not) has to
+actually exist when unsaver starts up, although their directory does
+have to exist. This means unsaver can detect hotplug events, but you
+have to be careful not to typo the device names.
+
+If your system doesn't keep its joystick device nodes in /dev/input, and/or
+if they're not named "js<num>", see ENVIRONMENT for a way to override
+the default names.
+
+ENVIRONMENT
+===========
+
+UNSAVER_JS_DIR Path to joystick device nodes. If your OS keeps them
+ somewhere besides "/dev/input", set this variable.
+
+UNSAVER_JS_NODE Base name for joystick device nodes. "js" by default.
+ *Don't* set this to "event", unsaver doesn't speak the
+ full Linux event protocol.
+
EXIT STATUS
===========
-Without the -D option, the exit status is 0 (success) if unsaver
+Without the -d option, the exit status is 0 (success) if unsaver
successfully forked into the background.
A non-zero exit status means an error in the command line arguments,
or else fork() failed. No daemon will be running in this case.
-With the -D option, unsaver never exits until it's killed.
+With the -d option, unsaver never exits until it's killed.
BUGS
====
@@ -166,15 +183,19 @@ be a log file, or use syslog (or is that overkill?).
It should be (but currently isn't) possible to at least work in
mouse-motion mode even without the XTest extension, via XWarpPointer().
+I *really* need to use the XKB extension rather than the old & deprecated
+Xlib keyboard API. This mainly affects the default "find an unused
+keycode" mode.
+
unsaver isn't portable. It only works on Linux, at least for now, for
three reasons:
-- It uses the Linux joystick API.
+ - It uses the Linux joystick API.
-- It uses inotify(7) to detect joystick hotplug events.
+ - It uses inotify(7) to detect joystick hotplug events.
-- I haven't even looked at other OSes to see if it would be possible
- to port the code.
+ - I haven't even looked at other OSes to see if it would be possible
+ to port the code.
.. EXAMPLES
.. ========