salmon(1)

NAME
salmon - a resource utilization monitor

SYNOPSIS
salmon [-v] [-h]
       [-iconic] [-withdrawn] [-standout]
       [-twelve hour] [-used] [-% percent]
       [-kbytes] [-mbytes] [-gbytes]
       [-position [+|-]x[+|-]y]
       [-name name]
       [-display name:number]
       [-background color]
       [-foreground color]
       [-refresh sec]
       [-options]
            [1 minute] [5 minute] [fifteen minute]
            [memory] [swap] [cache] [buffers] [shared]
            [time] [date] [Time] [Date]
            [user] [nice] [sys] [idle]
            [process counts] [uptime] [host name]
            [os type] [os version] [Moon phase]

DESCRIPTION
Salmon, (s)till (a)nother (l)oad (mon)itor, is an X11 resource utilization monitor. It can display the current load averages, the amount of free or used memory and swap space, memory in cache, buffers, and shared, the number of running and active processes, the load split between user, nice, system, and idle, the uptime, the current local and universal times, the date based on local and universal time, the OS type, the OS or kernel version, the name of the local host and the phase of the moon. The 64x64 pixel applet can be used in the Afterstep Wharf or the WindowMaker dock, or salmon can be run in daemon mode to act as a monitor for a remote server. The salmon display consists of up to six lines. The default arrangement is:
    (line #1)    the one minute load average,
    (line #2)    free memory,
    (line #3)    free swap space,
    (line #4)    time since boot,
    (line #5)    local time,
The -foreground and -background colors may be specified on invocation. The default foreground colors are (what else) salmon1 (#ff8c69) and salmon4 (#8b4c39). The colors may be specified by name or by hex value in the form "#rrbbgg". The double quotes and hash mark are required when using hex values, case is ignored. If not specified on invocation, the -refresh interval will be determined by which information lines are to be displayed. Lines that are likely to change more rapidly will cause the refresh interval to be set to one second. That includes memory amounts, cpu loads and the local and universal clocks. The uptime refresh interval defaults to once per minute, host, os type, dates and moon phase every ten minutes. A user specified refresh interval will override the automatically selected rate. If specified, the value must be between 1 and 3600 seconds. The local and universal times are displayed by default in twenty-four hour format with up to the first three characters of the time zone name to the right. The -twelve switch will cause the local time to be displayed in twelve hour format, and -Twelve will do the same for universal time. If the times are displayed in twelve hour format and the refresh rate is set slower than once per second, the letters AM or PM as appropriate will replace the colon and seconds between the time and the time zone name. The -year and -Year switches will include the year in the local and universal date formats. That is, display the date as [abbreviated month date, year] rather than the default of [abbreviated day of the week, abbreviated month date]. Free memory and swap space are shown by default in the smallest units that can be displayed in no more than six digits. The -used option changes from showing free to used memory and swap, -% changes the displayed units to percentages. The -kilo, -meg and -gig switches force the minimum units to go no smaller than requested, they will still change to larger units if required to fit in the display. The daemonize switch causes salmon to operate in daemon mode. This mode is intended to be used with the -display option when salmon is acting as a monitor on a remote server. Salmon will daemonize and fork and the child process will wait for its remote display to become available. The X server must be set to allow access to the remote unit using xhost. If the X display should become inaccessible, salmon will fork a new child process which will then wait until the display returns. The -name switch will change the name that salmon gives to the X server from the default. This permits the use of two or more instances to be used in versions of the Afterstep Wharf that would otherwise only accept one. Names that are 50 characters or longer will be silently ignored. The -option switch permits changing the information displayed and the order of display from the default. The argument can be a comma separated or double quoted, space separated list. The order of the options selected will determine where they appear in the display. The selected lines, up to six, will be spaced evenly in the display. Selecting an option more than once will cause an error, requests for more than six lines are silently ignored.

CONFIGURATION OPTIONS

-v
    Print the version of the program.

-h
    Print description and usage message.

-i
    Starts salmon in the iconized mode. The icon has the same appearance as the main window. When this option is given, the -p(osition) refers to the position of the icon window as well as the main window.

-w
    Starts salmon in the withdrawn mode. This option is necessary to be able to dock salmon in the WindowMaker dock. When this option is given, -p(osition) refers to the position of the icon window as well as the main window. Salmon ignores the -i(conic) option when started in withdrawn mode.

-s
    This changes the appearance of salmon display from "pushed-in" to "stand-out". The first is the default look. The "popped-out" applets look much better in WindowMaker's dock according to some opinions. Give it a try in any case.

-r <seconds>
    Specify the screen refresh rate in seconds. The minimum is one second which is the default for information that may change rapidly. The maximum rate is one hour or 3600 seconds.

-p <[+|-]x[+|-]y>
    Displays the window at the specified location on the screen. This works like the standard X Windows geometry option. (See XParseGeometry (3x)).

-n <name>
    Change the name presented to the X server from the default salmon.

-d <name:number>
    The name and number of the X server to open the window in. It works like the X Windows display option. Use this when running salmon as a remote server monitor. It may also be required with older X library versions.

-b <color>
    Change the color of the background of the applet. The default color is gray19 (#303030).

-f <color>
    Change the primary foreground color of the applet. The default colors are salmon1 (#ff8c69) and salmon4 (#8b4c39).

-z
    Daemonize and display a child process on a specified remote X server. Not for use in the Afterstep Wharf.

-u
    By default salmon displays the amount of free memory or swap space. This option tells salmon to display the amounts of memory and swap space already in use.

-%
    Display memory and swap as percentages.

-k
    Force the memory display in KBytes even if smaller units would fit into the window. Applies to memory, swap, shared, buffer and cache values.

-m
    Force the memory display in MBytes even if smaller units would fit into the window.

-g
    Force the memory display in GBytes even if smaller units would fit into the window.

-t
    Display local time in twelve hour format.

-T
    Display universal time in twelve hour format.

-y
    Display year with local date.

-Y
    Display year with universal date.

-o <options>
    Select what information is to be displayed and in what order. The available options are:

1
    Display the one minute load average.

5
    Display the five minute load average.

f
    Display the fifteen minute load average.

m
    Display the free or used memory.

s
    Display the free or used swap space.

a
    Display the shared memory.

b
    Display the buffer memory.

c
    Display the cache memory.

p
    Display the running and active process counts.

u
    Display time since boot.

e
    Display user cpu percentage.

n
    Display nice cpu percentage.

y
    Display system cpu percentage.

i
    Display idle cpu percentage.

t
    Display the local time.

d
    Display the date based on local time.

T
    Display the universal time.

D
    Display the date based on universal time.

h
    Display the local host name.

o
    Display the operating system type.

v
    Display the operating system or kernel version.

M
    Display the phase of the moon.

INVOCATION
Salmon can be called in different ways. The most common invocation is the command line:
	user@host[1]% salmon -b blue -f white &
Another way to call salmon is from the window manager:
	*Wharf "salmon" nil Swallow "salmon" salmon -f "#98FB98" &
This line, when placed in the wharf file in the user's Afterstep configuration directory will cause salmon to be a button on the Wharf(1) button bar under the Afterstep(1) window manager. If you run WindowMaker then you should use the "-w(ithdrawn)" option:
	user@host[1]% salmon -ws &
and then drag the icon to the dock. To use salmon across a slow link and display the remote host name and OS type, the phase of the moon, the host uptime and the local date and time in twelve hour format at a refresh rate of ten seconds:
	user@remote-host$ salmon -r 10 -to h,o,M,u,d,t &
To moniter a remote FreeBSD server with minimum cpu loading and display the server host name and a summary stochastic analysis of near term managerial performance probabilities, add this line to the server's /usr/local/etc/rc.d/guesswork.sh:
	/usr/X11R6/bin/salmon -zd yourdesktop:0 -p +1+1 -o h,M
and execute "/usr/X11R6/bin/xhost +remoteservername" in your desktop startx scripts.

FILES
Linux
/proc/uptime
/proc/loadavg
/proc/stat
/proc/version
/proc/meminfo

BUGS
(1) "Tigr" My programs do not have bugs, they just develop random features ;-) Well, there are limitations. All the strings for the color names, display name, and the geometry have the length limit of 50 characters (terminating zero included). The string copying routine cuts the names that are longer. (2) "Tricia" The characters are hard to read at higher screen resolutions. The default colors aren't on my list of favorites. I like salmon ok, but I prefer it fresh caught and broiled or in sushi. There are so many options that it should probably be called emacsalmon.

SEE ALSO
pom(6)
Linux proc(5)
FreeBSD sysctl(8)

COPYRIGHTS
Copyright (c) 2004 Tricia Kirk <grania@mthoodcards.com> Distributed under GNU General Public License v2 ; see LICENSE and COPYING files for more informations.

AUTHORS
    Albert "Tigr" Dorofeev <albert@tigr.net>
    Tricia Kirk <grania@mthoodcards.com> See the README file for credits.