i3status(1)
===========
Michael Stapelberg <michael@i3wm.org>
-v2.7, March 2013
+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
order += "ipv6"
order += "disk /"
order += "run_watch DHCP"
-order += "run_watch VPN"
+order += "run_watch VPNC"
+order += "path_exists VPN"
order += "wireless wlan0"
order += "ethernet eth0"
order += "battery 0"
battery 0 {
format = "%status %percentage %remaining %emptytime"
format_down = "No battery"
+ status_chr = "⚇ CHR"
+ status_bat = "⚡ BAT"
+ status_full = "☻ FULL"
path = "/sys/class/power_supply/BAT%d/uevent"
low_threshold = 10
}
pidfile = "/var/run/dhclient*.pid"
}
-run_watch VPN {
+run_watch VPNC {
+ # file containing the PID of a vpnc process
pidfile = "/var/run/vpnc/pid"
}
+path_exists VPN {
+ # path exists when a VPN tunnel launched by nmcli/nm-applet is active
+ path = "/proc/sys/net/ipv4/conf/tun0"
+}
+
tztime local {
format = "%Y-%m-%d %H:%M:%S"
}
Likewise, you can use the +color_separator+ directive to specify the color that
will be used to paint the separator bar. The separator is always output in
-color, even when colors are disabled by the +colors+ directive.
+color, even when colors are disabled by the +colors+ directive. This option has
+no effect when +output_format+ is set to +i3bar+ or +none+.
The +interval+ directive specifies the time in seconds for which i3status will
sleep before printing the next status line.
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
should only used for such quick glances, because it will only support very
basic output-features (for example you only get 3 bits of color depth).
none::
-Does not use any color codes. Separates values by the pipe symbol. This should
-be used with i3bar and can be used for custom scripts.
+Does not use any color codes. Separates values by the pipe symbol by default.
+This should be used with i3bar and can be used for custom scripts.
It's also possible to use the color_good, color_degraded, color_bad directives
to define specific colors per module. If one of these directives is defined
in a module section its value will override the value defined in the general
section just for this module.
+If you don't fancy the vertical separators between modules i3status/i3bar
+uses by default, you can employ the +separator+ directive to configure how
+modules are separated. You can either disable the default separator altogether
+setting it to the empty string. You might then define separation as part of a
+module's format string. This is your only option when using the i3bar output
+format as the separator is drawn by i3bar directly otherwise. For the other
+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 {
+ output_format = "xmobar"
+ separator = " "
+}
+
+order += "load"
+order += "disk /"
+
+load {
+ format = "[ load: %1min, %5min, %15min ]"
+}
+disk "/" {
+ format = "%avail"
+}
+-------------------------------------------------------------
+
=== IPv6
This module gets the IPv6 address used for outgoing connections (that is, the
*Example format_up*: +%ip+
-*Example format_down* +no IPv6+
+*Example format_down*: +no IPv6+
=== Disk
These values can also be expressed in percentages with the percentage_used,
percentage_free, percentage_avail and percentage_used_of_avail formats.
+Byte sizes are presented in a human readable format using a set of prefixes
+whose type can be specified via the "prefix_type" option. Three sets of
+prefixes are available:
+
+binary::
+IEC prefixes (Ki, Mi, Gi, Ti) represent multiples of powers of 1024.
+This is the default.
+decimal::
+SI prefixes (k, M, G, T) represent multiples of powers of 1000.
+custom::
+The custom prefixes (K, M, G, T) represent multiples of powers of 1024.
+
+It is possible to define a low_threshold that causes the disk text to be
+displayed using color_bad. The low_threshold type can be of threshold_type
+"bytes_free", "bytes_avail", "percentage_free", or "percentage_avail", where
+the former two can be prepended by a generic prefix (k, m, g, t) having
+prefix_type. So, if you configure low_threshold to 2, threshold_type to
+"gbytes_avail", and prefix_type to "binary", and the remaining available disk
+space is below 2 GiB, it will be colored bad. If not specified, threshold_type
+is assumed to be "percentage_avail" and low_threshold to be set to 0, which
+implies no coloring at all.
+
+You can define a different format with the option "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+
*Example format*: +%free (%avail)/ %total+
*Example format*: +%percentage_used used, %percentage_free free, %percentage_avail avail+
+*Example prefix_type*: +custom+
+
+*Example low_threshold*: +5+
+
+*Example threshold_type*: +percentage_free+
+
=== Run-watch
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+
*Example format*: +%title: %status+
+=== Path-exists
+
+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 format*: +%title: %status+
+
=== Wireless
-Gets the link quality and ESSID of the given wireless network interface. You
-can specify different format strings for the network being connected or not
-connected.
+Gets the link quality, frequency and ESSID of the given wireless network
+interface. You can specify different format strings for the network being
+connected or not connected.
+
+The special interface name `_first_` will be replaced by the first wireless
+network interface found on the system (excluding devices starting with "lo").
*Example order*: +wireless wlan0+
-*Example format*: +W: (%quality at %essid, %bitrate) %ip+
+*Example format*: +W: (%quality at %essid, %bitrate / %frequency) %ip+
=== Ethernet
interface. Getting the link speed requires the cap_net_admin capability. Set
it using +setcap cap_net_admin=ep $(which i3status)+.
+The special interface name `_first_` will be replaced by the first non-wireless
+network interface found on the system (excluding devices starting with "lo").
+
*Example order*: +ethernet eth0+
*Example format*: +E: %ip (%speed)+
design capacity (when using the design capacity, it may happen that your
battery is at 23% when fully charged because it’s old. In general, I want to
see it this way, because it tells me how worn off my battery is.), just specify
-+last_full_capacity = true+.
++last_full_capacity = true+. You can hide seconds in the remaining time and
+empty time estimations by setting +hide_seconds = true+.
If you want the battery percentage to be shown without decimals, add
+integer_battery_capacity = true+.
"percentage". So, if you configure low_threshold to 10 and threshold_type to
"time", and your battery lasts another 9 minutes, it will be colored red.
+Optionally custom strings including any UTF-8 symbols can be used for different
+battery states. This makes it possible to display individual symbols
+for each state (charging, discharging, full)
+Of course it will also work with special iconic fonts, such as FontAwesome.
+If any of this special status strings is omitted, the default (CHR, BAT, FULL)
+is used.
+
*Example order*: +battery 0+
*Example format*: +%status %remaining (%emptytime %consumption)+
+*Example format_down*: +No battery+
+
+*Example status_chr*: +⚇ CHR+
+
+*Example status_bat*: +⚡ BAT+
+
+*Example status_full*: +☻ FULL+
+
*Example low_threshold*: +30+
*Example threshold_type*: +time+
*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
+
+When using the i3bar output format, there are a few additional options that
+can be used with all modules to customize their appearance:
+
+align::
+ The alignment policy to use when the minimum width (see below) is not
+ reached. Either +center+ (default), +right+ or +left+.
+min_width::
+ The minimum width (in pixels) the module should occupy. If the module takes
+ less space than the specified size, the block will be padded to the left
+ and/or the right side, according to the defined alignment policy. This is
+ useful when you want to prevent the whole status line from shifting when
+ values take more or less space between each iteration.
+ The option can also be a string. In this case, the width of the given text
+ determines the minimum width of the block. This is useful when you want to
+ set a sensible minimum width regardless of which font you are using, and at
+ what particular size. Please note that a number enclosed with quotes will
+ still be treated as a number.
+
+*Example configuration*:
+-------------------------------------------------------------
+disk "/" {
+ format = "%avail"
+ align = "left"
+ min_width = 100
+}
+-------------------------------------------------------------
== Using i3status with dzen2
projects / i3 / i3status / blobdiff