X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=man%2Fi3status.man;h=86f6216b4fa0f3d81506ae921e790f73d63f9252;hb=4ea804b751f9394b7b10b520212169a491c698a6;hp=cb1c2488d193e0ac752bf42024e9ae2827ec4335;hpb=8d2ef5f99b2ebc08a0a9d1f26492094692b1fc6b;p=i3%2Fi3status diff --git a/man/i3status.man b/man/i3status.man index cb1c248..86f6216 100644 --- a/man/i3status.man +++ b/man/i3status.man @@ -1,7 +1,7 @@ i3status(1) =========== Michael Stapelberg -v2.10, January 2016 +v2.12, May 2018 == NAME @@ -24,13 +24,12 @@ configuration files in the following order: == 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 @@ -56,6 +55,7 @@ order += "wireless wlan0" order += "ethernet eth0" order += "battery 0" order += "cpu_temperature 0" +order += "memory" order += "load" order += "tztime local" order += "tztime berlin" @@ -114,6 +114,12 @@ cpu_temperature 0 { path = "/sys/devices/platform/coretemp.0/temp1_input" } +memory { + format = "%used" + threshold_degraded = "10%" + format_degraded = "MEMORY: %free" +} + disk "/" { format = "%free" } @@ -142,7 +148,7 @@ 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. -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:: @@ -154,7 +160,7 @@ etc.). 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. @@ -178,14 +184,14 @@ 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 +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 "`&`", "`<`", @@ -193,6 +199,7 @@ double-quote (""") characters need to be replaced with "`&`", "`<`", for generated content (e.g. wireless ESSID, time). *Example configuration*: + ------------------------------------------------------------- general { output_format = "xmobar" @@ -246,7 +253,8 @@ 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. +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 "". @@ -261,6 +269,8 @@ 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 @@ -290,27 +300,35 @@ There also is an option "format_down". You can hide the output with 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. +connected or not connected. The quality is padded with leading zeroes by +default; to pad with something else use +format_quality+. 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 / %frequency) %ip+ +*Example format_up*: +W: (%quality at %essid, %bitrate / %frequency) %ip+ + +*Example format_down*: +W: down+ + +*Example format_quality*: +"%03d%s"+ === 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. 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)+ +*Example format_up*: +E: %ip (%speed)+ + +*Example format_down*: +E: down+ === Battery @@ -328,7 +346,7 @@ If you want the battery percentage to be shown without decimals, add 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 @@ -375,7 +393,9 @@ FULL) is used. 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+ @@ -383,6 +403,8 @@ specified thermal zone is getting too hot. Defaults to 75 degrees C. *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 @@ -392,26 +414,78 @@ Gets the percentual CPU usage from +/proc/stat+ (Linux) or +sysctl(3)+ 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 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+ @@ -419,6 +493,8 @@ getting higher than the configured threshold. Defaults to 5. *Example max_threshold*: +"0,1"+ +*Example format_above_threshold*: +Warning: %1min %5min %15min+ + === Time Outputs the current time in the local timezone. @@ -439,6 +515,7 @@ The system's timezone database is usually installed in +/usr/share/zoneinfo+. 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+ @@ -446,6 +523,8 @@ in the +tztime+ module. *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. @@ -649,7 +728,7 @@ Put that in some script, say +.bin/my_i3status.sh+ and execute that instead of i 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