index.md - sites - public wiki contents of suckless.org
(HTM) git clone git://git.suckless.org/sites
(DIR) Log
(DIR) Files
(DIR) Refs
---
index.md (3910B)
---
1 statuscmd
2 =========
3
4 Description
5 -----------
6 This patch adds the ability to signal a status monitor program such as
7 [dwmblocks](https://github.com/torrinfail/dwmblocks) the location and button
8 when clicking on the status bar. Alternatively, there is a version that
9 executes shell commands defined in config.h instead of using signals.
10
11 Usage
12 -----
13 Both the nosignal version and the dwmblocks version will run their respective
14 shell commands/scripts with the environment variable BUTTON set to the button
15 that was pressed.
16
17 ### With signals
18 Apply the statuscmd patch and set the `STATUSBAR` macro in config.h
19 to the name of the status monitor.
20
21 Apply the corresponding statuscmd patch to your status monitor if there is
22 one, or extend the program on your own. Feel free to add patches for other
23 status monitors.
24
25 #### Patching status monitors
26 * Associate each section with a signal number in the range of 1-31.
27 * When setting the status text, print each section's respective signal number
28 as a raw byte before its text.
29 * With the 20241009 patch, printing the raw byte again at the end of block
30 output will end the clickable region.
31 * Create a signal handler:
32
33 void sighandler(int signum, siginfo_t *si, void *ucontext)
34 {
35 int signal = signum - SIGRTMIN;
36 int button = si->si_value.sival_int; /* if button is zero, the signal is not from a button press */
37 ... /* do whatever you want */
38 }
39
40 * Register the signal handler for each section in the following way, with
41 'signal' being the same signal from the first step:
42
43 struct sigaction sa = { .sa_sigaction = sighandler, .sa_flags = SA_SIGINFO };
44 sigaction(SIGRTMIN+signal, &sa, NULL);
45
46 ### Without signals
47 Apply the statuscmd-nosignal patch and fill the `statuscmds` array in config.h
48 with `StatusCmd` structs, which take a shell command string and an integer
49 identifier.
50
51 When setting the status, print the integer identifier as a raw byte before its
52 respective text.
53
54 For example, with `statuscmds` defined as such:
55
56 static const StatusCmd statuscmds[] = {
57 { "volume", 1 },
58 { "cpu", 2 },
59 { "battery", 3 },
60 };
61
62 And root name set like this:
63
64 xsetroot -name "$(printf '\x01 Volume \x01|\x02 CPU \x02|\x03 Battery\x03')"
65
66 Clicking on 'Volume |' would run `volume`, clicking on ' CPU |'
67 would run `cpu` and clicking on ' Battery' would run `battery`.
68
69 Example
70 -------
71 A script run from dwm or dwmblocks with this patch might look like this:
72
73 #!/bin/sh
74
75 case $BUTTON in
76 1) notify-send "CPU usage" "$(ps axch -o cmd,%cpu --sort=-%cpu | head)" ;;
77 3) st -e htop ;;
78 esac
79
80 printf '\x01Click Me!\x01'
81
82 Notes
83 -----
84 The signal version is not compatible with OpenBSD since it relies on `sigqueue`.
85
86 Be careful with newline characters in the status text since '\n' is equal to
87 '\x0a', which is a valid signal number. The problem where having certain
88 undrawable characters in the status bar can make dwm laggy is fixed since dwm
89 will not attempt to draw them with this patch.
90
91 Download
92 --------
93 ### dwm patches
94 * [dwm-statuscmd-20210405-67d76bd.diff](dwm-statuscmd-20210405-67d76bd.diff)
95 * [dwm-statuscmd-20241009-8933ebc.diff](./dwm-statuscmd-20241009-8933ebc.diff)
96 * [dwm-statuscmd-nosignal-20210402-67d76bd.diff](dwm-statuscmd-nosignal-20210402-67d76bd.diff)
97
98 If using [status2d](https://dwm.suckless.org/patches/status2d/), use these patches instead of the
99 above ones on top of a build already patched with status2d:
100
101 * [dwm-statuscmd-status2d-20210405-60bb3df.diff](dwm-statuscmd-status2d-20210405-60bb3df.diff)
102 * [dwm-statuscmd-nosignal-status2d-20210402-60bb3df.diff](dwm-statuscmd-nosignal-status2d-20210402-60bb3df.diff)
103
104 ### Status monitor patches
105 * [dwmblocks-statuscmd-20210402-96cbb45.diff](dwmblocks-statuscmd-20210402-96cbb45.diff)
106 * [gocaudices](https://github.com/LordRusk/gocaudices/tree/master/patches/statuscmd)
107
108 Author
109 ------
110 * Daniel Bylinka - <daniel.bylinka@gmail.com>
111 * Justinas Grigas - <dev@jstnas.com> (20241009)