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 %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.
 149
 150 *Example order*: +battery 0+
 151
 152 *Example format*: +%status %remaining+
 153
 154 === CPU-Temperature
 155
 156 Gets the temperature of the given thermal zone.
 157
 158 *Example order*: +cpu_temperature 0+
 159
 160 *Example format*: +T: %degrees °C+
 161
 162 === Load
 163
 164 Gets the system load (number of processes waiting for CPU time in the last
 165 5, 10 and 15 minutes).
 166
 167 *Example order*: +load+
 168
 169 *Example format*: +%5min %10min %15min+
 170
 171 === Time
 172
 173 Formats the current system time. See +strftime(3)+ for the format.
 174
 175 *Example order*: +time+
 176
 177 *Example format*: +%Y-%m-%d %H:%M:%S+
 178
 179 == Using i3status with dzen2
 180
 181 After installing dzen2, you can directly use it with i3status:
 182
 183 *Example for usage of i3status with dzen2*:
 184 --------------------------------------------------------------
 185 i3status | dzen2 -fg white -ta r -w 1280 \
 186 -fn "-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso8859-1"
 187 --------------------------------------------------------------
 188
 189 == Using i3status with xmobar
 190
 191 To get xmobar to start, you might need to copy the default configuration
 192 file to +~/.xmobarrc+.
 193
 194 *Example for usage of i3status with xmobar*:
 195 ---------------------------------------------------------------------
 196 i3status-xmobar | xmobar -o -t "%StdinReader%" -c "[Run StdinReader]"
 197 ---------------------------------------------------------------------
 198
 199 == SEE ALSO
 200
 201 +strftime(3)+, +date(1)+, +glob(3)+, +dzen2(1)+, +xmobar(1)+
 202
 203 == AUTHORS
 204
 205 Michael Stapelberg and contributors
 206
 207 Thorsten Toepper
 208
 209 Baptiste Daroussin