<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
 <!ENTITY kappname "&kpm;" > <!-- this only *seems* redundant -->
 <!ENTITY % addindex "IGNORE">
 <!ENTITY % English "INCLUDE" > <!-- change language only here -->
]>

<book id="kpm" lang="&language;">

<bookinfo>
<title>The &kpm; Handbook</title>

<authorgroup>

<author>
<firstname>Morgan</firstname>
<othername>N.</othername>
<surname>Sandquist</surname>
<affiliation>
<address><email>morgan@pipeline.com</email></address>
</affiliation>
</author>

<author>
<firstname>Mario</firstname>
<surname>Weilguni</surname>
<affiliation>
<address><email>mweilguni@kde.org</email></address>
</affiliation>
</author>

<othercredit role="developer">
<firstname>Mario</firstname>
<surname>Weilguni</surname>
<affiliation>
<address><email>mweilguni@kde.org</email></address>
</affiliation>
<contrib>Developer</contrib>
</othercredit>

<othercredit role="developer">
<firstname>Mattias</firstname>
<surname>Engdeg&aring;rd</surname>
<affiliation>
<address><email>f91-men@nada.kth.se</email></address>
</affiliation>
<contrib>Developer</contrib>
</othercredit>

<othercredit role="reviewer">
<firstname>Lauri</firstname>
<surname>Watts</surname>
<affiliation>
<address><email>lauri@kde.org</email></address>
</affiliation>
<contrib>Reviewer</contrib>
</othercredit>
<!-- TRANS:ROLES_OF_TRANSLATORS -->

</authorgroup>

<copyright>
<year>2000</year>
<holder>Morgan N. Sandquist</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2000-12-14</date>
<releaseinfo>2.00.00</releaseinfo>

    <keywordset>
<keyword>KDE</keyword>
<keyword>kdeadmin</keyword>
<keyword>kpm</keyword>
<keyword>process manager</keyword>
<keyword>top</keyword>
</keywordset>

<abstract><para>&kpm; is a utility that provides information about
processes and manages them.</para></abstract>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>&kpm; allows users to view and modify processes under Linux. It
shows detailed information about processes and the use of computer
resources like <acronym>CPU</acronym>, <acronym>RAM</acronym>, and swap
space, as well as general information like system uptime. Users can use
&kpm; to kill processes and modify their priority. The super-user also
has the ability to change scheduling settings.</para>

<para>&kpm; is heavily based on <ulink
url="mailto:f91-men@nada.kth.se">Mattias Engdeg&aring;rd's</ulink>
<application>qps</application>. The main difference between &kpm; and
<application>qps</application> is the &kde; interface. &kpm; adheres to
most &kde; standards, uses the &kde; configuration files, and has
session management.  Some features of <application>qps</application>
were removed (such as the ability to display &Mac; &OS; 7 style tables
or special check box widgets). </para>

</chapter>

<chapter id="using-kpm">
<title>Using &kpm;</title>

<sect1 id="kpm-start-up">
<title>&kpm; Start Up</title>

<para>When &kpm; starts there are displays showing load,
<acronym>CPU</acronym> usage, memory usage, swap usage, and uptime, as
well as a summarized view of processes.</para>

<screenshot>
<screeninfo>&kpm; at start up.</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kpmstart.png" format="PNG"/></imageobject>
<textobject><phrase>&kpm; at start up.</phrase></textobject>
</mediaobject>
</screenshot>

<sect2>
<title>Displays</title>

<screenshot>
<screeninfo>&kpm; with text displays.</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kpmtext.png" format="PNG"/></imageobject>
<textobject>
<phrase>&kpm; with text displays</phrase></textobject>
</mediaobject>
</screenshot>

<sect3>
<title>Load Display</title>

<para>The <guilabel>load</guilabel> display is a graph indicating the
average system load over time.  Clicking on the
<guilabel>load</guilabel> display will change it to a text-only display
that gives exact figures.</para>

</sect3>

<sect3>
<title><acronym>CPU</acronym> Display</title>

<para>The <guilabel>cpu</guilabel> display is a bar indicating the
percent of <acronym>CPU</acronym> resources used by
<guilabel>user</guilabel>, <guilabel>nice</guilabel>, and
<guilabel>sys</guilabel> (system) processes, as well as
<guilabel>idle</guilabel> resources. Clicking on the
<guilabel>cpu</guilabel> display will change it to a text-only display
that gives exact figures (as percentages).</para>

</sect3>

<sect3>
<title>Memory Display</title>

<para>The <guilabel>mem</guilabel> display is a bar indicating the
amount of memory <guilabel>used</guilabel>, <guilabel>buff</guilabel>
(buffered), <guilabel>cache</guilabel> (cached), and
<guilabel>free</guilabel>. Clicking on the <guilabel>mem</guilabel>
display will change it to a text-only display that gives exact figures
(in megabytes), along with the total memory available on the
system.</para>

</sect3>

<sect3>
<title>Swap Display</title>

<para>The <guilabel>swap</guilabel> display is a bar indicating the
amount of swap space being used.  Clicking on the
<guilabel>swap</guilabel> display will change it to a text-only display
that gives the exact figure (in megabytes), along with the total swap
space available on the system.</para>

</sect3>

<sect3>
<title>Uptime Display</title>

<para>The <guilabel>up</guilabel> display is a text-only display that
shows how long the system has been running.</para>

</sect3>

</sect2>

<sect2>
<title>Process List</title>

<para>By default, the process list shows all processes with the user
fields upon start up.  It can also be configured to show only the
current user's processes, non-root processes, or running processes, with
jobs fields, memory fields, or a custom selected set of fields. The list
can be sorted by any field by clicking on the column head. Clicking on
the column head again will reverse the order.</para>

<sect3>
<title>User Fields</title>

<variablelist>
<varlistentry>
<term><guilabel>PID</guilabel></term>
<listitem>
<para>Process <acronym>ID</acronym>.  Each process has a unique process
<acronym>ID</acronym> number (<acronym>PID</acronym>), starting at 1 and
going up. When a new process is created, the next unused
<acronym>PID</acronym> is allocated. <acronym>PID</acronym>s are
(currently) 16-bit signed integers, so they wrap around at
32767.</para>
</listitem> 
</varlistentry>

<varlistentry>
<term><guilabel>USER</guilabel></term>
<listitem>
<para>Process owner.  This is the name of the (real) owner of the
process.  If the effective user <acronym>ID</acronym> of a process is
different from the real user <acronym>ID</acronym>, this is indicated by
a trailing <guilabel>&ast;</guilabel> or <guilabel>&plus;</guilabel>.
The <guilabel>&ast;</guilabel> is used when the effective user is the
super-user (this usually indicates a binary that is
<command>setuid</command> to <systemitem
class="username">root</systemitem>).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>PRI</guilabel></term>
<listitem>
<para>Length of next time slice. This is the maximal length of the
process's next time slice (or what is left of its current time slice, if
it is the  currently running process). The number is rescaled to the
-20..20 interval, with a smaller number indicating a longer
time slice.</para>
</listitem> 
</varlistentry>

<varlistentry>
<term><guilabel>NICE</guilabel></term>
<listitem>
<para>Time-sharing priority. The nice value determines how often a
process is allowed to run, and the length of its time slice. The value is
in the range -20 to 20, 0 being the default.  Lower numbers give more
<acronym>CPU</acronym> time to a process. Only the super-user may lower
the nice value.</para>
</listitem> 
</varlistentry>

<varlistentry>
<term><guilabel>SIZE</guilabel></term>
<listitem>
<para>Virtual image size of the process (in kilobytes). This is the
total size of the image of the process. This includes all code, data,
and shared libraries used by the process, including pages that have been
swapped out.</para>
</listitem> 
</varlistentry>

<varlistentry>
<term><guilabel>RSS</guilabel></term>
<listitem>
<para>Resident set size (in kilobytes). This is the size of the part of
the process (code and data) that actually resides in
<acronym>RAM</acronym>, including shared libraries. This gives a fair
approximation of how much <acronym>RAM</acronym> a process is
using.</para>
</listitem> 
</varlistentry>

<varlistentry>
<term><guilabel>SHARE</guilabel></term>
<listitem>
<para>Shared memory (in kilobytes). This is the amount of memory that
the process shares with other processes. It doesn't mean that any of it
is actually used by any other process, just that it is
possible.</para>
</listitem> 
</varlistentry>

<varlistentry>
<term><guilabel>STAT</guilabel></term>
<listitem>
<para>State of the process. At any time, the process is in one of the
following states:</para> 

<variablelist>
<varlistentry>
<term><guilabel>R</guilabel></term>
<listitem><para>The process is running on a <acronym>CPU</acronym> or is ready
to run.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>S</guilabel></term>
<listitem>
<para>The process is waiting for an event to occur (such as I/O or a
timer).</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>D</guilabel></term>
<listitem><para>The process is waiting for an event to occur, without being
interruptible (usually waiting in a device driver).</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>T</guilabel></term>
<listitem><para>The process is stopped, or being traced by another
process.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Z</guilabel></term>
<listitem><para>The process has terminated, but the parent process is not yet
aware.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>W</guilabel></term>
<listitem><para>The process is completely swapped out (that is, it has no
resident pages). This is also true for kernel processes, such as
<filename>kswapd</filename>.</para></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>&percnt;CPU</guilabel></term>
<listitem>
<para>Percentage of <acronym>CPU</acronym> since last update. This is how much
of the <acronym>CPU</acronym> time the process used since the last update of
&kpm;'s process table.</para> 
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>&percnt;MEM</guilabel></term>
<listitem><para>Percentage of memory used. This is the percent of the total
<acronym>RAM</acronym> that is used by the process (as resident size). Shared
libraries are included, so this is an overstatement.</para> 
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>TIME</guilabel></term>
<listitem>
<para>Total <acronym>CPU</acronym> time used. This is how much
<acronym>CPU</acronym> time the process has used since it was
started.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>CMDLINE</guilabel></term>
<listitem>
<para>Command line that started the process. This the command line, including
arguments, that started the process. Processes swapped out may show just the
command name in parentheses. This is true for kernel processes as
well.</para></listitem>
</varlistentry>

</variablelist>

</sect3>

<sect3>
<title>Jobs Fields</title>

<screenshot>
<screeninfo>&kpm; jobs fields.</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="kpmjobs.png" format="PNG"/></imageobject>
<textobject><phrase>&kpm; jobs fields.</phrase></textobject>
</mediaobject>
</screenshot>

<variablelist>
<varlistentry>
<term><guilabel>PID</guilabel></term>
<listitem><para>Process ID.  Each process has a unique process
<acronym>ID</acronym> (<acronym>PID</acronym>) number, starting at 1 and going
up. When a new process is created, the next unused <acronym>PID</acronym> is
allocated. <acronym>PID</acronym>s are (currently) 16-bit signed integers, so
they wrap around at 32767.</para> </listitem>
</varlistentry>

<varlistentry>
<term><guilabel>PPID</guilabel></term>
<listitem><para>Parent process <acronym>ID</acronym>. Every process has one
parent process.  The exception is process 1 (<filename>init</filename>), which
is the root of the process hierarchy; it has no parent.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>PGID</guilabel></term>
<listitem><para>Process group <acronym>ID</acronym>. Each process is member of
one process group. Process groups are used for distribution of signals and by
terminals to arbitrate requests for their input. Processes that have the same
process group as the terminal are foreground and may read, while others will
block with a signal if they attempt to read.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>SID</guilabel></term>
<listitem><para>Session <acronym>ID</acronym>. Session <acronym>ID</acronym>s
are used mainly to determine what happens at terminal hangups.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>TTY</guilabel></term>
<listitem>
<para>Controlling <acronym>tty</acronym>. The controlling terminal
(<acronym>tty</acronym>) is usually the device (serial port,
<acronym>pty</acronym>, &etc;) from which the process was started, and
which it uses for input or output. Not all processes have a controlling
terminal.  &kpm; scans the <filename class="directory">/dev</filename>
directory to determine the name of the terminal, but this might fail. To
save space, only the two last characters of the tty name are shown (thus
<filename class="devicefile">/dev/ttyp6</filename> is shown as
<guilabel>p6</guilabel>).</para></listitem>
</varlistentry>
            
<varlistentry>
<term><guilabel>TPGID</guilabel></term>
<listitem><para>Process group <acronym>ID</acronym> of <acronym>tty</acronym>
owner. A <acronym>tty</acronym> in use is owned by a process. This is the
<guilabel>PGID</guilabel> of that process.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>STAT</guilabel></term>
<listitem><para>State of the process. At any time, the process is in one of the
following states:</para> 

<variablelist>
<varlistentry>
<term><guilabel>R</guilabel></term>
<listitem><para>The process is running on a <acronym>CPU</acronym> or is ready
to run.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>S</guilabel></term>
<listitem><para>The process is waiting for an event to occur (such as I/O or a
timer).</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>D</guilabel></term>
<listitem><para>The process is waiting for an event to occur, without being
interruptible (usually waiting in a device driver).</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>T</guilabel></term>
<listitem><para>The process is stopped, or being traced by another
process.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Z</guilabel></term>
<listitem><para>The process has terminated, but the parent process is not yet
aware.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>W</guilabel></term>
<listitem><para>The process is completely swapped out (that is, it has no
resident pages). This is also true for kernel processes, such as
<filename>kswapd</filename>.</para></listitem>
</varlistentry>
</variablelist>

</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>UID</guilabel></term>
<listitem>
<para>Numerical user <acronym>ID</acronym>. This is the
<acronym>ID</acronym> of the (real) owner of the
process.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>TIME</guilabel></term>
<listitem><para>Total <acronym>CPU</acronym> time used. This is how much
<acronym>CPU</acronym> time the process has used since it was
started.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>CMDLINE</guilabel></term>
<listitem><para>Command line that started the process. This the command line,
including arguments, that started the process. Processes swapped out may show
just the command name in parentheses. This is true for kernel processes as
well.</para></listitem>
</varlistentry>

</variablelist>

</sect3>

<sect3>
<title>Memory Fields</title>

<screenshot>
<screeninfo>&kpm; memory fields.</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kpmmemory.png" format="PNG"/></imageobject>
<textobject><phrase>&kpm; memory fields.</phrase></textobject>
</mediaobject>
</screenshot>

<variablelist>
<varlistentry>
<term><guilabel>PID</guilabel></term>
<listitem>
<para>Process <acronym>ID</acronym>.  Each process has a unique process
<acronym>ID</acronym> (<acronym>PID</acronym>) number, starting at 1 and
going up. When a new process is created, the next unused
<acronym>PID</acronym> is allocated. <acronym>PID</acronym>s are
(currently) 16-bit signed integers, so they wrap around at 32767.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>TTY</guilabel></term>
<listitem>
<para>Controlling tty. The controlling terminal (tty) is usually the
device (serial port, pty, &etc;) from which the process was started, and
which it uses for input or output. Not all processes have a controlling
terminal.  &kpm; scans the <filename class="directory">/dev</filename>
directory to determine the name of the terminal, but this might fail. To
save space, only the two last characters of the tty name are shown (thus
<filename>/dev/ttyp6</filename> is shown as
<guilabel>p6</guilabel>).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>MAJFLT</guilabel></term>
<listitem>
<para>Number of major faults that have occurred. A page fault occurs when
a process attempts to read or write from a memory page that is not
present in <acronym>RAM</acronym>. A major page fault is when disk
access is involved, such as swapping in and out memory pages.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>MINFLT</guilabel></term>
<listitem>
<para>Number of minor faults that have occurred. A page fault occurs when
a process attempts to read or write from a memory page that is not
present in <acronym>RAM</acronym>, or write to a page that isn't
writeable.  A minor fault is when there is no disk access involved, for
instance when writing to a copy-on-write shared page.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>TRS</guilabel></term>
<listitem>
<para>Text resident set size (in kilobytes). This is the size of the
text (that is, executable code) of the process that is currently present
in <acronym>RAM</acronym>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>DRS</guilabel></term>
<listitem>
<para>Data resident set size (in kilobytes). This is the size of the
data (not executable code) of the process that is currently present in
<acronym>RAM</acronym>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>SIZE</guilabel></term>
<listitem>
<para>Virtual image size of the process (in kilobytes). This is the
total size of the image of the process. This includes all code, data,
and shared libraries used by the process, including pages that have been
swapped out.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>SWAP</guilabel></term>
<listitem>
<para>Kilobytes on swap device. This is simply the difference between
SIZE and RSS, in other words how much of a process that resides on
disk.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>RSS</guilabel></term>
<listitem>
<para>Resident set size (in kilobytes). This is the size of the part of
the process (code and data) that actually resides in
<acronym>RAM</acronym>, including shared libraries. This gives a fair
approximation of how much <acronym>RAM</acronym> a process is
using.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>SHARE</guilabel></term>
<listitem>
<para>Shared memory (in kilobytes). This is the amount of memory that
the process shares with other processes. It doesn't mean that any of it
is actually used by any other process, just that it is possible.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>DT</guilabel></term>
<listitem>
<para>Number of dirty pages. This is the number of (not the number of
bytes) pages in <acronym>RAM</acronym> that have been modified since
they were last written to disk. Dirty pages have to be written to disk
before they are freed to be used for something else.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>CMDLINE</guilabel></term>
<listitem>
<para>Command line that started the process. This the command line,
including arguments, that started the process. Processes swapped out may
show just the command name in parentheses. This is true for kernel
processes as well.</para>
</listitem>
</varlistentry>

</variablelist>

</sect3>

<sect3>
<title>Other Fields</title>

<variablelist>
<varlistentry>
<term><guilabel>PLCY</guilabel></term>
<listitem>
<para>Scheduling policy. <acronym>FIFO</acronym>
(<guilabel>F</guilabel>) and Round-Robin (<guilabel>R</guilabel>) are
real time scheduling policies. Other (<guilabel>O</guilabel>) is the
normal &UNIX; time-sharing policy.  <guilabel>F</guilabel> and
<guilabel>R</guilabel> processes have a real time priority between 1 and
99.  A process will run as long as there is no runnable process with
higher priority. Round-Robin processes will run for the length of one
time-slice, after which they are placed last in the queue of their
priority. <acronym>FIFO</acronym> processes run until they give up their
<acronym>CPU</acronym> time (by sleeping or blocking) or are pre-empted
by a process with higher priority. Only the super-user (root) may change
the scheduling policy.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>RPRI</guilabel></term>
<listitem>
<para>Realtime processes (<acronym>FIFO</acronym> and Round-Robin) have
priorities between 1 and 99. A process will pre-empt any other process
that has lower priority. Normal time-sharing processes (policy
<guilabel>O</guilabel>) all have priority 0. Only the super-user (root)
may change the realtime priority.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>FLAGS</guilabel></term>
<listitem>
<para>Process flags (hexadecimal). This contains some additional
information about the state of a process.  Refer to the &Linux; kernel
source for details.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>WCHAN</guilabel></term>
<listitem>
<para>Function where process is sleeping. If the process is waiting for
something to happen, this is the kernel function where it is
stuck. Leading do&lowbar; or sys&lowbar; is stripped from the name to
make it shorter.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>&percnt;WCPU</guilabel></term>
<listitem>
<para>Weighted percentage of <acronym>CPU</acronym>. This is the
percentage of <acronym>CPU</acronym> time the process is using, averaged
over the last 30 seconds (exponentially decaying average).</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>START</guilabel></term>
<listitem>
<para>Time process started. This is when the process was created.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>COMM</guilabel></term>
<listitem>
<para>Command that started the process. This is the command (file name)
that started the process. Long names are truncated.</para>
</listitem>
</varlistentry>

</variablelist>

</sect3>

</sect2>

</sect1>

<sect1 id="monitoring-resources">
<title>Monitoring Resource Usage</title>

<para>By default, &kpm; will display system resource usage, including
average system load, <acronym>CPU</acronym> usage, memory usage, swap
space usage, and system up time. This data will appear in a series of
displays across the top of &kpm;'s main window.  These displays can be
toggled on and off by clicking on
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Show Resource
Info</guimenuitem></menuchoice>.  By default these displays will be
graphical.  However, any display can be changed to a more precise
text-only display by clicking on it or by changing its display
preferences through <menuchoice><guimenu>Settings</guimenu>
<guimenuitem>Preferences...</guimenuitem> </menuchoice>.</para>

</sect1>

<sect1 id="monitoring-processes">
<title>Monitoring Processes</title>

<para>&kpm; displays a list of processes on the host Linux system.  By
default, it will display all processes.  However, it can be changed to
show only the current user's processes, non-root processes, or currently
running processes through <guimenu>View</guimenu>, as described <link
linkend="view-processes">here</link>.</para>

<para>&kpm; displays a number of fields of information about each
process. By default, it displays the most common process fields.
However, through <guimenu>View</guimenu>, it can be changed to display
sets of fields relevant to job control or memory usage, or a custom
chosen set of fields, as described <link
linkend="view-fields">here</link>.</para>

<para>Finally, a list of <acronym>TCP</acronym> and
<acronym>UDP</acronym> sockets used by the selected process or processes
can be found by selecting <keycombo
action="simul">&Ctrl;<keycap>I</keycap></keycombo> or
<menuchoice><guimenu>Process</guimenu><guimenuitem>Socket
Info</guimenuitem></menuchoice>. A process is selected by clicking on
it.  Multiple processes are selected by holding down &Shift; while
clicking on each of them in turn.</para>

</sect1>

<sect1 id="managing-processes">
<title>Managing Processes</title>

<para>&kpm; performs three types of process management:</para>

<variablelist>
<varlistentry>
<term>Renice</term>
<listitem><para>Renice allows users to change the priority of their processes,
as described <link linkend="renice">here</link>. By selecting <keycombo
action="simul">&Ctrl;<keycap>R</keycap></keycombo> or
<menuchoice><guimenu>Process</guimenu>
<guimenuitem>Renice...</guimenuitem></menuchoice>, users can decrease the
priority of their processes. Additionally, the super-user can increase or
decrease the priority of any process.</para></listitem>
</varlistentry>

<varlistentry>
<term>Change Scheduling</term>
<listitem><para>The super-user can change the scheduling of processes, as
described <link linkend="change-scheduling">here</link>. This is done by
selecting either <keycombo
action="simul">&Ctrl;<keycap>S</keycap></keycombo> or
<menuchoice><guimenu>Process</guimenu> <guimenuitem>Change
Scheduling...</guimenuitem></menuchoice>.</para></listitem> 
</varlistentry>

<varlistentry>
<term>Signals</term>

<listitem><para>Users can send any of the POSIX signals listed in <xref
linkend="posix-signals"/> to their processes.  Additionally, the
super-user can send any of those signals to any process. Those signals
are sent using <guimenu>Signal</guimenu>, as described in <xref
linkend="signal-menu"/>.</para></listitem>
</varlistentry>

</variablelist>

</sect1>

</chapter>

<chapter id="commands">
<title>Command Reference</title>

<sect1 id="kpm-mainwindow">
<title>The Main &kpm; Window</title>

<sect2>
<title>The <guimenu>File</guimenu> Menu</title>

<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo>
</shortcut>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem>Iconify</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Iconifies the main window.</action> When iconfied, &kpm;
uses far less <acronym>CPU</acronym> time because there is no need to
update the process list. If &kwin; is the window manager, there will be
an icon in &kicker; displaying the average system load. Under other
window managers (such as <application>fvwm</application>), &kpm;'s icon
itself will show the load, depending on how the window manager is
configured.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
</shortcut>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem><accel>Q</accel>uit</guimenuitem>
</menuchoice></term>
<listitem><para><action>Quits</action> &kpm;. Closing the main window or
pressing <guibutton>Quit</guibutton> on the toolbar has the same
effect.</para></listitem>
</varlistentry>

</variablelist>

</sect2>

<sect2>
<title>The <guimenu>View</guimenu> Menu</title>

<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>U</keycap></keycombo>
</shortcut>
<guimenu><accel>V</accel>iew</guimenu>
<guimenuitem>Refresh process list</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Immediately updates the process list.</action> This is
very useful with rather long update periods. This can also be done by
pressing <guibutton>Refresh process list</guibutton> on the toolbar or
by pressing <keycap>Space</keycap>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term id="view-processes"><menuchoice>
<guimenu><accel>V</accel>iew</guimenu>
<guimenuitem>All Processes</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays all processes.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>V</accel>iew</guimenu>
<guimenuitem>Your Processes</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays processes started by current user.</action>
This includes those processes running under a different user (for example,
setuid <systemitem class="username">root</systemitem> programs started
by the current user).</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>V</accel>iew</guimenu>
<guimenuitem>Non-Root Processes</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays all processes except those started by
root.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>V</accel>iew</guimenu>
<guimenuitem>Running Processes</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays only running processes</action> (that is,
processes running or on the run queue).</para></listitem>
</varlistentry>

<varlistentry>
<term id="view-fields"><menuchoice>
<guimenu><accel>V</accel>iew</guimenu>
<guimenuitem>User Fields</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays the the most common process fields.</action>
These are those fields typically displayed by
<application>top</application>.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>V</accel>iew</guimenu>
<guimenuitem>Job Fields</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays the most relevant fields for job
control.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>V</accel>iew</guimenu>
<guimenuitem>Memory Fields</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays fields related to memory usage, page faults,
etc.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>V</accel>iew</guimenu>
<guimenuitem>Select Fields...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Allows the selection of a custom set of fields to be
displayed.</action></para></listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2>
<title>The <guimenu>Process</guimenu> Menu</title>

<variablelist>
<varlistentry id="renice">
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo>
</shortcut>
<guimenu><accel>P</accel>rocess</guimenu>
<guimenuitem>Renice...</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Modifes the priority of the marked process or
processes.</action> Under &Linux;, a process has a priority (nice value)
ranging from -20 (highest priority) to +20 (lowest priority), thus
increasing the nice value gives a process less <acronym>CPU</acronym>
time. Only the super-user allowed to lower the nice value (increase its
priority). This means that an ordinary user cannot lower the nice value
of a process, even if that user raised it previously. An ordinary user
is only allowed to alter the priority of that user's processes. The
super-user is allowed to modify the priority for any process, and only
the super-user may lower the nice value of a process.</para></listitem>
</varlistentry>

<varlistentry id="change-scheduling">
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>s</keycap></keycombo>
</shortcut>
<guimenu><accel>P</accel>rocess</guimenu>
<guimenuitem>Change Scheduling...</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Allows the super-user to change the scheduling policy of
the selected process or processes.</action> This function uses the
POSIX.1b real-time extensions present in &Linux; 2.0.x and later
kernels. Normal processes are set to
<filename>SCHED&lowbar;OTHER</filename> and have a static priority of
0. Real-time (soft) processes have a policy of
<filename>SCHED&lowbar;FIFO</filename> or
<filename>SCHED&lowbar;RR</filename> and a static priority in the range
of 1 to 99. This option is only available to the super-user.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>i</keycap></keycombo>
</shortcut>
<guimenu><accel>P</accel>rocess</guimenu>
<guimenuitem>Socket Info</guimenuitem>
</menuchoice></term>
<listitem>
<para><action>Displays a list</action> of <acronym>TCP</acronym> and
<acronym>UDP</acronym> sockets used by the selected process or
processes.</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2 id="signal-menu">
<title>The <guimenu>Signal</guimenu> Menu</title>

<para>The choices in the signal menu send various signals to all marked
processes. Be careful when doing this, especially if more than one
process is marked. The standard POSIX signals are explained <link
linkend="posix-signals">here</link>.</para>

<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>T</keycap></keycombo>
</shortcut>
<guimenu>S<accel>i</accel>gnal</guimenu>
<guimenuitem>Terminate</guimenuitem>
</menuchoice></term>
<listitem><para>Sends <errorcode>SIGTERM</errorcode> to the selected process or
processes.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo
action="simul">&Ctrl;<keycap>H</keycap></keycombo></shortcut>
<guimenu>S<accel>i</accel>gnal</guimenu>
<guimenuitem>Hangup</guimenuitem>
</menuchoice></term>
<listitem><para>Sends <errorcode>SIGHUP</errorcode> to the selected
process or processes.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>S<accel>i</accel>gnal</guimenu>
<guimenuitem>Interrupt</guimenuitem>
</menuchoice></term>
<listitem><para>Sends <errorcode>SIGINT</errorcode> to the selected
process or processes.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>k</keycap></keycombo>
</shortcut>
<guimenu>S<accel>i</accel>gnal</guimenu>
<guimenuitem>Kill</guimenuitem>
</menuchoice></term>
<listitem><para>Sends <errorcode>SIGKILL</errorcode> to the selected
process or processes.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>S<accel>i</accel>gnal</guimenu>
<guimenuitem>Other</guimenuitem>
</menuchoice></term>
<listitem><para><action>Presents a list of other signals to be sent to the
selected process or processes.</action></para></listitem>
</varlistentry>

</variablelist>

</sect2>

<sect2>
<title>The <guimenu>Settings</guimenu> Menu</title>

<variablelist>
<varlistentry>
<term><menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem>Show <accel>T</accel>oolbar</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggles display of the
toolbar.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem>Show <accel>C</accel>ommand Path</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggles display of the command path</action> in the
<guilabel>CMDLINE</guilabel> field of the process list.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem>Show <accel>R</accel>esource Info</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggles display of the resource
displays.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem><accel>S</accel>ave Options</guimenuitem>
</menuchoice></term>
<listitem><para><action>Saves the current settings.</action> Until a new set of
settings is saved, the saved settings will be used upon start up of
&kpm;.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem><accel>P</accel>references...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Opens a dialog</action> to change &kpm;
preferences.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem><accel>U</accel>pdate Period...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Opens a dialog to change the update
period.</action></para></listitem>
</varlistentry>
</variablelist>

</sect2>

</sect1>

</chapter>

<chapter id="signals">
<title>Signals</title>

<para>These are the signals as explained on the manual page of
<literal>signal(7)</literal>. For details consult the manual page by
typing:</para>

<screen><prompt>%</prompt> <userinput><command>man</command> <option>7 signal</option></userinput></screen>

<sect1 id="posix-signals">
<title>POSIX Signals</title>

<para>The following signals are defined by POSIX and can be sent by
&kpm;:</para> 

<variablelist>
<varlistentry>
<term><errorcode>SIGHUP</errorcode></term>
<listitem><para><errorname>Hangup detected on controlling terminal, or death of
controlling process.</errorname></para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGINT</errorcode></term>
<listitem><para><errorname>Interrupt from
keyboard.</errorname></para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGQUIT</errorcode></term>
<listitem><para><errorname>Quit from keyboard.</errorname></para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGILL</errorcode></term>
<listitem><para><errorname>Illegal Instruction.</errorname></para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGABRT</errorcode></term>
<listitem><para><errorname>Abort signal</errorname> from
<application>abort(3)</application>.</para></listitem> 
</varlistentry>

<varlistentry>
<term><errorcode>SIGFPE</errorcode></term>
<listitem><para><errorname>Floating point
exception.</errorname></para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGKILL</errorcode></term>
<listitem><para><errorname>Kill signal</errorname>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGSEG</errorcode></term>
<listitem><para><errorname>Invalid memory
reference</errorname>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGPIPE</errorcode></term>
<listitem><para><errorname>Broken pipe</errorname>: wrote to pipe with no
readers.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGALRM</errorcode></term>
<listitem><para><errorname>Timer signal</errorname> from
<application>alarm(1)</application>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGTERM</errorcode></term>
<listitem><para><errorname>Termination signal</errorname>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGUSR1</errorcode></term>
<listitem><para><errorname>User-defined signal 1</errorname>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGUSR2</errorcode></term>
<listitem><para><errorname>User-defined signal 2</errorname>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGCHLD</errorcode></term>
<listitem><para><errorname>Child stopped or
terminated</errorname>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGCONT</errorcode></term>
<listitem><para><errorname>Continue if stopped</errorname>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGSTOP</errorcode></term>
<listitem><para><errorname>Stop process</errorname>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGTSTP</errorcode></term>
<listitem><para><errorname>Stop sent from tty</errorname>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGTTIN</errorcode></term>
<listitem><para><errorname>tty input for background
process</errorname>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGTTOU</errorcode></term>
<listitem><para><errorname>tty output for background
process</errorname>.</para></listitem>
</varlistentry>

</variablelist>

</sect1>

<sect1 id="other-signals">
<title>Other Signals</title>

<para>These signals are not defined by POSIX, and are not supported by &kpm;
yet:</para>

<variablelist>
<varlistentry>
<term><errorcode>SIGTRAP</errorcode></term>
<listitem><para><errorname>Trace/breakpoint trap</errorname>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGIOT</errorcode></term>
<listitem><para><errorname>IOT trap</errorname>. A synonym for
<errorcode>SIGABRT</errorcode>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGBUS</errorcode></term>
<listitem><para><errorname>Bus error</errorname>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorname>SIGSYS</errorname></term>
<listitem><para><errorcode>Bad argument to routine
(SVID)</errorcode>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorname>SIGSTKFLT</errorname></term>
<listitem><para><errorcode>Stack fault on
coprocessor</errorcode>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGURG</errorcode></term>
<listitem><para><errorname>Urgent condition on socket (4.2
BSD)</errorname>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGIO</errorcode></term>
<listitem><para><errorname>I/O now possible (4.2
BSD)</errorname>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGPOLL</errorcode></term>
<listitem><para>Synonym for <errorcode>SIGIO</errorcode> (System
V).</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGCLD</errorcode></term>
<listitem><para>Synonym for <errorcode>SIGCHLD</errorcode>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGXCPU</errorcode></term>
<listitem><para><errorname>CPU time limit exceeded (4.2
BSD)</errorname>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGXFSZ</errorcode></term>
<listitem><para><errorname>File size limit exceeded</errorname> (4.2
BSD).</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGVTALRM</errorcode></term>
<listitem><para><errorname>Virtual alarm clock</errorname> (4.2
BSD).</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGPROF</errorcode></term>
<listitem><para><errorname>Profile alarm clock</errorname>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGPWR</errorcode></term>
<listitem><para><errorname>Power failure</errorname> (System
V).</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGINFO</errorcode></term>
<listitem><para>A synonym for <errorname>SIGPWR</errorname>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGLOST</errorcode></term>
<listitem><para><errorname>File lock lost</errorname>.</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGWINCH</errorcode></term>
<listitem><para><errorname>Window resize signal</errorname> (4.3 BSD,
Sun).</para></listitem>
</varlistentry>

<varlistentry>
<term><errorcode>SIGUNUSED</errorcode></term>
<listitem><para><errorname>Unused signal</errorname>.</para></listitem>
</varlistentry>

</variablelist>

</sect1>

</chapter>

<chapter id="faq">
<title>Questions and Answers</title>

<qandaset id="questions-and-answers">
<qandaentry>
<question><para>Why does &kpm; sometimes seg fault for no apparent
reason?</para></question>
<answer><para>&kpm; sometimes dies with a segmentation fault if more than one
process is marked and the list is updated. It is unclear why this
happens.</para></answer>
</qandaentry>

<qandaentry>
<question><para>Why does &kpm; use so many <acronym>CPU</acronym>
cycles?</para></question>
<answer><para>&kpm; can consume a lot of <acronym>CPU</acronym>
resources if the update period is too small. On the developer's system
(<acronym>AMD</acronym> K6PR200) it uses approximatly 5 percent
<acronym>CPU</acronym> time with an update period of one second. This
depends heavily on the total number of processes (not just those
displayed) and can be much higher than this under the right
circumstances.</para></answer>
</qandaentry>

<qandaentry>
<question><para>Why does the &percnt;CPU appear to be
incorrect?</para></question>
<answer><para>The &percnt;CPU number isn't accurate at very short update
periods due to timer granularity.</para></answer>
</qandaentry>

<qandaentry>
<question><para>Why is the <guilabel>WCHAN</guilabel> field
incorrect?</para></question>
<answer><para>The <guilabel>WCHAN</guilabel> field isn't correct if a process
sleeps in a location outside those listed in <filename>System.map</filename>
(for instance, in a kernel module). In these cases, the last entry in
<filename>System.map</filename> will be shown (something like
<guilabel>&lowbar;end</guilabel>).</para> </answer>
</qandaentry>

<qandaentry>
<question><para>Why don't cloned PIDs appear in &kpm;?</para></question>
<answer><para>&kpm; doesn't handle more than one process with the same
<acronym>PID</acronym>. Multiple <acronym>PID</acronym>s can occur when using
<literal>CLONE&lowbar;PID</literal> with the <function>clone()</function>
system call.</para></answer>
</qandaentry>

</qandaset>

</chapter>

<chapter id="credits">
<title>Credits and License</title>

<para>&kpm;</para>

<para>Program copyright 2000 Mario Weilguni
<email>mweilguni@kde.org</email> and Mattias Engdeg&aring;rd
<email>f91-men@nada.kth.se</email>.</para> 

<para>Documentation copyright 2000 Morgan N. Sandquist
<email>morgan@pipeline.com</email> and Mario Weilguni
<email>mweilguni@kde.org</email>.</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;

&underGPL;

</chapter>


<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-kpm">
<title>How to obtain &kpm;</title>

<para>&kpm; is part of the <ulink url="http://www.kde.org/">&kde;
project</ulink>.</para>

<para>&kpm; can be found in the kdeadmin package on <ulink
url="ftp://ftp.kde.org/pub/kde/">ftp://ftp.kde.org/pub/kde/</ulink>, the
main &FTP; site of the &kde; project.</para>

</sect1>

<sect1 id="requirements">
<title>Requirements for &kpm;</title>

<para>In order to successfully compile &kpm;, the following is needed:</para>

<itemizedlist>
<listitem>
<para>A &Linux; operating system based on kernel 2.0 or higher. &kpm;
uses &Linux;'s <filename class="directory">/proc</filename>
filesystem. (Unfortunately, &kpm; is not portable to other systems,
because every &UNIX; system has it's own way of gathering process
information.)</para> 
</listitem>
</itemizedlist>

</sect1>

<sect1 id="compilation">
<title>Compilation and Installation</title>

<para>To compile and install &kpm;, type the following in the base
directory of the &kpm; distribution:</para>

<screen><prompt>%</prompt> <userinput>./configure</userinput>
<prompt>%</prompt> <userinput><command>make</command></userinput>
<prompt>%</prompt> <userinput><command>make install</command></userinput></screen>

<para>Since &kpm; uses <command>autoconf</command> and
<command>automake</command> there should be no trouble compiling
it. Please report any problems to the &kde; mailing lists.</para>

</sect1>

</appendix>

&documentation.index; 
</book>

<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:

// vim:ts=0:sw=2:tw=78:noet
-->