git.sur5r.net Git - i3/i3status/blob - man/i3status.man

   1 i3status(1)
   2 ===========
   3 Michael Stapelberg <michael+i3@stapelberg.de>
   4 v2.3, July 2011
   5
   6 == NAME
   7
   8 i3status - Generates a status line for dzen2 or xmobar
   9
  10 == SYNOPSIS
  11
  12 i3status [-c configfile] [-h] [-v]
  13
  14 == OPTIONS
  15
  16 -c::
  17 Specifies an alternate configuration file path. By default, i3status looks for
  18 configuration files in the following order:
  19
  20 1. ~/.i3status.conf
  21 2. ~/.config/i3status/config (or $XDG_CONFIG_HOME/i3status/config if set)
  22 3. /etc/i3status.conf
  23 4. /etc/xdg/i3status/config (or $XDG_CONFIG_DIRS/i3status/config if set)
  24
  25 == DESCRIPTION
  26
  27 i3status is a small program (about 1500 SLOC) for generating a status bar for
  28 i3bar, dzen2, xmobar or similar programs. It is designed to be very
  29 efficient by issuing a very small number of system calls, as one generally
  30 wants to update such a status line every second. This ensures that even under
  31 high load, your status bar is updated correctly. Also, it saves a bit of energy
  32 by not hogging your CPU as much as spawning the corresponding amount of shell
  33 commands would.
  34
  35 == CONFIGURATION
  36
  37 Since version 2, the configuration file for i3status will be parsed using
  38 libconfuse. This makes configuration easier in the programmer’s point of
  39 view and more flexible for the user at the same time.
  40
  41 The basic idea of i3status is that you can specify which "modules" should
  42 be used (the order directive). You can then configure each module with its
  43 own section. For every module, you can specify the output format. See below
  44 for a complete reference.
  45
  46 .Sample configuration
  47 -------------------------------------------------------------
  48 general {
  49         output_format = "dzen2"
  50         colors = true
  51         interval = 5
  52 }
  53
  54 order  = "ipv6"
  55 order += "disk /"
  56 order += "run_watch DHCP"
  57 order += "run_watch VPN"
  58 order += "wireless wlan0"
  59 order += "ethernet eth0"
  60 order += "battery 0"
  61 order += "cpu_temperature 0"
  62 order += "load"
  63 order += "time"
  64
  65 wireless wlan0 {
  66         format_up = "W: (%quality at %essid, %bitrate) %ip"
  67         format_down = "W: down"
  68 }
  69
  70 ethernet eth0 {
  71         # if you use %speed, i3status requires the cap_net_admin capability
  72         format_up = "E: %ip (%speed)"
  73         format_down = "E: down"
  74 }
  75
  76 battery 0 {
  77         format = "%status %percentage %remaining"
  78 }
  79
  80 run_watch DHCP {
  81         pidfile = "/var/run/dhclient*.pid"
  82 }
  83
  84 run_watch VPN {
  85         pidfile = "/var/run/vpnc/pid"
  86 }
  87
  88 time {
  89         format = "%Y-%m-%d %H:%M:%S"
  90 }
  91
  92 load {
  93         format = "%5min"
  94 }
  95
  96 cpu_temperature 0 {
  97         format = "T: %degrees °C"
  98         path = "/sys/devices/platform/coretemp.0/temp1_input"
  99 }
 100
 101 disk "/" {
 102         format = "%free"
 103 }
 104 -------------------------------------------------------------
 105
 106 === General
 107
 108 The +colors+ directive will disable all colors if you set it to +false+. You can
 109 also specify the colors that will be used to display "good", "degraded" or "bad"
 110 values using the +color_good+, +color_degraded+ or +color_bad+ directives,
 111 respectively. Those directives are only used if color support is not disabled by
 112 the +colors+ directive. The input format for color values is the canonical RGB
 113 hexadecimal triplet (with no separators between the colors), prefixed by a hash
 114 character ("#").
 115
 116 *Example configuration*:
 117 -------------------------------------------------------------
 118 color_good = "#00FF00"
 119 -------------------------------------------------------------
 120
 121 Likewise, you can use the +color_separator+ directive to specify the color that
 122 will be used to paint the separator bar. The separator is always output in
 123 color, even when colors are disabled by the +colors+ directive.
 124
 125 The +interval+ directive specifies the time in seconds for which i3status will
 126 sleep before printing the next status line.
 127
 128 Using +output_format+ you can chose which format strings i3status should
 129 use in its output. Currently available are:
 130
 131 dzen2::
 132 Dzen is a general purpose messaging, notification and menuing program for X11.
 133 It was designed to be scriptable in any language and integrate well with window
 134 managers like dwm, wmii and xmonad though it will work with any windowmanger
 135 xmobar::
 136 xmobar is a minimalistic, text based, status bar. It was designed to work
 137 with the xmonad Window Manager.
 138 none::
 139 Does not use any color codes. Separates values by the pipe symbol. This should
 140 be used with i3bar and can be used for custom scripts.
 141
 142 === IPv6
 143
 144 This module gets the IPv6 address used for outgoing connections (that is, the
 145 best available public IPv6 address on your computer).
 146
 147 *Example format_up*: +%ip+
 148
 149 *Example format_down* +no IPv6+
 150
 151 === Disk
 152
 153 Gets used, free, available and total amount of bytes on the given mounted filesystem.
 154
 155 *Example order*: +disk /mnt/usbstick+
 156
 157 *Example format*: +%free (%avail)/ %total+
 158
 159 === Run-watch
 160
 161 Expands the given path to a pidfile and checks if the process ID found inside
 162 is valid (that is, if the process is running). You can use this to check if
 163 a specific application, such as a VPN client or your DHCP client is running.
 164
 165 *Example order*: +run_watch DHCP+
 166
 167 === Wireless
 168
 169 Gets the link quality and ESSID of the given wireless network interface. You
 170 can specify different format strings for the network being connected or not
 171 connected.
 172
 173 *Example order*: +wireless wlan0+
 174
 175 *Example format*: +W: (%quality at %essid, %bitrate) %ip+
 176
 177 === Ethernet
 178
 179 Gets the IP address and (if possible) the link speed of the given ethernet
 180 interface. Getting the link speed requires the cap_net_admin capability. Set
 181 it using +setcap cap_net_admin=ep $(which i3status)+.
 182
 183 *Example order*: +ethernet eth0+
 184
 185 *Example format*: +E: %ip (%speed)+
 186
 187 === Battery
 188
 189 Gets the status (charging, discharging, running), percentage and remaining
 190 time of the given battery. If you want to use the last full capacity instead
 191 of the design capacity (when using the design capacity, it may happen that
 192 your battery is at 23% when fully charged because it’s old. In general, I
 193 want to see it this way, because it tells me how worn off my battery is.),
 194 just specify +last_full_capacity = true+.
 195
 196 *Example order*: +battery 0+
 197
 198 *Example format*: +%status %remaining+
 199
 200 === CPU-Temperature
 201
 202 Gets the temperature of the given thermal zone.
 203
 204 *Example order*: +cpu_temperature 0+
 205
 206 *Example format*: +T: %degrees °C+
 207
 208 === CPU Usage
 209
 210 Gets the percentual CPU usage from +/proc/stat+.
 211
 212 *Example order*: +cpu_usage+
 213
 214 *Example format*: +%usage+
 215
 216 === Load
 217
 218 Gets the system load (number of processes waiting for CPU time in the last
 219 5, 10 and 15 minutes).
 220
 221 *Example order*: +load+
 222
 223 *Example format*: +%5min %10min %15min+
 224
 225 === Time
 226
 227 Formats the current system time. See +strftime(3)+ for the format.
 228
 229 *Example order*: +time+
 230
 231 *Example format*: +%Y-%m-%d %H:%M:%S+
 232
 233 === DDate
 234
 235 Outputs the current discordian date in user-specified format. See +ddate(1)+ for
 236 details on the format string.
 237 *Note*: Neither *%.* nor *%X* are implemented yet.
 238
 239 *Example order*: +ddate+
 240
 241 *Example format*: +%{%a, %b %d%}, %Y%N - %H+
 242
 243 === Volume
 244
 245 Outputs the volume of the specified mixer on the specified device. Works only
 246 on Linux because it uses ALSA.
 247
 248 *Example order*: +volume master+
 249
 250 *Example format*: +♪: %volume+
 251
 252 *Example configuration*:
 253 -------------------------------------------------------------
 254 volume master {
 255         format = "♪: %volume"
 256         device = "default"
 257         mixer = "Master"
 258         mixer_idx = 0
 259 }
 260 -------------------------------------------------------------
 261
 262 == Using i3status with dzen2
 263
 264 After installing dzen2, you can directly use it with i3status. Just ensure that
 265 +output_format+ is set to +dzen2+.
 266
 267 *Example for usage of i3status with dzen2*:
 268 --------------------------------------------------------------
 269 i3status | dzen2 -fg white -ta r -w 1280 \
 270 -fn "-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso8859-1"
 271 --------------------------------------------------------------
 272
 273 == Using i3status with xmobar
 274
 275 To get xmobar to start, you might need to copy the default configuration
 276 file to +~/.xmobarrc+. Also, ensure that the +output_format+ option for i3status
 277 is set to +xmobar+.
 278
 279 *Example for usage of i3status with xmobar*:
 280 ---------------------------------------------------------------------
 281 i3status | xmobar -o -t "%StdinReader%" -c "[Run StdinReader]"
 282 ---------------------------------------------------------------------
 283
 284 == External scripts/programs with i3status
 285
 286 In i3status, we don’t want to implement process management again. Therefore,
 287 there is no module to run arbitrary scripts or commands. Instead, you should
 288 use your shell, for example like this:
 289
 290 *Example for prepending the i3status output*:
 291 --------------------------------------------------------------
 292 i3status | while :
 293 do
 294         read line
 295         echo "mystuff | $line"
 296 done | i3bar -d
 297 --------------------------------------------------------------
 298
 299 == SEE ALSO
 300
 301 +strftime(3)+, +date(1)+, +glob(3)+, +dzen2(1)+, +xmobar(1)+
 302
 303 == AUTHORS
 304
 305 Michael Stapelberg and contributors
 306
 307 Thorsten Toepper
 308
 309 Baptiste Daroussin
 310
 311 Axel Wagner
 312
 313 Fernando Tarlá Cardoso Lemos