git.sur5r.net Git - i3/i3.github.io/blob - i3status/manpage.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"\r
   2     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\r
   4 <head>\r
   5 <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
   6 <meta name="generator" content="AsciiDoc 8.6.4" />\r
   7 <title>i3: i3status(1)</title>\r
   8 <link rel="stylesheet" href="/css/style.css" type="text/css" />\r
   9 <link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
  10 <script type="text/javascript">\r
  11 /*<![CDATA[*/\r
  12 window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}\r
  13 /*]]>*/\r
  14 </script>\r
  15 <script type="text/javascript" src="/js/asciidoc-xhtml11.js"></script>\r
  16 </head>\r
  17 <body class="article">\r
  18 \r
  19         <div id="main">\r
  20             <a href="/"><h1 id="title">i3 - improved tiling WM</h1></a>\r
  21                         <ul id="nav">\r
  22                                 <li><a style="border-bottom: 2px solid #fff" href="/docs">Docs</a></li>\r
  23                                 <li><a href="/screenshots">Screens</a></li>\r
  24                                 <li><a href="/contact">Contact</a></li>\r
  25                                 <li><a href="http://bugs.i3wm.org/">Bugs</a></li>\r
  26                         </ul>\r
  27         <br style="clear: both">\r
  28 <div id="content">\r
  29 <div id="header">\r
  30 <h1>i3status(1)</h1>\r
  31 <span id="author">Michael Stapelberg</span><br />\r
  32 <span id="email"><tt>&lt;<a href="mailto:michael+i3@stapelberg.de">michael+i3@stapelberg.de</a>&gt;</tt></span><br />\r
  33 <span id="revnumber">version 2.3,</span>\r
  34 <span id="revdate">July 2011</span>\r
  35 <div id="toc">
  36   <div id="toctitle">Table of Contents</div>
  37   <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
  38 </div>\r
  39 </div>\r
  40 <div class="sect1">\r
  41 <h2 id="_name">1. NAME</h2>\r
  42 <div class="sectionbody">\r
  43 <div class="paragraph"><p>i3status - Generates a status line for dzen2 or xmobar</p></div>\r
  44 </div>\r
  45 </div>\r
  46 <div class="sect1">\r
  47 <h2 id="_synopsis">2. SYNOPSIS</h2>\r
  48 <div class="sectionbody">\r
  49 <div class="paragraph"><p>i3status [-c configfile] [-h] [-v]</p></div>\r
  50 </div>\r
  51 </div>\r
  52 <div class="sect1">\r
  53 <h2 id="_options">3. OPTIONS</h2>\r
  54 <div class="sectionbody">\r
  55 <div class="dlist"><dl>\r
  56 <dt class="hdlist1">\r
  57 -c\r
  58 </dt>\r
  59 <dd>\r
  60 <p>\r
  61 Specifies an alternate configuration file path. By default, i3status looks for\r
  62 configuration files in the following order:\r
  63 </p>\r
  64 <div class="olist arabic"><ol class="arabic">\r
  65 <li>\r
  66 <p>\r
  67 ~/.i3status.conf\r
  68 </p>\r
  69 </li>\r
  70 <li>\r
  71 <p>\r
  72 ~/.config/i3status/config (or $XDG_CONFIG_HOME/i3status/config if set)\r
  73 </p>\r
  74 </li>\r
  75 <li>\r
  76 <p>\r
  77 /etc/i3status.conf\r
  78 </p>\r
  79 </li>\r
  80 <li>\r
  81 <p>\r
  82 /etc/xdg/i3status/config (or $XDG_CONFIG_DIRS/i3status/config if set)\r
  83 </p>\r
  84 </li>\r
  85 </ol></div>\r
  86 </dd>\r
  87 </dl></div>\r
  88 </div>\r
  89 </div>\r
  90 <div class="sect1">\r
  91 <h2 id="_description">4. DESCRIPTION</h2>\r
  92 <div class="sectionbody">\r
  93 <div class="paragraph"><p>i3status is a small program (about 1500 SLOC) for generating a status bar for\r
  94 i3bar, dzen2, xmobar or similar programs. It is designed to be very\r
  95 efficient by issuing a very small number of system calls, as one generally\r
  96 wants to update such a status line every second. This ensures that even under\r
  97 high load, your status bar is updated correctly. Also, it saves a bit of energy\r
  98 by not hogging your CPU as much as spawning the corresponding amount of shell\r
  99 commands would.</p></div>\r
 100 </div>\r
 101 </div>\r
 102 <div class="sect1">\r
 103 <h2 id="_configuration">5. CONFIGURATION</h2>\r
 104 <div class="sectionbody">\r
 105 <div class="paragraph"><p>Since version 2, the configuration file for i3status will be parsed using\r
 106 libconfuse. This makes configuration easier in the programmer’s point of\r
 107 view and more flexible for the user at the same time.</p></div>\r
 108 <div class="paragraph"><p>The basic idea of i3status is that you can specify which "modules" should\r
 109 be used (the order directive). You can then configure each module with its\r
 110 own section. For every module, you can specify the output format. See below\r
 111 for a complete reference.</p></div>\r
 112 <div class="listingblock">\r
 113 <div class="title">Sample configuration</div>\r
 114 <div class="content">\r
 115 <pre><tt>general {\r
 116         output_format = "dzen2"\r
 117         colors = true\r
 118         interval = 5\r
 119 }\r
 120 \r
 121 order  = "ipv6"\r
 122 order += "disk /"\r
 123 order += "run_watch DHCP"\r
 124 order += "run_watch VPN"\r
 125 order += "wireless wlan0"\r
 126 order += "ethernet eth0"\r
 127 order += "battery 0"\r
 128 order += "cpu_temperature 0"\r
 129 order += "load"\r
 130 order += "time"\r
 131 \r
 132 wireless wlan0 {\r
 133         format_up = "W: (%quality at %essid, %bitrate) %ip"\r
 134         format_down = "W: down"\r
 135 }\r
 136 \r
 137 ethernet eth0 {\r
 138         # if you use %speed, i3status requires the cap_net_admin capability\r
 139         format_up = "E: %ip (%speed)"\r
 140         format_down = "E: down"\r
 141 }\r
 142 \r
 143 battery 0 {\r
 144         format = "%status %percentage %remaining"\r
 145 }\r
 146 \r
 147 run_watch DHCP {\r
 148         pidfile = "/var/run/dhclient*.pid"\r
 149 }\r
 150 \r
 151 run_watch VPN {\r
 152         pidfile = "/var/run/vpnc/pid"\r
 153 }\r
 154 \r
 155 time {\r
 156         format = "%Y-%m-%d %H:%M:%S"\r
 157 }\r
 158 \r
 159 load {\r
 160         format = "%5min"\r
 161 }\r
 162 \r
 163 cpu_temperature 0 {\r
 164         format = "T: %degrees °C"\r
 165         path = "/sys/devices/platform/coretemp.0/temp1_input"\r
 166 }\r
 167 \r
 168 disk "/" {\r
 169         format = "%free"\r
 170 }</tt></pre>\r
 171 </div></div>\r
 172 <div class="sect2">\r
 173 <h3 id="_general">5.1. General</h3>\r
 174 <div class="paragraph"><p>The <tt>colors</tt> directive will disable all colors if you set it to <tt>false</tt>. You can\r
 175 also specify the colors that will be used to display "good", "degraded" or "bad"\r
 176 values using the <tt>color_good</tt>, <tt>color_degraded</tt> or <tt>color_bad</tt> directives,\r
 177 respectively. Those directives are only used if color support is not disabled by\r
 178 the <tt>colors</tt> directive. The input format for color values is the canonical RGB\r
 179 hexadecimal triplet (with no separators between the colors), prefixed by a hash\r
 180 character ("#").</p></div>\r
 181 <div class="paragraph"><p><strong>Example configuration</strong>:</p></div>\r
 182 <div class="listingblock">\r
 183 <div class="content">\r
 184 <pre><tt>color_good = "#00FF00"</tt></pre>\r
 185 </div></div>\r
 186 <div class="paragraph"><p>Likewise, you can use the <tt>color_separator</tt> directive to specify the color that\r
 187 will be used to paint the separator bar. The separator is always output in\r
 188 color, even when colors are disabled by the <tt>colors</tt> directive.</p></div>\r
 189 <div class="paragraph"><p>The <tt>interval</tt> directive specifies the time in seconds for which i3status will\r
 190 sleep before printing the next status line.</p></div>\r
 191 <div class="paragraph"><p>Using <tt>output_format</tt> you can chose which format strings i3status should\r
 192 use in its output. Currently available are:</p></div>\r
 193 <div class="dlist"><dl>\r
 194 <dt class="hdlist1">\r
 195 dzen2\r
 196 </dt>\r
 197 <dd>\r
 198 <p>\r
 199 Dzen is a general purpose messaging, notification and menuing program for X11.\r
 200 It was designed to be scriptable in any language and integrate well with window\r
 201 managers like dwm, wmii and xmonad though it will work with any windowmanger\r
 202 </p>\r
 203 </dd>\r
 204 <dt class="hdlist1">\r
 205 xmobar\r
 206 </dt>\r
 207 <dd>\r
 208 <p>\r
 209 xmobar is a minimalistic, text based, status bar. It was designed to work\r
 210 with the xmonad Window Manager.\r
 211 </p>\r
 212 </dd>\r
 213 <dt class="hdlist1">\r
 214 none\r
 215 </dt>\r
 216 <dd>\r
 217 <p>\r
 218 Does not use any color codes. Separates values by the pipe symbol. This should\r
 219 be used with i3bar and can be used for custom scripts.\r
 220 </p>\r
 221 </dd>\r
 222 </dl></div>\r
 223 </div>\r
 224 <div class="sect2">\r
 225 <h3 id="_ipv6">5.2. IPv6</h3>\r
 226 <div class="paragraph"><p>This module gets the IPv6 address used for outgoing connections (that is, the\r
 227 best available public IPv6 address on your computer).</p></div>\r
 228 <div class="paragraph"><p><strong>Example format_up</strong>: <tt>%ip</tt></p></div>\r
 229 <div class="paragraph"><p><strong>Example format_down</strong> <tt>no IPv6</tt></p></div>\r
 230 </div>\r
 231 <div class="sect2">\r
 232 <h3 id="_disk">5.3. Disk</h3>\r
 233 <div class="paragraph"><p>Gets used, free, available and total amount of bytes on the given mounted filesystem.</p></div>\r
 234 <div class="paragraph"><p><strong>Example order</strong>: <tt>disk /mnt/usbstick</tt></p></div>\r
 235 <div class="paragraph"><p><strong>Example format</strong>: <tt>%free (%avail)/ %total</tt></p></div>\r
 236 </div>\r
 237 <div class="sect2">\r
 238 <h3 id="_run_watch">5.4. Run-watch</h3>\r
 239 <div class="paragraph"><p>Expands the given path to a pidfile and checks if the process ID found inside\r
 240 is valid (that is, if the process is running). You can use this to check if\r
 241 a specific application, such as a VPN client or your DHCP client is running.</p></div>\r
 242 <div class="paragraph"><p><strong>Example order</strong>: <tt>run_watch DHCP</tt></p></div>\r
 243 </div>\r
 244 <div class="sect2">\r
 245 <h3 id="_wireless">5.5. Wireless</h3>\r
 246 <div class="paragraph"><p>Gets the link quality and ESSID of the given wireless network interface. You\r
 247 can specify different format strings for the network being connected or not\r
 248 connected.</p></div>\r
 249 <div class="paragraph"><p><strong>Example order</strong>: <tt>wireless wlan0</tt></p></div>\r
 250 <div class="paragraph"><p><strong>Example format</strong>: <tt>W: (%quality at %essid, %bitrate) %ip</tt></p></div>\r
 251 </div>\r
 252 <div class="sect2">\r
 253 <h3 id="_ethernet">5.6. Ethernet</h3>\r
 254 <div class="paragraph"><p>Gets the IP address and (if possible) the link speed of the given ethernet\r
 255 interface. Getting the link speed requires the cap_net_admin capability. Set\r
 256 it using <tt>setcap cap_net_admin=ep $(which i3status)</tt>.</p></div>\r
 257 <div class="paragraph"><p><strong>Example order</strong>: <tt>ethernet eth0</tt></p></div>\r
 258 <div class="paragraph"><p><strong>Example format</strong>: <tt>E: %ip (%speed)</tt></p></div>\r
 259 </div>\r
 260 <div class="sect2">\r
 261 <h3 id="_battery">5.7. Battery</h3>\r
 262 <div class="paragraph"><p>Gets the status (charging, discharging, running), percentage and remaining\r
 263 time of the given battery. If you want to use the last full capacity instead\r
 264 of the design capacity (when using the design capacity, it may happen that\r
 265 your battery is at 23% when fully charged because it’s old. In general, I\r
 266 want to see it this way, because it tells me how worn off my battery is.),\r
 267 just specify <tt>last_full_capacity = true</tt>.</p></div>\r
 268 <div class="paragraph"><p><strong>Example order</strong>: <tt>battery 0</tt></p></div>\r
 269 <div class="paragraph"><p><strong>Example format</strong>: <tt>%status %remaining</tt></p></div>\r
 270 </div>\r
 271 <div class="sect2">\r
 272 <h3 id="_cpu_temperature">5.8. CPU-Temperature</h3>\r
 273 <div class="paragraph"><p>Gets the temperature of the given thermal zone.</p></div>\r
 274 <div class="paragraph"><p><strong>Example order</strong>: <tt>cpu_temperature 0</tt></p></div>\r
 275 <div class="paragraph"><p><strong>Example format</strong>: <tt>T: %degrees °C</tt></p></div>\r
 276 </div>\r
 277 <div class="sect2">\r
 278 <h3 id="_cpu_usage">5.9. CPU Usage</h3>\r
 279 <div class="paragraph"><p>Gets the percentual CPU usage from <tt>/proc/stat</tt>.</p></div>\r
 280 <div class="paragraph"><p><strong>Example order</strong>: <tt>cpu_usage</tt></p></div>\r
 281 <div class="paragraph"><p><strong>Example format</strong>: <tt>%usage</tt></p></div>\r
 282 </div>\r
 283 <div class="sect2">\r
 284 <h3 id="_load">5.10. Load</h3>\r
 285 <div class="paragraph"><p>Gets the system load (number of processes waiting for CPU time in the last\r
 286 5, 10 and 15 minutes).</p></div>\r
 287 <div class="paragraph"><p><strong>Example order</strong>: <tt>load</tt></p></div>\r
 288 <div class="paragraph"><p><strong>Example format</strong>: <tt>%5min %10min %15min</tt></p></div>\r
 289 </div>\r
 290 <div class="sect2">\r
 291 <h3 id="_time">5.11. Time</h3>\r
 292 <div class="paragraph"><p>Formats the current system time. See <tt>strftime(3)</tt> for the format.</p></div>\r
 293 <div class="paragraph"><p><strong>Example order</strong>: <tt>time</tt></p></div>\r
 294 <div class="paragraph"><p><strong>Example format</strong>: <tt>%Y-%m-%d %H:%M:%S</tt></p></div>\r
 295 </div>\r
 296 <div class="sect2">\r
 297 <h3 id="_ddate">5.12. DDate</h3>\r
 298 <div class="paragraph"><p>Outputs the current discordian date in user-specified format. See <tt>ddate(1)</tt> for\r
 299 details on the format string.\r
 300 <strong>Note</strong>: Neither <strong>%.</strong> nor <strong>%X</strong> are implemented yet.</p></div>\r
 301 <div class="paragraph"><p><strong>Example order</strong>: <tt>ddate</tt></p></div>\r
 302 <div class="paragraph"><p><strong>Example format</strong>: <tt>%{%a, %b %d%}, %Y%N - %H</tt></p></div>\r
 303 </div>\r
 304 <div class="sect2">\r
 305 <h3 id="_volume">5.13. Volume</h3>\r
 306 <div class="paragraph"><p>Outputs the volume of the specified mixer on the specified device. Works only\r
 307 on Linux because it uses ALSA.</p></div>\r
 308 <div class="paragraph"><p><strong>Example order</strong>: <tt>volume master</tt></p></div>\r
 309 <div class="paragraph"><p><strong>Example format</strong>: <tt>♪: %volume</tt></p></div>\r
 310 <div class="paragraph"><p><strong>Example configuration</strong>:</p></div>\r
 311 <div class="listingblock">\r
 312 <div class="content">\r
 313 <pre><tt>volume master {\r
 314         format = "♪: %volume"\r
 315         device = "default"\r
 316         mixer = "Master"\r
 317         mixer_idx = 0\r
 318 }</tt></pre>\r
 319 </div></div>\r
 320 </div>\r
 321 </div>\r
 322 </div>\r
 323 <div class="sect1">\r
 324 <h2 id="_using_i3status_with_dzen2">6. Using i3status with dzen2</h2>\r
 325 <div class="sectionbody">\r
 326 <div class="paragraph"><p>After installing dzen2, you can directly use it with i3status. Just ensure that\r
 327 <tt>output_format</tt> is set to <tt>dzen2</tt>.</p></div>\r
 328 <div class="paragraph"><p><strong>Example for usage of i3status with dzen2</strong>:</p></div>\r
 329 <div class="listingblock">\r
 330 <div class="content">\r
 331 <pre><tt>i3status | dzen2 -fg white -ta r -w 1280 \\r
 332 -fn "-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso8859-1"</tt></pre>\r
 333 </div></div>\r
 334 </div>\r
 335 </div>\r
 336 <div class="sect1">\r
 337 <h2 id="_using_i3status_with_xmobar">7. Using i3status with xmobar</h2>\r
 338 <div class="sectionbody">\r
 339 <div class="paragraph"><p>To get xmobar to start, you might need to copy the default configuration\r
 340 file to <tt>~/.xmobarrc</tt>. Also, ensure that the <tt>output_format</tt> option for i3status\r
 341 is set to <tt>xmobar</tt>.</p></div>\r
 342 <div class="paragraph"><p><strong>Example for usage of i3status with xmobar</strong>:</p></div>\r
 343 <div class="listingblock">\r
 344 <div class="content">\r
 345 <pre><tt>i3status | xmobar -o -t "%StdinReader%" -c "[Run StdinReader]"</tt></pre>\r
 346 </div></div>\r
 347 </div>\r
 348 </div>\r
 349 <div class="sect1">\r
 350 <h2 id="_see_also">8. SEE ALSO</h2>\r
 351 <div class="sectionbody">\r
 352 <div class="paragraph"><p><tt>strftime(3)</tt>, <tt>date(1)</tt>, <tt>glob(3)</tt>, <tt>dzen2(1)</tt>, <tt>xmobar(1)</tt></p></div>\r
 353 </div>\r
 354 </div>\r
 355 <div class="sect1">\r
 356 <h2 id="_authors">9. AUTHORS</h2>\r
 357 <div class="sectionbody">\r
 358 <div class="paragraph"><p>Michael Stapelberg and contributors</p></div>\r
 359 <div class="paragraph"><p>Thorsten Toepper</p></div>\r
 360 <div class="paragraph"><p>Baptiste Daroussin</p></div>\r
 361 <div class="paragraph"><p>Axel Wagner</p></div>\r
 362 <div class="paragraph"><p>Fernando Tarlá Cardoso Lemos</p></div>\r
 363 </div>\r
 364 </div>\r
 365 </div>\r
 366 <div id="footnotes"><hr /></div>\r
 367 <div id="footer" lang="de">\r
 368 © 2009-2011 Michael Stapelberg, <a href="/impress.html">Impressum</a>\r
 369 </div>\r
 370 </body>\r
 371 </html>\r