X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=man%2Fi3status.man;h=86f6216b4fa0f3d81506ae921e790f73d63f9252;hb=4ea804b751f9394b7b10b520212169a491c698a6;hp=850848828b0a329f2dffedb755c17094543c91c8;hpb=c094f47b457104c267dd55782efc34c47f05cf9d;p=i3%2Fi3status diff --git a/man/i3status.man b/man/i3status.man index 8508488..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 @@ -17,20 +17,19 @@ i3status [-c configfile] [-h] [-v] Specifies an alternate configuration file path. By default, i3status looks for configuration files in the following order: -1. ~/.i3status.conf -2. ~/.config/i3status/config (or $XDG_CONFIG_HOME/i3status/config if set) -3. /etc/i3status.conf -4. /etc/xdg/i3status/config (or $XDG_CONFIG_DIRS/i3status/config if set) +1. ~/.config/i3status/config (or $XDG_CONFIG_HOME/i3status/config if set) +2. /etc/xdg/i3status/config (or $XDG_CONFIG_DIRS/i3status/config if set) +3. ~/.i3status.conf +4. /etc/i3status.conf == 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,12 +253,11 @@ 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. So you can just empty -the output for the given path with adding +format_not_mounted=""+ -to the config section. +which is used if the path does not exist or is not a mount point. Defaults to "". *Example order*: +disk /mnt/usbstick+ @@ -263,6 +269,8 @@ to the config section. *Example low_threshold*: +5+ +*Example format_below_threshold*: +Warning: %percentage_avail+ + *Example threshold_type*: +percentage_free+ === Run-watch @@ -292,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 @@ -330,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 @@ -338,6 +354,10 @@ colored red. The low_threshold type can be of threshold_type "time" or "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. +To show an aggregate of all batteries in the system, use "all" as the number. In +this case (for Linux), the /sys path must contain the "%d" sequence. Otherwise, +the number indicates the battery index as reported in /sys. + 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, unknown, full) @@ -345,7 +365,9 @@ Of course it will also work with special iconic fonts, such as FontAwesome. If any of these special status strings are omitted, the default (CHR, BAT, UNK, FULL) is used. -*Example order*: +battery 0+ +*Example order (for the first battery)*: +battery 0+ + +*Example order (aggregate of all batteries)*: +battery all+ *Example format*: +%status %remaining (%emptytime %consumption)+ @@ -363,13 +385,17 @@ FULL) is used. *Example threshold_type*: +time+ -*Example path*: +/sys/class/power_supply/CMB1/uevent+ +*Example path (%d replaced by title number)*: +/sys/class/power_supply/CMB%d/uevent+ + +*Example path (ignoring the number)*: +/sys/class/power_supply/CMB1/uevent+ === CPU-Temperature 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+ @@ -377,22 +403,89 @@ 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 -Gets the percentual CPU usage from +/proc/stat+ (Linux) or +sysctl(3)+ (FreeBSD/OpenBSD). +Gets the percentual CPU usage from +/proc/stat+ (Linux) or +sysctl(3)+ +(FreeBSD/OpenBSD). + +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. 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. 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+ @@ -400,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. @@ -420,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+ @@ -427,15 +523,18 @@ 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. *Example configuration (markup)*: ------------------------------------------------------------- -tztime time { +tztime berlin { format = "time: %time" format_time = "%H:%M %Z" + timezone = "Europe/Berlin" } ------------------------------------------------------------- @@ -467,10 +566,16 @@ 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). +where N is the index or name of the PulseAudio sink. You can obtain the name of +the sink with the following command: + + $ pacmd list-sinks | grep name: + name: + +The name is what's inside the angle brackets, not including them. If no sink is +specified the default sink 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+ @@ -496,6 +601,13 @@ volume master { device = "pulse:1" } ------------------------------------------------------------- +------------------------------------------------------------- +volume master { + format = "♪: %volume" + format_muted = "♪: muted (%volume)" + device = "pulse:alsa_output.pci-0000_00_14.2.analog-stereo" +} +------------------------------------------------------------- == Universal module options @@ -616,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