<!doctype linuxdoc system>

<!-- The KTop Handbook.

 -->

<article>

<!-- Title information -->

<title>The KTop Handbook
<author>Chris Schl&auml;ger, <tt/cs@axys.de/
<date>Version $Id: index.sgml,v 1.5.2.4 1999/04/13 07:45:26 cschlaeg Exp $
<abstract>This Handbook describes KTop Version 1.0.0

<!-- Table of contents -->
<toc>

<!-- Begin the document -->


<sect>Introduction

<sect1>About KTop<p>

KTop is the KDE Task Manager. It displays the processes running on
computer in list and tree form. Processes can be killed and various
other signals can be send to specific processes. It also features a
processor load and memory usage monitor.

<sect1> Authors<p>

KTop is currently developed and maintained by Chris Schl&auml;ger
<htmlurl url="mailto:cs@kde.org" name="cs@kde.org">. In the past several other people have worked on KTop:

<itemize>
<item> A. Sanda &lt;alex@darkstar.ping.at&gt;
<item> Ralf Mueller &lt;ralf@bj-ig.de&gt;
<item> Bernd Johannes Wuebben  &lt;wuebben@math.cornell.edu&gt;
<item> Nicolas Leclercq  &lt;nicknet@planete.net&gt;
</itemize>

The porting to other platforms than Linux was done by:

<itemize>
<item> FreeBSD: Hans Petter Bieker &lt;zerium@traad.lavvu.no&gt;
</itemize>

<sect1>License and Warranty<p>
<tscreen><verb>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

</verb></tscreen>

<sect>Installation
<p>
<sect1>How to obtain KTop
<p>
KTop is part of the <htmlurl url="http://www.kde.org" name="KDE
Project">.  KTop can be found on the <htmlurl
url="http://www.iss.rwth-aachen.de/~schlaege/ktop" name="KTop
Homepage"> or <htmlurl url="ftp://ftp.kde.org/pub/kde/" name="KDE FTP
Server">, the main ftp site of the KDE Project.

<sect1>Requirements
<p>
In order to successfully compile KTop, you need the KDE 1.x and Qt 1.42.
All required libraries as well as KTop itself can be found
on the <htmlurl url="ftp://ftp.kde.org/pub/kde/" name="KDE FTP Server">. 

At the moment the following flavors of UNIX are supported:

<itemize>
<item> Linux 2.x <p> For KTop to work it is necessary to compile the
Linux-Kernel with the /proc-File-system enabled. This is the default
setting and most Linux-Distribution have it already. For SMP support
Linux 2.2 is required.

<item> FreeBSD <p> 

The KTop program needs to be owned by the kmem group and needs to have
the setgid bit set.

</itemize>

Support for other platforms is in preparation. Your help is greatly
appreciated.

<sect1>Compilation and installation
<p>

In order to compile and install KTop on your system, type the following in the base 
directory of the KTop distribution:
<code>
% ./configure
% make
% make install
</code>

Should you run into problems please report them to the <sf/KDE/ mailing lists.

<sect1> Installing the Task Manager Icon/Performance Meter in the KDE panel <p>

It is possible to add the Task Manager to the panel. Simply use the
Start Menu/Panel/Add Application Menu to do so. If you have the xload
program installed you will see a performance history display instead
of the KTop icon. Clicking on the icon or performance meter will start
the Task Manager.

<sect1> Reporting Bugs <p>

No software is perfect and so KTop isn't. Although I made a lot of
efforts to ensure the usability you might encounter a situation where
KTop does not behave as you would expect. Please report all bugs to
the highly sophisticated <htmlurl url="http://bugs.kde.org" name="KDE
Bug Tracking System">. Do not report bugs directly to me. Reporting to
the Bug Track System will ensure that all developers have a chance to
read about it and fix it.

<sect>Using the KDE Task Manager
<p>

After you have started the Task Manager you will see a dialog box with
two pages. You can change to other pages by clicking on the handle
of the pages.

<sect1> The Main Menu <p>

<sect2> The File Menu <p>

This menu just contains on item. If you select it KTop will
terminate. On termination all settings are save automatically and
restored the next time KTop is invoked.

<sect2> The Refresh Rate Menu<p>

The refresh rate determines how often the process list will be
updated. This is particularly important for the calculation of the
processor load of each process. The load is averaged over the whole
time between updates. A slow, a medium and a fast update rate is
available. For most purposes the medium rate is a good
compromise. This menu is only available when the Process List page is
visible.

<sect2> The Process Menu<p>

This menu allows you to send certain signals to this process or change
it's scheduling priority. The latter is not available on all operating
systems. Changing the priority will affect the amount of CPU time the
process will receive to do it's job. As a normal user you can usually
only increase the value which will decrease the priority. The higher
the value the less likely the process will get CPU time. This can be
used on systems that are shared by many people. Longer running jobs
(batch jobs) should be "reniced" to preserve a short response time for
interactive processes.

This menu is only enabled when a process has been selected. It's also
available as Right-Mouse-Button-Pop-up menu when clicking on a process.

<sect1>The Process List Page<p>

The Process List Page gives you a list of processes on your
system. The list can be sorted by each column. Just press the left
mouse button over the head of the column. Another mouse click on the
same column will revert the sorting direction.

<figure>
<eps FILE="ProcessList.eps">
<img SRC="ProcessList.gif">
</figure>

Due to a bug in the underlying Qt widget the columns only expand
automatically, but do not shrink. This will hopefully be fixed in the
next release.

The list shows the following information about each process. Please
note that not all properties are available on every operating system.

<itemize>

<item> <bf/Name/ The name of the executable that started the process.

<item> <bf/PID/ The process ID. A unique number for each process.

<item> <bf/User ID/ The login name of the user that started the process.

<item> <bf/CPU/ The processor load of the process in percent.

<item> <bf/Time/ The total computation time of the process so far.

<item> <bf/Nice/ The scheduling priority.

<item> <bf/Status/ The process status.

<item> <bf/Memory/ The total amount of memory (in kBytes) the process
uses. This includes shared memory.

<item> <bf/Resident/ The amount of physical memory (in kBytes) the
process uses.

<item> <bf/Shared/ The amount of memory (in kBytes) the process shares
with other processes.

<item> <bf/Commandline/ The command that was used to invoke this process.

</itemize>

Underneath the table you find four buttons which will be described now
from left to right.

<sect2> The Show Tree Button<p>

This button is used to toggle between list and tree mode. In tree mode
the processes are displayed in a tree form to show their caller/callee
relationship. A tree is an elegant way to show this parent-child
relationship. The <sl/init/ process is the ancester of all processes.

<figure>
<eps FILE="ProcessTree.eps">
<img src="ProcessTree.gif">
</figure>

<sect2> The Process Filter <p>

The Process Filter can be used to reduce the number of processes
displayed in the table. You can filter out processes you are not
interested in. Currently you can display all processes, system
processes only, user processes only or your processes only.

<sect2> The Refresh Button <p>

This button can be used to force an immediate update of the process list.

<sect2> The Kill Button <p>

If you want to terminate a process you can send a kill signal to the
selected process by pressing this button.

<sect1> The Performance Meter Page <p>

The Performance Meter Page provides two meters that show the overall
processor load and the total memory used by the system. Most Unixes
try to minimize the accesses to the hard disk by caching files in
memory. Therefore it is normal to always have almost the whole
physical memory in use. This is not necessarily a sign of excessive
memory use by certain programs but a sign of good caching strategies.

<figure>
<eps FILE="Perfmeter.eps">
<img src="Perfmeter.gif">
</figure>

Physical memory that is used for buffers or data caching is displayed
in green and yellow. The red part is swapped-out memory. That is data
from your main memory that was temporarily swapped to the hard disk to
make room for more important data in memory.

On Linux 2.2 SMP systems you will get additional meters for each processor.

If the KTop window is large enough not only the load/memory history is
shown but also digital meters for each value. If you don't see them
just increase the size of the KTop window.

<sect>Questions and answers<p>

<sect1> I get the message "Your system is currently not supported.". What can I do? <p>

KTop will compile on many UNIX systems but it can only be used on
some. If your system is not yet supported you will get this message
when running KTop. You can download the sources from the KDE CVS or
the <htmlurl url="http://www.iss.rwth-aachen.de/~schlaege/ktop"
name="KTop Homepage">. Look at the OS*.h classes and implement support
for your OS. Please contact me in advance to avoid duplicated
efforts. Your help is greatly appreciated.

<sect1> I have a multi processor box but I don't get the additional meters for each CPU. Why not? <p>

Your operating system kernel needs to provide this information. If it
is not available KTop cannot display the load for each
processor. Currently only Linux 2.2 kernels provide this
information. Linux 2.0 or earlier kernels do not provide the required
information.

<sect> Known Bugs and Problems<p>

Some Linux users have reported a mystirous raise of the load averagde when KTop is running. This seems to happen periodically and lasts about 1 to 2 minutes. Since no CPU time is used the system performance is not affected. The more serious affect is that the system clock drift increases (up to a second a day). We have not had time to analyse this further but it seems to be a kernel issue, triggered by frequent reads of /proc/status. We will continue to inverstigate this.

The session management of KTop is rather crude. Exiting from KDE when KTop is still running will not case KTop to save the current settings. If you like to have KTop at a certain position, start it, move it to the desired position, quit it and start it again.

<p>
</article>

