Add a format_down example for battery

[i3/i3status] / man / i3status.man

diff --git a/man/i3status.man b/man/i3status.man
index 5938acbd0b42e06bdd9d830716cad2bdba288419..c36694a49ee59abab033969595acfd4105e81dc6 100644 (file)
--- a/man/i3status.man
+++ b/man/i3status.man
@@ -1,11 +1,11 @@
 i3status(1)
 ===========
 i3status(1)
 ===========

-Michael Stapelberg <michael+i3@stapelberg.de>
-v2.5, May 2012
+Michael Stapelberg <michael@i3wm.org>
+v2.8, January 2014

 
 == NAME
 
 
 == NAME
 

-i3status - Generates a status line for dzen2 or xmobar
+i3status - Generates a status line for i3bar, dzen2 or xmobar

 
 == SYNOPSIS
 
 
 == SYNOPSIS
 


@@ -50,13 +50,15 @@ general {
 order += "ipv6"
 order += "disk /"
 order += "run_watch DHCP"
 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"
 order += "cpu_temperature 0"
 order += "load"
 order += "wireless wlan0"
 order += "ethernet eth0"
 order += "battery 0"
 order += "cpu_temperature 0"
 order += "load"

-order += "time"
+order += "tztime local"
+order += "tztime berlin"

 
 wireless wlan0 {
         format_up = "W: (%quality at %essid, %bitrate) %ip"
 
 wireless wlan0 {
         format_up = "W: (%quality at %essid, %bitrate) %ip"


@@ -71,6 +73,7 @@ ethernet eth0 {
 
 battery 0 {
         format = "%status %percentage %remaining %emptytime"
 
 battery 0 {
         format = "%status %percentage %remaining %emptytime"

+        format_down = "No battery"

         path = "/sys/class/power_supply/BAT%d/uevent"
         low_threshold = 10
 }
         path = "/sys/class/power_supply/BAT%d/uevent"
         low_threshold = 10
 }


@@ -79,12 +82,23 @@ run_watch DHCP {
         pidfile = "/var/run/dhclient*.pid"
 }
 
         pidfile = "/var/run/dhclient*.pid"
 }
 

-run_watch VPN {
+run_watch VPNC {
+        # file containing the PID of a vpnc process

         pidfile = "/var/run/vpnc/pid"
 }
 
         pidfile = "/var/run/vpnc/pid"
 }
 

-time {
-       format = "%Y-%m-%d %H:%M:%S"
+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"
+}
+
+tztime berlin {
+        format = "%Y-%m-%d %H:%M:%S %Z"
+        timezone = "Europe/Berlin"

 }
 
 load {
 }
 
 load {


@@ -139,10 +153,21 @@ managers like dwm, wmii and xmonad though it will work with any windowmanger
 xmobar::
 xmobar is a minimalistic, text based, status bar. It was designed to work
 with the xmonad Window Manager.
 xmobar::
 xmobar is a minimalistic, text based, status bar. It was designed to work
 with the xmonad Window Manager.

+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
+easier because the terminal-output of i3status becomes much more readable, but
+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.
 
 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.
 

+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.
+

 === IPv6
 
 This module gets the IPv6 address used for outgoing connections (that is, the
 === IPv6
 
 This module gets the IPv6 address used for outgoing connections (that is, the


@@ -150,16 +175,35 @@ best available public IPv6 address on your computer).
 
 *Example format_up*: +%ip+
 
 
 *Example format_up*: +%ip+
 

-*Example format_down* +no IPv6+
+*Example format_down*: +no IPv6+

 
 === Disk
 
 Gets used, free, available and total amount of bytes on the given mounted filesystem.
 
 
 === Disk
 
 Gets used, free, available and total amount of bytes on the given mounted filesystem.
 

+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.
+

 *Example order*: +disk /mnt/usbstick+
 
 *Example format*: +%free (%avail)/ %total+
 
 *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+
+

 === Run-watch
 
 Expands the given path to a pidfile and checks if the process ID found inside
 === Run-watch
 
 Expands the given path to a pidfile and checks if the process ID found inside


@@ -170,6 +214,15 @@ a specific application, such as a VPN client or your DHCP client is running.
 
 *Example format*: +%title: %status+
 
 
 *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.
+
+*Example order*: +path_exists VPN+
+
+*Example format*: +%title: %status+
+

 === Wireless
 
 Gets the link quality and ESSID of the given wireless network interface. You
 === Wireless
 
 Gets the link quality and ESSID of the given wireless network interface. You


@@ -200,9 +253,13 @@ 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+.
 
 see it this way, because it tells me how worn off my battery is.), just specify
 +last_full_capacity = true+.
 

+If you want the battery percentage to be shown without decimals, add
++integer_battery_capacity = true+.
+

 If your battery is represented in a non-standard path in /sys, be sure to
 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.
+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,
+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
 colored red. The low_threshold type can be of threshold_type "time" or
 
 It is possible to define a low_threshold that causes the battery text to be
 colored red. The low_threshold type can be of threshold_type "time" or


@@ -213,18 +270,28 @@ colored red. The low_threshold type can be of threshold_type "time" or
 
 *Example format*: +%status %remaining (%emptytime %consumption)+
 
 
 *Example format*: +%status %remaining (%emptytime %consumption)+
 

+*Example format_down*: +No battery+
+

 *Example low_threshold*: +30+
 
 *Example threshold_type*: +time+
 
 *Example low_threshold*: +30+
 
 *Example threshold_type*: +time+
 

+*Example path*: +/sys/class/power_supply/CMB1/uevent+
+

 === CPU-Temperature
 
 === CPU-Temperature
 

-Gets the temperature of the given thermal zone.
+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.

 
 *Example order*: +cpu_temperature 0+
 
 *Example format*: +T: %degrees °C+
 
 
 *Example order*: +cpu_temperature 0+
 
 *Example format*: +T: %degrees °C+
 

+*Example max_threshold*: +42+
+
+*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).
 === CPU Usage
 
 Gets the percentual CPU usage from +/proc/stat+ (Linux) or +sysctl(3)+ (FreeBSD/OpenBSD).


@@ -236,20 +303,43 @@ Gets the percentual CPU usage from +/proc/stat+ (Linux) or +sysctl(3)+ (FreeBSD/
 === Load
 
 Gets the system load (number of processes waiting for CPU time in the last
 === Load
 
 Gets the system load (number of processes waiting for CPU time in the last

-1, 5 and 15 minutes).
+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.

 
 *Example order*: +load+
 
 *Example format*: +%1min %5min %15min+
 
 
 *Example order*: +load+
 
 *Example format*: +%1min %5min %15min+
 

+*Example max_threshold*: +"0,1"+
+

 === Time
 
 === Time
 

-Formats the current system time. See +strftime(3)+ for the format.
+Outputs the current time in the local timezone.
+To use a different timezone, you can set the TZ environment variable,
+or use the +tztime+ module.
+See +strftime(3)+ for details on the format string.

 
 *Example order*: +time+
 
 *Example format*: +%Y-%m-%d %H:%M:%S+
 
 
 *Example order*: +time+
 
 *Example format*: +%Y-%m-%d %H:%M:%S+
 

+=== TzTime
+
+Outputs the current time in the given timezone.
+If no timezone is given, local time will be used.
+See +strftime(3)+ for details on the format string.
+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.
+
+*Example order*: +tztime berlin+
+
+*Example format*: +%Y-%m-%d %H:%M:%S %Z+
+
+*Example timezone*: +Europe/Berlin+
+

 === DDate
 
 Outputs the current discordian date in user-specified format. See +ddate(1)+ for
 === DDate
 
 Outputs the current discordian date in user-specified format. See +ddate(1)+ for


@@ -265,18 +355,21 @@ details on the format string.
 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
 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+, +mixer+ and +mixder_idx+ options can be
+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
 ignored on these systems. On these systems the OSS API is used instead to

-query +/dev/mixer+ directly.
+query +/dev/mixer+ directly if +mixer_dix+ is -1, otherwise
++/dev/mixer++mixer_idx+.

 
 *Example order*: +volume master+
 
 *Example format*: +♪: %volume+
 
 *Example order*: +volume master+
 
 *Example format*: +♪: %volume+

+*Example format_muted*: +♪: 0%%+

 
 *Example configuration*:
 -------------------------------------------------------------
 volume master {
        format = "♪: %volume"
 
 *Example configuration*:
 -------------------------------------------------------------
 volume master {
        format = "♪: %volume"

+       format_muted = "♪: muted (%volume)"

        device = "default"
        mixer = "Master"
        mixer_idx = 0
        device = "default"
        mixer = "Master"
        mixer_idx = 0


@@ -360,6 +453,16 @@ done
 
 Put that in some script, say +.bin/my_i3status.sh+ and execute that instead of i3status.
 
 
 Put that in some script, say +.bin/my_i3status.sh+ and execute that instead of i3status.
 

+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/contrib
+
+== SIGNALS
+
+When receiving +SIGUSR1+, i3status’s nanosleep() will be interrupted and thus
+you will force an update. You can use killall -USR1 i3status to force an update
+after changing the system volume, for example.
+

 == SEE ALSO
 
 +strftime(3)+, +date(1)+, +glob(3)+, +dzen2(1)+, +xmobar(1)+
 == SEE ALSO
 
 +strftime(3)+, +date(1)+, +glob(3)+, +dzen2(1)+, +xmobar(1)+