# KTimemon Manual

Martin
Maierhofer

    m.maierhofer@tees.ac.uk

16/04/1999
0.03.01

Online help / Introduction to KTimemon. Covers version 0.3a.

&ktimemon; is a system monitor for the K Desktop Environment

KDE
ktimemon
system monitor
timemon

## Introduction

KTimemon is a small program to keep track of your computer's system usage. It can display bar graphs containing information about CPU, memory, and swap usage as well as disk usage and context switch activity. In keeping with the spirit of KDE, it supports configuration via a graphical user interface. It also supports docking, i.e. it can display information in the system panel tray.

Note: Currently, KTimemon only supports a limited number of systems: Linux based installations with the `/proc` file system, Solaris based installations with the kstat library, and Digital Unix (formerly DEC/OSF1) based installations with the table(2) system call. Help with porting it to other platforms is most welcome.

KTimemon can be started from the command line or from the KDE start menu (in the Utilities submenu). If you choose to start from the command line, KTimemon honours the usual X Windows program flags such as `-geometry`. KTimemon is session-aware, i.e. it keeps track of the current state (colours, etc) and restores it in the user's next session.

## Installation

You can obtain KTimemon from the KDE ftp server (and its mirror sites). Download the package to a directory of your choice and type the following commands:

    $ cd <the_directory_where_you_put_ktimemon-0.3a.tgz>
    $ gzip -cd ktimemon-0.3a.tgz | tar xfv -
    $ cd ktimemon-0.3a
    $ ./configure
    $ make install

Hopefully, KTimemon will be compiled and installed without any further intervention (if you have any problems installing KTimemon, please drop me a note at m.maierhofer@tees.ac.uk). KTimemon should end up in the KDE directory hierarchy, and you will be able to invoke it from the Utilities menu after you restart the panel.

## Onscreen Fundamentals

After starting KTimemon a small window will appear displaying information gathered from the operating system. If you move the mouse pointer over the KTimemon window and let it rest for a small amount of time, a tool-tip (i.e. a small transient window) will appear. The tool-tip contains numeric information about the system parameters displayed by the bar graphs. Tool-tips can be disabled (refer to Configuration).

### Display Modes

KTimemon can display two different sets of system information. As explained in the Configuration chapter, mouse buttons can be bound to various actions. Per default, the left mouse button is bound to the mode switch action, i.e. by clicking the left mouse button anywhere in the KTimemon window, the displayed information switches from "Normal Mode" (the default) to "Extended Mode", and vice versa.

#### Normal Mode

After starting KTimemon for the first time, it will show information about the current CPU activity, as well as memory and swap usage. Three bar graphs are used to show this information; they are updated regularly (the default sample interval is 0.5s, but it can be changed, see Configuration). The three bar graphs represent (from left to right):

CPU usage.

  KTimemon shows the bar in three different colours, representing CPU time spent in various modes. From bottom to top they are: kernel mode, user mode, and user mode with lowered priority (nice) - since Solaris does not seem to support statistics for nice mode, the topmost part of the bar represents time spent in the wait state on such systems. The gap from the top of the bar to the top of the window represents the percentage the CPU idle time.

Memory usage.

  Similar to the CPU usage bar, this bar is composed of three sub fields, representing (from bottom to top): memory allocated by processes, memory used for I/O buffering, and memory used for file caching. For Digital Unix based systems, the middle section represents "inactive" memory (i.e. memory allocated and not used for a certain amount of time), and for Solaris based systems, the middle section of the bar is not used, and the topmost section represents the amount of memory used by the kernel. Again, the gap from the top of the bar to the top of the window represents free memory.

Swap usage.

  This bar consists of a single field representing the current swap usage relative to the system's total amount of swap space.

Clicking the mouse button bound to "mode switch" in the KTimemon window switches to "Extended Mode".

#### Extended Mode

In this mode, the three bar graphs are used to display a different set of system information. Again from left to right, they show:

Paging activity.

  This bar consists of two parts, the lower half of which shows the number of memory pages written to secondary storage in the last sample interval. Similarly, the upper half indicates the number of pages read from secondary storage.

Swapping activity.

  The second bar displays the analogue information for swap activity.

Context switches.

  Again, this bar graph consists of a single field which indicates the number of context switches in the last sample interval.

Since there is no "natural" way of scaling the information shown in "Extended Mode", by default KTimemon uses autoscaling (explained in the Common Questions Section). There is, however, the possibility of specifying the scaling information, see the Configuration section.

Note that the two sets of bar graphs share the same colours, i.e. the colours setup for "Normal Mode" is also used for displaying information in "Extended Mode" (see also Configuration on how to change the colour scheme).

### Menu Structure

By default, the right mouse button is bound to the "menu pop-up" action, i.e. clicking the right mouse button anywhere in the KTimemon window brings up a menu, which is discussed in the following sections.

#### Help

The Help Menu is fairly conventional. Chances are good you already discovered this functionality.

#### Settings...

The Settings... Menu is used to pop up the configuration dialog. Configuration options are discussed in section Configuration.

#### Docked In Panel

By selecting the Docked In Panel menu, KTimemon switches between its standard display (i.e. a normal window) and the panelised state, where the KTimemon window disappears and a smaller version is displayed in the system panel. Apart from the reduction in size, the "panelised" KTimemon behaves exactly like its big brother.

#### Horizontal Bars

By selecting the Horizontal Bars menu entry, KTimemon switches from vertical bars to horizontal bars and vice versa. Not very useful, but it was easy to implement ;-)

#### Quit

The Quit menu - surprise, surprise -- is used to terminate KTimemon. It will save the current state (e.g. the colour scheme, window size, whether it is displayed in the panel) and restore the state in the next invocation.

The configuration information is saved in the file `$(HOME)/.kde/share/config/ktimemonrc`, where `$(HOME)` refers to the user's home directory. If this file is deleted, KTimemon will start in its default state in the next invocation.

## Configuration

KTimemon can be configured via a straight-forward dialog (see also the discussion of the Configuration Menu). On the General page, the sample interval can be specified as well as scaling information (see also the discussion of the extended mode). If the Autoscaling check box is ticked (autoscaling is explained in the FAQ section), the scaling factors cannot be edited, since KTimemon determines them automatically.

The Colours page can be used to tailor the colours of the bar graph to individual preferences. A small sample bar graph gives immediate feedback.

In the Interaction page, mouse bindings can be adapted. Clicking a mouse button on the KTimemon window can be ignored, trigger a mode switch (see also Modes), invoke the context menu (see also Menu), or invoke an external process. The command line specified for external processes is interpreted by the standard shell, i.e. shell commands, environment variables, redirection etc. can be used.

The Interaction page also contains a check box which can be used to disable to automatic appearance of tool-tips with numeric information about the bar graphs (compare Onscreen Fundamentals).

## Common Questions and Answers

Which operating systems does KTimemon support?

  KTimemon supports Linux based systems with the `/proc` file system, Solaris based systems with the kstat library, and Digital Unix (formerly DEC/OSF1) systems with the table(2) system call interface. Only the Linux version has been thoroughly tested, if you experience any problems with the Solaris/Digital Unix port, please do not hesitate to contact me.

  Also, contributions to KTimemon to adapt it to other platforms are most welcome. Please contact me at m.maierhofer@tees.ac.uk if you intend to port KTimemon to other flavours of Unix.

How does autoscaling work?

  Glad you asked. Since there is no sensible predetermined scaling factor for paging/swapping operations and context switches (unlike e.g. memory utilisation, where you can take the total memory size as baseline), KTimemon uses a semi-intelligent (well, ...) autoscaling mechanism. Autoscaling works as follows:

  - Each of the three bar graphs as described in the extended mode section has an associated scaling factor. The initial values of these factors are set to some predetermined value.

  - Each time a new sample is displayed, the respective value is tentatively scaled with the corresponding factor. If the value can be displayed in the scale chosen by the factor, no change occurs (i.e. small changes in the activity are reflected by a changing height of the bar).

  - If the scaled value would be either too large or too small to be displayed with the current scaling factor, the scaling is adjusted so that the new value displayed is roughly halfway up the bar graph. Thus, subsequent changes should have a good chance of getting displayed relative to the current value, without having to change the scale again.

Why does a message box with "diagnostic output from child command" pop up?

  If you bind a mouse button to an external command (as described in the Configuration chapter), KTimemon does not check for a valid command name. Instead, a command shell is invoked to execute the statement, i.e. shell commands, environment variables, etc. can be used. To allow some feedback to the user, KTimemon monitors the stderr outputof the command shell, and reports it in this message box.

  While this scheme can be helpful in case a command is not found, it can be quite annoying if the invoked command prints harmless diagnostic information on stderr. A simple and elegant solution to this problem is to add `2>/dev/null`, at the end of the command specification. This redirects diagnostic messages to Nirvana and stops the message box to come along.

## Revision History

Version 0.1.

  (29 July 1998) Initial release.

Version 0.2.

  (20 August 1998)

  - Added support for extended mode.

  - Changed the configuration dialog to use layouts instead of fixed geometry.

  - Changed details in the configuration dialog (e.g. the location of the `/proc` mount point are now detected automatically.

  - Added support for internationalisation.

Version 0.2a.

  (29 August 1998)

  - Fixed small bug in auto detection of the `/proc` file system from `/etc/mtab`.

Version 0.2b.

  (3 December 1998)

  - Fixed tiny compatibility problem with the default colour allocation (has anyone changed QColor "recently"?).

Version 0.3.

  (11 February 1999)

  - Fixed bug in handling the configuration courtesy of Cristian Tibirna. You may want to remove the `ktimemonrc` file from `$(HOME)/.kde/share/config` to start with a "clean" configuration.

  - The configuration dialog is now only allocated on demand. This reduces the memory footprint of KTimemon a bit.

  - Initial port to Digital Unix (DEC/OSF1) and Solaris.

  - Configurable vertical and horizontal bars.

  - The layout of the memory usage information has been slightly rearranged.

  - Configurable mouse binding.

  - Some preliminary support for SMP. Don't hold your breath though.

Version 0.3a.

  (16 April 1999)

  - Added tooltips to timemon widget (suggested by Mark Krischer).

  - Added missing internationalisation in the configuration panel and cleaned up translation (thanks to Lubos Lunak for the report).

  - Minor code cleanup in the sample class.

## Thanks and Acknowledgements

KTimemon is based on an Xt version by my brother.

Thanks to Tobe Toben, Cristian Tibirna, Dirk A. Mueller, Mark Krischer and Lubos Lunak for bug reports, patches, comments, suggestions.