blob: 5b5f0d6f7f5eb6a68cd70e3ee2a8a749de6ce007 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
|
.TH PISS 1 "DECEMBER 2025" "1.0" "PISS Manual"
.SH NAME
piss \- a lightweight socket-based X11 keybinding daemon
.SH SYNOPSIS
.B piss
[\fICONFIG_FILE\fR]
.br
.B piss bind
\fIKEYCOMBO\fR \fICOMMAND\fR
.br
.B piss wait
.SH DESCRIPTION
.B piss
is a minimal utility designed to manage X11 global hotkeys. It operates as a daemon that listens on a Unix domain socket for binding requests.
.PP
When started without a command,
.B piss
launches the daemon, creates a socket at \fB/tmp/piss.sock\fR, and executes the specified \fICONFIG_FILE\fR. This architecture allows for dynamic configuration using any scripting language.
.SH COMMANDS
.TP
.B (default)
Starts the daemon mode. If no \fICONFIG_FILE\fR is provided, it defaults to \fB~/.config/piss/pissrc\fR. The daemon exports the \fBPISS_BIN\fR environment variable to the child process.
.TP
.B bind \fIKEYCOMBO\fR \fICOMMAND\fR
Connects to the running daemon and registers a new binding. \fIKEYCOMBO\fR should follow the format "Modifier+Key" (e.g., "Super+Shift+Return").
.TP
.B wait
Blocks execution until the daemon has successfully initialized its Unix socket. This is essential for preventing race conditions in configuration scripts.
.SH ENVIRONMENT
.TP
.B PISS_BIN
Set by the daemon to the absolute path of the current binary. Recommended for use within scripts to ensure the client calls the correct version of the tool.
.SH FILES
.TP
.I /tmp/piss.sock
The Unix domain socket used for IPC communication.
.TP
.I ~/.config/piss/pissrc
The default user configuration script (must be executable).
.SH EXAMPLES
.PP
Example of a Lua-based \fBpissrc\fR:
.IP
#!/usr/bin/lua
.br
local p = os.getenv("PISS_BIN") or "piss"
.br
os.execute(p .. " wait")
.br
os.execute(p .. ' bind "Super+Return" "alacritty"')
.SH TROUBLESHOOTING
.TP
.B Syntax error: "(" unexpected
This occurs if the daemon tries to run a Lua config using \fB/bin/sh\fR. Ensure your \fBpissrc\fR has a proper shebang (\fB#!/usr/bin/lua\fR) and that the daemon is using \fBexecvp\fR instead of \fBexecl\fR.
.TP
.B piss: cannot open display
The \fBDISPLAY\fR environment variable is not set. Ensure you are running \fBpiss\fR within an active X11 session.
.TP
.B Bindings not working
Check if another window manager or application has already "grabbed" the key. \fBpiss\fR cannot override existing global grabs from programs like \fBi3\fR or \fBbspwm\fR if they started first.
.TP
.B pissA: not found
This indicates a buffer overflow or null-termination issue in the \fBPISS_BIN\fR detection logic. Ensure \fBreadlink\fR is correctly null-terminating the path string in \fBdaemon.c\fR.
.TP
.B Connection refused
The \fBpiss wait\fR command timed out or the daemon crashed. Check if \fB/tmp/piss.sock\fR exists. If a stale socket remains after a crash, delete it manually.
.SH DIAGNOSTICS
If \fBpiss\fR fails to launch the config script, ensure the script is executable (\fBchmod +x\fR) and has a valid shebang line.
|
