i3status(1)
===========
Michael Stapelberg <michael@i3wm.org>
-v2.10, January 2016
+v2.12, May 2018
== NAME
== DESCRIPTION
-i3status is a small program (about 1500 SLOC) for generating a status bar for
-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
-by not hogging your CPU as much as spawning the corresponding amount of shell
-commands would.
+i3status is a small program for generating a status bar for 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 by not hogging
+your CPU as much as spawning the corresponding amount of shell commands would.
== CONFIGURATION
order += "ethernet eth0"
order += "battery 0"
order += "cpu_temperature 0"
+order += "memory"
order += "load"
order += "tztime local"
order += "tztime berlin"
}
ethernet eth0 {
- # if you use %speed, i3status requires the cap_net_admin capability
format_up = "E: %ip (%speed)"
format_down = "E: down"
}
path = "/sys/devices/platform/coretemp.0/temp1_input"
}
+memory {
+ format = "%used"
+ threshold_degraded = "10%"
+ format_degraded = "MEMORY: %free"
+}
+
disk "/" {
format = "%free"
}
The +interval+ directive specifies the time in seconds for which i3status will
sleep before printing the next status line.
-Using +output_format+ you can chose which format strings i3status should
+Using +output_format+ you can choose which format strings i3status should
use in its output. Currently available are:
i3bar::
dzen2::
Dzen is a general purpose messaging, notification and menuing program for X11.
It was designed to be scriptable in any language and integrate well with window
-managers like dwm, wmii and xmonad though it will work with any windowmanger
+managers like dwm, wmii and xmonad though it will work with any window manager
xmobar::
xmobar is a minimalistic, text based, status bar. It was designed to work
with the xmonad Window Manager.
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
+modules are separated. You can also disable the default separator altogether by
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
+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 "`&`", "`<`",
for generated content (e.g. wireless ESSID, time).
*Example configuration*:
+
-------------------------------------------------------------
general {
output_format = "xmobar"
"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.
+implies no coloring at all. You can customize the output format when below
+low_threshold with format_below_threshold.
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. Defaults to "".
*Example low_threshold*: +5+
+*Example format_below_threshold*: +Warning: %percentage_avail+
+
*Example threshold_type*: +percentage_free+
=== Run-watch
*Example order*: +wireless wlan0+
-*Example format*: +W: (%quality at %essid, %bitrate / %frequency) %ip+
+*Example format_up*: +W: (%quality at %essid, %bitrate / %frequency) %ip+
+
+*Example format_down*: +W: down+
=== Ethernet
Gets the IP address and (if possible) the link speed of the given ethernet
-interface. Getting the link speed requires the cap_net_admin capability. Set
-it using +setcap cap_net_admin=ep $(which i3status)+.
+interface. If no IPv4 address is available and an IPv6 address is, it will be
+displayed.
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)+
+*Example format_up*: +E: %ip (%speed)+
+
+*Example format_down*: +E: down+
=== Battery
If your battery is represented in a non-standard path in /sys, be sure to
modify the "path" property accordingly, i.e. pointing to the uevent file on
-your system. The first occurence of %d gets replaced with the battery number,
+your system. The first occurrence of %d gets replaced with the battery number,
but you can just hard-code a path as well.
It is possible to define a low_threshold that causes the battery text to be
Gets the temperature of the given thermal zone. It is possible to
define a max_threshold that will color the temperature red in case the
-specified thermal zone is getting too hot. Defaults to 75 degrees C.
+specified thermal zone is getting too hot. Defaults to 75 degrees C. The
+output format when above max_threshold can be customized with
+format_above_threshold.
*Example order*: +cpu_temperature 0+
*Example max_threshold*: +42+
+*Example format_above_threshold*: +Warning T above threshold: %degrees °C+
+
*Example path*: +/sys/devices/platform/coretemp.0/temp1_input+
=== CPU Usage
It is possible to define a max_threshold that will color the load
value red in case the CPU average over the last interval is getting
-higher than the configured threshold. Defaults to 95.
+higher than the configured threshold. Defaults to 95. The output
+format when above max_threshold can be customized with
+format_above_threshold.
It is possible to define a degraded_threshold that will color the load
value yellow in case the CPU average over the last interval is getting
-higher than the configured threshold. Defaults to 90.
+higher than the configured threshold. Defaults to 90. The output format
+when above degraded threshold can be customized with
+format_above_degraded_threshold.
+
+For displaying the Nth CPU usage, you can use the %cpu<N> format string,
+starting from %cpu0. This feature is currently not supported in FreeBSD.
*Example order*: +cpu_usage+
-*Example format*: +%usage+
+*Example format*: +all: %usage CPU_0: %cpu0 CPU_1: %cpu1+
*Example max_threshold*: +75+
+*Example format_above_threshold*: +Warning above threshold: %usage+
+
*Example degraded_threshold*: +25+
+*Example format_above_degraded_threshold*: +Warning above degraded threshold: %usage+
+
+=== Memory
+
+Gets the memory usage from system on a Linux system from +/proc/meminfo+. Other
+systems are currently not supported.
+
+As format placeholders, +total+, +used+, +free+, +available+ and +shared+ are
+available. These will print human readable values. It's also possible to prefix
+the placeholders with +percentage_+ to get a value in percent.
+
+It's possible to define a +threshold_degraded+ and a +threshold_critical+ to
+color the status bar output in yellow or red, if the available memory falls
+below the given threshold. Possible values of the threshold can be any integer,
+suffixed with an iec symbol (+T+, +G+, +M+, +K+). Alternatively, the integer
+can be suffixed by a percent sign, which then rets evaluated relatively to
+total memory.
+
+If the +format_degraded+ parameter is given and either the critical or the
+degraded threshold applies, +format_degraded+ will get used as format string.
+It acts equivalently to +format+.
+
+As Linux' meminfo doesn't expose the overall memory in use, there are multiple
+methods to distinguish the actually used memory.
+
+*Example memory_used_method*: +memavailable+ ("total memory" - "MemAvailable", matches +free+ command)
+
+*Example memory_used_method*: +classical+ ("total memory" - "free" - "buffers" - "cache", matches gnome system monitor)
+
+*Example order*: +memory+
+
+*Example format*: +%free %available (%used) / %total+
+
+*Example format*: +%percentage_used used, %percentage_free free, %percentage_shared shared+
+
+*Example threshold_degraded*: +10%+
+
+*Example threshold_critical*: +5%+
+
+*Example format_degraded*: +Memory LOW: %free+
+
=== Load
Gets the system load (number of processes waiting for CPU time in the last
1, 5 and 15 minutes). It is possible to define a max_threshold that will
color the load value red in case the load average of the last minute is
-getting higher than the configured threshold. Defaults to 5.
+getting higher than the configured threshold. Defaults to 5. The output
+format when above max_threshold can be customized with
+format_above_threshold.
*Example order*: +load+
*Example max_threshold*: +"0,1"+
+*Example format_above_threshold*: +Warning: %1min %5min %15min+
+
=== Time
Outputs the current time in the local timezone.
Files below that path make for valid timezone strings, e.g. for
+/usr/share/zoneinfo/Europe/Berlin+ you can set timezone to +Europe/Berlin+
in the +tztime+ module.
+To override the locale settings of your environment, set the +locale+ option.
*Example order*: +tztime berlin+
*Example timezone*: +Europe/Berlin+
+*Example locale*: +de_DE.UTF-8+
+
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.
Note that if you want to use the JSON output format (with colors in i3bar), you
need to use a slightly more complex wrapper script. There are examples in the
-contrib/ folder, see http://code.i3wm.org/i3status/tree/master/contrib
+contrib/ folder, see https://github.com/i3/i3status/tree/master/contrib
== SIGNALS