diff options
Diffstat (limited to 'unsaver.rst')
| -rw-r--r-- | unsaver.rst | 137 |
1 files changed, 79 insertions, 58 deletions
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 .. ======== |