procutils-top 0.2.0

# 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

| 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:

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

| 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) |