diff options
Diffstat (limited to 'unsaver.1')
| -rw-r--r-- | unsaver.1 | 141 |
1 files changed, 79 insertions, 62 deletions
@@ -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 . .\" ======== |