README (5718B)
1 infobar - Unixy status monitor 2 ============================== 3 infobar is an event-driven status monitor for Linux, fully customizable 4 and extensible via shell scripting. 5 6 7 Overview 8 -------- 9 infobar, a shell script, is a status program 10 created for [swm](<https://wolog.xyz/repos/swm). Unlike 11 [slstatus](<https://tools.suckless.org/slstatus>) and the like that update 12 all components every second or so, infobar blocks until new information 13 comes in and selectively updates components. These are achieved with 14 the help of two small dedicated utilities, fifolog and ticktack, which 15 are explained later. 16 17 Using infobar with swm, by default the following components are displayed, 18 with most being clickable: 19 20 - Network. An icon indicates either no internet connection or the type 21 and state of the connection; this is updated upon relevant netlink 22 messages. When clicked, it unfolds to include network traffic and, 23 if the connection is wireless, signal strength as well; these are 24 updated every second. Clicking the component again folds it. 25 26 - Volume. There's an icon indicating whether the master device is 27 muted or not, followed by the real-time volume percentage, updated 28 upon relevant device events. Pointing the mouse to it, scrolling up 29 and down changes the volume and right clicking toggles muting. 30 31 - Processor. By default the load average over the last minute (read from 32 /proc/loadavg) is displayed and updated every minute. When clicked, 33 it shows in addition CPU usage percentage and frequency, and also adds 34 a new component showing memory usage; these are updated every second. 35 Click either component to fold them. 36 37 - Battery. This shows the battery percentage, which is updated every 38 minute, followed by possibly a lighting icon to indicate charging, 39 which is updated upon relevant ACPI events. This one doesn't respond 40 to the mouse. 41 42 - Clock. Shows time with the precision of minutes, updated at the start 43 of every minute. Clicking it toggles whether seconds and other details 44 are shown. 45 46 47 Installation 48 ------------ 49 Execute the following command, as root if necessary: 50 51 make install 52 53 infobar, fifolog and ticktack are installed into /usr/local/bin by 54 default. 55 56 Requirements of running infobar: 57 58 - the ip command for the network component. 59 60 - aximer and alsactl for the volume component. 61 62 - acpi_listen for the battery component. 63 64 To make icons output by infobar rendered correctly, make sure [font 65 awesome](https://fontawesome.com) version 5 or above is installed and 66 that swm (or whatever that renders the status text) loads the font. 67 You may as well change the script to avoid using that font. 68 69 70 Customization 71 ------------- 72 You can find a line in the infobar script like this: 73 74 setbar ' %n %v %p %b %c ' 75 76 Modify the string to customize the bar. See the comments there for help. 77 78 You can further customize and extend infobar by changing the script. 79 Sections below will give you an idea about how it operates. 80 81 Tip for debugging: Run infobar on the command line. 82 83 84 fifolog 85 ------- 86 fifolog takes its arguments as paths to FIFOs. It polls the FIFOs, 87 and every time some of them become ready for reading, it reads whole 88 lines from each and output the lines to stdout, each prefixed with the 89 basename of the source FIFO followed by a space. Besides paths of FIFOs, 90 when given an "-" argument (the default argument when none is given) 91 fifolog also polls from its standard input, and the prefix for lines 92 read from there is "-" followed by a space. 93 94 When the write end of one of the FIFOs is closed, fifolog outputs the 95 base name of the FIFO prefixed by "!" followed by a space, and reopens 96 the FIFO to continue polling. If the standard input is polled and its 97 write end gets closed, fifolog exits. 98 99 100 ticktack 101 -------- 102 ticktack accepts options -s and -m. When given -s, ticktack outputs a 103 line with the single letter "s" at the start of every second. When given 104 -m, ticktack outputs a line with the single letter "m" at the start of 105 every minute. If both are given, ticktack outputs "s" at the start of 106 every second, except for the start of first second of every minute when 107 it outputs "m". When given no option, ticktack blocks indefinitely. 108 109 Internally, ticktack uses the time since the Epoch to determine when the 110 start of next second or next minute is, with the latter being the next 111 time the seconds since the Epoch become divisible by 60, which should 112 be aligned with second zero of minutes as output by the date command. 113 114 Once knowing the next time to output, ticktack uses clock_nanosleep with 115 flag TIMER_ABSTIME to sleep till that absolute time. Have the program 116 been written to sleep for, say, for a minute, then, once the system gets 117 suspended in the middle of the sleep, after resumption the sleep will 118 continue even when it might have been hours later. By sleeping to an 119 absolute point of time, if the system gets suspended past the target 120 time, the sleep will stop right after system resumption and ticktack 121 will be able to immediately detect a prolonged sleep and output what it 122 should have. 123 124 125 The Script 126 ---------- 127 infobar creates a temporary directory (named /tmp/infobar.<pid>) and 128 makes FIFOs there to listen to notifier commands, like `alsa monitor` 129 that notifies about volume and muting change. fifolog is used for 130 collecting input lines from the FIFOs and stdin and feeding them to the 131 main loop in the script. ticktack functions as one notifier program. 132 infobar always runs it with only necessary options, and would kill and 133 rerun ticktack to ensure that. 134 135 Other details remain to be learnt from the script. If you know shell 136 scripting well the script probably explains itself more articulately 137 than documentation could do.