<!DOCTYPE book PUBLIC  "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN" [
 <!ENTITY kappname "&kpm;" -- this only *seems* redundant -->
 <!ENTITY % addindex "IGNORE">
 <!ENTITY % English "INCLUDE" -- change language only here -->
 <!ENTITY % ents PUBLIC "-//KDE//ENTITIES Documentation V1.0//EN">
  %ents;
]>

<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>vampyr@atconnex.net</email></address>
</affiliation>
<contrib>Reviewer</contrib>
</othercredit>

</authorgroup>

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

<legalnotice>&FDLNotice;</legalnotice>

<date>14/12/2000</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 CPU,
RAM, 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 abilty 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 config files, and has session
managment.  Some features of <application>qps</application> were removed (such
as the ability to display Mac OS7 style tables or special checkbox
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>cach</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 avaiable 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 <filename>setuid</filename> to
root).</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>PRI</guilabel></term>
<listitem><para>Length of next timeslice. This is the maximal length of the
process's next timeslice (or what is left of its current timeslice, if it is the
currently running process). The number is rescaled to the -20..20 interval, with
a smaller number indicating a longer timeslice.</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 timeslice. 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 ina 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>, <abbrev>etc.</abbrev>) 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>/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>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 ID.  Each process has a unique process ID (PID) number, starting at 1 and
going up. When a new process is created, the next unused PID is allocated. PIDs
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>/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 occured. A page fault occurs when a process attempts to
read or write from a memory page that is not present in RAM. 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 occured. A page fault occurs when a process attempts to
read or write from a memory page that is not present in RAM, 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 RAM.</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 RAM.</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 RAM, including shared libraries. This gives a fair approximation
of how much RAM 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 RAM 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. FIFO (<guilabel>F</guilabel>) and Round-Robin (<guilabel>R</guilabel>) are
realtime scheduling policies. Other (<guilabel>O</guilabel>) is the normal Unix time-sharing policy. 
<guilabel>F</guilabel> and <guilabel>R</guilabel> processes have a realtime 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. FIFO
processes run until they give up their CPU 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 (FIFO 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 CPU. This is the percentage of CPU 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"><keycap>Ctrl</keycap><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 <keycap>Shift</keycap> 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"><keycap>Ctrl</keycap><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"><keycap>Ctrl</keycap><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"><keycap>Ctrl</keycap><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 <filename>KWin</filename> is the window manager, there will be
an icon in <application>Kicker</application> displaying the average system load. Under
other window managers (such as fvwm), &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"><keycap>Ctrl</keycap><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"><keycap>Ctrl</keycap><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,
<filename>setuid</filename> root 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"><keycap>Ctrl</keycap><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 CPU 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
oridnary 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"><keycap>Ctrl</keycap><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"><keycap>Ctrl</keycap><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"><keycap>Ctrl</keycap><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"><keycap>Ctrl</keycap><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"><keycap>Ctrl</keycap><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
<filename>signal(7)</filename>. 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>

&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>/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 width="40">
<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 <application>autoconf</application> and
<application>automake</application> there should be no trouble compiling
it. Please report any problems to the KDE mailing lists.</para>

</sect1>

</appendix>


<![ %addindex; [ &kdedocindex; ]]>
</book>








