.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "THD 1" .TH THD 1 "2024-01-07" "0.5.0" "Triggerhappy daemon" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" thd \-\- triggerhappy global hotkey daemon .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBthd\fR [\fB\-\-help\fR] [\fB\-\-user\fR \fIname\fR] [\fB\-\-listevents\fR] [\fB\-\-dump\fR] [\fB\-\-socket\fR \fIsocket\fR] [\fB\-\-triggers\fR \fIconfig\fR] [\fB\-\-daemon\fR] [\fB\-\-pidfile\fR \fIfile\fR] [\fB\-\-uinput\fR \fIdevice\fR][\fB\-\-ignore\fR \fIevent\fR] [\fB\-\-deviceglob\fR \fIpattern\fR] [\fIdevices...\fR] .SH "DESCRIPTION" .IX Header "DESCRIPTION" Triggerhappy is a hotkey daemon that operates on a system wide scale. It watches all configured input devices for key, switch or button events and can launch arbitrary commands specified by the administrator. In contrast to hotkey services provided by desktop environments, Triggerhappy is especially suited to hardware related switches like volume or wifi control; it works independently from a specific user being logged in and is also suitable for embedded systems that do not a graphical user interface. .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fB\-\-help\fR" 4 .IX Item "--help" Shows usage instructions .IP "\fB\-\-listevents\fR" 4 .IX Item "--listevents" Prints a list of all known event names. .IP "\fB\-\-triggers\fR \fIconf\fR" 4 .IX Item "--triggers conf" Read trigger definitions from \fIconf\fR, which can either be a file or a directory. If a directory is specified, all its files matching the pattern *.conf are loaded. .IP "\fB\-\-dump\fR" 4 .IX Item "--dump" Dump all recognized events to \s-1STDOUT.\s0 This can also be utilized to create a skeleton trigger configuration by redirecting the printed configuration lines to a configuration file, adding the desired command and activating the generated line by removing the comment mark \*(L"#\*(R" at its beginning: .Sp .Vb 1 \& thd \-\-dump /dev/input/event* | grep ^# > /etc/triggerhappy/triggers.d/skeleton.conf .Ve .IP "\fB\-\-socket\fR \fIfile\fR" 4 .IX Item "--socket file" Open a unix domain socket at \fIfile\fR; this socket can be used to send commands to the running daemon (by using the program th-cmd), e.g. for adding or removing devices. .IP "\fB\-\-daemon\fR" 4 .IX Item "--daemon" Run as a background daemon and detach from the terminal. .IP "\fB\-\-pidfile\fR \fIfile\fR" 4 .IX Item "--pidfile file" Write \s-1PID\s0 to \fIfile\fR. .IP "\fB\-\-uinput\fR \fIdevice\fR" 4 .IX Item "--uinput device" Open uinput file (probably \fI/dev/input/uinput\fR) to generate synthetic events. .IP "\fB\-\-ignore\fR \fIeventname\fR" 4 .IX Item "--ignore eventname" Ignore key and switch event labeled \fIeventname\fR. This can be used to suppress the \s-1FN\s0 key on some notebooks which only generates events sometimes and might screw up key combinations. .IP "\fB\-\-normalize\fR" 4 .IX Item "--normalize" Normalize \s-1REL\s0 and \s-1ABS\s0 events. If this option is enabled, the values of axis movement events are mapped to the three values \-1, 0 and 1, depending on the sign of the value reported by the kernel. .IP "\fB\-\-user\fR \fIname\fR" 4 .IX Item "--user name" Change to user id \fIname\fR after opening files. This usually prevents thd from opening additional input devices, unless they are opened by the th-cmd program and their file descriptor are passed to the daemon. .IP "\fB\-\-deviceglob\fR \fIpattern\fR" 4 .IX Item "--deviceglob pattern" Open device files matching the glob \fIpattern\fR. .PP Additional command line arguments are considered filenames of input devices. .SH "CONFIGURATION" .IX Header "CONFIGURATION" .SS "Configuring event handlers" .IX Subsection "Configuring event handlers" The hotkey bindings used by Triggerhappy are set in the configuration file specified by \fB\-\-triggers\fR. Each line consists of three segments: The symbolic name of the key or event name to react on, the value carried by the expected event, and of course the command to be launched. .PP The event names can be identified by operating the desired key or switch while running the triggerhappy daemon with the option \fB\-\-dump\fR. .PP Key events carry the value \fI1\fR for a key being pressed and transmit the payload \fI0\fR when it is released; holding the key down constantly yields events with a value of \fI2\fR. .PP The command can include any number of arguments. Please include the full path to avoid trouble through different \f(CW$PATH\fR settings for the daemon and your interactive session. .PP The three fields are separated by an arbitrary number of whitespaces, while anything behind a # character is ignored and considered a comment. .SH "EXAMPLE" .IX Header "EXAMPLE" .SS "Starting the daemon" .IX Subsection "Starting the daemon" \&\fBthd \-\-dump /dev/input/event*\fR .PP Dump all events processable by thd to the console; this is useful to find out the correct event name for a specific key. .PP \&\fBthd \-\-triggers /etc/triggerhappy/triggers.d/ /dev/input/event*\fR .PP Read from all currently connected input devices and process events according to the files in \fI/etc/triggerhappy/triggers.d/\fR. .PP \&\fBthd \-\-triggers /etc/triggerhappy/triggers.conf \-\-socket /var/run/thd.socket\fR .PP Do not open any input devices yet, but bind the socket \fI/var/run/thd.socket\fR for th-cmd to connect to. .SS "Configuration files" .IX Subsection "Configuration files" Any number of event handlers can be placed in the configuration file: .PP .Vb 5 \& # /etc/triggerhappy/triggers.d/suspend.conf \& # \& # Suspend the system \& KEY_SLEEP 1 /usr/sbin/hibernate\-ram \& KEY_SLEEP+KEY_LEFTSHIFT 1 /usr/sbin/hibernate\-disk \& \& # /etc/triggerhappy/triggers.d/audio.conf \& # Change mixer volume when pressing the appropriate keys (or holding them) \& KEY_VOLUMEUP 1 /usr/bin/amixer set Master 5%+ \& KEY_VOLUMEUP 2 /usr/bin/amixer set Master 5%+ \& KEY_VOLUMEDOWN 1 /usr/bin/amixer set Master 5%\- \& KEY_VOLUMEDOWN 2 /usr/bin/amixer set Master 5%\- .Ve .PP In more complex situations, triggerhappy can provide multiple modes that map a single event to different keys; triggers are bound to a specific mode by appending its name to the event name: .PP .Vb 2 \& KEY_KPPLUS@media 1 /usr/bin/mpc next \& KEY_KPMINUS@media 1 /usr/bin/mpc prev .Ve .PP These two lines will only cause mpc to be called if the triggerhappy daemon is in \&\*(L"media\*(R" mode. Changing the mode can be achieved by placing a special trigger inside the configuration: .PP .Vb 2 \& KEY_F12@ 1 @media \& KEY_F12@media 1 @ .Ve .PP These two lines make the F12 key toggle between the (nameless) default mode and the newly defined media mode. .PP Triggers with \*(L"@\*(R" appended are only executed if the specified mode is active; all other triggers are enabled in every mode. .PP When launched with the option \fB\-\-uinput\fR, triggerhappy can be used to generate synthetic events. A virtual input device is created which emits specified key presses once a special trigger is reached: .PP .Vb 1 \& KEY_KPASTERISK 1 KEY_ENTER 1 /usr/bin/mpc stop .Ve .PP Defining the hotkey in this way will only trigger the handler if the event is received from a device tagged \*(L"remote\*(R". .SH "AUTHOR" .IX Header "AUTHOR" Stefan Tomanek