NAME

ascpu - the AfterStep CPU load monitor

SYNOPSIS

ascpu [-h] [-H] [-V] [-iconic] [-withdrawn] [-standout] [-position [+|-]x[+|-]y] [-dev device] [-cpu number] [-u update rate] [-samples number] [-history number] [-nonice] [-display display] [-title name] [-exe command] [-bg color] [-fg color] [-sys color] [-nice color] [-user color] [-idle color]

DESCRIPTION

The ascpu is a X11 application that acts as an a CPU load monitor for computers running Linux, FreeBSD or HP-UX. The ascpu provides a distinctive Afterstep window manager look and feel and features multiple options to allow the customization.

The right (big) area displays the running history of the CPU load. With the default update period of 1 second it shows the current CPU load. It can be made to show average CPU load in bigger steps.

On the left side you have an indicator that shows the same values taken average over a number of samples. The default number of samples is 60. This means with the default setting of update rate you see the average CPU load during the last minute. If you change it to 1 second you'll see the current CPU load there.

The load indicators are divided (by using different colors) into three parts: system CPU time (bright), nice CPU time (medium), and the user CPU time (dark). The consumed CPU time is displayed in percents of total (plus idle time that is) CPU time passed.

CONFIGURATION OPTIONS

-h or -H

prints a short description and usage message.

-V

Version control. Prints out the version of the program.

-position [+|-]x[+|-]y

Displays the window at the specified location on the screen. This works as standard X Windows geometry option.

-iconic

Starts the ascpu application in the iconized mode. The icon has the same appearance with the main window. When this option is given, the -position refers to the position of the icon window as well as the main window.

-withdrawn

Starts the ascpu application in the withdrawn mode. This option is necessary to be able to dock the ascpu in the WindowMaker dock. When this option is given, the -position refers to the position of the icon window as well as the main window. ascpu ignores the -iconic option when started in withdrawn mode.

-standout

This changes the appearance of the ascpu display from "pushed-in" to "popped-out". The first is the default look. According to some the second looks much better in WindowMaker's dock. Give it a try in any case.

-dev <device>

Using this option you can specify the location of the file that serves the CPU statistics information. The default location of the this device on Linux systems is /proc/stat.

-cpu <number>

Without this parameter the ascpu displays statistics for the overall system usage on both single-CPU and SMP machines. On SMP machines, however, it is possible to obtain statistics per CPU. Using this parameter you give the CPU number (counted from zero) that you wish to watch.

If you give a CPU number which is bigger than any you actually have on your machine (or any CPU number on a single-CPU machine) ascpu will not show anything in its window and start complaining about "invalid character while reading /proc/stat" on the stnadard output.

This works only on Linux machines at the moment (I do not have a FreeBSD machine myself).

-u <update rate>

Changes the polling rate for accessing the CPU statistics data. The "-samples" and "-history" are specified in units of this polling rate. The update rate is specified in seconds. The value of 1 is the minimum. Default value is 1 second.

This is useful to change when you use value of 1 for neither -samples nor -history. For example, if you want to use "-samples 2 -history 60" (the bar on the left shows average load over two seconds and the running history shows load update every one minute) you should better use "-u 2 -samples 1 -history 30" to decrease the load on the CPU produced by the CPU monitor itself.

-samples <number>

The number of samples that should be taken for the calculations of the average load on the CPU (the bar on the left). The default value is 60. The minimum number of samples that can be specified is 1. At the sample rate of 1 you turn it into the current load indicator. While it it used as an average load indicator (sample rate > 1) the average value is calculated statistically over the last "<number>" of samples.

-history <number>

The number of samples that go into one value displayed in the running history window. The CPU load is sampled for the specified number of cycles and the value is displayed. The default value is 1.

-nonice

Force ascpu to show the nice CPU time as idle. This may become handy if you run some task "niced" in the background and you do not want to see the CPU indicator to show 100% load all the time. If this switch is specified the nice CPU time is simply added to the idle CPU time and you see CPU load only if user/system CPU cycles are consumed.

-display <name>

The name of the display to start the window in. It works just as X Windows display option.

-title <name>

Set the window title and the icon title to the specified name.

-exe <command>

Execute the given command when the applet is clicked with the mouse.

-fg <color>

The color for the "foreground". This color is used to draw the system CPU time. It is darkened by 1.2 to draw the nice CPU time. It is darkened by 1.4 to draw the user CPU time. See options -sys, -nice, -user to use different colors.

-bg <color>

The color for the background of the meter. It is used to draw the idle CPU time and it is lightened a bit and darkened a bit to create the 3D appearance of the ground plate. See -idle option to draw idle time in a different color.

-sys <color>

The color to use for the system CPU time. It overrides the color specified with the -fg option.

-nice <color>

The color to use for the nice CPU time. It overrides the color specified with the -fg option.

-user <color>

The color to use for the user CPU time. It overrides the color specified with the -fg option.

-idle <color>

The color to use for the idle CPU time. It overrides the color specified with the -bg option.

INVOCATION

ascpu can be called in different ways. The most common invocation is the command line:

	user@host[1]% ascpu -history 15 -samples 1 -fg "#d04040" &

Another way to call ascpu is from the window manager:

	*Wharf "ascpu" nil Swallow "ascpu" ascpu -u 2 -samples 15 &

This line, when placed in the wharf file in the users Afterstep configuration directory will cause ascpu to be a button on the Wharf (1) button bar under the afterstep (1) window manager.

If you have an SMP machine with two CPUs you can watch both CPUs separately and the overall statistics at the same time:

	*Wharf "ascpu" nil Swallow "ascpu" ascpu &
	*Wharf "ascpu-0" nil Swallow "ascpu-0" ascpu -cpu 0 -title ascpu-0 &
	*Wharf "ascpu-1" nil Swallow "ascpu-1" ascpu -cpu 1 -title ascpu-1 &

This will result in three ascpu windows in your Wharf each showing the respective statistics.

If you run WindowMaker then you should use the "-withdrawn" option:

	user@host[1]% ascpu -withdrawn -standout &

and then drag the icon to the dock.

BUGS

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. The limit on the statistics file name is 256 characters.

I had to limit the number of the CPUs in the SMP system you are using (lucky you :). Currently up to the CPU number 15 can be shown (that's 16 of them). If you want more you will have to edit the header file state.h and recompile.

The SMP support is not available for FreeBSD at the moment. Any volunteers to submit the necessary info and lend a hand with development and testing?

FILES

/proc/stat

COPYRIGHTS

Distributed under GNU General Public License v2 ; see LICENSE file for more informations.

AUTHORS

Albert Dorofeev <albert@tigr.net>

See README file for credits.