# The &kpm; Handbook

Morgan
N.
Sandquist

    morgan@pipeline.com

Mario
Weilguni

    mweilguni@kde.org

Mario
Weilguni

    mweilguni@kde.org

Developer
Mattias
Engdegård

    f91-men@nada.kth.se

Developer
Lauri
Watts

    vampyr@atconnex.net

Reviewer
2000
Morgan N. Sandquist
&FDLNotice;
14/12/2000
2.00.00
KDE
kdeadmin
kpm
process manager
top

&kpm; is a utility that provides information about processes and manages them.

## Introduction

&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.

&kpm; is heavily based on Mattias Engdegård's qps. The main difference between &kpm; and qps is the KDE interface. &kpm; adheres to most KDE standards, uses the KDE config files, and has session managment. Some features of qps were removed (such as the ability to display Mac OS7 style tables or special checkbox widgets).

## Using &kpm;

### &kpm; Start Up

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

&kpm; at start up.
&kpm; at start up.

#### Displays

&kpm; with text displays.
&kpm; with text displays

##### Load Display

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

##### CPU Display

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

##### Memory Display

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

##### Swap Display

The swap display is a bar indicating the amount of swap space being used. Clicking on the swap 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.

##### Uptime Display

The up display is a text-only display that shows how long the system has been running.

#### Process List

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.

##### User Fields

PID

  Process ID. Each process has a unique process ID number (PID), 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.

USER

  Process owner. This is the name of the (real) owner of the process. If the effective user ID of a process is different from the real user ID, this is indicated by a trailing &ast; or &plus;. The &ast; is used when the effective user is the super-user (this usually indicates a binary that is `setuid` to root).

PRI

  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.

NICE

  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 CPU time to a process. Only the super-user may lower the nice value.

SIZE

  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.

RSS

  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.

SHARE

  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.

STAT

  State of the process. At any time, the process is in one of the following states:

  R

    The process is running on a CPU or is ready to run.

  S

    The process is waiting for an event to occur (such as I/O or a timer).

  D

    The process is waiting for an event to occur, without being interruptible (usually waiting ina device driver).

  T

    The process is stopped, or being traced by another process.

  Z

    The process has terminated, but the parent process is not yet aware.

  W

    The process is completely swapped out (that is, it has no resident pages). This is also true for kernel processes, such as `kswapd`.

&percnt;CPU

  Percentage of CPU since last update. This is how much of the CPU time the process used since the last update of &kpm;'s process table.

&percnt;MEM

  Percentage of memory used. This is the percent of the total RAM that is used by the process (as resident size). Shared libraries are included, so this is an overstatement.

TIME

  Total CPU time used. This is how much CPU time the process has used since it was started.

CMDLINE

  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.

##### Jobs Fields

&kpm; jobs fields.
&kpm; jobs fields.

PID

  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.

PPID

  Parent process ID. Every process has one parent process. The exception is process 1 (`init`), which is the root of the process hierarchy; it has no parent.

PGID

  Process group ID. 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.

SID

  Session ID. Session IDs are used mainly to determine what happens at terminal hangups.

TTY

  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 `/dev` 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 `/dev/ttyp6` is shown as p6).

TPGID

  Process group ID of tty owner. A tty in use is owned by a process. This is the PGID of that process.

STAT

  State of the process. At any time, the process is in one of the following states:

  R

    The process is running on a CPU or is ready to run.

  S

    The process is waiting for an event to occur (such as I/O or a timer).

  D

    The process is waiting for an event to occur, without being interruptible (usually waiting in a device driver).

  T

    The process is stopped, or being traced by another process.

  Z

    The process has terminated, but the parent process is not yet aware.

  W

    The process is completely swapped out (that is, it has no resident pages). This is also true for kernel processes, such as `kswapd`.

UID

  Numerical user ID. This is the ID of the (real) owner of the process.

TIME

  Total CPU time used. This is how much CPU time the process has used since it was started.

CMDLINE

  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.

##### Memory Fields

&kpm; memory fields.
&kpm; memory fields.

PID

  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.

TTY

  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 `/dev` 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 `/dev/ttyp6` is shown as p6).

MAJFLT

  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.

MINFLT

  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.

TRS

  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.

DRS

  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.

SIZE

  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.

SWAP

  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.

RSS

  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.

SHARE

  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.

DT

  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.

CMDLINE

  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.

##### Other Fields

PLCY

  Scheduling policy. FIFO (F) and Round-Robin (R) are realtime scheduling policies. Other (O) is the normal Unix time-sharing policy. F and R 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.

RPRI

  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 O) all have priority 0. Only the super-user (root) may change the realtime priority.

FLAGS

  Process flags (hexadecimal). This contains some additional information about the state of a process. Refer to the Linux kernel source for details.

WCHAN

  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.

&percnt;WCPU

  Weighted percentage of CPU. This is the percentage of CPU time the process is using, averaged over the last 30 seconds (exponentially decaying average).

START

  Time process started. This is when the process was created.

COMM

  Command that started the process. This is the command (file name) that started the process. Long names are truncated.

### Monitoring Resource Usage

By default, &kpm; will display system resource usage, including average system load, CPU 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 Settings Show Resource Info. 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 Settings Preferences... .

### Monitoring Processes

&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 View, as described here.

&kpm; displays a number of fields of information about each process. By default, it displays the most common process fields. However, through View, 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 here.

Finally, a list of TCP and UDP sockets used by the selected process or processes can be found by selecting CtrlI or Process Socket Info. A process is selected by clicking on it. Multiple processes are selected by holding down Shift while clicking on each of them in turn.

### Managing Processes

&kpm; performs three types of process management:

Renice

  Renice allows users to change the priority of their processes, as described here. By selecting CtrlR or Process Renice..., users can decrease the priority of their processes. Additionally, the super-user can increase or decrease the priority of any process.

Change Scheduling

  The super-user can change the scheduling of processes, as described here. This is done by selecting either CtrlS or Process Change Scheduling....

Signals

  Users can send any of the POSIX signals listed in to their processes. Additionally, the super-user can send any of those signals to any process. Those signals are sent using Signal, as described in .

## Command Reference

### The Main &kpm; Window

#### The File Menu

CtrlZ File Iconify

  Iconifies the main window. When iconfied, &kpm; uses far less CPU 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 fvwm), &kpm;'s icon itself will show the load, depending on how the window manager is configured.

CtrlQ File Quit

  Quits &kpm;. Closing the main window or pressing Quit on the toolbar has the same effect.

#### The View Menu

CtrlU View Refresh process list

  Immediately updates the process list. This is very useful with rather long update periods. This can also be done by pressing Refresh process list on the toolbar or by pressing Space.

View All Processes

  Displays all processes.

View Your Processes

  Displays processes started by current user. This includes those processes running under a different user (for example, `setuid` root programs started by the current user).

View Non-Root Processes

  Displays all processes except those started by root.

View Running Processes

  Displays only running processes (that is, processes running or on the run queue).

View User Fields

  Displays the the most common process fields. These are those fields typically displayed by top.

View Job Fields

  Displays the most relevant fields for job control.

View Memory Fields

  Displays fields related to memory usage, page faults, etc.

View Select Fields...

  Allows the selection of a custom set of fields to be displayed.

#### The Process Menu

CtrlR Process Renice...

  Modifes the priority of the marked process or processes. 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.

Ctrls Process Change Scheduling...

  Allows the super-user to change the scheduling policy of the selected process or processes. This function uses the POSIX.1b real-time extensions present in Linux 2.0.x and later kernels. Normal processes are set to `SCHED&lowbar;OTHER` and have a static priority of 0. Real-time (soft) processes have a policy of `SCHED&lowbar;FIFO` or `SCHED&lowbar;RR` and a static priority in the range of 1 to 99. This option is only available to the super-user.

Ctrli Process Socket Info

  Displays a list of TCP and UDP sockets used by the selected process or processes.

#### The Signal Menu

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 here.

CtrlT Signal Terminate

  Sends SIGTERM to the selected process or processes.

CtrlH Signal Hangup

  Sends SIGHUP to the selected process or processes.

Signal Interrupt

  Sends SIGINT to the selected process or processes.

Ctrlk Signal Kill

  Sends SIGKILL to the selected process or processes.

Signal Other

  Presents a list of other signals to be sent to the selected process or processes.

#### The Settings Menu

Settings Show Toolbar

  Toggles display of the toolbar.

Settings Show Command Path

  Toggles display of the command path in the CMDLINE field of the process list.

Settings Show Resource Info

  Toggles display of the resource displays.

Settings Save Options

  Saves the current settings. Until a new set of settings is saved, the saved settings will be used upon start up of &kpm;.

Settings Preferences...

  Opens a dialog to change &kpm; preferences.

Settings Update Period...

  Opens a dialog to change the update period.

## Signals

These are the signals as explained on the manual page of `signal(7)`. For details consult the manual page by typing:

    % man 7 signal

### POSIX Signals

The following signals are defined by POSIX and can be sent by &kpm;:

SIGHUP

  Hangup detected on controlling terminal, or death of controlling process.

SIGINT

  Interrupt from keyboard.

SIGQUIT

  Quit from keyboard.

SIGILL

  Illegal Instruction.

SIGABRT

  Abort signal from abort(3).

SIGFPE

  Floating point exception.

SIGKILL

  Kill signal.

SIGSEG

  Invalid memory reference.

SIGPIPE

  Broken pipe: wrote to pipe with no readers.

SIGALRM

  Timer signal from alarm(1).

SIGTERM

  Termination signal.

SIGUSR1

  User-defined signal 1.

SIGUSR2

  User-defined signal 2.

SIGCHLD

  Child stopped or terminated.

SIGCONT

  Continue if stopped.

SIGSTOP

  Stop process.

SIGTSTP

  Stop sent from tty.

SIGTTIN

  tty input for background process.

SIGTTOU

  tty output for background process.

### Other Signals

These signals are not defined by POSIX, and are not supported by &kpm; yet:

SIGTRAP

  Trace/breakpoint trap.

SIGIOT

  IOT trap. A synonym for SIGABRT.

SIGBUS

  Bus error.

SIGSYS

  Bad argument to routine (SVID).

SIGSTKFLT

  Stack fault on coprocessor.

SIGURG

  Urgent condition on socket (4.2 BSD).

SIGIO

  I/O now possible (4.2 BSD).

SIGPOLL

  Synonym for SIGIO (System V).

SIGCLD

  Synonym for SIGCHLD.

SIGXCPU

  CPU time limit exceeded (4.2 BSD).

SIGXFSZ

  File size limit exceeded (4.2 BSD).

SIGVTALRM

  Virtual alarm clock (4.2 BSD).

SIGPROF

  Profile alarm clock.

SIGPWR

  Power failure (System V).

SIGINFO

  A synonym for SIGPWR.

SIGLOST

  File lock lost.

SIGWINCH

  Window resize signal (4.3 BSD, Sun).

SIGUNUSED

  Unused signal.

## Questions and Answers

Why does &kpm; sometimes seg fault for no apparent reason?

&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.

Why does &kpm; use so many CPU cycles?

&kpm; can consume a lot of CPU resources if the update period is too small. On the developer's system (AMD K6PR200) it uses approximatly 5 percent CPU 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.

Why does the &percnt;CPU appear to be incorrect?

The &percnt;CPU number isn't accurate at very short update periods due to timer granularity.

Why is the WCHAN field incorrect?

The WCHAN field isn't correct if a process sleeps in a location outside those listed in `System.map` (for instance, in a kernel module). In these cases, the last entry in `System.map` will be shown (something like &lowbar;end).

Why don't cloned PIDs appear in &kpm;?

&kpm; doesn't handle more than one process with the same PID. Multiple PIDs can occur when using `CLONE&lowbar;PID` with the `clone()` system call.

## Credits and License

&kpm;

Program copyright 2000 Mario Weilguni mweilguni@kde.org and Mattias Engdegård f91-men@nada.kth.se.

Documentation copyright 2000 Morgan N. Sandquist morgan@pipeline.com and Mario Weilguni mweilguni@kde.org.

&underFDL;

&underGPL;

## Installation

### How to obtain &kpm;

&kpm; is part of the KDE project.

&kpm; can be found in the kdeadmin package on ftp://ftp.kde.org/pub/kde/, the main ftp site of the KDE project.

### Requirements for &kpm;

In order to successfully compile &kpm;, the following is needed:

- A Linux operating system based on kernel 2.0 or higher. &kpm; uses Linux's `/proc` filesystem. (Unfortunately, &kpm; is not portable to other systems, because every UNIX system has it's own way of gathering process information.)

### Compilation and installation

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

    % ./configure
    % make
    % make install

Since &kpm; uses autoconf and automake there should be no trouble compiling it. Please report any problems to the KDE mailing lists.