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 of USER_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 the TZ environment variable -- used to render the wall-clock time in the header without pulling in chrono or 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 when c is toggled).
• /etc/passwd -- UID to username resolution, cached across refreshes.

Arguments

Behavior

TUI mode (default)

The terminal is divided into two regions:

1. Summary header -- variable height (5 lines + per-CPU lines):

   • top - HH:MM:SS up ..., N users, load average: a, b, c
   • Tasks: 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+cache
   • MiB Swap: total / free / used / available

2. 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 (v descending / ^ 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

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

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