"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\r
<head>\r
-<link rel="icon" type="image/png" href="/favicon.png">\r
+<link rel="icon" type="image/x-icon" href="/favicon.ico">\r
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />\r
-<meta name="generator" content="AsciiDoc 8.6.6" />\r
+<meta name="generator" content="AsciiDoc 8.6.10" />\r
<title>i3: i3status(1)</title>\r
<link rel="stylesheet" href="/css/style.css" type="text/css" />\r
<link rel="stylesheet" href="/css/xhtml11.css" type="text/css" />\r
<script type="text/javascript">\r
/*<![CDATA[*/\r
-window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}\r
+document.addEventListener("DOMContentLoaded", function(){asciidoc.footnotes(); asciidoc.toc(2);}, false);\r
/*]]>*/\r
</script>\r
<script type="text/javascript" src="/js/asciidoc-xhtml11.js"></script>\r
<ul id="nav">\r
<li><a style="border-bottom: 2px solid #fff" href="/docs">Docs</a></li>\r
<li><a href="/screenshots">Screens</a></li>\r
+ <li><a href="https://www.reddit.com/r/i3wm/">FAQ</a></li>\r
<li><a href="/contact">Contact</a></li>\r
- <li><a href="http://bugs.i3wm.org/">Bugs</a></li>\r
+ <li><a href="https://github.com/i3/i3/issues">Bugs</a></li>\r
</ul>\r
<br style="clear: both">\r
<div id="content">\r
<div id="header">\r
<h1>i3status(1)</h1>\r
<span id="author">Michael Stapelberg</span><br />\r
-<span id="email"><tt><<a href="mailto:michael+i3@stapelberg.de">michael+i3@stapelberg.de</a>></tt></span><br />\r
-<span id="revnumber">version 2.5,</span>\r
-<span id="revdate">May 2012</span>\r
+<span id="email"><tt><<a href="mailto:michael@i3wm.org">michael@i3wm.org</a>></tt></span><br />\r
+<span id="revnumber">version 2.12,</span>\r
+<span id="revdate">May 2018</span>\r
<div id="toc">
<div id="toctitle">Table of Contents</div>
<noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
<div class="sect1">\r
<h2 id="_name">1. NAME</h2>\r
<div class="sectionbody">\r
-<div class="paragraph"><p>i3status - Generates a status line for dzen2 or xmobar</p></div>\r
+<div class="paragraph"><p>i3status - Generates a status line for i3bar, dzen2, xmobar or lemonbar</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
<div class="olist arabic"><ol class="arabic">\r
<li>\r
<p>\r
-~/.i3status.conf\r
+~/.config/i3status/config (or $XDG_CONFIG_HOME/i3status/config if set)\r
</p>\r
</li>\r
<li>\r
<p>\r
-~/.config/i3status/config (or $XDG_CONFIG_HOME/i3status/config if set)\r
+/etc/xdg/i3status/config (or $XDG_CONFIG_DIRS/i3status/config if set)\r
</p>\r
</li>\r
<li>\r
<p>\r
-/etc/i3status.conf\r
+~/.i3status.conf\r
</p>\r
</li>\r
<li>\r
<p>\r
-/etc/xdg/i3status/config (or $XDG_CONFIG_DIRS/i3status/config if set)\r
+/etc/i3status.conf\r
</p>\r
</li>\r
</ol></div>\r
<div class="sect1">\r
<h2 id="_description">4. DESCRIPTION</h2>\r
<div class="sectionbody">\r
-<div class="paragraph"><p>i3status is a small program (about 1500 SLOC) for generating a status bar for\r
-i3bar, dzen2, xmobar or similar programs. It is designed to be very\r
-efficient by issuing a very small number of system calls, as one generally\r
-wants to update such a status line every second. This ensures that even under\r
-high load, your status bar is updated correctly. Also, it saves a bit of energy\r
-by not hogging your CPU as much as spawning the corresponding amount of shell\r
-commands would.</p></div>\r
+<div class="paragraph"><p>i3status is a small program for generating a status bar for i3bar, dzen2,\r
+xmobar, lemonbar or similar programs. It is designed to be very efficient by\r
+issuing a very small number of system calls, as one generally wants to update\r
+such a status line every second. This ensures that even under high load, your\r
+status bar is updated correctly. Also, it saves a bit of energy by not hogging\r
+your CPU as much as spawning the corresponding amount of shell commands would.</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
order += "ipv6"\r
order += "disk /"\r
order += "run_watch DHCP"\r
-order += "run_watch VPN"\r
+order += "run_watch VPNC"\r
+order += "path_exists VPN"\r
order += "wireless wlan0"\r
order += "ethernet eth0"\r
order += "battery 0"\r
order += "cpu_temperature 0"\r
order += "load"\r
-order += "time"\r
+order += "tztime local"\r
+order += "tztime berlin"\r
\r
wireless wlan0 {\r
format_up = "W: (%quality at %essid, %bitrate) %ip"\r
\r
battery 0 {\r
format = "%status %percentage %remaining %emptytime"\r
+ format_down = "No battery"\r
+ status_chr = "⚡ CHR"\r
+ status_bat = "🔋 BAT"\r
+ status_unk = "? UNK"\r
+ status_full = "☻ FULL"\r
path = "/sys/class/power_supply/BAT%d/uevent"\r
+ low_threshold = 10\r
}\r
\r
run_watch DHCP {\r
pidfile = "/var/run/dhclient*.pid"\r
}\r
\r
-run_watch VPN {\r
+run_watch VPNC {\r
+ # file containing the PID of a vpnc process\r
pidfile = "/var/run/vpnc/pid"\r
}\r
\r
-time {\r
+path_exists VPN {\r
+ # path exists when a VPN tunnel launched by nmcli/nm-applet is active\r
+ path = "/proc/sys/net/ipv4/conf/tun0"\r
+}\r
+\r
+tztime local {\r
format = "%Y-%m-%d %H:%M:%S"\r
}\r
\r
+tztime berlin {\r
+ format = "%Y-%m-%d %H:%M:%S %Z"\r
+ timezone = "Europe/Berlin"\r
+}\r
+\r
load {\r
format = "%5min"\r
}\r
</div></div>\r
<div class="paragraph"><p>Likewise, you can use the <tt>color_separator</tt> directive to specify the color that\r
will be used to paint the separator bar. The separator is always output in\r
-color, even when colors are disabled by the <tt>colors</tt> directive.</p></div>\r
+color, even when colors are disabled by the <tt>colors</tt> directive. This option has\r
+no effect when <tt>output_format</tt> is set to <tt>i3bar</tt> or <tt>none</tt>.</p></div>\r
<div class="paragraph"><p>The <tt>interval</tt> directive specifies the time in seconds for which i3status will\r
sleep before printing the next status line.</p></div>\r
-<div class="paragraph"><p>Using <tt>output_format</tt> you can chose which format strings i3status should\r
+<div class="paragraph"><p>Using <tt>output_format</tt> you can choose which format strings i3status should\r
use in its output. Currently available are:</p></div>\r
<div class="dlist"><dl>\r
<dt class="hdlist1">\r
</p>\r
</dd>\r
<dt class="hdlist1">\r
+lemonbar\r
+</dt>\r
+<dd>\r
+<p>\r
+lemonbar is a lightweight bar based entirely on XCB. It has full UTF-8 support\r
+and is EWMH compliant.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+term\r
+</dt>\r
+<dd>\r
+<p>\r
+Use ANSI Escape sequences to produce a terminal-output as close as possible to\r
+the graphical outputs. This makes debugging your config file a little bit\r
+easier because the terminal-output of i3status becomes much more readable, but\r
+should only used for such quick glances, because it will only support very\r
+basic output-features (for example you only get 3 bits of color depth).\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
none\r
</dt>\r
<dd>\r
<p>\r
-Does not use any color codes. Separates values by the pipe symbol. This should\r
-be used with i3bar and can be used for custom scripts.\r
+Does not use any color codes. Separates values by the pipe symbol by default.\r
+This should be used with i3bar and can be used for custom scripts.\r
</p>\r
</dd>\r
</dl></div>\r
+<div class="paragraph"><p>It’s also possible to use the color_good, color_degraded, color_bad directives\r
+to define specific colors per module. If one of these directives is defined\r
+in a module section its value will override the value defined in the general\r
+section just for this module.</p></div>\r
+<div class="paragraph"><p>If you don’t fancy the vertical separators between modules i3status/i3bar\r
+uses by default, you can employ the <tt>separator</tt> directive to configure how\r
+modules are separated. You can also disable the default separator altogether by\r
+setting it to the empty string. You might then define separation as part of a\r
+module’s format string. This is your only option when using the i3bar output\r
+format as the separator is drawn by i3bar directly otherwise. For the other\r
+output formats, the provided non-empty string will be automatically enclosed\r
+with the necessary coloring bits if color support is enabled.</p></div>\r
+<div class="paragraph"><p>i3bar supports Pango markup, allowing your format strings to specify font,\r
+color, size, etc. by setting the <tt>markup</tt> directive to "pango". Note that the\r
+ampersand ("&"), less-than ("<"), greater-than (">"), single-quote ("'"), and\r
+double-quote (""") characters need to be replaced with "<tt>&amp;</tt>", "<tt>&lt;</tt>",\r
+"<tt>&gt;</tt>", "<tt>&apos;</tt>", and "<tt>&quot;</tt>" respectively. This is done automatically\r
+for generated content (e.g. wireless ESSID, time).</p></div>\r
+<div class="paragraph"><p><strong>Example configuration</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>general {\r
+ output_format = "xmobar"\r
+ separator = " "\r
+}\r
+\r
+order += "load"\r
+order += "disk /"\r
+\r
+load {\r
+ format = "[ load: %1min, %5min, %15min ]"\r
+}\r
+disk "/" {\r
+ format = "%avail"\r
+}</tt></pre>\r
+</div></div>\r
</div>\r
<div class="sect2">\r
<h3 id="_ipv6">5.2. IPv6</h3>\r
<div class="paragraph"><p>This module gets the IPv6 address used for outgoing connections (that is, the\r
best available public IPv6 address on your computer).</p></div>\r
<div class="paragraph"><p><strong>Example format_up</strong>: <tt>%ip</tt></p></div>\r
-<div class="paragraph"><p><strong>Example format_down</strong> <tt>no IPv6</tt></p></div>\r
+<div class="paragraph"><p><strong>Example format_down</strong>: <tt>no IPv6</tt></p></div>\r
</div>\r
<div class="sect2">\r
<h3 id="_disk">5.3. Disk</h3>\r
<div class="paragraph"><p>Gets used, free, available and total amount of bytes on the given mounted filesystem.</p></div>\r
+<div class="paragraph"><p>These values can also be expressed in percentages with the percentage_used,\r
+percentage_free, percentage_avail and percentage_used_of_avail formats.</p></div>\r
+<div class="paragraph"><p>Byte sizes are presented in a human readable format using a set of prefixes\r
+whose type can be specified via the "prefix_type" option. Three sets of\r
+prefixes are available:</p></div>\r
+<div class="dlist"><dl>\r
+<dt class="hdlist1">\r
+binary\r
+</dt>\r
+<dd>\r
+<p>\r
+IEC prefixes (Ki, Mi, Gi, Ti) represent multiples of powers of 1024.\r
+This is the default.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+decimal\r
+</dt>\r
+<dd>\r
+<p>\r
+SI prefixes (k, M, G, T) represent multiples of powers of 1000.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+custom\r
+</dt>\r
+<dd>\r
+<p>\r
+The custom prefixes (K, M, G, T) represent multiples of powers of 1024.\r
+</p>\r
+</dd>\r
+</dl></div>\r
+<div class="paragraph"><p>It is possible to define a low_threshold that causes the disk text to be\r
+displayed using color_bad. The low_threshold type can be of threshold_type\r
+"bytes_free", "bytes_avail", "percentage_free", or "percentage_avail", where\r
+the former two can be prepended by a generic prefix (k, m, g, t) having\r
+prefix_type. So, if you configure low_threshold to 2, threshold_type to\r
+"gbytes_avail", and prefix_type to "binary", and the remaining available disk\r
+space is below 2 GiB, it will be colored bad. If not specified, threshold_type\r
+is assumed to be "percentage_avail" and low_threshold to be set to 0, which\r
+implies no coloring at all. You can customize the output format when below\r
+low_threshold with format_below_threshold.</p></div>\r
+<div class="paragraph"><p>You can define a different format with the option "format_not_mounted"\r
+which is used if the path does not exist or is not a mount point. Defaults to "".</p></div>\r
<div class="paragraph"><p><strong>Example order</strong>: <tt>disk /mnt/usbstick</tt></p></div>\r
<div class="paragraph"><p><strong>Example format</strong>: <tt>%free (%avail)/ %total</tt></p></div>\r
+<div class="paragraph"><p><strong>Example format</strong>: <tt>%percentage_used used, %percentage_free free, %percentage_avail avail</tt></p></div>\r
+<div class="paragraph"><p><strong>Example prefix_type</strong>: <tt>custom</tt></p></div>\r
+<div class="paragraph"><p><strong>Example low_threshold</strong>: <tt>5</tt></p></div>\r
+<div class="paragraph"><p><strong>Example format_below_threshold</strong>: <tt>Warning: %percentage_avail</tt></p></div>\r
+<div class="paragraph"><p><strong>Example threshold_type</strong>: <tt>percentage_free</tt></p></div>\r
</div>\r
<div class="sect2">\r
<h3 id="_run_watch">5.4. Run-watch</h3>\r
<div class="paragraph"><p>Expands the given path to a pidfile and checks if the process ID found inside\r
is valid (that is, if the process is running). You can use this to check if\r
-a specific application, such as a VPN client or your DHCP client is running.</p></div>\r
+a specific application, such as a VPN client or your DHCP client is running.\r
+There also is an option "format_down". You can hide the output with\r
+<tt>format_down=""</tt>.</p></div>\r
<div class="paragraph"><p><strong>Example order</strong>: <tt>run_watch DHCP</tt></p></div>\r
<div class="paragraph"><p><strong>Example format</strong>: <tt>%title: %status</tt></p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_wireless">5.5. Wireless</h3>\r
-<div class="paragraph"><p>Gets the link quality and ESSID of the given wireless network interface. You\r
-can specify different format strings for the network being connected or not\r
-connected.</p></div>\r
+<h3 id="_path_exists">5.5. Path-exists</h3>\r
+<div class="paragraph"><p>Checks if the given path exists in the filesystem. You can use this to check if\r
+something is active, like for example a VPN tunnel managed by NetworkManager.\r
+There also is an option "format_down". You can hide the output with\r
+<tt>format_down=""</tt>.</p></div>\r
+<div class="paragraph"><p><strong>Example order</strong>: <tt>path_exists VPN</tt></p></div>\r
+<div class="paragraph"><p><strong>Example format</strong>: <tt>%title: %status</tt></p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_wireless">5.6. Wireless</h3>\r
+<div class="paragraph"><p>Gets the link quality, frequency and ESSID of the given wireless network\r
+interface. You can specify different format strings for the network being\r
+connected or not connected.</p></div>\r
+<div class="paragraph"><p>The special interface name <tt>_first_</tt> will be replaced by the first wireless\r
+network interface found on the system (excluding devices starting with "lo").</p></div>\r
<div class="paragraph"><p><strong>Example order</strong>: <tt>wireless wlan0</tt></p></div>\r
-<div class="paragraph"><p><strong>Example format</strong>: <tt>W: (%quality at %essid, %bitrate) %ip</tt></p></div>\r
+<div class="paragraph"><p><strong>Example format_up</strong>: <tt>W: (%quality at %essid, %bitrate / %frequency) %ip</tt></p></div>\r
+<div class="paragraph"><p><strong>Example format_down</strong>: <tt>W: down</tt></p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_ethernet">5.6. Ethernet</h3>\r
+<h3 id="_ethernet">5.7. Ethernet</h3>\r
<div class="paragraph"><p>Gets the IP address and (if possible) the link speed of the given ethernet\r
-interface. Getting the link speed requires the cap_net_admin capability. Set\r
-it using <tt>setcap cap_net_admin=ep $(which i3status)</tt>.</p></div>\r
+interface. If no IPv4 address is available and an IPv6 address is, it will be\r
+displayed. Getting the link speed requires the cap_net_admin capability.\r
+Set it using <tt>setcap cap_net_admin=ep $(which i3status)</tt>.</p></div>\r
+<div class="paragraph"><p>The special interface name <tt>_first_</tt> will be replaced by the first non-wireless\r
+network interface found on the system (excluding devices starting with "lo").</p></div>\r
<div class="paragraph"><p><strong>Example order</strong>: <tt>ethernet eth0</tt></p></div>\r
-<div class="paragraph"><p><strong>Example format</strong>: <tt>E: %ip (%speed)</tt></p></div>\r
+<div class="paragraph"><p><strong>Example format_up</strong>: <tt>E: %ip (%speed)</tt></p></div>\r
+<div class="paragraph"><p><strong>Example format_down</strong>: <tt>E: down</tt></p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_battery">5.7. Battery</h3>\r
-<div class="paragraph"><p>Gets the status (charging, discharging, running), percentage and remaining\r
-time of the given battery and when it’s estimated to be empty. If you want\r
-to use the last full capacity instead of the design capacity (when using\r
-the design capacity, it may happen that your battery is at 23% when fully\r
-charged because it’s old. In general, I want to see it this way, because\r
-it tells me how worn off my battery is.), just specify\r
-<tt>last_full_capacity = true</tt>.</p></div>\r
+<h3 id="_battery">5.8. Battery</h3>\r
+<div class="paragraph"><p>Gets the status (charging, discharging, unknown, full), percentage, remaining\r
+time and power consumption (in Watts) of the given battery and when it’s\r
+estimated to be empty. If you want to use the last full capacity instead of the\r
+design capacity (when using the design capacity, it may happen that your\r
+battery is at 23% when fully charged because it’s old. In general, I want to\r
+see it this way, because it tells me how worn off my battery is.), just specify\r
+<tt>last_full_capacity = true</tt>. You can hide seconds in the remaining time and\r
+empty time estimations by setting <tt>hide_seconds = true</tt>.</p></div>\r
+<div class="paragraph"><p>If you want the battery percentage to be shown without decimals, add\r
+<tt>integer_battery_capacity = true</tt>.</p></div>\r
<div class="paragraph"><p>If your battery is represented in a non-standard path in /sys, be sure to\r
-modify the "path" property accordingly. The first occurence of %d gets replaced\r
-with the battery number, but you can just hard-code a path as well.</p></div>\r
-<div class="paragraph"><p><strong>Example order</strong>: <tt>battery 0</tt></p></div>\r
-<div class="paragraph"><p><strong>Example format</strong>: <tt>%status %remaining (%emptytime)</tt></p></div>\r
+modify the "path" property accordingly, i.e. pointing to the uevent file on\r
+your system. The first occurrence of %d gets replaced with the battery number,\r
+but you can just hard-code a path as well.</p></div>\r
+<div class="paragraph"><p>It is possible to define a low_threshold that causes the battery text to be\r
+colored red. The low_threshold type can be of threshold_type "time" or\r
+"percentage". So, if you configure low_threshold to 10 and threshold_type to\r
+"time", and your battery lasts another 9 minutes, it will be colored red.</p></div>\r
+<div class="paragraph"><p>To show an aggregate of all batteries in the system, use "all" as the number. In\r
+this case (for Linux), the /sys path must contain the "%d" sequence. Otherwise,\r
+the number indicates the battery index as reported in /sys.</p></div>\r
+<div class="paragraph"><p>Optionally custom strings including any UTF-8 symbols can be used for different\r
+battery states. This makes it possible to display individual symbols\r
+for each state (charging, discharging, unknown, full)\r
+Of course it will also work with special iconic fonts, such as FontAwesome.\r
+If any of these special status strings are omitted, the default (CHR, BAT, UNK,\r
+FULL) is used.</p></div>\r
+<div class="paragraph"><p><strong>Example order (for the first battery)</strong>: <tt>battery 0</tt></p></div>\r
+<div class="paragraph"><p><strong>Example order (aggregate of all batteries)</strong>: <tt>battery all</tt></p></div>\r
+<div class="paragraph"><p><strong>Example format</strong>: <tt>%status %remaining (%emptytime %consumption)</tt></p></div>\r
+<div class="paragraph"><p><strong>Example format_down</strong>: <tt>No battery</tt></p></div>\r
+<div class="paragraph"><p><strong>Example status_chr</strong>: <tt>⚡ CHR</tt></p></div>\r
+<div class="paragraph"><p><strong>Example status_bat</strong>: <tt>🔋 BAT</tt></p></div>\r
+<div class="paragraph"><p><strong>Example status_unk</strong>: <tt>? UNK</tt></p></div>\r
+<div class="paragraph"><p><strong>Example status_full</strong>: <tt>☻ FULL</tt></p></div>\r
+<div class="paragraph"><p><strong>Example low_threshold</strong>: <tt>30</tt></p></div>\r
+<div class="paragraph"><p><strong>Example threshold_type</strong>: <tt>time</tt></p></div>\r
+<div class="paragraph"><p><strong>Example path (%d replaced by title number)</strong>: <tt>/sys/class/power_supply/CMB%d/uevent</tt></p></div>\r
+<div class="paragraph"><p><strong>Example path (ignoring the number)</strong>: <tt>/sys/class/power_supply/CMB1/uevent</tt></p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_cpu_temperature">5.8. CPU-Temperature</h3>\r
-<div class="paragraph"><p>Gets the temperature of the given thermal zone.</p></div>\r
+<h3 id="_cpu_temperature">5.9. CPU-Temperature</h3>\r
+<div class="paragraph"><p>Gets the temperature of the given thermal zone. It is possible to\r
+define a max_threshold that will color the temperature red in case the\r
+specified thermal zone is getting too hot. Defaults to 75 degrees C. The\r
+output format when above max_threshold can be customized with\r
+format_above_threshold.</p></div>\r
<div class="paragraph"><p><strong>Example order</strong>: <tt>cpu_temperature 0</tt></p></div>\r
<div class="paragraph"><p><strong>Example format</strong>: <tt>T: %degrees °C</tt></p></div>\r
+<div class="paragraph"><p><strong>Example max_threshold</strong>: <tt>42</tt></p></div>\r
+<div class="paragraph"><p><strong>Example format_above_threshold</strong>: <tt>Warning T above threshold: %degrees °C</tt></p></div>\r
+<div class="paragraph"><p><strong>Example path</strong>: <tt>/sys/devices/platform/coretemp.0/temp1_input</tt></p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_cpu_usage">5.9. CPU Usage</h3>\r
-<div class="paragraph"><p>Gets the percentual CPU usage from <tt>/proc/stat</tt>.</p></div>\r
+<h3 id="_cpu_usage">5.10. CPU Usage</h3>\r
+<div class="paragraph"><p>Gets the percentual CPU usage from <tt>/proc/stat</tt> (Linux) or <tt>sysctl(3)</tt>\r
+(FreeBSD/OpenBSD).</p></div>\r
+<div class="paragraph"><p>It is possible to define a max_threshold that will color the load\r
+value red in case the CPU average over the last interval is getting\r
+higher than the configured threshold. Defaults to 95. The output\r
+format when above max_threshold can be customized with\r
+format_above_threshold.</p></div>\r
+<div class="paragraph"><p>It is possible to define a degraded_threshold that will color the load\r
+value yellow in case the CPU average over the last interval is getting\r
+higher than the configured threshold. Defaults to 90. The output format\r
+when above degraded threshold can be customized with\r
+format_above_degraded_threshold.</p></div>\r
+<div class="paragraph"><p>For displaying the Nth CPU usage, you can use the %cpu<N> format string,\r
+starting from %cpu0. This feature is currently not supported in FreeBSD.</p></div>\r
<div class="paragraph"><p><strong>Example order</strong>: <tt>cpu_usage</tt></p></div>\r
-<div class="paragraph"><p><strong>Example format</strong>: <tt>%usage</tt></p></div>\r
+<div class="paragraph"><p><strong>Example format</strong>: <tt>all: %usage CPU_0: %cpu0 CPU_1: %cpu1</tt></p></div>\r
+<div class="paragraph"><p><strong>Example max_threshold</strong>: <tt>75</tt></p></div>\r
+<div class="paragraph"><p><strong>Example format_above_threshold</strong>: <tt>Warning above threshold: %usage</tt></p></div>\r
+<div class="paragraph"><p><strong>Example degraded_threshold</strong>: <tt>25</tt></p></div>\r
+<div class="paragraph"><p><strong>Example format_above_degraded_threshold</strong>: <tt>Warning above degraded threshold: %usage</tt></p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_load">5.10. Load</h3>\r
+<h3 id="_load">5.11. Load</h3>\r
<div class="paragraph"><p>Gets the system load (number of processes waiting for CPU time in the last\r
-1, 5 and 15 minutes).</p></div>\r
+1, 5 and 15 minutes). It is possible to define a max_threshold that will\r
+color the load value red in case the load average of the last minute is\r
+getting higher than the configured threshold. Defaults to 5. The output\r
+format when above max_threshold can be customized with\r
+format_above_threshold.</p></div>\r
<div class="paragraph"><p><strong>Example order</strong>: <tt>load</tt></p></div>\r
<div class="paragraph"><p><strong>Example format</strong>: <tt>%1min %5min %15min</tt></p></div>\r
+<div class="paragraph"><p><strong>Example max_threshold</strong>: <tt>"0,1"</tt></p></div>\r
+<div class="paragraph"><p><strong>Example format_above_threshold</strong>: <tt>Warning: %1min %5min %15min</tt></p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_time">5.11. Time</h3>\r
-<div class="paragraph"><p>Formats the current system time. See <tt>strftime(3)</tt> for the format.</p></div>\r
+<h3 id="_time">5.12. Time</h3>\r
+<div class="paragraph"><p>Outputs the current time in the local timezone.\r
+To use a different timezone, you can set the TZ environment variable,\r
+or use the <tt>tztime</tt> module.\r
+See <tt>strftime(3)</tt> for details on the format string.</p></div>\r
<div class="paragraph"><p><strong>Example order</strong>: <tt>time</tt></p></div>\r
<div class="paragraph"><p><strong>Example format</strong>: <tt>%Y-%m-%d %H:%M:%S</tt></p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_ddate">5.12. DDate</h3>\r
+<h3 id="_tztime">5.13. TzTime</h3>\r
+<div class="paragraph"><p>Outputs the current time in the given timezone.\r
+If no timezone is given, local time will be used.\r
+See <tt>strftime(3)</tt> for details on the format string.\r
+The system’s timezone database is usually installed in <tt>/usr/share/zoneinfo</tt>.\r
+Files below that path make for valid timezone strings, e.g. for\r
+<tt>/usr/share/zoneinfo/Europe/Berlin</tt> you can set timezone to <tt>Europe/Berlin</tt>\r
+in the <tt>tztime</tt> module.\r
+To override the locale settings of your environment, set the <tt>locale</tt> option.</p></div>\r
+<div class="paragraph"><p><strong>Example order</strong>: <tt>tztime berlin</tt></p></div>\r
+<div class="paragraph"><p><strong>Example format</strong>: <tt>%Y-%m-%d %H:%M:%S %Z</tt></p></div>\r
+<div class="paragraph"><p><strong>Example timezone</strong>: <tt>Europe/Berlin</tt></p></div>\r
+<div class="paragraph"><p><strong>Example locale</strong>: <tt>de_DE.UTF-8</tt></p></div>\r
+<div class="paragraph"><p>If you would like to use markup in this section, there is a separate\r
+<tt>format_time</tt> option that is automatically escaped. Its output then replaces\r
+%time in the format string.</p></div>\r
+<div class="paragraph"><p><strong>Example configuration (markup)</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>tztime berlin {\r
+ format = "<span foreground='#ffffff'>time:</span> %time"\r
+ format_time = "%H:%M %Z"\r
+ timezone = "Europe/Berlin"\r
+}</tt></pre>\r
+</div></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_ddate">5.14. DDate</h3>\r
<div class="paragraph"><p>Outputs the current discordian date in user-specified format. See <tt>ddate(1)</tt> for\r
details on the format string.\r
<strong>Note</strong>: Neither <strong>%.</strong> nor <strong>%X</strong> are implemented yet.</p></div>\r
<div class="paragraph"><p><strong>Example format</strong>: <tt>%{%a, %b %d%}, %Y%N - %H</tt></p></div>\r
</div>\r
<div class="sect2">\r
-<h3 id="_volume">5.13. Volume</h3>\r
-<div class="paragraph"><p>Outputs the volume of the specified mixer on the specified device. Works only\r
-on Linux because it uses ALSA.</p></div>\r
+<h3 id="_volume">5.15. Volume</h3>\r
+<div class="paragraph"><p>Outputs the volume of the specified mixer on the specified device. PulseAudio\r
+and ALSA (Linux only) are supported. If PulseAudio is absent, a simplified\r
+configuration can be used on FreeBSD and OpenBSD due to the lack of ALSA, the\r
+<tt>device</tt> and <tt>mixer</tt> options can be ignored on these systems. On these systems\r
+the OSS API is used instead to query <tt>/dev/mixer</tt> directly if <tt>mixer_idx</tt> is\r
+-1, otherwise <tt>/dev/mixer</tt>+mixer_idx+.</p></div>\r
+<div class="paragraph"><p>To get PulseAudio volume information, one must use the following format in the\r
+device line:</p></div>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><tt>device = "pulse"</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>or</p></div>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><tt>device = "pulse:N"</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>where N is the index or name of the PulseAudio sink. You can obtain the name of\r
+the sink with the following command:</p></div>\r
+<div class="literalblock">\r
+<div class="content">\r
+<pre><tt>$ pacmd list-sinks | grep name:\r
+ name: <alsa_output.pci-0000_00_14.2.analog-stereo></tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p>The name is what’s inside the angle brackets, not including them. If no sink is\r
+specified the default sink is used. If the device string is missing or is set\r
+to "default", PulseAudio will be tried if detected and will fallback to ALSA\r
+(Linux) or OSS (FreeBSD/OpenBSD).</p></div>\r
<div class="paragraph"><p><strong>Example order</strong>: <tt>volume master</tt></p></div>\r
<div class="paragraph"><p><strong>Example format</strong>: <tt>♪: %volume</tt></p></div>\r
+<div class="paragraph"><p><strong>Example format_muted</strong>: <tt>♪: 0%%</tt></p></div>\r
<div class="paragraph"><p><strong>Example configuration</strong>:</p></div>\r
<div class="listingblock">\r
<div class="content">\r
<pre><tt>volume master {\r
format = "♪: %volume"\r
+ format_muted = "♪: muted (%volume)"\r
device = "default"\r
mixer = "Master"\r
mixer_idx = 0\r
}</tt></pre>\r
</div></div>\r
+<div class="paragraph"><p><strong>Example configuration (PulseAudio)</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>volume master {\r
+ format = "♪: %volume"\r
+ format_muted = "♪: muted (%volume)"\r
+ device = "pulse:1"\r
+}</tt></pre>\r
+</div></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>volume master {\r
+ format = "♪: %volume"\r
+ format_muted = "♪: muted (%volume)"\r
+ device = "pulse:alsa_output.pci-0000_00_14.2.analog-stereo"\r
+}</tt></pre>\r
+</div></div>\r
+</div>\r
</div>\r
</div>\r
+<div class="sect1">\r
+<h2 id="_universal_module_options">6. Universal module options</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>When using the i3bar output format, there are a few additional options that\r
+can be used with all modules to customize their appearance:</p></div>\r
+<div class="dlist"><dl>\r
+<dt class="hdlist1">\r
+align\r
+</dt>\r
+<dd>\r
+<p>\r
+ The alignment policy to use when the minimum width (see below) is not\r
+ reached. Either <tt>center</tt> (default), <tt>right</tt> or <tt>left</tt>.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+min_width\r
+</dt>\r
+<dd>\r
+<p>\r
+ The minimum width (in pixels) the module should occupy. If the module takes\r
+ less space than the specified size, the block will be padded to the left\r
+ and/or the right side, according to the defined alignment policy. This is\r
+ useful when you want to prevent the whole status line from shifting when\r
+ values take more or less space between each iteration.\r
+ The option can also be a string. In this case, the width of the given text\r
+ determines the minimum width of the block. This is useful when you want to\r
+ set a sensible minimum width regardless of which font you are using, and at\r
+ what particular size. Please note that a number enclosed with quotes will\r
+ still be treated as a number.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+separator\r
+</dt>\r
+<dd>\r
+<p>\r
+ A boolean value which specifies whether a separator line should be drawn\r
+ after this block. The default is true, meaning the separator line will be\r
+ drawn. Note that if you disable the separator line, there will still be a\r
+ gap after the block, unless you also use separator_block_width.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+separator_block_width\r
+</dt>\r
+<dd>\r
+<p>\r
+ The amount of pixels to leave blank after the block. In the middle of this\r
+ gap, a separator symbol will be drawn unless separator is disabled. This is\r
+ why the specified width should leave enough space for the separator symbol.\r
+</p>\r
+</dd>\r
+</dl></div>\r
+<div class="paragraph"><p><strong>Example configuration</strong>:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>disk "/" {\r
+ format = "%avail"\r
+ align = "left"\r
+ min_width = 100\r
+ separator = false\r
+ separator_block_width = 1\r
+}</tt></pre>\r
+</div></div>\r
+</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_using_i3status_with_dzen2">6. Using i3status with dzen2</h2>\r
+<h2 id="_using_i3status_with_dzen2">7. Using i3status with dzen2</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>After installing dzen2, you can directly use it with i3status. Just ensure that\r
<tt>output_format</tt> is set to <tt>dzen2</tt>.</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_using_i3status_with_xmobar">7. Using i3status with xmobar</h2>\r
+<h2 id="_using_i3status_with_xmobar">8. Using i3status with xmobar</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>To get xmobar to start, you might need to copy the default configuration\r
file to <tt>~/.xmobarrc</tt>. Also, ensure that the <tt>output_format</tt> option for i3status\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_what_about_memory_usage_or_cpu_frequency">8. What about memory usage or CPU frequency?</h2>\r
+<h2 id="_what_about_memory_usage_or_cpu_frequency">9. What about memory usage or CPU frequency?</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>While talking about two specific things, please understand this section as a\r
general explanation why your favorite information is not included in i3status.</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_external_scripts_programs_with_i3status">9. External scripts/programs with i3status</h2>\r
+<h2 id="_external_scripts_programs_with_i3status">10. External scripts/programs with i3status</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>In i3status, we don’t want to implement process management again. Therefore,\r
there is no module to run arbitrary scripts or commands. Instead, you should\r
done</tt></pre>\r
</div></div>\r
<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
+<div class="paragraph"><p>Note that if you want to use the JSON output format (with colors in i3bar), you\r
+need to use a slightly more complex wrapper script. There are examples in the\r
+contrib/ folder, see <a href="https://github.com/i3/i3status/tree/master/contrib">https://github.com/i3/i3status/tree/master/contrib</a></p></div>\r
+</div>\r
+</div>\r
+<div class="sect1">\r
+<h2 id="_signals">11. SIGNALS</h2>\r
+<div class="sectionbody">\r
+<div class="paragraph"><p>When receiving <tt>SIGUSR1</tt>, i3status’s nanosleep() will be interrupted and thus\r
+you will force an update. You can use killall -USR1 i3status to force an update\r
+after changing the system volume, for example.</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_see_also">10. SEE ALSO</h2>\r
+<h2 id="_see_also">12. SEE ALSO</h2>\r
<div class="sectionbody">\r
<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
</div>\r
</div>\r
<div class="sect1">\r
-<h2 id="_authors">11. AUTHORS</h2>\r
+<h2 id="_authors">13. AUTHORS</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>Michael Stapelberg and contributors</p></div>\r
<div class="paragraph"><p>Thorsten Toepper</p></div>\r
projects / i3 / i3.github.io / blobdiff