Technical Manual

1.1 · What ngtop is

ngtop is a system monitor for the terminal. It joins the processor, memory and process view of btop, the GPU view of nvtop and the network, disk and service views of a graphical task manager in one full-screen interface with five sections. It is one static executable for Linux x86_64: copy it to any distribution and it runs, with nothing to install. This manual explains how it works, for whoever wants to understand it, maintain it or extend it.

1.2 · Design principles

The design is the same in every file. These rules were fixed before the code was written and they explain choices that would otherwise look odd, such as a services thread that never shares a lock with the interface, or a signal dialog that checks a process twice.

1.3 · The project in numbers

The numbers below are counted from the sources every time this manual is built, so they cannot drift. Unit tests live next to the code they test, inside the same files, and are counted with them.

Besides code, tests/fixtures/ holds the fake system trees (snapshots of /proc, /sys and /etc reduced to the files ngtop reads), and mockup/ holds the HTML mock-ups the interface was designed from; mockup/app.html is the visual reference.

2.1 · The repository

Everything is in one Cargo package. The library holds the collectors and the interface; the program is a thin main.rs on top of it, so the integration tests can call the same functions the program does.

NG-TOP/
├── Cargo.toml  # one package, release profile tuned for size and speed
├── build.sh  # static build + check
├── src/
│   ├── main.rs  # entry point, diagnostic modes
│   ├── lib.rs  # library root
│   ├── config.rs  # command line and configuration file
│   ├── collect/  # collectors: no interface code
│   │   ├── mod.rs  # System, Roots
│   │   ├── cpu.rs  mem.rs  load.rs  sensors.rs
│   │   ├── process.rs  procdetail.rs
│   │   ├── net.rs  disk.rs  conn.rs  gpu.rs
│   │   └── services/  # systemd: backend, worker thread, cgroup, fake
│   └── ui/  # interface: ratatui
│       ├── mod.rs  app.rs  view.rs  keys.rs  doc.rs  history.rs  fmt.rs  theme.rs  tz.rs  snapshot.rs
│       ├── widgets/  # Panel, BrailleGraph, Meter, Sparkline, ProcTable, TabBar, KeyBar, Dialog
│       └── sections/  # one file per section; servizi/ is a folder
├── tests/  # integration tests
│   └── fixtures/  # fake /proc, /sys, /etc trees
├── scripts/  # test-distro.sh, third-party.py
├── site/  # landing page, publishing, licence page
├── mockup/  # HTML mock-ups of the interface (visual reference)
├── docs/  # these manuals
│   └── sources/  # generator, style, chapters
└── dist/  # the finished binary (not in the repository)

2.2 · Tools and build commands

Four tools are enough to build and test ngtop. Rust is installed with rustup in ~/.cargo/bin; add it to PATH if it is missing.

What build.sh does. It stops at the first error (set -euo pipefail), puts ~/.cargo/bin on the path, runs cargo build --release --target x86_64-unknown-linux-musl, copies the result to dist/ngtop (after removing the old file, so a running copy does not give “text file busy”), and finally runs ldd on it. If ldd does not say “not a dynamic executable” or “statically linked”, the script prints the dependencies and exits with an error. Only then is the file called static: see ch. 9 “The static build”.

The release profile (Cargo.toml): opt-level = 3, lto = "fat" (the whole program is optimised together), codegen-units = 1 and strip = true (no symbols). It is slower to compile and makes the file smaller and faster.

$ bash build.sh
...
OK: dist/ngtop is static (3.5M)

2.3 · Folders outside src

Each folder outside src/ has one job.

2.4 · The file map

Every source file with its line count. The counts are taken from the files at every build of the manual. A file that exists but is not described here would appear under “Other files” at the end, with a dash instead of a role: that is the sign that this list needs a new line.

3.1 · Collect and draw

ngtop has two halves. The collectors (src/collect/) read the kernel's files and turn counters into numbers: percentages, rates, latencies. The interface (src/ui/) keeps the recent past of those numbers and draws them. The only thing that ties them is the System structure, which the interface reads and never writes.

System (src/collect/mod.rs) holds the latest value of everything: cpu, mem, load, uptime, processes, net, gpu, disks, conns, cpu_temp and zram. It also holds the previous sample of the counters it needs for differences (for example prev_cpu, prev_cores and prev_procs). A collector never stores history: it knows only “now” and “the sample before”.

App (src/ui/app.rs) keeps what the interface needs to remember: the histories (cpu_hist, mem_hist, and one per network interface, disk and GPU), the process list in the order shown, the selection, the filter, the open dialog and the state of each section. After every refresh, App::update() pushes the new values into the histories (600 samples each, HISTORY_LEN) and rebuilds the process list.

3.2 · One refresh, step by step

System::refresh() measures the time since the previous call with the real clock and passes it to refresh_with_dt(dt). Tests call refresh_with_dt directly with a chosen dt, so rates do not depend on how fast the test runs. With dt <= 0 (the first sample) every rate is zero.

Step 4 also adds to each process the GPU share and GPU memory it found, so the process table can sort by GPU without knowing where the number came from. Details of each step are in ch. 4 “Data sources”.

3.3 · The event loop

The loop is in event_loop() (src/ui/mod.rs). It is single-threaded and sleeps most of the time.

At the start, run() does everything that can fail or allocate a lot (time zone, the first sample) before it touches the terminal. Then it switches to raw mode and the alternate screen, optionally turns on the mouse, and enters the loop. How the terminal is given back, even after an error or a signal, is in 7.6 “Terminal restore”.

3.4 · Threads

ngtop starts three kinds of thread, and none of them is a pool: each exists because one call can block.

The pattern is always the same: the interface sends a request and goes on; later poll() takes whatever answers have arrived, without waiting (try_recv). The interface can therefore draw, scroll and take keys while systemd is slow or absent. The tests l_interfaccia_non_attende_il_backend and un_azione_lenta_non_blocca_la_coda_e_ce_ne_e_una_sola check it with a deliberately slow backend.

3.5 · State and drawing

The interface state is one App value passed by reference to the drawing code. The pieces that are specific to a section live in their own structure, so a section can be read on its own.

Layout mode. LayoutMode::for_size() chooses between large and compact: compact when the terminal is narrower than 100 columns or lower than 30 rows. The mode is recomputed on every resize event; only the Overview has a different compact layout (6.2 “The Overview section”).

Drawing. view::draw() splits the screen into the top line, the body and the bottom line, asks the active section to draw the body, then draws the key bar for that section, the status line of signals and nice (which replaces the key bar for five seconds), and last the help or the dialog on top. Every widget writes into the same ratatui Buffer (ch. 5 “The UI framework”).

4.1 · How the collectors read

A collector is a function that reads a few small text files and returns a plain value. All of them follow the same four rules, which is why a missing file never becomes an error on screen.

4.2 · CPU, temperature

The processor view is built from two files and one directory.

Temperature. find_cpu_temp_path() looks once, at the first refresh, for the file to read, and the answer (even “none”) is remembered. It scans /sys/class/hwmon/hwmon* in name order and accepts the first sensor whose name is known: coretemp (label “Package id 0”), k10temp (labels “Tctl” then “Tdie”), zenpower (“Tdie” then “Tctl”) and cpu_thermal / cpu-thermal. If the wanted label is not found it falls back to temp1_input. If no hwmon matches, it looks for a thermal zone of type x86_pkg_temp. The value is in thousandths of a degree and is divided by 1000. The same read_temp() reads disk and GPU temperatures.

4.3 · Memory, swap, load

Memory comes from one file, /proc/meminfo, whose values are in kB; the parser multiplies by 1024 (a value with no unit is taken as bytes). Missing keys count as zero.

Load and uptime. /proc/loadavg: the first three numbers are the 1, 5 and 15 minute averages; the fourth, “running/total”, gives the number of runnable and existing scheduling entities. /proc/uptime: seconds since boot, and idle seconds summed over all cores. The tab bar shows uptime as 3d 04:12 or 04:12:05.

4.4 · Processes

Reading every process is the most expensive part of a refresh, so process::read_all() is written to do as little as possible per process. For each directory in /proc whose name is a number it reads stat every time and the other files only when needed.

The name (comm) is in parentheses and may contain spaces and even a “)”, so parse_stat() takes the text between the first “(” and the last “)”, and counts fields after it.

CPU % of a process is a share of the whole machine, from 0 to 100:

cpu% = Δ(utime + stime) ÷ hz ÷ dt ÷ ncores × 100, clamped to 0–100

where hz is the number of clock ticks per second (clock_ticks_per_second()), dt is the real time between the two refreshes, and ncores is the number of cores listed in /proc/stat. A process that fully uses one core of eight shows 12.5. The previous sample counts only if it has the same start time: if a pid was reused by a new process, its first sample shows zero instead of a wrong number.

Memory is the resident set: rss pages × page size, with the page size read once from the system.

Tree order. tree_order() puts each process under its parent, children sorted by pid, with the prefixes ├─ , └─ and │ . A process whose parent does not exist is a root; if a loop in the parent ids ever existed, the leftover processes are made roots instead of being lost or looping forever. Sorting (sort_processes()) is always stable: ties are broken by pid.

The selected process. DetailCollector::refresh() reads, only for the pid selected in the Processes section, exe and cwd (links), stat (last core, scheduling policy), status (CPU affinity, swap), cgroup, io and the number of open files. Heavy files are read only when their tab is shown: task/*/stat (Threads, with per-thread CPU %), fd and limits (Files), the socket tables (Net), environ (Env), limits (Limits) and the cgroup files (cgroup). smaps_rollup (PSS, shared, swap) can take tens of milliseconds on a large process, so it is read only on the General tab, when the process changes and then every 5th cycle. Lists are capped: 200 files (MAX_FILES) and 500 environment variables (MAX_ENV).

4.5 · Network

Network data is split into what changes every cycle (the byte counters) and what hardly ever does (routes, addresses, link speed). The second group is reread every 5th cycle.

The interface shown. NetInfo::pick() chooses the one the user selected, else the interface of the default route, else the first one that is not lo. NetInfo::cycle() moves to the next or previous one and skips lo when others exist.

4.6 · Connections: inode to pid

A line of /proc/net/tcp gives two addresses, the state, the queue sizes and an inode, but not the process. The process is found by looking for a descriptor that points to socket:[inode]. Doing that for every connection on every cycle would open the fd directory of every process, so the result is kept.

The algorithm of conn::refresh_with():

4.7 · Disks and filesystems

The disk view combines a kernel counter file, a few static files and the mount table.

Filesystems. parse_mountinfo() keeps only the mounts of real filesystem types (ext2/3/4, btrfs, xfs, f2fs, vfat, exfat, zfs, nfs, nfs4, cifs, smb3, ntfs, ntfs3, fuseblk, jfs, reiserfs, bcachefs, hfsplus), skips the mounts under Docker, Podman and snap folders, and drops duplicates (same mount point, or same device and same root: bind mounts of one subvolume). Octal escapes such as \040 in paths are decoded. The disk of a mount is found from its source (disk_of_source()): /dev/nvme0n1p2 is nvme0n1; device-mapper and network sources have none.

Why threads. statvfs on a network mount whose server has vanished can block for minutes, and nothing can interrupt it. FsMonitor therefore starts one thread per mount point ngtop-statvfs. Every 5th cycle the interface asks each one for a new measurement, but only those with no request in flight; it never queues a second. It collects answers that have already arrived without waiting (only the very first refresh waits, at most 300 ms, so the first screen is not empty). A mount with no answer for more than 5 seconds (FS_TIMEOUT) is shown as unresponsive and the others are unaffected. A mount that disappears from the list has its thread closed.

4.8 · GPU: devices

GPU data comes from two places: the device's own files in sysfs, and, for who uses the GPU, the fdinfo file of every open GPU descriptor of every process.

Identity. Read once per card (read_static()): vendor and device from device/vendor and device/device; PCI slot and driver from device/uevent (PCI_SLOT_NAME, DRIVER); the name from product_name if the card has it, otherwise from the pci.ids database (pci_name(): the bracketed commercial name, with the maker in front), otherwise “AMD GPU [1002:xxxx]”. The PCI slot is the key of the device everywhere in the program.

The temperature shown is the hwmon “junction” sensor, else “edge”, else the first one. Power is power1_average (else power1_input), in microwatts divided by 10⁶; the fan is fan1_input in RPM, or pwm1 ÷ 255 as a percentage. The PCIe text “4.0 ×16” is built from current_link_speed in GT/s (2, 5, 8, 16, 32, 64 map to PCIe 1.0 to 6.0) and current_link_width.

4.9 · GPU: processes and the fdinfo files

Modern kernels (amdgpu, i915, xe) publish, for each open GPU descriptor, a file /proc/[pid]/fdinfo/N with the DRM client's counters. That is the only source of “who is using the GPU”, and it needs no special library.

Finding the files. A process's GPU descriptors are the ones in /proc/[pid]/fd that point to /dev/dri/…. Listing them for every process every cycle would be slow, so the answer is cached per pid with the process's start time. A new pid is scanned at once; a process that has GPU descriptors is rescanned every 5th cycle, one without every 20th (both staggered by pid so not all happen together); a process whose fd folder was denied is not scanned again until it is a different process. Kernel threads are never scanned. Then only the known descriptors are read, each cycle.

One client, many processes. A DRM client can be reachable from several processes at once (a parent and its forked children share the descriptor). If each were counted, one workload would appear many times. The collector walks pids in ascending order and keeps the first process that shows a given (card, client id); the others are ignored. The client is attributed to the lowest pid that holds it.

4.10 · Services, sessions, boot

The Services section needs systemd. It is available only if /run/systemd/system exists (systemd_present()); otherwise the section says so. All the following happens in the services thread (3.4 “Threads”).

Bus and timeouts. The system scope uses the system bus, the user scope the session bus. Queries wait at most 10 seconds (QUERY_TIMEOUT); actions use a separate connection that waits up to 120 seconds (ACTION_TIMEOUT) because polkit may be waiting for a password. Subprocesses are run by run_with_timeout(), which polls every 20 ms and kills the child at the limit.

5.1 · ratatui and the frame

ngtop uses ratatui 0.30 for what it does well — a screen as a grid of cells, a layout engine, a test backend — and crossterm 0.29 for the terminal. It does not use ratatui's ready-made widgets. Every visible element is a small struct in src/ui/widgets/ with a render(area, buf) method that writes cells straight into the ratatui Buffer. This costs a little code and buys exact control over characters, colours and widths, the same on every terminal.

Drawing is a pure function of App and System. It happens inside Terminal::draw, and ratatui sends the terminal only the cells that changed since the last frame. The same function runs on a ratatui TestBackend in src/ui/snapshot.rs: render_app() returns the buffer, to_text() turns it into lines of text (empty meter cells become “·” so they can be told from full ones) and to_ansi() into text with truecolor escape sequences. This is what ngtop --snapshot WxH prints.

5.2 · Safe writing and widths

Terminals have no exceptions, but the code that writes to a ratatui buffer does: setting a cell outside the buffer panics. A monitor must survive being resized to one row, or to an enormous size. So no widget calls ratatui's writing functions directly.

Unicode widths. A character can occupy zero, one or two cells (CJK, many emoji; combining marks take none). Process names and command lines come from the system and can contain anything. Wherever a text is placed in a column (put_line() in proctable.rs), ngtop advances by the width of each character and skips zero-width ones; a wide character that does not fit whole in the column is not drawn, so it can never spill into the next. The characters ngtop draws itself — braille, “■”, block elements, box lines, “▼”, “▲” — are one cell wide.

Arithmetic. Sizes are u16. Wherever a product could overflow on a huge terminal or a machine with thousands of cores, the code widens to u32 first (for example core_layout()) or uses saturating_sub and saturating_add.

5.3 · The widgets

All widgets are in src/ui/widgets/. Each takes the data to show and a rectangle.

The widgets keep no state. All state (selection, scroll offset, histories) is in App.

5.4 · The braille graph

Every graph in ngtop — the CPU history, the network rate, the GPU load — is a braille graph. A braille character (U+2800 to U+28FF) has a grid of 2 × 4 dots, so one terminal cell carries two columns and four levels of the graph: eight times the resolution of the cell, with a single character.

The algorithm is braille_rows(vals, w, h, down) in src/ui/widgets/braille.rs. The graph is w cells wide and h cells high, so it has 2w columns of 4h levels.

With down the graph hangs from the top edge and the bit tables are swapped, which gives the mirror image used under a graph that goes up (network received and sent, GPU history). The rate graphs are given values already divided by a “round” maximum: nice_max(v, floor) in fmt.rs returns the smallest power of two that is at least the largest recent value (and at least the floor), so the scale does not jump at every cycle.

5.5 · Theme and gradients

Colours are defined once, in src/ui/theme.rs, as 24-bit values. They are ten gradients: lists of two to four colour stops between which the program interpolates. They were taken from the mock-up (mockup/tui.js).

grad(stops, t) takes t from 0 to 1 (outside the range or NaN is brought back to 0–1), scales it to the number of segments, finds the segment and mixes the two colours channel by channel: colour = a + (b − a) × f, rounded. One stop gives a flat colour; none gives the default text colour.

Each panel has a colour taken from the gradient of its content (CPU green, memory cyan, network blue, disks orange, processes orange, GPU purple). Percentages are coloured with pct_color(), temperatures by grad(TEMP, (t − 30) ÷ 60).

5.6 · Colour depth

Most terminals can show 24-bit colour, but not all: the Linux console has 16 colours, and some terminals only 256. ngtop draws everything in truecolor and converts at the very end.

In the event loop, after view::draw() and before the buffer is sent, convert_buffer() visits every cell once and converts its foreground and background. In truecolor it does nothing. It is the only place where depth is considered, so no widget needs to know about it.

5.7 · Layout

The interface has two layouts. LayoutMode::for_size() picks the compact one when the terminal is narrower than 100 columns or lower than 30 rows. It is recomputed at every resize. The other four sections adapt by hiding what does not fit; only the Overview is redrawn with a compact version.

The compact Overview is a short header — CPU (meter, percentage, temperature, clock, and one sparkline cell per core), MEM, a GPU line if there is a GPU, NET and DSK — over a short process table (small_columns(): PID, User, CPU%, Mem, Command).

6.1 · Switching sections

The five sections are the five files in src/ui/sections/. Each has the same shape: a draw() function that fills the body rectangle, and, when it has keys of its own, an on_key() that gets the key before the general handler of App::on_key(). The order matters: when the dialog is open it takes every key; then the Services section; then the filter being typed; then the Network & Disks and Processes sections; then the keys common to all.

6.2 · The Overview section

The first section shows the whole machine at a glance, and is the one the program starts in.

Compact layout. Under 100 columns or 30 rows, the Overview becomes a header of one-line meters (CPU with a sparkline of the cores, MEM, GPU, NET, DSK) above a table of PID, User, CPU%, Mem and Command. The bottom bar shortens to Help, Filter, Tree, Sort, Sig, Quit.

6.3 · The GPU section

The GPU section is nvtop inside ngtop: one panel per device, a history of the selected one, and the processes that use any GPU.

With no GPU the section shows a panel saying “No GPU detected”. With an NVIDIA card or a card asleep, the device panel says what it can: ngtop never invents a figure for what it did not read.

6.4 · The Processes section

Processes is the process manager: a large table, and for the selected process a detail area with seven tabs.

6.5 · The Network & Disks section

This section joins what a network monitor and a disk monitor would show on two screens.

The connection list is collected only while this section is visible (4.6 “Connections: inode to pid”). The height of the blocks is shared out by allocate() (5.7 “Layout”).

6.6 · The Services section

Services is a systemd manager: it lists the units, shows the detail and the journal of the selected one, and starts, stops, restarts, enables or disables it after asking.

Layout. With 120 columns × 38 rows or more (a body of 120 × 36): list (58 %) and detail (42 %) on top, boot and sessions below. From 100 columns: list and detail side by side. Narrower: the list above and the detail below. Waiting. While a request is outstanding, the section polls the thread every 100 ms. If a request has waited 10 seconds, the status line says “systemd is not responding”. No systemd. If /run/systemd/system does not exist, the section shows a single panel: “Services unavailable: systemd not found”.

Rhythm of requests (Servizi::schedule()): the unit list every 2 s (every 0.6 s until it has been received twice); the detail and the journal only 200 ms after the selection has stopped moving (so scrolling quickly asks for nothing), the detail every 2 s and the journal every 5 s; the sessions every 10 s; boot times and the slowest units once. All requests are in 4.10 “Services, sessions, boot”.

7.1 · Signals: pidfd and start time

A signal sent to a pid is dangerous for one reason: pids are reused. Between the moment the user sees a process in the list and the moment they press Enter, that process may have ended and the kernel may have given its number to another one. A naive “kill the pid” would then kill an innocent. ngtop closes this window in three ways.

send_signal() is the only function that sends a signal. Its order is deliberate: open first, check after. If it checked and then opened, the pid could change in between; opened first, the descriptor and the check refer to the same process.

No C library is involved: the calls are in rustix (pidfd_open, pidfd_send_signal, kill_process, setpriority_process), which makes the raw system calls.

7.2 · The signal dialog

The dialog (SignalDialog, key F9 or k) lets the user choose a signal and whether it also goes to the descendants.

Up and Down choose the signal, Space toggles “whole subtree”, Enter sends, Esc cancels. These are the rules:

The result appears for five seconds in the bottom line instead of the key bar: “SIGTERM sent to 1234 firefox”, “SIGTERM sent to 7 processes (subtree of …)”, “SIGKILL to 1234 x: permission denied (EPERM)”, or “…: 5 sent, 2 errors (first: …)”. If some targets have vanished the line adds “(N no longer exist)”.

7.3 · Nice

Keys F7 and F8 lower and raise the nice value of the selected process by one.

7.4 · Service actions

Starting and stopping a service is another action that cannot be undone by ngtop, so it has its own care.

What ngtop does not do: it never edits unit files, never masks, never runs a command through a shell. Its only two external programs, journalctl and systemd-analyze, are read-only and get a fixed list of arguments, with the unit name as a separate argument and never through a shell.

7.5 · GPUs that must not be woken

A discrete GPU in D3cold or runtime-suspended costs almost nothing; reading its files wakes it, which can take a second and a few watts. A monitor that does this every second keeps the card on forever. The rule is therefore strict.

7.6 · Terminal restore

A terminal program that leaves the terminal in raw mode on the alternate screen, with the cursor hidden and the mouse on, ruins the user's shell. ngtop gives the terminal back in every way it can end.

TerminalGuard is a value whose Drop calls restore_terminal(): it leaves the alternate screen, turns off the mouse, leaves raw mode and shows the cursor. Every step ignores errors and the function can be called several times, so the guard, the panic hook and the signal path can all run it. Everything that can fail is done before the terminal is touched: the first sample, the time zone, the configuration file.

Output to a closed pipe (for example ngtop --dump | head -1) is also safe: write_stdout() ignores write errors, so there is no panic for a broken pipe.

7.7 · Time zone without trust

To show the clock, ngtop must know the local time zone offset. The usual way is a C library function, which a static musl binary has in a poorer form, so src/ui/tz.rs does it in Rust. The data are untrusted — a file anyone may have written — so the parser is cautious.

Tests: nessun_panic_su_prefissi_e_file_troncati feeds the parser every prefix of a POSIX rule, and of a real zone file; tzif_inventato_e_rotto builds files with impossible counts; posix_semplici_e_non_validi tries malformed rules.

8.1 · Budget and measurements

A monitor that uses a lot of CPU gives the wrong picture of the machine it watches. ngtop's goal is to be invisible: about one percent of one core at the default 1-second refresh on a small machine, a few megabytes of memory, and a start that feels instant.

What the benchmark does. ngtop --bench (hidden option, bench() in src/main.rs) sets a 182 × 52 test terminal, shows each section in turn, runs three warm-up cycles and then thirty measured ones, each with its three parts timed separately: refresh (all collectors), update (histories, process list) and draw (a whole frame into a buffer). Terminal output is not included: ratatui sends only changed cells, and that is cheap by comparison.

$ ngtop --bench
1 Overview           refresh  7.42 + update 0.17 + draw 2.91 = 10.50 ms
2 GPU                refresh  6.93 + update 0.17 + draw 2.08 =  9.19 ms
3 Processes          refresh  6.66 + update 0.40 + draw 2.15 =  9.21 ms
4 Network & Disks    refresh  8.02 + update 0.28 + draw 2.26 = 10.56 ms
5 Services           refresh  6.67 + update 0.17 + draw 1.52 =  8.37 ms
(248 processes, 1 GPU(s))

8.2 · Caches and schedules

Two thirds or more of a cycle is refresh, and most of that is reading one small file per process. Drawing a frame is 2 to 3 ms. The design follows from this: read less, not faster.

Why staggered? If every pid were rechecked in the same cycle (say every 15th), that cycle would be much slower than the others and the display would stutter. Adding the pid to the cycle counter spreads the work evenly. The same trick is used for the GPU descriptors.

8.3 · The interface side

The interface side is kept cheap too.

Known costs, for whoever wants to go further. App::update() clones the process vector from System on every cycle and sorts it; the tree and the filter are rebuilt each time. With thousands of processes this would be the first thing to optimise. And the whole refresh runs in the interface thread: a very slow /proc (a machine under heavy load) delays the next frame by the same amount.

9.1 · Why static

ngtop is meant to be copied to a server, a container or an old workstation and run there. A normal Linux executable depends on the machine's C library, and the version it was built against must not be newer than the one it finds. A static executable carries everything it needs: it asks the kernel for services, and nothing else.

$ ldd dist/ngtop
	statically linked
$ bash build.sh
...
OK: dist/ngtop is static (3.5M)

9.2 · Dependencies: Rust only

The seven direct dependencies are all Rust. Each does one job.

The full tree for the musl target has about 150 crates (cargo tree --target x86_64-unknown-linux-musl). The ordinary way for a crate to compile C is the cc crate in a build script; cargo tree -e normal,build -i cc --target x86_64-unknown-linux-musl finds nothing, which is the proof that none does. The crate libc is in the tree, but it only declares function signatures; with musl, the functions come from the musl library that the toolchain links in. The licences of all these crates are listed by scripts/third-party.py.

9.3 · musl and build.sh

The default Linux toolchain links against glibc, and a program built that way cannot be copied to Alpine or to an old CentOS. For x86_64-unknown-linux-musl Rust ships its own musl and links statically by default, so no C compiler or musl package is needed on the build machine: only the target, added once with rustup target add x86_64-unknown-linux-musl.

The result is about 3.5 MB: opt-level = 3, lto = "fat", codegen-units = 1 and strip = true (no debugging symbols).

9.4 · What static takes away

Static linking with musl removes some conveniences a dynamic program takes for granted. ngtop works around each of them in its own code.

9.5 · Why not NVML

Of the three GPU makers, AMD and Intel publish their counters in the kernel, in sysfs and in each process's fdinfo. NVIDIA's proprietary driver does not; its numbers come from NVML, the NVIDIA management library, a closed-source shared library installed with the driver. A program uses it by loading it at run time. A static musl executable has no dynamic loader, so it cannot load a library built for glibc.

10.1 · Kinds of test

There are two kinds of test, and a few tools to look at the screen without a terminal. Nothing needs root, a GPU, systemd or a network: everything runs from fake trees and a fake services backend.

10.2 · Fixtures and two samples

A rate needs two samples, so the fixtures come in pairs: A and B, as if taken one second apart. A test loads A, refreshes with dt = 0, swaps the roots to B and refreshes with dt = 1.0. Then every number is exact and nothing depends on the real clock.

fn sistema() -> System {
    let mut s = System::new(roots("snap_a"));
    s.clock_ticks = 100;
    s.page_size = 4096;
    s.refresh_with_dt(0.0);      // first sample: rates are zero
    s.roots = roots("snap_b");
    s.refresh_with_dt(1.0);      // one second later
    s
}

Take the CPU. The cpu line of snapshot A is 1000 0 500 8000 500 0 0 0 0 0, of B 1100 0 550 8050 500 0 0 0 0 0. Totals: 10 000 and 10 200, so Δtotal = 200. Idle (idle + iowait): 8 500 and 8 550, so Δidle = 50. Usage = (200 − 50) × 100 ÷ 200 = 75 %, which is exactly what the test asserts. For a process, 80 ticks at 100 Hz in 1 s on 2 cores is 40 %.

10.3 · Seeing the screen: snapshot, dump, sweep

Drawing is tested in two ways: by looking at its text, and by trying to break it.

$ ngtop --snapshot 80x24 --section 2
$ ngtop --roots tests/fixtures/gpu/amd_a --snapshot 120x36 --section 2 --ansi

The sweep. tutte_le_misure_e_sezioni_senza_panic draws all five sections at every combination of widths 1, 5, 12, 40, 80, 99, 100, 101, 182 and heights 1, 3, 5, 12, 24, 29, 30, 31, 52, and converts each frame to ANSI. The values straddle the thresholds (99 and 100, 29 and 30) and include terminals so small nothing fits. The same is done in other files for narrower sets of sizes: the GPU and Overview views over six GPU fixtures (tasto_d_cambia_dispositivo_e_sweep), Network & Disks (rendering_a_ogni_misura), Services (rendering_a_quattro_misure_senza_panic) and every Processes tab (disegno_senza_panic_alle_misure_previste). molti_core_si_adattano builds machines with 1, 4, 24, 64 and 128 cores and checks that the frame has exactly the requested number of lines and that the last core is present — or, at 128 cores in a small window, that “not shown” is.

10.4 · Tests that guard the promises

Most of ngtop's safety is a promise about when something happens. These tests make the promise checkable.

10.5 · Distributions

scripts/test-distro.sh runs the finished binary dist/ngtop in containers, with rootless podman, on the images below. It needs only podman and the binary; the containers have no network (--network=none).

The script prints a table with OK or ERROR for each image and keeps a log per case in the folder given as first argument (default /tmp). Other images can be passed as further arguments.

10.6 · What to run

11.1 · Add a collector

This tutorial adds a small collector from start to finish: the number of file handles in use on the whole system, from /proc/sys/fs/file-nr. The pattern is the one of every collector in src/collect/.

1. Write the module src/collect/filenr.rs. A data struct; a parse_*() that takes text and never panics; a read_*() that takes a path and uses read_text(). Put the test in the same file. Start the file with the two licence lines used everywhere (ch. 12 “Conventions”).src/collect/filenr.rs

   //! Open file handles of the whole system, from /proc/sys/fs/file-nr.
   
   use std::path::Path;
   
   use super::read_text;
   
   #[derive(Debug, Clone, PartialEq, Eq, Default)]
   pub struct FileNr {
       /// Handles in use.
       pub used: u64,
       /// System-wide limit.
       pub max: u64,
   }
   
   /// "allocated  unused  max": in use = allocated - unused.
   pub fn parse_file_nr(text: &str) -> FileNr {
       let n: Vec<u64> = text
           .split_whitespace()
           .map(|x| x.parse().unwrap_or(0))
           .collect();
       let get = |i: usize| n.get(i).copied().unwrap_or(0);
       FileNr {
           used: get(0).saturating_sub(get(1)),
           max: get(2),
       }
   }
   
   pub fn read_file_nr(path: &Path) -> FileNr {
       read_text(path).map(|t| parse_file_nr(&t)).unwrap_or_default()
   }
   
   #[cfg(test)]
   mod tests {
       use super::*;
   
       #[test]
       fn file_nr() {
           let f = parse_file_nr("3456\t0\t9223372036854775807\n");
           assert_eq!((f.used, f.max), (3456, 9223372036854775807));
           assert_eq!(parse_file_nr(""), FileNr::default());
       }
   }

2. Connect it to System. Four lines in src/collect/mod.rs. Always build the path from self.roots, never write /proc in the collector.src/collect/mod.rs

   // src/collect/mod.rs
   pub mod filenr;                                  // 1. declare the module
   
   pub struct System {
       // ...
       pub files: filenr::FileNr,                   // 2. the field
   }
   
   // in System::new():
       files: filenr::FileNr::default(),            // 3. its initial value
   
   // in System::refresh_with_dt():
       self.files = filenr::read_file_nr(           // 4. read it, through the roots
           &self.roots.proc.join("sys/fs/file-nr"),
       );

3. Decide how often. One small file can be read every cycle. A costly one should be read every 5th cycle, like routes (refresh_count.is_multiple_of(5)), or only when a section is visible, like connections (a collect_* flag, set in event_loop(), snapshot() and bench()). See 8.2 “Caches and schedules”.
4. Add the file to the fixtures. Put proc/sys/fs/file-nr in tests/fixtures/snap_a/ and snap_b/, with different numbers if it is a rate, then a test in tests/collect.rs that asserts the value after the two samples (10.2 “Fixtures and two samples”).
5. Show it. The quickest place is dump() in src/main.rs: one more outln!. To show it on screen, see the next section.
6. Run cargo test, cargo clippy --all-targets -- -D warnings, cargo fmt, and ngtop --dump.

11.2 · Add a panel or a section

A new panel inside a section, or a new section, is only drawing. The data is already in System and App.

1. Draw with a Panel. Panel::new(title, colour).right(text).render(area, buf) returns the inner rectangle. Inside, write with put() and putn(), never with ratatui's own functions (5.2 “Safe writing and widths”). Use Meter for bars and BrailleGraph for histories; take the colour from a gradient in theme.rs.
2. Check the size first. Return at once if inner.width or inner.height is too small for your content, as the existing panels do (if inner.width < 20 || inner.height < 3 { return; }).
3. Place it in the layout of the section's draw() (a Layout::vertical or horizontal of the existing code). Decide what gives way on a small terminal; hide the panel rather than squeeze it.
4. If it needs history, add a History to App and push to it in App::update().
5. If it has keys, handle them in the section's on_key(), and add them to the key table in src/ui/keys.rs: the bottom bar, and the lines of the F1 help.
6. Test that the section still draws at every size: the sweep in tests/ui.rs covers all sections automatically.

A whole new section is the same work plus a list of places that know there are five of them. Search the source for Section::ALL, Section::Servizi and the text “1-5”:

11.3 · Where things go

A short guide to deciding where something belongs.

12.1 · Language, names and headers

The rules below are the ones the code already follows. Where a rule can be checked by a tool, the tool is named.

// Copyright (c) 2026 Nicola Fiorillo
// SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0

//! Memoria e swap da /proc/meminfo (valori in byte).

12.2 · Rules for robust code

A monitor runs for weeks beside everything else on a machine. It must not be the thing that crashes. These rules are applied everywhere in src/.

12.3 · Habits of the code base

Habits that keep the code uniform.

13.1 · The project's own words

Words ngtop uses as terms, in the code and in this manual, with the section that explains them. Several source files keep their Italian names; the first terms tell which is which.

Collector

A function or module that reads kernel files and computes numbers; it knows nothing about the screen (src/collect/). See 3.1 “Collect and draw”.

Roots

The three folders (proc, sys, etc) every collector reads from. Real on the machine, fake in tests. See 4.1 “How the collectors read”.

System

The structure that holds the latest data of the whole machine and the previous samples for rates (src/collect/mod.rs). See 3.2 “One refresh, step by step”.

App

The state of the interface: histories, selection, filter, dialog, state of each section (src/ui/app.rs). See 3.5 “State and drawing”.

Section

One of the five main screens, selected with 1 to 5: Overview, GPU, Processes, Network & Disks, Services. In the code, the modules and variants have Italian names: panoramica / Panoramica is the Overview, processi / Processi is Processes, retedischi / ReteDischi is Network & Disks, servizi / Servizi is Services; gpu is the same in both languages. See ch. 6 “The sections”.

Large layout, compact layout

The two forms of the Overview: compact under 100 columns or 30 rows. See 5.7 “Layout”.

Tick

One cycle of the event loop that refreshes the data and redraws; its length is the refresh interval (250 ms to 5 s). See 3.3 “The event loop”.

dt

The real time, in seconds, between two refreshes. A rate is a difference of counters divided by dt; it is zero for the first sample. See 3.2 “One refresh, step by step”.

Frame, buffer

One whole screen as a grid of cells (ratatui Buffer), drawn from scratch each time and sent to the terminal as the cells that changed. See 5.1 “ratatui and the frame”.

Widget

A small struct that draws one kind of element into a buffer (Panel, Meter…). See 5.3 “The widgets”.

Panel

A bordered rectangle with a title on its border; the unit of every section. See 5.3 “The widgets”.

Braille cell

One character U+2800 to U+28FF: a 2 × 4 grid of dots, used to draw graphs at eight times the cell resolution. See 5.4 “The braille graph”.

Gradient

A list of colour stops between which the program interpolates; every bar, graph and percentage takes its colour from one. See 5.5 “Theme and gradients”.

Truecolor, 256, 16

The three colour depths of a terminal; ngtop draws in truecolor and converts the frame at the end. See 5.6 “Colour depth”.

Alternate screen

A second terminal screen that a full-screen program draws on and then leaves, so the shell's text comes back intact. See 7.6 “Terminal restore”.

Raw mode

Terminal mode in which keys reach the program without being edited or echoed. See 7.6 “Terminal restore”.

Fixture

A fake /proc, /sys, /etc tree in tests/fixtures/ used by tests and by documentation screenshots. See 10.2 “Fixtures and two samples”.

Snapshot

One frame drawn on a test backend and printed as text or ANSI: ngtop --snapshot WxH. See 10.3 “Seeing the screen: snapshot, dump, sweep”.

Sweep

A test that draws every section at many sizes, including absurd ones, to prove there is no panic. See 10.3 “Seeing the screen: snapshot, dump, sweep”.

Backend (services)

The trait through which the Services section talks to systemd. The real one uses D-Bus; the fake one gives demo data. See 3.4 “Threads”, 4.10 “Services, sessions, boot”.

Worker thread

The thread that executes the slow requests of the Services section while the interface keeps running. See 3.4 “Threads”.

13.2 · Linux and system terms

Terms of the system that ngtop reads, and what they mean for it.

amdgpu, i915, xe

The Linux kernel drivers of AMD, Intel (older) and Intel (newer) graphics. They publish counters in sysfs and in fdinfo. See 4.8 “GPU: devices”.

cgroup

The kernel's grouping of processes with its accounting. systemd puts each service in one; ngtop reads memory and CPU of a service from its cgroup files. See 4.10 “Services, sessions, boot”.

Clock tick, hz

The unit of CPU times in /proc: usually 100 per second. See 4.2 “CPU, temperature”, 4.4 “Processes”.

D3cold

The deepest power state of a PCI device. A GPU in D3cold is not read. See 7.5 “GPUs that must not be woken”.

DRM client

One user of a GPU, with its own counters, identified on a card by its client id. A process can show it, and so can its children. See 4.9 “GPU: processes and the fdinfo files”.

D-Bus, polkit

The message bus of Linux and the service that decides if an action may be done, asking for a password if necessary. See 7.4 “Service actions”.

Engine

A part of a GPU that works on one kind of task: graphics, compute, copy, video decode or encode. See 4.9 “GPU: processes and the fdinfo files”.

fdinfo

The file /proc/[pid]/fdinfo/N, with the counters of a DRM client for one open GPU descriptor. See 4.9 “GPU: processes and the fdinfo files”.

hwmon, thermal zone

The kernel's sensor interfaces under /sys/class. ngtop reads temperatures, power and fans from them. See 4.2 “CPU, temperature”.

Inode (socket)

The number in /proc/net/tcp that identifies a socket; the same number appears in socket:[N] in a process's file descriptors. See 4.6 “Connections: inode to pid”.

IOPS, latency, queue

Operations per second, average time per operation, and requests in flight, of a disk. See 4.7 “Disks and filesystems”.

musl

A small C library that can be linked into an executable completely; with it ngtop is one static file. See 9.3 “musl and build.sh”.

NSS

The name service switch of the C library, which lets programs ask directories (LDAP, sssd) for user names. A static musl program has none. See 9.4 “What static takes away”.

NVML

NVIDIA's management library; shared and closed. The reason NVIDIA cards are only detected. See 9.5 “Why not NVML”.

pidfd

A file descriptor that refers to one process for ever, immune to reuse of the pid number. See 7.1 “Signals: pidfd and start time”.

Runtime PM

Power management that suspends a device when idle. A discrete GPU suspended this way is not woken. See 7.5 “GPUs that must not be woken”.

Start time (starttime)

The moment a process started, in clock ticks since boot; with the pid, the identity of a process. See 7.1 “Signals: pidfd and start time”.

statvfs

The call that gives the size and free space of a filesystem; on a stuck network mount it can block, so it runs in a thread. See 4.7 “Disks and filesystems”.

TZif

The binary format of time zone files in /usr/share/zoneinfo, read by ngtop's own parser. See 7.7 “Time zone without trust”.

zswap, ZRAM

Two ways of compressing memory instead of swapping it out to disk; the Overview shows the saving. See 4.3 “Memory, swap, load”.