Environment Variables – Setting the TOPCOLORS Variable

environment-variablestop

I don't seem to be able to find any examples on the Internet for this environment variable, which top will apparently read and use to display colours.

How would I set this variable correctly so top used alternate colours in its output?

I have Solaris top version 3.5beta9.

Best Answer

The TOPCOLORS variable in this top (also referred to as unixtop) is not available in the version you are using. It first appeared in version 3.6 of this utility, as stated in the COLOR section of the README file. For some reason, it seems that the usual BSD don't include an updated version of top (FreeBSD 9.1 has 3.5beta12).

If you can install or compile an updated version, the man page should give you more information on how to set colours. In version 3.8beta1 that is what it prints:

TOPCOLORS

Specifies colors to use and conditions for which they should be used. At the present time, only numbers in the summary display area can be colored. In a future version it will be possible to highlight numbers in the process display area as well. The environment variable is the only way to specify color: there is no equivalent command line option. Note that the environment variable TOPCOLOURS is also understood. The British spelling takes precedence. The use of color only works on terminals that understand and process ANSI color escape sequences.

The environment variable is a sequence of color specifications, separated by colons. Each specification takes the form tag=min,max#code where

  • tag is the name of the value to check,
  • min and max specify a range for the value, and
  • code is an ANSI color code.

Multiple color codes can be listed and separated with semi-colons. A missing min implies the lowest possible value (usually 0) and a missing max implies infinity. The comma must always be present.

When specifying numbers for load averages, they should be multiplied by 100. For example, the specification:

  • 1min=500,1000#31 indicates that a 1 minute load average between 5 and 10 should be displayed in red.

Color attributes can be combined. For example, the specification:

  • 5min=1000,#37;41 indicates that a 5 minute load average higher than 10 should be displayed with white characters on a red background.

A special tag named header is used to control the color of the header for process display. It should be specified with no lower and upper limits, specifically header=,# followed by the ANSI color code.

You can see a list of color codes recognized by this installation of top with the -T option. This will also show the current set of tests used for color highligting, as specified in the environment.

(end of man page extract)

Colour Codes

The color.h file from the source code list the tags and codes the utility understands. The tags are:

/*
 * These color tag names are currently in use
 * (or reserved for future use):
 *
 * cpu, size, res, time, 1min, 5min, 15min, host
 */

And the color are the ANSI ones:

/*
 * Valid ANSI values for colors are:
 *
 * 0    Reset all attributes
 * 1    Bright
 * 2    Dim
 * 4    Underscore  
 * 5    Blink
 * 7    Reverse
 * 8    Hidden
 * 
 *  Foreground Colours
 * 30   Black
 * 31   Red
 * 32   Green
 * 33   Yellow
 * 34   Blue
 * 35   Magenta
 * 36   Cyan
 * 37   White
 * 
 *  Background Colours
 * 40   Black
 * 41   Red
 * 42   Green
 * 43   Yellow
 * 44   Blue
 * 45   Magenta
 * 46   Cyan
 * 47   White
 */

Example

Using the following setup, you can get a glimpse at the possibilities (here for top 3.8beta1 compiled on FreeBSD):

export TOPCOLORS="header=,#1\
:1min=,399#32:1min=400,799#33:1min=800,#31\
:5min=,299#32:5min=300,599#33:5min=600,#31\
:15min=,199#32:15min=200,399#33:15min=400,#31\
:cpu.user=,9#32:cpu.user=10,49#33:cpu.user=50,#31\
:cpu.system=,9#32:cpu.system=10,49#33:cpu.system=50,#31\
:cpu.interrupt=,9#32:cpu.interrupt=10,49#33:cpu.interrupt=50,#31"

A call to top -T will directly show you if top understands the color setup you've declared. It will also list all the tags understood (which in my case where somewhat different from the content of the color.h file).

Alternatives

On different UNIX systems, alternatives are used. Under Linux you usually find the top utility coming from the procps package. You can also install htop which is a nice colourful alternative that is also available on OSX and FreeBSD (where it relies on the Linux layer), but AFAIK not on Solaris.

Related Question