MAN page from Fedora 17 ascpu-1.11-6.fc17.i686.rpm

ascpu

Section: User Commands (1)
Updated: 10 October 2005
Index

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 asan a CPU load monitor for computers running Linux,FreeBSD or HP-UX.The ascpu provides a distinctive Afterstepwindow manager look and feel and features multipleoptions to allow the customization.

The right (big) area displays the running historyof the CPU load. With the default update period of1 second it shows the current CPU load. It can bemade to show average CPU load in bigger steps.

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

The load indicators are divided (by using different colors) into three parts: system CPU time (bright), nice CPUtime (medium), and the user CPU time (dark).The consumed CPU time is displayed in percents oftotal (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 locationon the screen. This works as standard X Windowsgeometry option.

-iconic

: Starts the ascpu application in the iconized mode.The icon has the same appearance with the mainwindow.When this option is given, the -position refers tothe 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 theascpu in the WindowMaker dock.When this option is given, the -position refers tothe position of the icon window as well as the main window.ascpu ignores the -iconic option when startedin 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 filethat serves the CPU statistics information. The defaultlocation of the this device on Linux systems is /proc/stat.

-cpu <number>

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

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

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

-u <update rate>

: Changes the polling rate for accessing the CPUstatistics data. The "-samples" and "-history" arespecified in units of this polling rate.The update rate is specified in seconds. The valueof 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 wantto use "-samples 2 -history 60" (the bar on the left showsaverage load over two seconds and the running historyshows load update every one minute) you should betteruse "-u 2 -samples 1 -history 30" to decrease the loadon the CPU produced by the CPU monitor itself.

-samples <number>

: The number of samples that should be taken for the calculationsof 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 loadindicator. While it it used as an average load indicator(sample rate > 1) the average value is calculated statisticallyover the last "<number>" of samples.

-history <number>

: The number of samples that go into one value displayedin the running history window. The CPU load is sampled forthe 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. Thismay become handy if you run some task "niced" in the background and you do not want to see the CPU indicator toshow 100% load all the time. If this switch is specified thenice CPU time is simply added to the idle CPU time and yousee 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 drawthe system CPU time. It is darkened by 1.2 to draw the niceCPU 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 bitto 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 thecolor specified with the -fg option.

-nice <color>

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

-user <color>

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

-idle <color>

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

INVOCATION

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

        userAATThost[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 Afterstepconfiguration directory will cause ascpu to be abutton on the Wharf (1) button bar under the afterstep (1)window manager.

If you have an SMP machine with two CPUs you can watch bothCPUs 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 Wharfeach showing the respective statistics.

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

        userAATThost[1]% ascpu -withdrawn -standout &

and then drag the icon to the dock.

BUGS

My programs do not have bugs, they just develop randomfeatures ;-)

Well, there are limitations. All the strings for thecolor names, display name, and the geometry have thelength 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 systemyou are using (lucky you :). Currently up to the CPU number15 can be shown (that's 16 of them). If you want more youwill 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 handwith development and testing?

FILES

/proc/stat

COPYRIGHTS

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

AUTHORS

Albert Dorofeev <albertAATTtigr.net>

See README file for credits.

This document was created byman2html,using the manual pages.