diff options
| -rw-r--r-- | Makefile | 22 | ||||
| -rw-r--r-- | jsmond.1 | 95 | ||||
| -rw-r--r-- | jsmond.c | 342 | ||||
| -rw-r--r-- | jsmond.html | 96 | ||||
| -rw-r--r-- | jsmond.rst | 83 |
5 files changed, 425 insertions, 213 deletions
@@ -7,13 +7,13 @@ MAX_STICKS=16 # base name of joystick devices on your OS, gets numbers 0 to MAX_STICKS -# appended to it during autodetection -JSDEVBASE="/dev/input/js" +# appended to it during autodetection. This is the base filename without +# the directory. If your first joystick is /dev/input/js0, say js here. +JSNODE=js -# If you can think of a reason to compile without X11 support, -# set this to 0 (or anything other than 1). Note that you can -# compile with X11 and then disable it at runtime with -x. -HAVE_X11=1 +# directory where joystick devices live. monitored via inotify(7) to +# detect hotplug events. +EVENTDIR=/dev/input # Intended for optimizations, but you could include other flags here. # Override this, not CFLAGS @@ -54,14 +54,10 @@ PROJ=jsmond # the .rst is the authoritative source for the version number. VERSION=$(shell fgrep '.. |version| replace::' $(PROJ).rst | cut -d' ' -f4) -DEFINES=-DVERSION=\"$(VERSION)\" -DMAX_STICKS=$(MAX_STICKS) -DJSDEVBASE=\"$(JSDEVBASE)\" - -ifeq ($(HAVE_X11),1) -CFLAGS+=$(shell pkg-config --cflags x11) -LDFLAGS+=$(shell pkg-config --libs x11) -DEFINES+=-DHAVE_X11 -endif +DEFINES=-DVERSION=\"$(VERSION)\" -DMAX_STICKS=$(MAX_STICKS) -DJSNODE=\"$(JSNODE)\" -DEVENTDIR=\"$(EVENTDIR)\" +CFLAGS+=$(shell pkg-config --cflags x11 xtst) +LDFLAGS+=$(shell pkg-config --libs x11 xtst) CFLAGS=$(OPTFLAGS) $(DEFINES) LDFLAGS+=$(LDEXTRA) @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH JSMOND 1 "2020-05-16" "0.1.0" "Urchlay" +.TH JSMOND 1 "2020-05-17" "0.2.0" "Urchlay" .SH NAME jsmond \- deactivate screensaver on joystick activity . @@ -36,52 +36,72 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] . .SH SYNOPSIS .sp -jsmond [\fB\-c command\fP] [\fB\-i seconds\fP] [\fB\-d\fP] [\fB\-x\fP] [\fBjoydev [joydev ...]\fP] +jsmond [\fB\-i interval\fP] [\fB\-k keycode\fP | \fB\-b button\fP] [\fB\-d dir\fP] [\fB\-j name\fP] [\fB\-D\fP] [\fBjoydev [joydev ...]\fP] .SH DESCRIPTION .sp jsmond lets you play games with your joysticks/gamepads without -xscreensaver activating due to lack of keyboard/mouse input. +the screen saver activating due to lack of keyboard/mouse input. .sp Multiple joystick devices can be monitored. By default, jsmond 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. .sp -Every \fIinterval\fP seconds (60, or whatever \fB\-i\fP is set to), jsmond +Every \fIinterval\fP milliseconds (250, or whatever \fB\-i\fP is set to), jsmond checks to see if there\(aqs been any activity on any of the devices it\(aqs -monitoring. If so, it runs the \fBxscreensaver\-command \-deactivate\fP -(or whatever the \fB\-c\fP argument is set to). The command will be run no -more than once every \fIinterval\fP seconds. +monitoring. If so, it sends a fake keystroke or mouse button click, which +the screen saver will see as activity. .sp It\(aqs recommended to let jsmond 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 +jsmond should be started from your \fB\&.xinitrc\fP or whatever X startup +script your windowmanager or desktop environment uses. By default, it +will exit when the X server does. There\(aqs no PID file: use "pkill jsmond" +if you need to kill the daemon. .SH OPTIONS .INDENT 0.0 .TP .B \-\-help Print usage summary .TP -.BI \-c \ <command> -Run <command> when activity was detected during the -last \fIinterval\fP\&. +.BI \-i \ <millis> +Interval to check for activity, in milliseconds. +Default: 250. .TP -.BI \-i \ <seconds> -Interval to check for activity. Should be set a minute or -so less than your xscreensaver timeout. Setting this too low -will waste resources. Default: 60. +.BI \-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 \fIdoesn\(aqt\fP map to a keysym +in your usual keymapping (use "xmodmap \-pk" to find one). .TP -.B \-d -Debug mode: run in foreground and print verbose messages. +.BI \-b \ <button> +Send a click of this button when activity is detected, +rather than a keystroke. Should be a button that +applications don\(aqt normally respond to (6 or higher). +.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". +.TP +.BI \-j \ <name> +Name of joystick device nodes, without any numeric +suffix. Default is "js". .TP -.B \-x -Don\(aqt try to connect to X server (and don\(aqt exit until killed). +.B \-D +Debug mode: run in foreground and print verbose messages. .UNINDENT -.SH NOTES .sp A space is required between an option and its argument, as shown -above. Use e.g. \fB\-i 120\fP, not \fB\-i120\fP\&. +above. Use e.g. \fB\-i 300\fP, not \fB\-i300\fP\&. +.SH NOTES .sp By default, jsmond searches for and monitors all the joysticks it can find, up to MAX_STICKS (normally 16; see the \fB\-\-help\fP output to find @@ -92,33 +112,26 @@ those devices will be monitored. \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 at compile time (see the \fB\-\-help\fP output to find the -compiled\-in default). +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 jsmond +to detect hotplug events! .sp Note that it\(aqs \fInot\fP an error to give nonexistent joystick device names. jsmond will wait for devices to come into existence (e.g. as created by \fBudev\fP). .sp -jsmond should be started from your \fB\&.xinitrc\fP or whatever X startup -script your windowmanager or desktop environment uses. By default, it -will exit when the X server does. -.sp -If you can think of a use for jsmond outside of X, give it the \-x argument -so it won\(aqt complain about not being able to connect to the X server. This -will also prevent it from exiting when the X server does. When using -\-x, be careful not to spawn multiple instances of jsmond (although they -won\(aqt hurt anything, just waste resources). -.sp -There\(aqs no PID file. Just use "pkill jsmond". +If the screensaver is configured to lock the screen, and it has already +activated, pressing a joystick button/direction will just bring up the +password dialog, same as pressing a key or mouse button would. .SH EXIT STATUS .sp -Without the \-d option, the exit status is 0 (success) if jsmond +Without the \-D option, the exit status is 0 (success) if jsmond 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, jsmond never exits until it\(aqs killed. +With the \-D option, jsmond never exits until it\(aqs killed. .SH BUGS .sp There\(aqs no way to distinguish between an invalid device name and a @@ -126,7 +139,17 @@ device name that doesn\(aqt happen to exist yet because its device hasn\(aqt been plugged in yet. Try to avoid typos, if you really have to use device names (better to autodetect). .sp -jsmond isn\(aqt portable. It only works on Linux, at least for now. +jsmond isn\(aqt portable. It only works on Linux, at least for now, for +three reasons: +.INDENT 0.0 +.IP \(bu 2 +It uses the Linux joystick API. +.IP \(bu 2 +It uses inotify(7) to detect joystick hotplug events. +.IP \(bu 2 +I haven\(aqt even looked at other OSes to see if it would be possible +to port the code. +.UNINDENT .\" EXAMPLES . .\" ======== @@ -1,57 +1,51 @@ /* need this, or else we don't get a prototype for strdup() from string.h */ -#define _POSIX_C_SOURCE 200809L +#define _XOPEN_SOURCE 500 #include <string.h> #include <stdio.h> #include <unistd.h> #include <stdlib.h> -#include <linux/joystick.h> #include <sys/types.h> #include <sys/stat.h> #include <fcntl.h> #include <limits.h> #include <errno.h> -#ifdef HAVE_X11 -# include <X11/Xlib.h> -#endif - -#ifndef PATH_MAX -# define PATH_MAX 1024 -#endif - -/* -c option: */ -const char *command = "xscreensaver-command -deactivate"; -/* -i option: */ -int interval = 60; -/* cleared if user supplies one or more joysticks on command line: */ -int autodiscover = 1; -/* -d option: */ -int debug = 0; +#include <X11/X.h> +#include <X11/Xlib.h> +#include <X11/extensions/XTest.h> +#include <linux/joystick.h> +#include <sys/inotify.h> + +/* user options */ +int interval = 250; /* -i */ +int debug = 0; /* -D */ +int keycode = -1; /* -k */ +int button = -1; /* -b */ +char *event_dir = EVENTDIR; /* -d */ +char *js_node_name = JSNODE; /* -j */ +int autodiscover = 1; /* cleared if user supplies joydev args */ + +/* joystick stuff */ char *joynames[MAX_STICKS + 1]; int last_joyname = 0; +int joyfds[MAX_STICKS + 1]; const char *self; -#ifdef HAVE_X11 +/* X stuff */ Display *xdisp; -int use_x = 1; -#endif + +/* inotify stuff */ +int inotify_fd, watch_fd; +char inotify_buf[sizeof(struct inotify_event) + NAME_MAX + 1]; +struct inotify_event *inotify_ev = (struct inotify_event *)inotify_buf; void usage(void) { printf("jsmond v" VERSION " by B. Watson, WTFPL\n"); - printf("Usage: %s [-c cmd] [-i interval] " -#ifdef HAVE_X11 - "[-x] " -#endif - "[joystick [...]]\n", self); - printf("Build options: " -#ifndef HAVE_X11 - "no " -#endif - "X11 support, MAX_STICKS %d, JSDEVBASE " JSDEVBASE "\n", - MAX_STICKS); + printf("Usage: %s [-i interval] [-b button | -k keycode] [-j name]\n", self); + printf(" [-d dir] [-D] [joystick [...]]\n"); printf("See man page for details\n"); exit(0); } @@ -61,7 +55,6 @@ void die(const char *msg) { exit(1); } -#ifdef HAVE_X11 /* make some trivial Xlib call that will result in Xlib killing this process if it fails. XNoOp looks like it was meant for exactly this, but it keeps returning 1 even if the X server is killed. */ @@ -69,44 +62,110 @@ void ping_x_server(void) { (void)XPending(xdisp); if(debug) fprintf(stderr, "X server is still alive\n"); } -#endif +void send_fake_key(void) { + if(debug) fprintf(stderr, "sending keycode %d\n", keycode); + + /* press... */ + XTestFakeKeyEvent(xdisp, keycode, 1, 0L); + XSync(xdisp, 0); + + /* ...wait 1/10 sec... */ + usleep(100000); + + /* ...release */ + XTestFakeKeyEvent(xdisp, keycode, 0, 0L); + XSync(xdisp, 0); +} + +void send_fake_click(void) { + if(debug) fprintf(stderr, "sending button %d click\n", button); + + /* press... */ + XTestFakeButtonEvent(xdisp, button, 1, 0L); + XSync(xdisp, 0); + + /* ...wait 1/10 sec... */ + usleep(100000); + + /* ...release */ + XTestFakeButtonEvent(xdisp, button, 0, 0L); + XSync(xdisp, 0); +} + +void open_joysticks(void) { + int fdcount, i; + struct js_event e; + + fdcount = 0; + 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); + if(joyfds[i] > -1) { + fdcount++; + while( (read(joyfds[i], &e, sizeof(e)) > 0) && (e.type & JS_EVENT_INIT) ) + synthev++; + if(debug) + fprintf(stderr, "opened %s, fd %d, skipped %d synthetic events\n", + joynames[i], joyfds[i], synthev); + } + } + if(debug) fprintf(stderr, "opened %d devices\n", fdcount); +} + +void init_joysticks(void) { + int i; + for(i = 0; i < MAX_STICKS; i++) + joyfds[i] = -1; + open_joysticks(); +} + +void check_inotify() { + int res; + + res = read(inotify_fd, inotify_buf, sizeof(inotify_buf) + NAME_MAX + 1); + + if(res > 0) { + if(debug) { + fprintf(stderr, "read %d bytes from inotify_fd\n", res); + if(!inotify_ev->len) { + fprintf(stderr, "got event with no name: %x\n", inotify_ev->mask); + } else { + fprintf(stderr, "got event with name %s: %x\n", inotify_ev->name, inotify_ev->mask); + } + } + usleep(100000); /* might not need, be paranoid */ + open_joysticks(); + } else { + if(errno != EAGAIN) { + fprintf(stderr, "%s: failed to read from inotify_fd: %s\n", + self, strerror(errno)); + exit(1); + } + } +} + +/* this is the point of no return. the only way out of main_loop() + is process death. */ void main_loop(void) { struct js_event e; - int joyfds[MAX_STICKS + 1]; - int i, fdcount, active; + int i, active; fprintf(stderr, "entering main_loop()\n"); while(1) { - active = 0; -#ifdef HAVE_X11 - if(use_x) ping_x_server(); -#endif - - /* open all the files named in the list. - doing it this way is more work than opening each one once before - main_loop() and keeping it open, but this lets us easily track - when devices appear and disappear. */ - fdcount = 0; - for(i = 0; i < last_joyname; i++) { - int synthev = 0; - joyfds[i] = 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) ) - synthev++; - if(debug) - fprintf(stderr, "opened %s, fd %d, skipped %d synthetic events\n", - joynames[i], joyfds[i], synthev); - } - } - if(debug) fprintf(stderr, "opened %d devices, sleeping %d sec\n", fdcount, interval); + /* Xlib will obligingly kill us, if X goes away */ + ping_x_server(); - /* let them gather events as we sleep */ - sleep(interval); + /* check_inotify() will close & reopen the joystick fds as needed */ + check_inotify(); - /* now see if any of the fds got any events while we slept */ + /* let the fds gather events as we slumber */ + if(debug) fprintf(stderr, "sleeping %dms...\n", interval); + usleep(interval * 1000); + + /* now see if any of them got any events while we took a nap */ active = 0; for(i = 0; i < last_joyname; i++) { if(joyfds[i] < 0) continue; @@ -128,15 +187,12 @@ void main_loop(void) { /* if we got any activity on any of the fds, do our thing */ if(active) { - int res; - if(debug) fprintf(stderr, "*** got activity! executing: %s\n", command); - res = system(command); - if(debug) fprintf(stderr, "exit status %d (%s)\n", res, (res ? "failed" : "OK")); + if(debug) fprintf(stderr, "*** got activity!\n"); + if(button > -1) + send_fake_click(); + else + send_fake_key(); } else if(debug) fprintf(stderr, "no activity\n"); - - /* close 'em all */ - for(i = 0; i < last_joyname; i++) - close(joyfds[i]); } } @@ -161,7 +217,7 @@ void add_joystick_name(const char *name) { if(*name >= '0' && *name <= '9') { char buf[PATH_MAX + 1]; - sprintf(buf, JSDEVBASE "%d", atoi(name)); + sprintf(buf, "%s/%s%d", event_dir, js_node_name, atoi(name)); add_joystick_name(buf); return; } @@ -175,40 +231,66 @@ void add_joystick_name(const char *name) { last_joyname++; } -void enumerate_names(void) { +void populate_joynames(void) { int i; char buf[PATH_MAX + 1]; for(i = 0; i < MAX_STICKS; i++) { - sprintf(buf, "%s%d", JSDEVBASE, i); + sprintf(buf, "%s/%s%d", event_dir, js_node_name, i); add_joystick_name(buf); } } void parse_args(int argc, char **argv) { + char *nextarg; + if(argc > 1 && strcmp(argv[1], "--help") == 0) usage(); + while(++argv, --argc) { if(argv[0][0] == '-') { - char *nextarg = argv[1]; + if(argv[0][1] && argv[0][2]) + die("spaces required between options and arguments, please"); + nextarg = argv[1]; switch(argv[0][1]) { -#ifdef HAVE_X11 - case 'x': use_x = 0; break; -#endif - case 'c': + case 'k': if(nextarg) { - command = nextarg; + keycode = atoi(nextarg); /* TODO: error check */ + argv++, argc--; + } else { + die("-k requires a keycode argument, 0-255"); + } + break; + case 'b': + if(nextarg && (button = atoi(nextarg))) { + keycode = -1; argv++, argc--; } else { - die("-c requires a command argument"); + die("-b requires a positive integer button argument"); } break; case 'i': if(nextarg && (interval = atoi(nextarg)) > 0) argv++, argc--; else - die("-i requires a positive integer argument in seconds"); + 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; default: @@ -220,9 +302,14 @@ void parse_args(int argc, char **argv) { autodiscover = 0; } } + + if((keycode > -1) && (button > -1)) + die("can't send both keycode and button events"); } -/* make ourselves a daemon, double-fork technique */ +/* make ourselves a daemon, double-fork technique. + verbose comments are not here because I think you need them, they're + here for me so I don't forget what this gibberish is for... */ void daemonize(void) { pid_t pid; @@ -235,21 +322,26 @@ void daemonize(void) { exit(0); } - /* the only reason for the first fork() was because setsid() can't + /* now we're in the child, aka the 2nd generation parent. + the only reason for the first fork() was because setsid() can't be run in the parent process */ - setsid(); + if( (setsid() < 0) ) { + fprintf(stderr, "%s: %s\n", self, strerror(errno)); + die("failed to daemonize"); + } /* go on, do it again */ if((pid = fork()) < 0) { - /* in parent, fork failed */ + /* in 2nd gen parent, fork failed */ fprintf(stderr, "%s: %s\n", self, strerror(errno)); die("failed to daemonize"); } else if(pid) { - /* in parent, fork succeeded */ + /* in 2nd gen parent, fork succeeded */ + fprintf(stderr, "%s: daemonized, PID %u\n", self, pid); exit(0); } - /* we no longer need stdin/out/err */ + /* now we're in the grandchild, and we no longer need stdin/out/err */ close(0); close(1); close(2); @@ -259,25 +351,85 @@ void daemonize(void) { chdir("/"); } -#ifdef HAVE_X11 +void init_inotify(void) { + inotify_fd = inotify_init1(IN_NONBLOCK); + if( inotify_fd < 0) { + fprintf(stderr, "%s: inotify_init1() failed: %s", + self, strerror(errno)); + exit(1); + } + + if(debug) fprintf(stderr, "inotify_init1() returned %d\n", inotify_fd); + + watch_fd = inotify_add_watch(inotify_fd, event_dir, IN_CREATE | IN_DELETE); + if( watch_fd < 0) { + fprintf(stderr, "%s: inotify_add_watch() failed: %s", + self, strerror(errno)); + exit(1); + } + + if(debug) fprintf(stderr, "inotify_add_watch() on %s returned %d\n", event_dir, inotify_fd); +} + void connect_to_x(void) { - if(debug) fprintf(stderr, "connecting to X display...\n"); + int ignoreme; + + if(debug) fprintf(stderr, "connecting to X server...\n"); + xdisp = XOpenDisplay(getenv("DISPLAY")); + if(!xdisp) die("can't connect to X server"); - if(debug) fprintf(stderr, "connected to X display\n"); + if(debug) fprintf(stderr, "connected to X server\n"); + + if(XTestQueryExtension(xdisp, &ignoreme, &ignoreme, &ignoreme, &ignoreme)) { + if(debug) fprintf(stderr, "X server supports XTest extension, good\n"); + } else { + die("X server doesn't support XTest extension\n"); + } +} + +/* the goggles, they do nothing! */ +void find_keycode() { + int i, min_code = 0, max_code = 0; + + /* man page doesn't document the return value */ + (void)XDisplayKeycodes(xdisp, &min_code, &max_code); + + if(debug) fprintf(stderr, "XDisplayKeycodes min %d, max %d\n", min_code, max_code); + + /* XXX: XKeycodeToKeysym() is deprecated. I must learn XKB. */ + for(i = min_code; i <= max_code; i++) { + KeySym ks = XKeycodeToKeysym(xdisp, i, 0); + if(ks == NoSymbol) { + keycode = i; + if(debug) fprintf(stderr, "using keycode %d\n", keycode); + break; + } + } + + if(keycode < 0) { + fprintf(stderr, "%s: can't find a free keycode in the keymap, using 255\n", self); + keycode = 255; + } +} + +void init_x(void) { + connect_to_x(); + if(keycode < 0 && button < 0) find_keycode(); } -#endif int main(int argc, char **argv) { set_exe_name(argv[0]); parse_args(argc, argv); - if(autodiscover) enumerate_names(); + if(autodiscover) populate_joynames(); + + init_joysticks(); + + init_inotify(); -#ifdef HAVE_X11 - if(use_x) connect_to_x(); -#endif + init_x(); if(!debug) daemonize(); diff --git a/jsmond.html b/jsmond.html index c90e0bb..29a9bdf 100644 --- a/jsmond.html +++ b/jsmond.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>jsmond</title> -<meta name="date" content="2020-05-16" /> +<meta name="date" content="2020-05-17" /> <style type="text/css"> /* @@ -373,34 +373,37 @@ 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-16</td></tr> +<td>2020-05-17</td></tr> <tr><th class="docinfo-name">Version:</th> -<td>0.1.0</td></tr> +<td>0.2.0</td></tr> </tbody> </table> <!-- RST source for jsmond(1) man page. Convert with: --> <!-- rst2man.py jsmond.rst > jsmond.1 --> <div class="section" id="synopsis"> <h1>SYNOPSIS</h1> -<p>jsmond [<strong>-c command</strong>] [<strong>-i seconds</strong>] [<strong>-d</strong>] [<strong>-x</strong>] [<strong>joydev [joydev ...]</strong>]</p> +<p>jsmond [<strong>-i interval</strong>] [<strong>-k keycode</strong> | <strong>-b button</strong>] [<strong>-d dir</strong>] [<strong>-j name</strong>] [<strong>-D</strong>] [<strong>joydev [joydev ...]</strong>]</p> </div> <div class="section" id="description"> <h1>DESCRIPTION</h1> <p>jsmond lets you play games with your joysticks/gamepads without -xscreensaver activating due to lack of keyboard/mouse input.</p> +the screen saver activating due to lack of keyboard/mouse input.</p> <p>Multiple joystick devices can be monitored. By default, jsmond 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> seconds (60, or whatever <strong>-i</strong> is set to), jsmond +<p>Every <em>interval</em> milliseconds (250, or whatever <strong>-i</strong> is set to), jsmond checks to see if there's been any activity on any of the devices it's -monitoring. If so, it runs the <strong>xscreensaver-command -deactivate</strong> -(or whatever the <strong>-c</strong> argument is set to). The command will be run no -more than once every <em>interval</em> seconds.</p> +monitoring. If so, it sends a fake keystroke or mouse button click, which +the screen saver will see as activity.</p> <p>It's recommended to let jsmond 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>jsmond should be started from your <strong>.xinitrc</strong> or whatever X startup +script your windowmanager or desktop environment uses. By default, it +will exit when the X server does. There's no PID file: use "pkill jsmond" +if you need to kill the daemon.</p> </div> <div class="section" id="options"> <h1>OPTIONS</h1> @@ -412,27 +415,46 @@ will be monitored (no search is done).</p> <kbd><span class="option">--help</span></kbd></td> <td>Print usage summary</td></tr> <tr><td class="option-group"> -<kbd><span class="option">-c <var><command></var></span></kbd></td> -<td>Run <command> when activity was detected during the -last <em>interval</em>.</td></tr> +<kbd><span class="option">-i <var><millis></var></span></kbd></td> +<td>Interval to check for activity, in milliseconds. +Default: 250.</td></tr> <tr><td class="option-group"> -<kbd><span class="option">-i <var><seconds></var></span></kbd></td> -<td>Interval to check for activity. Should be set a minute or -so less than your xscreensaver timeout. Setting this too low -will waste resources. Default: 60.</td></tr> +<kbd><span class="option">-k <var><keycode></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 +manually, it should be a keycode that <em>doesn't</em> map to a keysym +in your usual keymapping (use "xmodmap -pk" to find one).</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> +<kbd><span class="option">-b <var><button></var></span></kbd></td> +<td>Send a click of this button when activity is detected, +rather than a keystroke. Should be a button that +applications don't normally respond to (6 or higher).</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><dir></var></span></kbd></td> +<td>Path to the directory containing joystick device nodes. +Default is "/dev/input".</td></tr> <tr><td class="option-group"> -<kbd><span class="option">-x</span></kbd></td> -<td>Don't try to connect to X server (and don't exit until killed).</td></tr> +<kbd><span class="option">-j <var><name></var></span></kbd></td> +<td>Name of joystick device nodes, without any numeric +suffix. Default is "js".</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 class="section" id="notes"> <h1>NOTES</h1> -<p>A space is required between an option and its argument, as shown -above. Use e.g. <strong>-i 120</strong>, not <strong>-i120</strong>.</p> <p>By default, jsmond searches for and monitors all the joysticks it can find, up to MAX_STICKS (normally 16; see the <strong>--help</strong> output to find the compiled-in default). You can override the search on the command @@ -441,28 +463,23 @@ those devices will be monitored.</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 "/dev/input/js", but -can be changed at compile time (see the <strong>--help</strong> output to find the -compiled-in default).</p> +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 jsmond +to detect hotplug events!</p> <p>Note that it's <em>not</em> an error to give nonexistent joystick device names. jsmond will wait for devices to come into existence (e.g. as created by <strong>udev</strong>).</p> -<p>jsmond should be started from your <strong>.xinitrc</strong> or whatever X startup -script your windowmanager or desktop environment uses. By default, it -will exit when the X server does.</p> -<p>If you can think of a use for jsmond outside of X, give it the -x argument -so it won't complain about not being able to connect to the X server. This -will also prevent it from exiting when the X server does. When using --x, be careful not to spawn multiple instances of jsmond (although they -won't hurt anything, just waste resources).</p> -<p>There's no PID file. Just use "pkill jsmond".</p> +<p>If the screensaver is configured to lock the screen, and it has already +activated, pressing a joystick button/direction will just bring up the +password dialog, same as pressing a key or mouse button would.</p> </div> <div class="section" id="exit-status"> <h1>EXIT STATUS</h1> -<p>Without the -d option, the exit status is 0 (success) if jsmond +<p>Without the -D option, the exit status is 0 (success) if jsmond 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, jsmond never exits until it's killed.</p> +<p>With the -D option, jsmond never exits until it's killed.</p> </div> <div class="section" id="bugs"> <h1>BUGS</h1> @@ -470,7 +487,14 @@ or else fork() failed. No daemon will be running in this case.</p> device name that doesn't happen to exist yet because its device hasn't been plugged in yet. Try to avoid typos, if you really have to use device names (better to autodetect).</p> -<p>jsmond isn't portable. It only works on Linux, at least for now.</p> +<p>jsmond isn't portable. It only works on Linux, at least for now, for +three reasons:</p> +<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> <!-- EXAMPLES --> <!-- ======== --> </div> @@ -1,7 +1,7 @@ .. RST source for jsmond(1) man page. Convert with: .. rst2man.py jsmond.rst > jsmond.1 -.. |version| replace:: 0.1.0 +.. |version| replace:: 0.2.0 .. |date| date:: ====== @@ -20,51 +20,67 @@ deactivate screensaver on joystick activity SYNOPSIS ======== -jsmond [**-c command**] [**-i seconds**] [**-d**] [**-x**] [**joydev [joydev ...]**] +jsmond [**-i interval**] [**-k keycode** | **-b button**] [**-d dir**] [**-j name**] [**-D**] [**joydev [joydev ...]**] DESCRIPTION =========== jsmond lets you play games with your joysticks/gamepads without -xscreensaver activating due to lack of keyboard/mouse input. +the screen saver activating due to lack of keyboard/mouse input. Multiple joystick devices can be monitored. By default, jsmond 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. -Every *interval* seconds (60, or whatever **-i** is set to), jsmond +Every *interval* milliseconds (250, or whatever **-i** is set to), jsmond checks to see if there's been any activity on any of the devices it's -monitoring. If so, it runs the **xscreensaver-command -deactivate** -(or whatever the **-c** argument is set to). The command will be run no -more than once every *interval* seconds. +monitoring. If so, it sends a fake keystroke or mouse button click, which +the screen saver will see as activity. It's recommended to let jsmond 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). +jsmond should be started from your **.xinitrc** or whatever X startup +script your windowmanager or desktop environment uses. By default, it +will exit when the X server does. There's no PID file: use "pkill jsmond" +if you need to kill the daemon. + OPTIONS ======= --help Print usage summary --c <command> Run <command> when activity was detected during the - last *interval*. +-i <millis> Interval to check for activity, in milliseconds. + Default: 250. --i <seconds> Interval to check for activity. Should be set a minute or - so less than your xscreensaver timeout. Setting this too low - will waste resources. Default: 60. +-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 + in your usual keymapping (use "xmodmap -pk" to find one). --d Debug mode: run in foreground and print verbose messages. +-b <button> Send a click of this button when activity is detected, + rather than a keystroke. Should be a button that + applications don't normally respond to (6 or higher). --x Don't try to connect to X server (and don't exit until killed). +These options are intended for developers and *really* shouldn't be +needed for normal use: -NOTES -===== +-d <dir> Path to the directory containing joystick device nodes. + Default is "/dev/input". + +-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 120**, not **-i120**. +above. Use e.g. **-i 300**, not **-i300**. + +NOTES +===== By default, jsmond searches for and monitors all the joysticks it can find, up to MAX_STICKS (normally 16; see the **--help** output to find @@ -75,35 +91,28 @@ those devices will be monitored. **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 at compile time (see the **--help** output to find the -compiled-in default). +can be changed via the **-d** and **-j** options. Note that (currently) +all the joystick devices have to be in the same directory for jsmond +to detect hotplug events! Note that it's *not* an error to give nonexistent joystick device names. jsmond will wait for devices to come into existence (e.g. as created by **udev**). -jsmond should be started from your **.xinitrc** or whatever X startup -script your windowmanager or desktop environment uses. By default, it -will exit when the X server does. - -If you can think of a use for jsmond outside of X, give it the -x argument -so it won't complain about not being able to connect to the X server. This -will also prevent it from exiting when the X server does. When using --x, be careful not to spawn multiple instances of jsmond (although they -won't hurt anything, just waste resources). - -There's no PID file. Just use "pkill jsmond". +If the screensaver is configured to lock the screen, and it has already +activated, pressing a joystick button/direction will just bring up the +password dialog, same as pressing a key or mouse button would. EXIT STATUS =========== -Without the -d option, the exit status is 0 (success) if jsmond +Without the -D option, the exit status is 0 (success) if jsmond 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, jsmond never exits until it's killed. +With the -D option, jsmond never exits until it's killed. BUGS ==== @@ -113,7 +122,15 @@ device name that doesn't happen to exist yet because its device hasn't been plugged in yet. Try to avoid typos, if you really have to use device names (better to autodetect). -jsmond isn't portable. It only works on Linux, at least for now. +jsmond isn't portable. It only works on Linux, at least for now, for +three reasons: + +- It uses the Linux joystick API. + +- 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. .. EXAMPLES .. ======== |