i3status(1)
===========
Michael Stapelberg <michael@i3wm.org>
-v2.9, March 2015
+v2.10, January 2016
== NAME
-i3status - Generates a status line for i3bar, dzen2 or xmobar
+i3status - Generates a status line for i3bar, dzen2, xmobar or lemonbar
== SYNOPSIS
== DESCRIPTION
i3status is a small program (about 1500 SLOC) for generating a status bar for
-i3bar, dzen2, xmobar or similar programs. It is designed to be very
+i3bar, dzen2, xmobar, lemonbar or similar programs. It is designed to be very
efficient by issuing a very small number of system calls, as one generally
wants to update such a status line every second. This ensures that even under
high load, your status bar is updated correctly. Also, it saves a bit of energy
battery 0 {
format = "%status %percentage %remaining %emptytime"
format_down = "No battery"
- status_chr = "⚇ CHR""
+ status_chr = "⚇ CHR"
status_bat = "⚡ BAT"
status_full = "☻ FULL"
path = "/sys/class/power_supply/BAT%d/uevent"
xmobar::
xmobar is a minimalistic, text based, status bar. It was designed to work
with the xmonad Window Manager.
+lemonbar::
+lemonbar is a lightweight bar based entirely on XCB. It has full UTF-8 support
+and is EWMH compliant.
term::
Use ANSI Escape sequences to produce a terminal-output as close as possible to
the graphical outputs. This makes debugging your config file a little bit
output formats, the provided non-empty string will be automatically enclosed
with the necessary coloring bits if color support is enabled.
+i3bar supports Pango markup, allowing your format strings to specify font
+color, size, etc. by setting the +markup+ directive to "pango". Note that the
+ampersand ("&"), less-than ("<"), greater-than (">"), single-quote ("'"), and
+double-quote (""") characters need to be replaced with "`&`", "`<`",
+"`>`", "`'`", and "`"`" respectively. This is done automatically
+for generated content (e.g. wireless ESSID, time).
+
*Example configuration*:
-------------------------------------------------------------
general {
implies no coloring at all.
You can define a different format with the option "format_not_mounted"
-which is used if the path is not a mount point. So you can just empty
-the output for the given path with adding »format_not_mounted=""«
+which is used if the path does not exist or is not a mount point. So you can just empty
+the output for the given path with adding +format_not_mounted=""+
to the config section.
*Example order*: +disk /mnt/usbstick+
Expands the given path to a pidfile and checks if the process ID found inside
is valid (that is, if the process is running). You can use this to check if
a specific application, such as a VPN client or your DHCP client is running.
+There also is an option "format_down". You can hide the output with
++format_down=""+.
*Example order*: +run_watch DHCP+
Checks if the given path exists in the filesystem. You can use this to check if
something is active, like for example a VPN tunnel managed by NetworkManager.
+There also is an option "format_down". You can hide the output with
++format_down=""+.
*Example order*: +path_exists VPN+
*Example timezone*: +Europe/Berlin+
+If you would like to use markup in this section, there is a separate
++format_time+ option that is automatically escaped. Its output then replaces
+%time in the format string.
+
+*Example configuration (markup)*:
+-------------------------------------------------------------
+tztime time {
+ format = "<span foreground='#ffffff'>time:</span> %time"
+ format_time = "%H:%M %Z"
+}
+-------------------------------------------------------------
+
=== DDate
Outputs the current discordian date in user-specified format. See +ddate(1)+ for
=== Volume
-Outputs the volume of the specified mixer on the specified device. Works only
-on Linux because it uses ALSA.
-A simplified configuration can be used on FreeBSD and OpenBSD due to
-the lack of ALSA, the +device+ and +mixer+ options can be
-ignored on these systems. On these systems the OSS API is used instead to
-query +/dev/mixer+ directly if +mixer_dix+ is -1, otherwise
-+/dev/mixer++mixer_idx+.
+Outputs the volume of the specified mixer on the specified device. PulseAudio
+and ALSA (Linux only) are supported. If PulseAudio is absent, a simplified
+configuration can be used on FreeBSD and OpenBSD due to the lack of ALSA, the
++device+ and +mixer+ options can be ignored on these systems. On these systems
+the OSS API is used instead to query +/dev/mixer+ directly if +mixer_idx+ is
+-1, otherwise +/dev/mixer++mixer_idx+.
+
+To get PulseAudio volume information, one must use the following format in the
+device line:
+
+ device = "pulse"
+
+or
+
+ device = "pulse:N"
+
+where N is the index of the PulseAudio sink. If no sink is specified the
+default is used. If the device string is missing or is set to "default",
+PulseAudio will be tried if detected and will fallback to ALSA (Linux)
+or OSS (FreeBSD/OpenBSD).
*Example order*: +volume master+
*Example format*: +♪: %volume+
+
*Example format_muted*: +♪: 0%%+
*Example configuration*:
mixer_idx = 0
}
-------------------------------------------------------------
+*Example configuration (PulseAudio)*:
+-------------------------------------------------------------
+volume master {
+ format = "♪: %volume"
+ format_muted = "♪: muted (%volume)"
+ device = "pulse:1"
+}
+-------------------------------------------------------------
== Universal module options
<head>\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.8" />\r
+<meta name="generator" content="AsciiDoc 8.6.9" />\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
<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
<h1>i3status(1)</h1>\r
<span id="author">Michael Stapelberg</span><br />\r
<span id="email"><tt><<a href="mailto:michael@i3wm.org">michael@i3wm.org</a>></tt></span><br />\r
-<span id="revnumber">version 2.9,</span>\r
-<span id="revdate">March 2015</span>\r
+<span id="revnumber">version 2.10,</span>\r
+<span id="revdate">January 2016</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 i3bar, 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
<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
+i3bar, dzen2, xmobar, lemonbar 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
battery 0 {\r
format = "%status %percentage %remaining %emptytime"\r
format_down = "No battery"\r
- status_chr = "⚇ CHR""\r
+ status_chr = "⚇ CHR"\r
status_bat = "⚡ BAT"\r
status_full = "☻ FULL"\r
path = "/sys/class/power_supply/BAT%d/uevent"\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
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
is assumed to be "percentage_avail" and low_threshold to be set to 0, which\r
implies no coloring at all.</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 is not a mount point. So you can just empty\r
-the output for the given path with adding »format_not_mounted=""«\r
+which is used if the path does not exist or is not a mount point. So you can just empty\r
+the output for the given path with adding <tt>format_not_mounted=""</tt>\r
to the config section.</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
<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="_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.</p></div>\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="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>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 time {\r
+ format = "<span foreground='#ffffff'>time:</span> %time"\r
+ format_time = "%H:%M %Z"\r
+}</tt></pre>\r
+</div></div>\r
</div>\r
<div class="sect2">\r
<h3 id="_ddate">5.14. DDate</h3>\r
</div>\r
<div class="sect2">\r
<h3 id="_volume">5.15. 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.\r
-A simplified configuration can be used on FreeBSD and OpenBSD due to\r
-the lack of ALSA, the <tt>device</tt> and <tt>mixer</tt> options can be\r
-ignored on these systems. On these systems the OSS API is used instead to\r
-query <tt>/dev/mixer</tt> directly if <tt>mixer_dix</tt> is -1, otherwise\r
-<tt>/dev/mixer</tt>+mixer_idx+.</p></div>\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 of the PulseAudio sink. If no sink is specified the\r
+default is used. If the device string is missing or is set to "default",\r
+PulseAudio will be tried if detected and will fallback to ALSA (Linux)\r
+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>\r
-<strong>Example format_muted</strong>: <tt>♪: 0%%</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
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>\r
</div>\r
</div>\r
projects / i3 / i3.github.io / commitdiff