X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=man%2Fi3status.man;h=4896a739a7fd1ee39390b5dd854edf1263745cc0;hb=1c3fb04fb9c8d31a627ce0ad1b6ee4782e4ee610;hp=b7f362e950b7ff809848c73016ff884b53224dba;hpb=6298377bd467a241dc1b05ef54f4e6ce02e06de1;p=i3%2Fi3status diff --git a/man/i3status.man b/man/i3status.man index b7f362e..4896a73 100644 --- a/man/i3status.man +++ b/man/i3status.man @@ -1,7 +1,7 @@ i3status(1) =========== Michael Stapelberg -v2.1, April 2010 +v2.4, December 2011 == NAME @@ -9,22 +9,28 @@ i3status - Generates a status line for dzen2 or xmobar == SYNOPSIS -i3status [-c configfile] +i3status [-c configfile] [-h] [-v] == OPTIONS -c:: -Specifies an alternate configuration file path (default is /etc/i3status.conf -or ~/.i3status.conf). +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) == DESCRIPTION -i3status is a small program (less than 1000 SLOC) for generating a status bar -for dzen2, xmobar 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 (about 1500 SLOC) for generating a status bar for +i3bar, dzen2, xmobar 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 @@ -45,7 +51,7 @@ general { interval = 5 } -order = "ipv6" +order += "ipv6" order += "disk /" order += "run_watch DHCP" order += "run_watch VPN" @@ -57,17 +63,19 @@ order += "load" order += "time" wireless wlan0 { - format_up = "W: (%quality at %essid) %ip" + format_up = "W: (%quality at %essid, %bitrate) %ip" format_down = "W: down" } ethernet eth0 { # if you use %speed, i3status requires the cap_net_admin capability - format = "E: %ip (%speed)" + format_up = "E: %ip (%speed)" + format_down = "E: down" } battery 0 { - format = "%status %percentage %remaining" + format = "%status %percentage %remaining %emptytime" + path = "/sys/class/power_supply/BAT%d/uevent" } run_watch DHCP { @@ -88,6 +96,7 @@ load { cpu_temperature 0 { format = "T: %degrees °C" + path = "/sys/devices/platform/coretemp.0/temp1_input" } disk "/" { @@ -97,9 +106,25 @@ disk "/" { === General -The colors directive will disable all colors if you set it to +false+. -+interval+ is the time in seconds which i3status will sleep until printing -the next status line. +The +colors+ directive will disable all colors if you set it to +false+. You can +also specify the colors that will be used to display "good", "degraded" or "bad" +values using the +color_good+, +color_degraded+ or +color_bad+ directives, +respectively. Those directives are only used if color support is not disabled by +the +colors+ directive. The input format for color values is the canonical RGB +hexadecimal triplet (with no separators between the colors), prefixed by a hash +character ("#"). + +*Example configuration*: +------------------------------------------------------------- +color_good = "#00FF00" +------------------------------------------------------------- + +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. + +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 use in its output. Currently available are: @@ -112,7 +137,8 @@ xmobar:: xmobar is a minimalistic, text based, status bar. It was designed to work with the xmonad Window Manager. none:: -Does not use any color codes. Separates values by the pipe symbol. +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. === IPv6 @@ -125,11 +151,11 @@ best available public IPv6 address on your computer). === Disk -Gets used, free and total amount of bytes on the given mounted filesystem. +Gets used, free, available and total amount of bytes on the given mounted filesystem. *Example order*: +disk /mnt/usbstick+ -*Example format*: +%free / %total+ +*Example format*: +%free (%avail)/ %total+ === Run-watch @@ -139,6 +165,8 @@ a specific application, such as a VPN client or your DHCP client is running. *Example order*: +run_watch DHCP+ +*Example format*: +%title: %status+ + === Wireless Gets the link quality and ESSID of the given wireless network interface. You @@ -147,7 +175,7 @@ connected. *Example order*: +wireless wlan0+ -*Example format*: +W: (%quality at %essid) %ip+ +*Example format*: +W: (%quality at %essid, %bitrate) %ip+ === Ethernet @@ -162,15 +190,20 @@ it using +setcap cap_net_admin=ep $(which i3status)+. === Battery Gets the status (charging, discharging, running), percentage and remaining -time of the given battery. If you want to use the last full capacity instead -of the 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+. +time of the given battery and when it's estimated to be empty. If you want +to use the last full capacity instead of the 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+. + +If your battery is represented in a non-standard path in /sys, be sure to +modify the "path" property accordingly. The first occurence of %d gets replaced +with the battery number, but you can just hard-code a path as well. *Example order*: +battery 0+ -*Example format*: +%status %remaining+ +*Example format*: +%status %remaining (%emptytime)+ === CPU-Temperature @@ -180,14 +213,22 @@ Gets the temperature of the given thermal zone. *Example format*: +T: %degrees °C+ +=== CPU Usage + +Gets the percentual CPU usage from +/proc/stat+. + +*Example order*: +cpu_usage+ + +*Example format*: +%usage+ + === Load Gets the system load (number of processes waiting for CPU time in the last -5, 10 and 15 minutes). +1, 5 and 15 minutes). *Example order*: +load+ -*Example format*: +%5min %10min %15min+ +*Example format*: +%1min %5min %15min+ === Time @@ -207,9 +248,29 @@ details on the format string. *Example format*: +%{%a, %b %d%}, %Y%N - %H+ +=== Volume + +Outputs the volume of the specified mixer on the specified device. Works only +on Linux because it uses ALSA. + +*Example order*: +volume master+ + +*Example format*: +♪: %volume+ + +*Example configuration*: +------------------------------------------------------------- +volume master { + format = "♪: %volume" + device = "default" + mixer = "Master" + mixer_idx = 0 +} +------------------------------------------------------------- + == Using i3status with dzen2 -After installing dzen2, you can directly use it with i3status: +After installing dzen2, you can directly use it with i3status. Just ensure that ++output_format+ is set to +dzen2+. *Example for usage of i3status with dzen2*: -------------------------------------------------------------- @@ -220,13 +281,67 @@ i3status | dzen2 -fg white -ta r -w 1280 \ == Using i3status with xmobar To get xmobar to start, you might need to copy the default configuration -file to +~/.xmobarrc+. +file to +~/.xmobarrc+. Also, ensure that the +output_format+ option for i3status +is set to +xmobar+. *Example for usage of i3status with xmobar*: --------------------------------------------------------------------- -i3status-xmobar | xmobar -o -t "%StdinReader%" -c "[Run StdinReader]" +i3status | xmobar -o -t "%StdinReader%" -c "[Run StdinReader]" --------------------------------------------------------------------- +== What about memory usage or CPU frequency? + +While talking about two specific things, please understand this section as a +general explanation why your favorite information is not included in i3status. + +Let’s talk about memory usage specifically. It is hard to measure memory in a +way which is accurate or meaningful. An in-depth understanding of how paging +and virtual memory work in your operating system is required. Furthermore, even +if we had a well-defined way of displaying memory usage and you would +understand it, I think that it’s not helpful to repeatedly monitor your memory +usage. One reason for that is that I have not run out of memory in the last few +years. Memory has become so cheap that even in my 4 year old notebook, I have +8 GiB of RAM. Another reason is that your operating system will do the right +thing anyway: Either you have not enough RAM for your workload, but you need to +do it anyway, then your operating system will swap. Or you don’t have enough +RAM and you want to restrict your workload so that it fits, then the operating +system will kill the process using too much RAM and you can act accordingly. + +For CPU frequency, the situation is similar. Many people don’t understand how +frequency scaling works precisely. The generally recommended CPU frequency +governor ("ondemand") changes the CPU frequency far more often than i3status +could display it. The display number is therefore often incorrect and doesn’t +tell you anything useful either. + +In general, i3status wants to display things which you would often look at +anyways, like the current date/time, whether you are connected to a WiFi +network or not, and if you have enough disk space to fit that 4.3 GiB download. + +However, if you need to look at some kind of information more than once in a +while (like checking repeatedly how full your RAM is), you are probably better +of with a script doing that, which pops up an alert when your RAM usage reaches +a certain threshold. + +== External scripts/programs with i3status + +In i3status, we don’t want to implement process management again. Therefore, +there is no module to run arbitrary scripts or commands. Instead, you should +use your shell, for example like this: + +*Example for prepending the i3status output*: +-------------------------------------------------------------- +#!/bin/sh +# shell script to prepend i3status with more stuff + +i3status | while : +do + read line + echo "mystuff | $line" || exit 1 +done +-------------------------------------------------------------- + +Put that in some script, say +.bin/my_i3status.sh+ and execute that instead of i3status. + == SEE ALSO +strftime(3)+, +date(1)+, +glob(3)+, +dzen2(1)+, +xmobar(1)+ @@ -238,3 +353,7 @@ Michael Stapelberg and contributors Thorsten Toepper Baptiste Daroussin + +Axel Wagner + +Fernando Tarlá Cardoso Lemos