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