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

   1 i3status(1)
   2 ===========
   3 Michael Stapelberg <michael+i3@stapelberg.de>
   4 v2, October 2009
   5
   6 == NAME
   7
   8 i3status - Generates a status line for dzen2 or xmobar
   9
  10 == SYNOPSIS
  11
  12 i3status [-c configfile]
  13
  14 == OPTIONS
  15
  16 -c::
  17 Specifies an alternate configuration file path (default is /etc/i3status.conf
  18 or ~/.i3status.conf).
  19
  20 == DESCRIPTION
  21
  22 i3status is a small program (less than 1000 SLOC) for generating a status bar
  23 for dzen2, xmobar or similar programs. It is designed to be very efficient by
  24 issuing a very small number of systemcalls, as one generally wants to update
  25 such a status line every second. This ensures that even under high load, your
  26 status bar is updated correctly. Also, it saves a bit of energy by not hogging
  27 your CPU as much as spawning the corresponding amount of shell commands would.
  28
  29 == CONFIGURATION
  30
  31 Since version 2, the configuration file for i3status will be parsed using
  32 libconfuse. This makes configuration easier in the programmer’s point of
  33 view and more flexible for the user at the same time.
  34
  35 The basic idea of i3status is that you can specify which "modules" should
  36 be used (the order directive). You can then configure each module with its
  37 own section. For every module, you can specify the output format. See below
  38 for a complete reference.
  39
  40 .Sample configuration
  41 -------------------------------------------------------------
  42 general {
  43         colors = true
  44         interval = 5
  45 }
  46
  47 order  = "ipv6"
  48 order += "disk /"
  49 order += "run_watch DHCP"
  50 order += "run_watch VPN"
  51 order += "wireless wlan0"
  52 order += "ethernet eth0"
  53 order += "battery 0"
  54 order += "cpu_temperature 0"
  55 order += "load"
  56 order += "time"
  57
  58 wireless wlan0 {
  59         format_up = "W: (%quality at %essid) %ip"
  60         format_down = "W: down"
  61 }
  62
  63 ethernet eth0 {
  64         # if you use %speed, i3status requires root privileges
  65         format = "E: %ip (%speed)"
  66 }
  67
  68 battery 0 {
  69         format = "%status %percentage %remaining"
  70 }
  71
  72 run_watch DHCP {
  73         pidfile = "/var/run/dhclient*.pid"
  74 }
  75
  76 run_watch VPN {
  77         pidfile = "/var/run/vpnc/pid"
  78 }
  79
  80 time {
  81         format = "%Y-%m-%d %H:%M:%S"
  82 }
  83
  84 load {
  85         format = "%5min"
  86 }
  87
  88 cpu_temperature 0 {
  89         format = "T: %degrees °C"
  90 }
  91
  92 disk "/" {
  93         format = "%free"
  94 }
  95 -------------------------------------------------------------
  96
  97 === General
  98
  99 The colors directive will disable all colors if you set it to +false+.
 100 +interval+ is the time in seconds which i3status will sleep until printing
 101 the next status line.
 102
 103 === IPv6
 104
 105 This module gets the IPv6 address used for outgoing connections (that is, the
 106 best available public IPv6 address on your computer).
 107
 108 *Example format*: +%ip+
 109
 110 === Disk
 111
 112 Gets used, free and total amount of bytes on the given mounted filesystem.
 113
 114 *Example order*: +disk /mnt/usbstick+
 115
 116 *Example format*: +%free / %total+
 117
 118 === Run-watch
 119
 120 Expands the given path to a pidfile and checks if the process ID found inside
 121 is valid (that is, if the process is running). You can use this to check if
 122 a specific application, such as a VPN client or your DHCP client is running.
 123
 124 *Example order*: +run_watch DHCP+
 125
 126 === Wireless
 127
 128 Gets the link quality and ESSID of the given wireless network interface. You
 129 can specify different format strings for the network being connected or not
 130 connected.
 131
 132 *Example order*: +wireless wlan0+
 133
 134 *Example format*: +W: (%quality at %essid) %ip+
 135
 136 === Ethernet
 137
 138 Gets the IP address and (if possible) the link speed of the given ethernet
 139 interface. Getting the link speed requires root privileges.
 140
 141 *Example order*: +ethernet eth0+
 142
 143 *Example format*: +E: %ip (%speed)+
 144
 145 === Battery
 146
 147 Gets the status (charging, discharging, running), percentage and remaining
 148 time of the given battery. If you want to use the last full capacity instead
 149 of the design capacity (when using the design capacity, it may happen that
 150 your battery is at 23% when fully charged because it’s old. In general, I
 151 want to see it this way, because it tells me how worn off my battery is.),
 152 just specify +last_full_capacity = true+.
 153
 154 *Example order*: +battery 0+
 155
 156 *Example format*: +%status %remaining+
 157
 158 === CPU-Temperature
 159
 160 Gets the temperature of the given thermal zone.
 161
 162 *Example order*: +cpu_temperature 0+
 163
 164 *Example format*: +T: %degrees °C+
 165
 166 === Load
 167
 168 Gets the system load (number of processes waiting for CPU time in the last
 169 5, 10 and 15 minutes).
 170
 171 *Example order*: +load+
 172
 173 *Example format*: +%5min %10min %15min+
 174
 175 === Time
 176
 177 Formats the current system time. See +strftime(3)+ for the format.
 178
 179 *Example order*: +time+
 180
 181 *Example format*: +%Y-%m-%d %H:%M:%S+
 182
 183 == Using i3status with dzen2
 184
 185 After installing dzen2, you can directly use it with i3status:
 186
 187 *Example for usage of i3status with dzen2*:
 188 --------------------------------------------------------------
 189 i3status | dzen2 -fg white -ta r -w 1280 \
 190 -fn "-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso8859-1"
 191 --------------------------------------------------------------
 192
 193 == Using i3status with xmobar
 194
 195 To get xmobar to start, you might need to copy the default configuration
 196 file to +~/.xmobarrc+.
 197
 198 *Example for usage of i3status with xmobar*:
 199 ---------------------------------------------------------------------
 200 i3status-xmobar | xmobar -o -t "%StdinReader%" -c "[Run StdinReader]"
 201 ---------------------------------------------------------------------
 202
 203 == SEE ALSO
 204
 205 +strftime(3)+, +date(1)+, +glob(3)+, +dzen2(1)+, +xmobar(1)+
 206
 207 == AUTHORS
 208
 209 Michael Stapelberg and contributors
 210
 211 Thorsten Toepper
 212
 213 Baptiste Daroussin