'\" t
.\"     Title: sxhkd
.\"    Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 09/27/2025
.\"    Manual: Sxhkd Manual
.\"    Source: Sxhkd 0.6.3
.\"  Language: English
.\"
.TH "SXHKD" "1" "09/27/2025" "Sxhkd 0\&.6\&.3" "Sxhkd Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sxhkd \- Simple X hotkey daemon
.SH "SYNOPSIS"
.sp
\fBsxhkd\fR [\fIOPTIONS\fR] [\fIEXTRA_CONFIG\fR \&...]
.SH "DESCRIPTION"
.sp
sxhkd is a simple X hotkey daemon with a powerful and compact configuration syntax\&.
.SH "OPTIONS"
.PP
\fB\-h\fR
.RS 4
Print the synopsis to standard output and exit\&.
.RE
.PP
\fB\-v\fR
.RS 4
Print the version information to standard output and exit\&.
.RE
.PP
\fB\-m\fR \fICOUNT\fR
.RS 4
Handle the first
\fICOUNT\fR
mapping notify events\&.
.RE
.PP
\fB\-t\fR \fITIMEOUT\fR
.RS 4
Timeout in seconds for the recording of chord chains\&.
.RE
.PP
\fB\-c\fR \fICONFIG_FILE\fR
.RS 4
Read the main configuration from the given file\&.
.RE
.PP
\fB\-r\fR \fIREDIR_FILE\fR
.RS 4
Redirect the commands output to the given file\&.
.RE
.PP
\fB\-s\fR \fISTATUS_FIFO\fR
.RS 4
Output status information to the given FIFO\&.
.RE
.PP
\fB\-a\fR \fIABORT_KEYSYM\fR
.RS 4
Name of the keysym used for aborting chord chains\&.
.RE
.SH "BEHAVIOR"
.sp
\fBsxhkd\fR is a daemon that listens to keyboard events and execute commands\&.
.sp
It reads its configuration file from \fB$XDG_CONFIG_HOME/sxhkd/sxhkdrc\fR by default, or from the given file if the \fB\-c\fR option is used\&.
.sp
Additional configuration files can be passed as arguments\&.
.sp
If \fBsxhkd\fR receives a \fISIGUSR1\fR (resp\&. \fISIGUSR2\fR) signal, it will reload its configuration file (resp\&. toggle the grabbing state of all its bindings)\&.
.sp
If \fBsxhkd\fR recieves a \fISIGALRM\fR signal, it will break the current chain if there is one in progress\&.
.sp
The commands are executed via \fBSHELL\fR \fI\-c\fR \fBCOMMAND\fR (hence you can use environment variables)\&.
.sp
\fBSHELL\fR will be the content of the first defined environment variable in the following list: \fBSXHKD_SHELL\fR, \fBSHELL\fR\&.
.sp
\fBSXHKD_PID\fR will be automatically set to the pid of \fBsxhkd\fR in processes spawned by \fBsxhkd\fR, which may be used by the child process to send easily signals such as \fISIGALRM\fR to the correct instance of \fBsxhkd\fR\&.
.sp
If you have a non\-QWERTY keyboard or a non\-standard layout configuration, you should provide a \fICOUNT\fR of \fI1\fR to the \fB\-m\fR option or \fI\-1\fR (interpreted as infinity) if you constantly switch from one layout to the other (\fBsxhkd\fR ignores all mapping notify events by default because the majority of those events are pointless)\&.
.SH "CONFIGURATION"
.sp
Each line of the configuration file is interpreted as so:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
If it is empty or starts with
#, it is ignored\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
If it starts with a space, it is read as a command\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Otherwise, it is read as a hotkey\&.
.RE
.sp
General syntax:
.sp
.if n \{\
.RS 4
.\}
.nf
HOTKEY
    [;]COMMAND

HOTKEY      := CHORD_1 ; CHORD_2 ; \&... ; CHORD_n
CHORD_i     := [MODIFIERS_i +] [~][@]KEYSYM_i
MODIFIERS_i := MODIFIER_i1 + MODIFIER_i2 + \&... + MODIFIER_ik
.fi
.if n \{\
.RE
.\}
.sp
The valid modifier names are: \fIsuper\fR, \fIhyper\fR, \fImeta\fR, \fIalt\fR, \fIcontrol\fR, \fIctrl\fR, \fIshift\fR, \fImode_switch\fR, \fIlock\fR, \fImod1\fR, \fImod2\fR, \fImod3\fR, \fImod4\fR, \fImod5\fR and \fIany\fR\&.
.sp
The keysym names are given by the output of \fBxev \-event keyboard\fR\&.
.sp
Hotkeys and commands can be spread across multiple lines by ending each partial line with a backslash character\&.
.sp
When multiple chords are separated by semicolons, the hotkey is a chord chain: the command will only be executed after receiving each chord of the chain in consecutive order\&.
.sp
The colon character can be used instead of the semicolon to indicate that the chord chain shall not be aborted when the chain tail is reached\&.
.sp
If a command starts with a semicolon, it will be executed synchronously, otherwise asynchronously\&.
.sp
The \fIEscape\fR key can be used to abort a chord chain\&.
.sp
If \fB@\fR is added at the beginning of the keysym, the command will be run on key release events, otherwise on key press events\&.
.sp
If \fB~\fR is added at the beginning of the keysym, the captured event will be replayed for the other clients\&.
.sp
Pointer hotkeys can be defined by using one of the following special keysym names: \fIbutton1\fR, \fIbutton2\fR, \fIbutton3\fR, \&..., \fIbutton24\fR\&.
.sp
The hotkey and the command may contain sequences of the form \fI{STRING_1,\&...,STRING_N}\fR\&. Braces can be escaped with \fB\e\fR\&.
.sp
In addition, the sequences can contain ranges of the form \fIA\fR\-\fIZ\fR where \fIA\fR and \fIZ\fR are alphanumeric characters\&.
.sp
The underscore character represents an empty sequence element\&.
.SH "AUTHOR"
.sp
Bastien Dejean <nihilhill at gmail\&.com>
.SH "MAILING LIST"
.sp
sxhkd at librelist\&.com