diff options
| -rw-r--r-- | usr.bin/usbhidaction/usbhidaction.1 | 70 |
1 files changed, 41 insertions, 29 deletions
diff --git a/usr.bin/usbhidaction/usbhidaction.1 b/usr.bin/usbhidaction/usbhidaction.1 index b83eb407b203..4c0f6a36574e 100644 --- a/usr.bin/usbhidaction/usbhidaction.1 +++ b/usr.bin/usbhidaction/usbhidaction.1 @@ -49,28 +49,30 @@ .Op Fl p Ar pidfile .Ar arg ... .Sh DESCRIPTION +The .Nm +utility can be used to execute commands when certain values appear on HID controls. The normal operation for this program is to read the configuration file and then become a daemon and execute commands as the HID items specify. -If a read from the HID device fails the program dies; this will make it +If a read from the HID device fails, the program dies; this will make it die when the USB device is unplugged. .Pp The options are as follows: -.Bl -tag -width Ds +.Bl -tag -width indent .It Fl d Toggle the daemon flag. .It Fl e Instruct .Nm -to die early. Useful when specified with multiple -verbose options to see how files are parsed. +to die early. +Useful when specified with multiple verbose options to see how files are parsed. .It Fl i -Ignore HID items in the config file that does not exist in the device. +Ignore HID items in the configuration file that do not exist in the device. .It Fl v Be verbose, and do not become a daemon. .It Fl c Ar config-file -Specify a path name for the config file. +Specify a path name for the configuration file. .It Fl f Ar device Specify a path name for the device to operate on. If @@ -84,13 +86,17 @@ An absolute path is taken to be the literal device pathname. Specify an alternate file in which to store the process ID. .El .Pp -The config file will be re-read if the process gets a HUP signal. +The configuration file will be re-read if the process gets a +.Dv SIGHUP +signal. .Sh CONFIGURATION The configuration file has a very simple format. Each line describes an -action; if a line begins with a whitespace it is considered a continuation +action; if a line begins with a whitespace, it is considered a continuation of the previous line. -Lines beginning with `#' are considered as comments. +Lines beginning with +.Ql # +are considered as comments. .Pp Each line has four parts: a name of a USB HID item, a value for that item, a debounce value, and an action. @@ -101,30 +107,37 @@ The item names are similar to those used by but each part must be prefixed by its page name. .Pp The value is simply a numeric value. -When the item reports this value +When the item reports this value, the action will be performed. -If the value is `*' it will match any value. +If the value is +.Ql * , +it will match any value. .Pp -The debouce value is an integer not less than 0. The value of 0 -indicates that no debouncing should occur. A value of 1 will only -execute the action when the state changes. Values greater than one -specify that an action should be performed only when the value -changes by that amount. +The debounce value is an integer not less than 0. +The value of 0 indicates that no debouncing should occur. +A value of 1 will only execute the action when the state changes. +Values greater than one specify that an action should be performed +only when the value changes by that amount. .Pp The action is a normal command that is executed with .Xr system 3 . Before it is executed some substitution will occur: -`$n' will be replaced by the nth argument on the -command line, `$V' will be replaced by the numeric value -of the HID item, `$N' will be replaced by the name -of the control, and `$H' will be replaced by the name -of the HID device. +.Ql $n +will be replaced by the +.Ar n Ns th +argument on the command line, +.Ql $V +will be replaced by the numeric value of the HID item, +.Ql $N +will be replaced by the name of the control, and +.Ql $H +will be replaced by the name of the HID device. .Sh FILES -.Bl -tag -width indent +.Bl -tag -width ".Pa /usr/share/misc/usb_hid_usages" .It Pa /usr/share/misc/usb_hid_usages The HID usage table. .It Pa /var/run/usbaction.pid -The default location of the pid file. +The default location of the PID file. .El .Sh EXAMPLES The following configuration file can be used to control a pair @@ -140,12 +153,11 @@ Consumer:Channel_Top.Microsoft:Base_Down 1 0 mixer -f $1 bass -1 .Ed .Pp A sample invocation using this configuration would be -.Bd -literal -offset indent -usbhidaction -f /dev/uhid1 -c conf /dev/mixer1 -.Ed .Pp -The following example controls the mixer volume using a Logitech Wingman. -Notice the debouce of 1 for buttons and 5 for the slider. +.Dl "usbhidaction -f /dev/uhid1 -c conf /dev/mixer1" +.Pp +The following example controls the mixer volume using a Logitech Wingman. +Notice the debounce of 1 for buttons and 5 for the slider. .Bd -literal -offset indent Button:Button_1 1 1 mixer vol +10 Button:Button_2 1 1 mixer vol -10 @@ -163,5 +175,5 @@ command first appeared in .Nx 1.6 . The .Nm -command appeard in +command appeared in .Fx 5.1 . |