top
Dynamic real-time view of running processes.
Description
Displays a continuously updating summary of system state and a sorted table
of processes, similar to the top(1) provided by procps-ng. Defaults to
an interactive TUI; can also run in batch mode for non-interactive output.
Press q to quit.
Inputs
System-wide
/proc/stat– aggregate and per-CPU jiffies (user, nice, system, idle, iowait, irq, softirq, steal). Used to compute CPU% deltas between samples./proc/meminfo–MemTotal,MemFree,MemAvailable,Buffers,Cached,SReclaimable,SwapTotal,SwapFree./proc/loadavg– 1/5/15-minute load averages./proc/uptime– system uptime in seconds./var/run/utmp– count ofUSER_PROCESS(type 7) entries; reported as the user count in the header. Each entry is assumed to be 384 bytes (Linux x86_64 layout)./etc/localtime(TZif v1/v2/v3) or theTZenvironment variable – used to render the wall-clock time in the header without pulling inchronoor libc time facilities.
Per-process
/proc/[pid]/stat– pid, comm, state, priority, nice, vsize, rss, utime, stime./proc/[pid]/status–euid,RssFile,RssShmem(used to derive SHR)./proc/[pid]/cmdline– full command line (shown whencis toggled)./etc/passwd– UID to username resolution, cached across refreshes.
Arguments
| Flag | Description |
|---|---|
-d, --delay SECS | Refresh interval in seconds (default: 3.0, minimum: 0.1) |
-n, --iterations N | Exit after N display updates |
-b, --batch | Batch mode – non-interactive plain-text output, suitable for piping |
-p, --pid PIDS | Show only the given PIDs (comma-separated) |
-u, --user USER | Show only processes for this user (name or numeric UID) |
-1 | Start with per-CPU display enabled |
Behavior
TUI mode (default)
The terminal is divided into two regions:
-
Summary header – variable height (5 lines + per-CPU lines):
top - HH:MM:SS up ..., N users, load average: a, b, cTasks: T total, R running, S sleeping, T stopped, Z zombie%Cpu(s):aggregate, or one line per CPU when per-CPU mode is on (us, sy, ni, id, wa, hi, si, st)MiB Mem:total / free / used / buff+cacheMiB Swap:total / free / used / available
-
Process table – remaining space:
- Columns: PID, USER, PR, NI, VIRT, RES, SHR, S, %CPU, %MEM, TIME+, COMMAND
- Sorted by the active sort field (default: %CPU descending)
- Sort indicator (
vdescending /^ascending) shown next to the active column
Batch mode (-b)
Prints summary and process table to stdout each iteration in plain text
(no TUI, no colors, no cursor control). Repeats every --delay seconds
for --iterations rounds, or until interrupted.
CPU% computation
Per-process %CPU is computed as the process’s utime + stime delta divided
by the total system CPU ticks delta between samples, scaled by the number
of online CPUs so a single fully-busy core reports approximately 100%.
The first refresh has no previous sample, so per-process %CPU is reported
as 0.0 and CPU summary lines show cumulative percentages since boot.
Columns
| Column | Description |
|---|---|
| PID | Process ID |
| USER | Effective user name (truncated to 8 chars) |
| PR | Scheduling priority; rt if priority < -99 |
| NI | Nice value |
| VIRT | Virtual memory size |
| RES | Resident set size |
| SHR | Shared resident memory (RssFile + RssShmem) |
| S | State: R running, S sleeping, I idle, D disk-sleep, T/t stopped, Z zombie |
| %CPU | Per-process CPU percentage (see above) |
| %MEM | RES as a percentage of MemTotal |
| TIME+ | Cumulative CPU time, formatted M:SS.cc |
| COMMAND | comm by default; full cmdline when c is toggled |
Size formatting
VIRT, RES and SHR are formatted with the shared format_kb helper,
producing human-readable units (K / M / G / T) scaled automatically.
Color
State column color reflects process state:
- Green: R (running)
- Yellow: T or t (stopped / traced)
- Red: Z (zombie)
- Default: all others
The active sort column header is highlighted via the table header style.
Interactive commands
| Key | Action |
|---|---|
q / Q | Quit |
| Space | Force immediate refresh |
P | Sort by %CPU |
M | Sort by %MEM |
N | Sort by PID |
T | Sort by TIME+ |
R | Reverse the current sort order |
c | Toggle full command line vs. comm |
1 | Toggle aggregate / per-CPU display |
Up / k | Scroll up one row |
Down / j | Scroll down one row |
| Page Up | Scroll up 20 rows |
| Page Down | Scroll down 20 rows |
| Home | Scroll to top |
| End | Scroll to bottom |
| Mouse wheel | Scroll up/down 3 rows |
Sort changes and scroll actions trigger a redraw without a full /proc
rescan; only the timer expiry or Space re-reads /proc.
Terminal handling
Uses ratatui with crossterm as the terminal backend. Enters alternate
screen, raw mode, and mouse capture on startup; restores the terminal on
exit. Pending mouse events are drained between redraws so a flurry of
scroll events does not trigger repeated /proc scans.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Normal exit |
| 1 | Failure (terminal initialization error) |