cgroup v2-aware CPU & memory metering (tracking)

[Oblynx]

cgroup v2-aware CPU & memory metering

Tracking issue for this project. Project management + design docs live here. Upstream goal: land in htop-dev/htop (relates to upstream #1538 and #1020).

Problem

htop running inside a container (Kubernetes pod, Docker, LXC) misreports resources. The Memory and CPU meters source host-wide values from procfs — /proc/meminfo, /proc/stat, and host CPU topology under /sys/devices/system/cpu/ — which the kernel does not namespace per-container. So in a pod limited to e.g. 16 vCPU / 32 GB on a 224-thread / 2 TB host, htop shows the host's 224 threads and 2 TB as if available. The meters lie.

What htop does today (research findings)

• cgroup support is display/labeling only: CGROUP/CCGROUP/CONTAINER columns in linux/CGroupUtils.c pretty-print the cgroup path. No limit file is ever read.
• Meters source host procfs: LinuxMachine_scanMemoryInfo() (/proc/meminfo), LinuxMachine_scanCPUTime() (/proc/stat), LinuxMachine_updateCPUcount() (host /sys/devices/system/cpu/*/online).
• A Running_containerized flag exists but is currently used only for ZFS memory accounting in linux/Platform.c — not for the meters.
• Zero cgroup-limit awareness anywhere in metering.

Prior art

• Upstream Consider adding option to hide irrelevant CPU and RAM stats inside container htop-dev/htop#1538 (open, unassigned, no PR) requests exactly this — read v1 memory.limit_in_bytes/cpuset.cpus or v2 memory.max/cpuset.cpus.
• Upstream CPU list must use available (selected) core numbers htop-dev/htop#1020 (open) is the CPU/cpuset half.
• btop solved only cpuset-CPU highlighting (PR configure: restore hwloc support htop-dev/htop#1220, reads cpuset.cpus.effective); no memory-limit awareness.
• bottom is partway on CPU (Add foot terminal to terminalSupportsDefinedKeys htop-dev/htop#1754 open); memory scoping still requested.
• glances does per-container stats but its own host panels still show host totals when limited.
• LXCFS virtualizes /proc so unmodified tools read correct values — but it's host/runtime-provided and not default in Docker or stock k8s, so it doesn't cover the pod case. We should detect lxcfs-virtualized /proc and defer to it to avoid double-correction.

No tool in this class has shipped cgroup v2 memory-limit-aware metering. This work is non-duplicative.

Scope & plan

Memory + CPU, delivered as 2 separate PRs:

1. PR 1 — Memory (first, simpler). Resolve the process's own cgroup, read the effective memory limit (v1 memory.limit_in_bytes, v2 memory.max), use it as the Memory meter denominator with usage from memory.current. Walk ancestors and take the min for the effective limit. Fall back to host total when unlimited (max).
2. PR 2 — CPU. Handle both independent limits: quota/period (cpu.max → fractional effective vCPUs) and cpuset (cpuset.cpus.effective → which cores).

Goal: upstream

Target htop-dev/htop. Follow docs/styleguide.md, keep footprint small (htop is a system tool that runs under stress), acknowledge AI assistance via Co-authored-by: per CONTRIBUTING.

UX: automatic

The meters must show the effective limit without any user action when started in a limited environment. Auto-detect; no toggle required to get correct numbers.

Design footguns to handle

• cgroup v1 vs v2 both in the wild (modern k8s/distros are v2); support both.
• Nested cgroups: a leaf memory.max may be max while an ancestor (kubepods.slice) holds the real cap — walk ancestors, take the min.
• max = unlimited → fall back to host total, never divide by infinity.
• CPU = two independent limits (quota/period vs cpuset); a container may have either, both, or neither.
• Memory "used" should come from memory.current, not host /proc/meminfo. RAM-only vs RAM+swap (memory.swap.max) decision.
• LXCFS deference to avoid double-correction.

Code orientation

• linux/LinuxMachine.c — meter data sources; injection point for limit clamp.
• linux/Platform.c — Platform_setMemoryValues()/setCPUValues(); holds Running_containerized.
• linux/CGroupUtils.c — home for new helpers to resolve /proc/self/cgroup and parse limit files.
• MemoryMeter.c / CPUMeter.c — rendering.

---

Scoping research conducted with AI assistance (Claude).

[Oblynx]

Design Spec — PR 1: cgroup-aware Memory & Swap metering

Status: approved 2026-06-18. Scoping & design done with AI assistance (Claude).

Goal & UX

Make htop's Memory and Swap meters reflect the effective cgroup limit automatically when htop runs inside a limited environment (Kubernetes pod, Docker, LXC). No user action, no toggle. With no limit (or unreadable cgroup), behavior is identical to today — zero regression.

Display model (approved): in-place denominator swap + host total as context:

Mem[||||||||||  2.10G/4.00G  host:1.92T]

The Memory meter's total becomes the effective limit; the host total is appended as host:<N> so nothing is hidden (also the most transparent option for upstream review).

Scope

	Memory meter	Swap meter
cgroup v2	✅ memory.max / memory.current / memory.stat	✅ memory.swap.max / memory.swap.current
cgroup v1	✅ memory.limit_in_bytes / usage_in_bytes / memory.stat	❌ (v1 memsw combines RAM+swap; deliberately skipped)

Out of scope for PR 1: CPU (separate PR 2 — cpu.max quota/period + cpuset.cpus.effective + lxcfs deference), any new config option / column, opt-out toggle (pure auto; can add later if upstream asks).

Effective-limit computation (core logic)

1. Resolve own cgroup from /proc/self/cgroup:
   • v2: single line 0::<path>.
   • v1: controller line matching …:memory:<path> (swap is v2-only, so no memsw line is parsed).
2. Locate hierarchy / version: detect cgroup2 via statfs CGROUP2_SUPER_MAGIC (or /proc/mounts). v2 limit at /sys/fs/cgroup/<path>/memory.max; v1 at /sys/fs/cgroup/memory/<path>/memory.limit_in_bytes. Handle hybrid mounts (memory controller may sit on either hierarchy).
3. Walk ancestors → min: read the limit at every level from the leaf cgroup up to root; the effective limit is the minimum. Rationale: in k8s a leaf cgroup often reads max while an ancestor (kubepods.slice) imposes the real cap.
4. Unlimited sentinels: v2 literal max; v1 large PAGE_COUNTER_MAX (~0x7FFFFFFFFFFFF000). If every level is unlimited ⇒ no limit ⇒ fall back to host total.
5. "Limited?" decision: feature activates only when the effective limit < host MemTotal. Otherwise host totals, feature inert.

Bar contents (segments)

• total = effective limit.
• used = memory.current − file (v1: usage_in_bytes − cache).
• cache = memory.stat file (v1 total_cache); includes shmem.
• Documented behavior (approved): cgroups do not expose a separate buffers/shared breakdown the way /proc/meminfo does, so the bar collapses to two segments — used + cache. The host-total mode's buffers/shared segments are intentionally not reproduced in cgroup mode. This will be called out in code comments and the PR description so reviewers understand the segment count changes inside a limit.

Code placement (follows existing platform abstraction)

• linux/CGroupUtils.{c,h} — new helpers:
  • resolve /proc/self/cgroup → cgroup path + detected version,
  • generic "read a cgroup limit file, walk ancestors, return min",
  • parse memory.stat for the file field.
  • Kept as pure functions over file contents wherever possible, so they unit-test without a real cgroup.
• linux/LinuxMachine.{c,h} — new struct fields: cgroupMemLimit, cgroupMemCurrent, cgroupMemCache, and swap equivalents; populated alongside LinuxMachine_scanMemoryInfo().
• linux/Platform.c — Platform_setMemoryValues() (and swap path): when limited, set the meter total + value segments from the cgroup fields and stash host total for the host: suffix. Reuse existing Running_containerized plumbing.
• MemoryMeter.c / SwapMeter.c — render the host:<N> context suffix; otherwise unchanged.

Refresh cadence & footprint

• Resolve cgroup path + version once at startup (cache it).
• Re-read the 2–3 small limit/usage/stat files every refresh, so live resize (k8s in-place vertical pod scaling) is reflected.
• Cost is negligible vs. the procfs scans htop already does each tick — respects htop's "small footprint, performs under stress" mandate.

Edge cases & fallback

• No cgroup / root cgroup / all-unlimited / read failure (permissions, missing files) / limit ≥ host MemTotal → silently fall back to host totals. Never crash, never overflow the bar.
• LXCFS: if /proc/meminfo is already lxcfs-virtualized, MemTotal already equals the limit and our cgroup value matches — consistent, no double-correction. (Explicit lxcfs deference logic is reserved for the CPU PR, where it matters.)

Testing

• Unit: factor parsing + ancestor-min as pure functions; test with synthetic fixtures — fake /sys/fs/cgroup trees, max sentinels, nested-limit (leaf max + ancestor cap), v1 vs v2 layouts. Fits htop's existing test setup (test_spec.lua / TESTPLAN).
• Manual: docker run --memory=4g on a large host, on both a cgroup v2 host and a v1 host; verify 4.00G host:<hostTotal> and correct used/cache split; verify swap meter on v2.

Upstream / process

• Target: land in htop-dev/htop (relates to upstream Consider adding option to hide irrelevant CPU and RAM stats inside container htop-dev/htop#1538, CPU list must use available (selected) core numbers htop-dev/htop#1020). 2 PRs, memory first.
• Follow docs/styleguide.md (3-space indent, Module_function naming, header-guard-before-copyright, include ordering, xMalloc/String_eq helpers).
• Commit trailers: Assisted-by:/Co-authored-by: for AI disclosure and Signed-off-by: (DCO). Per repo policy, the agent must not add Signed-off-by: on the contributor's behalf without explicit confirmation — to be obtained at PR time.

Decisions log

1. Display: in-place denominator swap + host: context. (rejected: separate meter — not auto; denominator-only — bar still lies.)
2. Used semantics: from cgroup memory.current + memory.stat. (rejected: keep host meminfo segments — misleading.)
3. cgroup versions: memory v1+v2; swap v2 only. (v1 memsw skipped for complexity.)
4. Segments: used + cache only; buffers/shared collapse — documented.
5. No opt-out toggle in PR 1 (pure auto); add later if upstream requests.

[Oblynx]

Design Spec v2 (converged) — cgroup-aware Memory & Swap metering

Supersedes the first spec above. Revised after two rounds of adversarial review (namespace reality, kernel semantics, htop source, and upstream-maintainer signals). Scoping & design done with AI assistance (Claude).

What changed from v1 (and why)

• Min-walk dropped. Inside a cgroup namespace (default for k8s pods / Docker ≥20.10), /proc/self/cgroup is 0::/ and cgroupfs is rooted at the namespace boundary — ancestors are not visible (cgroup_namespaces(7)). Walking to kubepods.slice cannot execute there. We read the limit at our own cgroup node via the actual mount and trust the kernel's enforcement.
• v2-first. v1 semantics are messy (usage_in_bytes is a documented "fuzz value") and upstream is trimming legacy (PR Remove obsolete OpenVZ and VServer support htop-dev/htop#2010). v1 systems fall back cleanly to host totals; v1 support is a possible later PR.
• UX = auto in-place, visually unambiguous, default-ON setting. Preserves "no user action" while giving maintainers the opt-out they've signalled they want (Linux/PSI: Add cgroup variants for PSI meters htop-dev/htop#1191: "I don't love it" / "better suited for a dedicated screen/tab" — natoscott, BenBE).
• Host-total context deferred. It can't render in bar mode (BarMeterMode_draw: 3-char caption + right-aligned overlay truncates it) and would force cgroup logic into platform-neutral shared files. Revisit later if maintainers want it.
• New file linux/CGroupMem.c — linux/CGroupUtils.c already exists and is the CCGROUP/CONTAINER label sanitizer; we do not conflate limit-accounting into it.

Goal & UX

When htop runs under a cgroup v2 memory limit, the Memory (and Swap) meter automatically shows usage against that limit — no user action. The meter is made visually unambiguous that it reflects a cgroup limit (caption marker). A setting cgroup-aware meters (default ON) lets users disable it → host totals. No limit / v1 / unreadable / setting off → identical to today (zero regression).

Scope

• Memory meter: cgroup v2 (memory.max, memory.current, memory.stat).
• Swap meter: cgroup v2 (memory.swap.max, memory.swap.current).
• Out of scope: v1 (clean host fallback), host-total context display, CPU (PR 2: cpu.max + cpuset.cpus.effective + lxcfs deference), any new column.

Resolution & limit reading (read our own node)

1. Discover the v2 mount by parsing /proc/self/mountinfo for a cgroup2 filesystem; record its mount point and mount root. Detect pure-v2 vs v1/hybrid (no v2 mount with the memory controller → inactive, host fallback).
2. Locate our node. Prefer reusing the cgroup path htop already collects per refresh (look up htop's own PID in the process table) per maintainer guidance (Linux/PSI: Add cgroup variants for PSI meters htop-dev/htop#1191); fall back to reading /proc/self/cgroup (0::<path>) once at startup. Join with the mount to get our node directory.
3. Read at our node only (no ancestor walk): memory.max, memory.current, memory.stat.
4. Unlimited sentinel: memory.max literal max → unlimited → host fallback.
5. Known limitation (documented): a BestEffort pod whose only cap is an invisible ancestor reads max at its own node → feature does not activate, shows host total. This is inherent to namespace isolation, not a bug.

Activation predicate

Activate cgroup mode for the Memory meter iff: setting is ON and a finite memory.max is readable at our node and memory.max < host MemTotal. Otherwise host totals. Running_containerized (already maintained in linux/Platform.c) is used as a gating hint; we extend it rather than inventing a parallel detection path (aligns with the in-flight detection rework, htop-dev#1223).

Bar contents (value decomposition, v2)

Map cgroup figures onto htop's fixed 6-class memory model (Platform_memoryClasses[]); set unused classes to NAN:

• total = memory.max (effective limit).
• file = memory.stat file (page cache; includes shmem in cgroup accounting).
• MEMORY_CLASS_USED = memory.current − file. Documented: this residual includes anon and kernel/slab/sock memory — all genuinely charged against the limit — so it is intentionally not identical to host-mode "used" (which derives from /proc/meminfo). Called out in code comments + PR description.
• MEMORY_CLASS_CACHE = file.
• MEMORY_CLASS_AVAILABLE = memory.max − memory.current.
• SHARED, COMPRESSED, BUFFERS = NAN (no clean cgroup analog; the bar shows two filled segments — used + cache).
• Coexistence: in cgroup mode, short-circuit the existing zswap and ZFS adjustments in Platform_setMemoryValues (ZFS is already gated on !Running_containerized); ensure no double-counting.

Swap (v2)

• memory.swap.max = max → host swap behavior (no cgroup treatment).
• memory.swap.max = 0 → swap disabled; guard divide-by-zero, render empty/zero swap, no 100%-bar artifact.
• otherwise total = memory.swap.max, used = memory.swap.current.
• v1 → host swap, no cgroup treatment (documented; v1 memsw combines RAM+swap and is deliberately skipped).

Code placement (strict cross-platform discipline)

• linux/CGroupMem.{c,h} (new) — pure functions over file contents: mountinfo discovery, node-path resolution, parse memory.max/current/stat/swap.*, sentinel & failure handling. No globals, no UI — unit-testable without a real cgroup.
• linux/LinuxMachine.{c,h} — new fields (cgroupMemMax, cgroupMemCurrent, cgroupMemFile, cgroupSwapMax, cgroupSwapCurrent, activation flags); populated alongside LinuxMachine_scanMemoryInfo().
• linux/Platform.c — Platform_setMemoryValues() / swap path: when active, set this->total + class values from the Linux fields and NaN the rest; short-circuit zswap/ZFS. All cgroup logic stays here.
• Shared files (MemoryMeter.c/SwapMeter.c/Meter.c): no cgroup-specific branches. Visual unambiguity uses a generic, platform-supplied caption/annotation seam (Linux sets a short marker, e.g. caption Mem → cgroup-marked); shared code only gains the generic ability to render a platform-supplied caption override, with no cgroup awareness. This one small generic seam is the most likely upstream negotiation point and is isolated to PR 1b.

Refresh cadence & footprint

• Resolve mount + node path once at startup (cache); prefer the already-collected per-PID cgroup string for resolution.
• Per refresh: read memory.current + memory.max (+ memory.stat only when the cache segment is displayed). Bounded, trivial vs. the per-refresh procfs process scan; catches live in-place pod resize (memory.max changes value, path stable).
• Tolerate ENOENT/read failure (cgroup teardown) → fall back to host totals, never error.

Edge cases & fallback

No v2 mount / unlimited / read failure / limit ≥ MemTotal / setting off → host totals; never crash, never overflow the bar. LXCFS: if /proc/meminfo is already lxcfs-virtualized, MemTotal already equals the limit, so the predicate (limit < MemTotal) is false and we don't double-correct — consistent. (Explicit lxcfs deference is a CPU-PR concern.) memory.high (throttle) intentionally ignored for the limit; a future "you're being throttled" indicator could use memory.high + memory.events.

Testing

• Unit: pure parse + resolution functions against synthetic fixtures — v2 trees, max sentinel, swap.max=0, malformed/short reads, missing files, namespaced 0::/. Fits htop's existing test setup.
• Manual: docker run --memory=4g on a large v2 host → meter shows …/4.00G, labeled cgroup, correct used/cache; toggle setting off → host totals; v1 host → host totals (no regression).

PR shaping — single PR, three reviewable commits

This ships as one PR (memory + swap, cgroup v2). To keep it easy to review, it is structured as three logically-separable commits the reviewer reads in order:

1. Commit 1 — pure cgroup helpers + unit tests (linux/CGroupMem.c). Zero UI/behavior change; the load-bearing logic is isolated and fully covered by fixture tests.
2. Commit 2 — wire into Memory meter (v2): LinuxMachine fields + Platform_setMemoryValues, activation, caption marker + the generic caption seam, the cgroup-aware meters setting. Linux + Platform only.
3. Commit 3 — Swap (v2): isolates the swap.max=0 guard.

The commit boundaries mirror the earlier 1a/1b/1c split, so each concern is still reviewable on its own inside the one PR. The generic caption seam (commit 2) remains the single shared-rendering touch and the likeliest upstream negotiation point.

Upstream prep

• Target htop-dev/htop; reference Consider adding option to hide irrelevant CPU and RAM stats inside container htop-dev/htop#1538, CPU list must use available (selected) core numbers htop-dev/htop#1020, Linux/PSI: Add cgroup variants for PSI meters htop-dev/htop#1191, Having overlayfs mounted may not be a good indication of running in a container htop-dev/htop#1223. Pre-empt the "silent repurposing" objection via the caption marker + default-ON toggle; reuse Running_containerized; justify bounded per-tick cost.
• Commit trailers: Assisted-by:/Co-authored-by: for AI disclosure and Signed-off-by: (DCO). Per repo policy the agent must not sign off on the contributor's behalf without explicit confirmation — to be obtained before the first commit.
• Follow docs/styleguide.md (3-space indent, Module_function, header-guard-before-copyright, include ordering, xMalloc/String_eq).

Decisions log

1. Read own cgroup node; min-walk dropped (namespace hides ancestors). BestEffort ancestor-only cap → documented host fallback.
2. v2-first; v1 = clean fallback now, optional later PR.
3. UX = auto in-place + caption marker + default-ON cgroup-aware meters setting.
4. Host-total context deferred (renderer + cross-platform constraints).
5. Decomposition: USED = current − file (incl kernel), CACHE = file, AVAILABLE = max − current, rest NaN — documented as differing from host mode.
6. New file linux/CGroupMem.c; no logic in existing CGroupUtils.c; no cgroup branches in shared meter files.
7. Swap v2 only; swap.max=0 divide-by-zero guard.
8. Single PR (memory + swap, v2), organized as three reviewable commits (helpers / memory / swap).

[Oblynx]

cgroup v2-aware Memory & Swap Metering — Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make htop's Memory and Swap meters automatically show usage against the cgroup v2 limit when htop runs inside a limited container, falling back to host totals otherwise.

Architecture: A new, libc-only Linux helper module (linux/CGroupMem.c) discovers the cgroup v2 mount + our own cgroup node and reads memory.max/memory.current/memory.stat/memory.swap.*. LinuxMachine caches the result each refresh; linux/Platform.c (the Linux implementation of Platform_setMemoryValues/Platform_setSwapValues) overrides the meter total + segment values when a limit is active and marks the meter caption. A new default-ON cgroupAwareMeters setting gates the behavior. No cgroup logic enters platform-neutral files.

Tech Stack: C99, GNU autotools (automake/autoconf), htop's OO-C meter framework.

Global Constraints

• cgroup v2 only. v1 systems detect-and-do-nothing → host totals (no regression). No v1 paths.
• No edits to platform-neutral files for cgroup logic. Allowed shared-file edits are limited to: the generic Settings bool (Settings.h/Settings.c) and its DisplayOptionsPanel.c checkbox. The caption marker is applied from linux/Platform.c via the existing public Meter_setCaption() — no edit to MemoryMeter.c/SwapMeter.c/Meter.c.
• linux/CGroupMem.{c,h} are libc-only (<stdio.h>, <string.h>, <stdlib.h>, <stdbool.h>, <stddef.h>, <limits.h> only). No config.h, no XUtils.h, no Compat.h. Internal byte/kB values use unsigned long long. This keeps the unit-test binary self-contained.
• Units: htop's memory_t values are in kB (/proc/meminfo is parsed as kB). cgroup files are in bytes. All CGroupMem outputs are converted to kB via integer division by 1024.
• Style (docs/styleguide.md): 3-space indent, never tabs; Module_functionName() naming; header guard #ifndef HEADER_CGroupMem before the copyright comment; includes ordered (system, then program), each group sorted, subdir paths after parent. Braces omitted around single simple statements; if any branch in an if/else chain needs braces, all do.
• Commits: every commit signed with git commit -s only after the human confirms (DCO sign-off must not be added on the contributor's behalf without confirmation — see Task 0). Each commit message includes an AI-disclosure trailer: Assisted-by: Claude <noreply@anthropic.com>.
• Single PR organized as three commit groups: Commit 1 = Tasks 1–7 (helpers + tests), Commit 2 = Tasks 8–10 (memory wiring), Commit 3 = Task 11 (swap).

---

File Structure

• Create linux/CGroupMem.h — public types + function decls (libc-only).
• Create linux/CGroupMem.c — pure parsers + file-reading orchestration + cached discovery.
• Create linux/CGroupMemTest.c — standalone assert-based unit test (no framework).
• Modify Makefile.am — add linux/CGroupMem.h, linux/CGroupMem.c, and a check_PROGRAMS test target.
• Modify linux/LinuxMachine.h — add a CGroupMemData cgroupMem; field.
• Modify linux/LinuxMachine.c — call CGroupMem_scan() at the end of LinuxMachine_scanMemoryInfo().
• Modify linux/Platform.c — cgroup branch in Platform_setMemoryValues() and Platform_setSwapValues() + caption marker.
• Modify Settings.h / Settings.c / DisplayOptionsPanel.c — the cgroupAwareMeters setting (default ON).

---

Task 0: Confirm sign-off + branch setup

• Step 1: Ask the human to confirm DCO sign-off. htop requires Signed-off-by: certifying the Developer Certificate of Origin. Per repo policy an agent must not add it on the contributor's behalf without confirmation. Ask: "Confirm I may add Signed-off-by: <your name> <your email> to commits on your behalf, and give the exact name/email." Record the answer; use it in every git commit -s below. If declined, commit without -s and the human signs off before pushing.

• Step 2: Create the feature branch

cd /home/container_user/.claude_host/jobs/bf6a4abe/tmp/work/htop
git checkout -b feat/cgroup-v2-memory main

• Step 3: Verify a clean baseline build

Run:

./autogen.sh && ./configure && make -j"$(nproc)"

Expected: builds an htop binary with no errors.

---

Task 1: CGroupMem module skeleton + first parser (CGroupMem_parseLimit) + test harness

Files:

• Create: linux/CGroupMem.h
• Create: linux/CGroupMem.c
• Create: linux/CGroupMemTest.c
• Modify: Makefile.am (header list ~line 191; sources list ~line 218; new check_PROGRAMS block)

Interfaces:

• Produces: typedef struct CGroupMemData_ { bool active; bool swapActive; unsigned long long limit, current, file, swapLimit, swapCurrent; } CGroupMemData; (all sizes in kB).

• Produces: bool CGroupMem_parseLimit(const char* content, unsigned long long* outKB); — returns false for "max"/empty/invalid (limit unlimited or unreadable), true with *outKB set otherwise.

• Step 1: Write linux/CGroupMem.h

#ifndef HEADER_CGroupMem
#define HEADER_CGroupMem
/*
htop - CGroupMem.h
(C) 2026 htop dev team
Released under the GNU GPLv2+, see the COPYING file
in the source distribution for its full text.
*/

#include <stdbool.h>
#include <stddef.h>


/* All byte counts are stored in kB (bytes / 1024) to match htop's memory_t convention. */
typedef struct CGroupMemData_ {
   bool active;               /* a finite memory.max < host total was found */
   bool swapActive;           /* a finite memory.swap.max was found */
   unsigned long long limit;        /* memory.max, kB */
   unsigned long long current;      /* memory.current, kB */
   unsigned long long file;         /* memory.stat 'file', kB */
   unsigned long long swapLimit;    /* memory.swap.max, kB (may be 0 = swap disabled) */
   unsigned long long swapCurrent;  /* memory.swap.current, kB */
} CGroupMemData;

/* Pure parsers (testable with string inputs). */

/* Parse a cgroup limit file body ("max\n" or "<bytes>\n"). Returns false for
   "max"/empty/invalid (unlimited or unreadable); true with *outKB set otherwise. */
bool CGroupMem_parseLimit(const char* content, unsigned long long* outKB);

/* Parse a cgroup usage file body ("<bytes>\n"). false if not a number. */
bool CGroupMem_parseUsage(const char* content, unsigned long long* outKB);

/* Parse memory.stat body for `key` (e.g. "file"); value is bytes → kB. false if key absent. */
bool CGroupMem_parseStat(const char* content, const char* key, unsigned long long* outKB);

/* Parse /proc/self/cgroup body; copy the v2 ("0::") path into pathBuf. false if no 0:: line. */
bool CGroupMem_parseSelfCgroup(const char* content, char* pathBuf, size_t bufSize);

/* Parse /proc/self/mountinfo body; copy the cgroup2 mount point into mountBuf. false if none. */
bool CGroupMem_parseMountinfo(const char* content, char* mountBuf, size_t mountSize);

/* Read the cgroup files under nodeDir and fill `data`. hostTotalMemKB gates activation
   (active only when a finite limit < host total). Tolerant of missing files. */
void CGroupMem_readNode(const char* nodeDir, unsigned long long hostTotalMemKB, CGroupMemData* data);

/* Resolve (and cache) our cgroup v2 node, then read it. Fills data->active = false on any failure. */
void CGroupMem_scan(unsigned long long hostTotalMemKB, CGroupMemData* data);

#endif /* HEADER_CGroupMem */

• Step 2: Write linux/CGroupMem.c with only CGroupMem_parseLimit implemented (other functions added in later tasks)

/*
htop - CGroupMem.c
(C) 2026 htop dev team
Released under the GNU GPLv2+, see the COPYING file
in the source distribution for its full text.
*/

#include "linux/CGroupMem.h"

#include <limits.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>


bool CGroupMem_parseLimit(const char* content, unsigned long long* outKB) {
   if (!content)
      return false;

   while (*content == ' ' || *content == '\t')
      content++;

   if (strncmp(content, "max", 3) == 0)
      return false;

   char* end;
   unsigned long long bytes = strtoull(content, &end, 10);
   if (end == content)
      return false;

   *outKB = bytes / 1024;
   return true;
}

• Step 3: Write linux/CGroupMemTest.c harness with the first test

/*
htop - CGroupMemTest.c
(C) 2026 htop dev team
Released under the GNU GPLv2+, see the COPYING file
in the source distribution for its full text.
*/

#include "linux/CGroupMem.h"

#include <stdio.h>


static int checks = 0;
static int failures = 0;

#define CHECK(cond)                                                          \
   do {                                                                      \
      checks++;                                                              \
      if (!(cond)) {                                                         \
         failures++;                                                         \
         fprintf(stderr, "FAIL %s:%d: %s\n", __FILE__, __LINE__, #cond);     \
      }                                                                      \
   } while (0)


static void test_parseLimit(void) {
   unsigned long long kb = 999;
   CHECK(CGroupMem_parseLimit("max\n", &kb) == false);
   CHECK(CGroupMem_parseLimit("", &kb) == false);
   CHECK(CGroupMem_parseLimit("4294967296\n", &kb) == true);
   CHECK(kb == 4194304ULL); /* 4 GiB / 1024 */
}

int main(void) {
   test_parseLimit();

   if (failures) {
      fprintf(stderr, "%d/%d checks FAILED\n", failures, checks);
      return 1;
   }
   printf("All %d checks passed\n", checks);
   return 0;
}

• Step 4: Wire into Makefile.am

Add linux/CGroupMem.h to the headers list, immediately before linux/CGroupUtils.h (line 191), so:

	linux/CGroupMem.h \
	linux/CGroupUtils.h \

Add linux/CGroupMem.c to linux_platform_sources, immediately before linux/CGroupUtils.c (line ~218), so:

	linux/CGroupMem.c \
	linux/CGroupUtils.c \

Add a test target near the end of Makefile.am (after the existing cppcheck: rule, ~line 528). Per-target _CPPFLAGS forces a renamed object so CGroupMem.o does not collide with the htop build:

check_PROGRAMS = linux/CGroupMemTest
TESTS = $(check_PROGRAMS)
linux_CGroupMemTest_SOURCES = linux/CGroupMemTest.c linux/CGroupMem.c linux/CGroupMem.h
linux_CGroupMemTest_CPPFLAGS = $(AM_CPPFLAGS)

• Step 5: Regenerate the build and run the test — expect PASS

Run:

./autogen.sh && ./configure && make check

Expected: linux/CGroupMemTest builds and prints All 4 checks passed; make check reports the test as PASS.

• Step 6: Commit

git add linux/CGroupMem.h linux/CGroupMem.c linux/CGroupMemTest.c Makefile.am
git commit -s -m "linux: add CGroupMem helper skeleton + parseLimit with unit test

Assisted-by: Claude <noreply@anthropic.com>"

(omit -s if the human declined in Task 0)

---

Task 2: CGroupMem_parseUsage

Files:

• Modify: linux/CGroupMem.c
• Modify: linux/CGroupMemTest.c

Interfaces:

• Produces: bool CGroupMem_parseUsage(const char* content, unsigned long long* outKB); — true with kB for a numeric body, false otherwise. (Unlike parseLimit, there is no "max" case.)

• Step 1: Add the failing test to CGroupMemTest.c

Add this function and call it from main() before the if (failures) block:

static void test_parseUsage(void) {
   unsigned long long kb = 0;
   CHECK(CGroupMem_parseUsage("2202009600\n", &kb) == true);
   CHECK(kb == 2150400ULL); /* 2202009600 / 1024 */
   CHECK(CGroupMem_parseUsage("garbage\n", &kb) == false);
}

Add test_parseUsage(); after test_parseLimit(); in main().

• Step 2: Run the test to verify it fails

Run: make check
Expected: FAIL — link error "undefined reference to CGroupMem_parseUsage".

• Step 3: Implement CGroupMem_parseUsage in CGroupMem.c

bool CGroupMem_parseUsage(const char* content, unsigned long long* outKB) {
   if (!content)
      return false;

   char* end;
   unsigned long long bytes = strtoull(content, &end, 10);
   if (end == content)
      return false;

   *outKB = bytes / 1024;
   return true;
}

• Step 4: Run the test — expect PASS

Run: make check
Expected: All 7 checks passed.

• Step 5: Commit

git add linux/CGroupMem.c linux/CGroupMemTest.c
git commit -s -m "linux: add CGroupMem_parseUsage

Assisted-by: Claude <noreply@anthropic.com>"

---

Task 3: CGroupMem_parseStat

Files:

• Modify: linux/CGroupMem.c
• Modify: linux/CGroupMemTest.c

Interfaces:

• Produces: bool CGroupMem_parseStat(const char* content, const char* key, unsigned long long* outKB); — scans newline-separated "<key> <bytes>" lines; matches key exactly (whole first token); converts bytes→kB.

• Step 1: Add the failing test

static void test_parseStat(void) {
   const char* stat =
      "anon 1048576\n"
      "file 524288000\n"
      "kernel_stack 16384\n"
      "file_mapped 100\n";
   unsigned long long kb = 0;
   CHECK(CGroupMem_parseStat(stat, "file", &kb) == true);
   CHECK(kb == 512000ULL); /* 524288000 / 1024 */
   CHECK(CGroupMem_parseStat(stat, "anon", &kb) == true);
   CHECK(kb == 1024ULL);
   /* must not match the "file_mapped" prefix when asked for "file" — exact token only */
   CHECK(CGroupMem_parseStat(stat, "slab", &kb) == false);
}

Add test_parseStat(); to main().

• Step 2: Run — expect FAIL (undefined reference to CGroupMem_parseStat)

Run: make check

• Step 3: Implement CGroupMem_parseStat

bool CGroupMem_parseStat(const char* content, const char* key, unsigned long long* outKB) {
   if (!content || !key)
      return false;

   size_t keyLen = strlen(key);
   const char* p = content;
   while (*p) {
      const char* eol = strchr(p, '\n');
      size_t lineLen = eol ? (size_t)(eol - p) : strlen(p);

      /* match "key " at the start of the line (exact token, space-delimited) */
      if (lineLen > keyLen && strncmp(p, key, keyLen) == 0 && p[keyLen] == ' ') {
         char* end;
         unsigned long long bytes = strtoull(p + keyLen + 1, &end, 10);
         if (end != p + keyLen + 1) {
            *outKB = bytes / 1024;
            return true;
         }
      }

      if (!eol)
         break;
      p = eol + 1;
   }
   return false;
}

• Step 4: Run — expect PASS (All 11 checks passed)

Run: make check

• Step 5: Commit

git add linux/CGroupMem.c linux/CGroupMemTest.c
git commit -s -m "linux: add CGroupMem_parseStat

Assisted-by: Claude <noreply@anthropic.com>"

---

Task 4: CGroupMem_parseSelfCgroup

Files:

• Modify: linux/CGroupMem.c
• Modify: linux/CGroupMemTest.c

Interfaces:

• Produces: bool CGroupMem_parseSelfCgroup(const char* content, char* pathBuf, size_t bufSize); — finds the 0::<path> line (v2), copies <path> (newline stripped) into pathBuf. false if no 0:: line (pure-v1 system).

• Step 1: Add the failing test

static void test_parseSelfCgroup(void) {
   char buf[256];
   /* namespaced container: path is the namespace root */
   CHECK(CGroupMem_parseSelfCgroup("0::/\n", buf, sizeof(buf)) == true);
   CHECK(buf[0] == '/' && buf[1] == '\0');
   /* hybrid: v1 controller lines then a v2 line */
   CHECK(CGroupMem_parseSelfCgroup("4:memory:/foo\n0::/bar/baz\n", buf, sizeof(buf)) == true);
   CHECK(CGroupMem_parseSelfCgroup("0::/bar/baz\n", buf, sizeof(buf)) == true);
   /* compare the second result */
   CHECK(buf[0] == '/' && buf[1] == 'b' && buf[2] == 'a' && buf[3] == 'r');
   /* pure v1: no 0:: line */
   CHECK(CGroupMem_parseSelfCgroup("4:memory:/foo\n", buf, sizeof(buf)) == false);
}

Add test_parseSelfCgroup(); to main().

• Step 2: Run — expect FAIL

Run: make check

• Step 3: Implement CGroupMem_parseSelfCgroup

bool CGroupMem_parseSelfCgroup(const char* content, char* pathBuf, size_t bufSize) {
   if (!content || bufSize == 0)
      return false;

   const char* p = content;
   while (*p) {
      const char* eol = strchr(p, '\n');
      size_t lineLen = eol ? (size_t)(eol - p) : strlen(p);

      if (lineLen >= 3 && strncmp(p, "0::", 3) == 0) {
         const char* path = p + 3;
         size_t pathLen = lineLen - 3;
         if (pathLen >= bufSize)
            pathLen = bufSize - 1;
         memcpy(pathBuf, path, pathLen);
         pathBuf[pathLen] = '\0';
         return true;
      }

      if (!eol)
         break;
      p = eol + 1;
   }
   return false;
}

• Step 4: Run — expect PASS (All 17 checks passed)

Run: make check

• Step 5: Commit

git add linux/CGroupMem.c linux/CGroupMemTest.c
git commit -s -m "linux: add CGroupMem_parseSelfCgroup

Assisted-by: Claude <noreply@anthropic.com>"

---

Task 5: CGroupMem_parseMountinfo

Files:

• Modify: linux/CGroupMem.c
• Modify: linux/CGroupMemTest.c

Interfaces:

• Produces: bool CGroupMem_parseMountinfo(const char* content, char* mountBuf, size_t mountSize); — finds the line whose post-" - " filesystem type is cgroup2, copies the mount point (pre-separator field index 4, 0-based) into mountBuf. false if no cgroup2 mount.

• Step 1: Add the failing test

static void test_parseMountinfo(void) {
   char buf[256];
   const char* mi =
      "23 28 0:22 / /proc rw,nosuid - proc proc rw\n"
      "29 23 0:25 / /sys/fs/cgroup ro,nosuid,nodev,noexec - cgroup2 cgroup2 rw,nsdelegate\n";
   CHECK(CGroupMem_parseMountinfo(mi, buf, sizeof(buf)) == true);
   CHECK(strcmp(buf, "/sys/fs/cgroup") == 0);
   /* no cgroup2 mount → false */
   const char* none = "23 28 0:22 / /proc rw - proc proc rw\n";
   CHECK(CGroupMem_parseMountinfo(none, buf, sizeof(buf)) == false);
}

Add test_parseMountinfo(); to main(). (Requires #include <string.h> in the test for strcmp — add it under the existing #include <stdio.h>.)

• Step 2: Run — expect FAIL

Run: make check

• Step 3: Implement CGroupMem_parseMountinfo

bool CGroupMem_parseMountinfo(const char* content, char* mountBuf, size_t mountSize) {
   if (!content || mountSize == 0)
      return false;

   const char* p = content;
   while (*p) {
      const char* eol = strchr(p, '\n');
      size_t lineLen = eol ? (size_t)(eol - p) : strlen(p);

      /* the filesystem type is the first token after the " - " separator */
      const char* sep = strstr(p, " - ");
      if (sep && (!eol || sep < eol)) {
         const char* fstype = sep + 3;
         if (strncmp(fstype, "cgroup2 ", 8) == 0 || strncmp(fstype, "cgroup2\t", 8) == 0) {
            /* mount point is the 5th space-separated field (index 4) of the pre-separator part */
            const char* q = p;
            int field = 0;
            while (field < 4 && q < sep) {
               q = strchr(q, ' ');
               if (!q || q >= sep)
                  break;
               q++;
               field++;
            }
            if (field == 4 && q < sep) {
               const char* mpEnd = strchr(q, ' ');
               if (mpEnd && mpEnd <= sep) {
                  size_t mpLen = (size_t)(mpEnd - q);
                  if (mpLen >= mountSize)
                     mpLen = mountSize - 1;
                  memcpy(mountBuf, q, mpLen);
                  mountBuf[mpLen] = '\0';
                  return true;
               }
            }
         }
      }

      if (!eol)
         break;
      p = eol + 1;
   }
   return false;
}

• Step 4: Run — expect PASS (All 20 checks passed)

Run: make check

• Step 5: Commit

git add linux/CGroupMem.c linux/CGroupMemTest.c
git commit -s -m "linux: add CGroupMem_parseMountinfo

Assisted-by: Claude <noreply@anthropic.com>"

---

Task 6: CGroupMem_readNode (reads files from a node directory)

Files:

• Modify: linux/CGroupMem.c
• Modify: linux/CGroupMemTest.c

Interfaces:

• Consumes: CGroupMem_parseLimit, CGroupMem_parseUsage, CGroupMem_parseStat.

• Produces: void CGroupMem_readNode(const char* nodeDir, unsigned long long hostTotalMemKB, CGroupMemData* data); — reads nodeDir/memory.max, memory.current, memory.stat, memory.swap.max, memory.swap.current. Sets active = (finite limit AND limit < hostTotalMemKB); swapActive = (memory.swap.max present and not "max"). Missing files are tolerated (leave the corresponding field 0 / inactive).

• Step 1: Add a static file-reader helper to CGroupMem.c (libc-only)

Add near the top of CGroupMem.c, after the includes:

/* Read up to size-1 bytes of nodeDir/name into buf (NUL-terminated). Returns false on failure. */
static bool CGroupMem_readFile(const char* nodeDir, const char* name, char* buf, size_t size) {
   char path[PATH_MAX];
   int n = snprintf(path, sizeof(path), "%s/%s", nodeDir, name);
   if (n < 0 || (size_t)n >= sizeof(path))
      return false;

   FILE* fp = fopen(path, "r");
   if (!fp)
      return false;

   size_t got = fread(buf, 1, size - 1, fp);
   buf[got] = '\0';
   fclose(fp);
   return got > 0;
}

• Step 2: Add the failing test (uses a fixture directory created at runtime)

Add to CGroupMemTest.c (the test writes fixture files into a temp dir, then calls readNode):

#include <stdlib.h>   /* add near the top with the other includes */

static void writeFile(const char* dir, const char* name, const char* body) {
   char path[1024];
   snprintf(path, sizeof(path), "%s/%s", dir, name);
   FILE* fp = fopen(path, "w");
   if (fp) { fputs(body, fp); fclose(fp); }
}

static void test_readNode(void) {
   char dir[] = "/tmp/cgmtestXXXXXX";
   if (!mkdtemp(dir)) { CHECK(0 && "mkdtemp failed"); return; }

   writeFile(dir, "memory.max", "4294967296\n");        /* 4 GiB */
   writeFile(dir, "memory.current", "2202009600\n");    /* ~2.05 GiB */
   writeFile(dir, "memory.stat", "anon 1048576\nfile 524288000\n");
   writeFile(dir, "memory.swap.max", "1073741824\n");   /* 1 GiB */
   writeFile(dir, "memory.swap.current", "10485760\n"); /* 10 MiB */

   CGroupMemData data = {0};
   /* host has 64 GiB → limit (4 GiB) < host → active */
   CGroupMem_readNode(dir, 64ULL * 1024 * 1024, &data);
   CHECK(data.active == true);
   CHECK(data.limit == 4194304ULL);
   CHECK(data.current == 2150400ULL);
   CHECK(data.file == 512000ULL);
   CHECK(data.swapActive == true);
   CHECK(data.swapLimit == 1048576ULL);
   CHECK(data.swapCurrent == 10240ULL);

   /* unlimited memory.max → inactive */
   writeFile(dir, "memory.max", "max\n");
   CGroupMemData data2 = {0};
   CGroupMem_readNode(dir, 64ULL * 1024 * 1024, &data2);
   CHECK(data2.active == false);
}

Add #include <string.h> (already added in Task 5) and test_readNode(); to main(). Note: requires _DEFAULT_SOURCE for mkdtemp — handled in Step 4.

• Step 3: Run — expect FAIL (undefined reference to CGroupMem_readNode)

Run: make check

• Step 4: Implement CGroupMem_readNode and make mkdtemp available to the test

Add to CGroupMem.c:

void CGroupMem_readNode(const char* nodeDir, unsigned long long hostTotalMemKB, CGroupMemData* data) {
   char buf[4096];

   data->active = false;
   data->swapActive = false;
   data->limit = data->current = data->file = 0;
   data->swapLimit = data->swapCurrent = 0;

   if (CGroupMem_readFile(nodeDir, "memory.max", buf, sizeof(buf))) {
      unsigned long long kb;
      if (CGroupMem_parseLimit(buf, &kb) && kb > 0 && kb < hostTotalMemKB) {
         data->limit = kb;
         data->active = true;
      }
   }

   if (data->active) {
      if (CGroupMem_readFile(nodeDir, "memory.current", buf, sizeof(buf)))
         CGroupMem_parseUsage(buf, &data->current);
      if (CGroupMem_readFile(nodeDir, "memory.stat", buf, sizeof(buf)))
         CGroupMem_parseStat(buf, "file", &data->file);
   }

   if (CGroupMem_readFile(nodeDir, "memory.swap.max", buf, sizeof(buf))) {
      unsigned long long kb;
      if (CGroupMem_parseLimit(buf, &kb)) {
         data->swapLimit = kb;
         data->swapActive = true;
         if (CGroupMem_readFile(nodeDir, "memory.swap.current", buf, sizeof(buf)))
            CGroupMem_parseUsage(buf, &data->swapCurrent);
      }
   }
}

Note on the swap=0 case: memory.swap.max of 0 parses as a finite limit → swapActive = true, swapLimit = 0; the meter renders an empty bar safely (Meter.c guards total > 0.0).

In Makefile.am, the test needs mkdtemp (POSIX). Add a feature-test macro to the test's flags:

linux_CGroupMemTest_CPPFLAGS = $(AM_CPPFLAGS) -D_DEFAULT_SOURCE

• Step 5: Run — expect PASS (All 28 checks passed)

Run: make check

• Step 6: Commit

git add linux/CGroupMem.c linux/CGroupMemTest.c Makefile.am
git commit -s -m "linux: add CGroupMem_readNode reading limit/usage/stat/swap

Assisted-by: Claude <noreply@anthropic.com>"

---

Task 7: CGroupMem_scan (cached discovery of our v2 node)

Files:

• Modify: linux/CGroupMem.c

Interfaces:

• Consumes: CGroupMem_parseMountinfo, CGroupMem_parseSelfCgroup, CGroupMem_readNode.
• Produces: void CGroupMem_scan(unsigned long long hostTotalMemKB, CGroupMemData* data); — on first call resolves and caches the node directory (<cgroup2 mount> + <0:: path>); thereafter re-reads only the value files. Sets data->active = false on any resolution failure (no v2 mount / pure-v1 / read error).

Discovery is impure (reads /proc/self/mountinfo, /proc/self/cgroup) so it is verified by build + runtime, not the unit harness; its two parsers are already unit-tested (Tasks 4–5).

• Step 1: Implement CGroupMem_scan with a static cache

void CGroupMem_scan(unsigned long long hostTotalMemKB, CGroupMemData* data) {
   static bool resolved = false;
   static bool available = false;
   static char nodeDir[PATH_MAX];

   if (!resolved) {
      resolved = true;
      available = false;

      char mountBuf[PATH_MAX];
      char cgPath[PATH_MAX];
      char fileBuf[8192];

      FILE* fp = fopen("/proc/self/mountinfo", "r");
      if (fp) {
         size_t got = fread(fileBuf, 1, sizeof(fileBuf) - 1, fp);
         fileBuf[got] = '\0';
         fclose(fp);
         if (!CGroupMem_parseMountinfo(fileBuf, mountBuf, sizeof(mountBuf)))
            mountBuf[0] = '\0';
      } else {
         mountBuf[0] = '\0';
      }

      if (mountBuf[0]) {
         fp = fopen("/proc/self/cgroup", "r");
         if (fp) {
            size_t got = fread(fileBuf, 1, sizeof(fileBuf) - 1, fp);
            fileBuf[got] = '\0';
            fclose(fp);
            if (CGroupMem_parseSelfCgroup(fileBuf, cgPath, sizeof(cgPath))) {
               /* node dir = mount point + cgroup path; "0::/" → the mount point itself */
               int n;
               if (cgPath[0] == '/' && cgPath[1] == '\0')
                  n = snprintf(nodeDir, sizeof(nodeDir), "%s", mountBuf);
               else
                  n = snprintf(nodeDir, sizeof(nodeDir), "%s%s", mountBuf, cgPath);
               if (n > 0 && (size_t)n < sizeof(nodeDir))
                  available = true;
            }
         }
      }
   }

   if (!available) {
      data->active = false;
      data->swapActive = false;
      return;
   }

   CGroupMem_readNode(nodeDir, hostTotalMemKB, data);
}

• Step 2: Rebuild and verify no warnings

Run: make -j"$(nproc)" && make check
Expected: clean build; All 28 checks passed (scan has no new unit test).

• Step 3: Runtime smoke test of discovery (host, unlimited)

Run:

./htop --version && echo 'manual: run ./htop on this host; Memory meter unchanged (no limit) — confirmed in Task 10'

Expected: builds/runs; on an unlimited host CGroupMem_scan sets active=false (verified end-to-end in Task 10).

• Step 4: Commit

git add linux/CGroupMem.c
git commit -s -m "linux: add cached CGroupMem_scan node discovery

Assisted-by: Claude <noreply@anthropic.com>"

---

Task 8: Cache cgroup data in LinuxMachine each refresh

Files:

• Modify: linux/LinuxMachine.h (struct field + include)
• Modify: linux/LinuxMachine.c (call CGroupMem_scan at end of LinuxMachine_scanMemoryInfo)

Interfaces:

• Consumes: CGroupMem_scan, CGroupMemData (from linux/CGroupMem.h).

• Produces: ((LinuxMachine*)host)->cgroupMem — a populated CGroupMemData, read by Platform.c in Tasks 10–11.

• Step 1: Add the include and struct field to linux/LinuxMachine.h

Add to the program-header include group at the top of LinuxMachine.h:

#include "linux/CGroupMem.h"

Add a field to the LinuxMachine struct, after ZswapStats zswap;:

   CGroupMemData cgroupMem;

• Step 2: Call CGroupMem_scan at the end of LinuxMachine_scanMemoryInfo

In linux/LinuxMachine.c, add the program-header include #include "linux/CGroupMem.h" to the include block (alphabetically before linux/Compat.h). Then, at the very end of LinuxMachine_scanMemoryInfo() (after this->zswap.usedZswapOrig = zswapOrigMem;), add:

   /* host->totalMem is in kB; CGroupMem works in kB. */
   CGroupMem_scan(host->totalMem, &this->cgroupMem);

• Step 3: Build — expect success

Run: make -j"$(nproc)"
Expected: compiles and links with no errors or warnings.

• Step 4: Verify the field is populated (debug print, then revert)

Temporarily add at the end of LinuxMachine_scanMemoryInfo (remove before commit):

   fprintf(stderr, "cgroupMem active=%d limit=%lluKB current=%lluKB\n", this->cgroupMem.active, this->cgroupMem.limit, this->cgroupMem.current);

Run on the host: ./htop 2>/tmp/cg.log (quit immediately), then tail /tmp/cg.log. On an unlimited host expect active=0. Remove the debug line.

• Step 5: Commit

git add linux/LinuxMachine.h linux/LinuxMachine.c
git commit -s -m "linux: scan cgroup v2 memory limits each refresh

Assisted-by: Claude <noreply@anthropic.com>"

---

Task 9: Add the cgroupAwareMeters setting (default ON)

Files:

• Modify: Settings.h (bool field)
• Modify: Settings.c (default = true; htoprc read; htoprc write)
• Modify: DisplayOptionsPanel.c (checkbox)

Interfaces:

• Produces: settings->cgroupAwareMeters (bool, default true), read by Platform.c in Tasks 10–11.

• Step 1: Declare the field in Settings.h

Add after bool showCachedMemory; (line ~106):

   bool cgroupAwareMeters;

• Step 2: Set the default in Settings.c

Find where showCachedMemory is defaulted in Settings_defaultInit/Settings_new (search this->showCachedMemory =) and add directly after it:

   this->cgroupAwareMeters = true;

• Step 3: Parse from htoprc — in Settings_read, add an else if next to the highlight_base_name branch:

      } else if (String_eq(option[0], "cgroup_aware_meters")) {
         this->cgroupAwareMeters = atoi(option[1]);

• Step 4: Write to htoprc — in Settings_write, next to the printSettingInteger("highlight_base_name", ...) line, add:

   printSettingInteger("cgroup_aware_meters", this->cgroupAwareMeters);

• Step 5: Add the checkbox in DisplayOptionsPanel.c — after the "Show program path" Panel_add line:

   Panel_add(super, (Object*) CheckItem_newByRef("Show cgroup limits in Memory/Swap meters when containerized", &(settings->cgroupAwareMeters)));

• Step 6: Build and verify the setting round-trips

Run:

make -j"$(nproc)"
rm -f /tmp/htoprc_test
HTOPRC=/tmp/htoprc_test ./htop -C >/dev/null 2>&1 &   # -C disables color; runs briefly
sleep 1; kill %1 2>/dev/null
grep cgroup_aware_meters /tmp/htoprc_test

Expected: cgroup_aware_meters=1 present in the written htoprc.

• Step 7: Commit

git add Settings.h Settings.c DisplayOptionsPanel.c
git commit -s -m "Settings: add cgroupAwareMeters option (default on)

Assisted-by: Claude <noreply@anthropic.com>"

---

Task 10: Memory meter cgroup branch + caption marker

Files:

• Modify: linux/Platform.c (Platform_setMemoryValues; add #include "XUtils.h" if not present for String_eq)

Interfaces:

• Consumes: lhost->cgroupMem (Task 8), settings->cgroupAwareMeters (Task 9), Meter_setCaption (already declared in Meter.h), String_eq (XUtils.h).

• Step 1: Replace the body of Platform_setMemoryValues with the cgroup-aware version

void Platform_setMemoryValues(Meter* this) {
   const Machine* host = this->host;
   const LinuxMachine* lhost = (const LinuxMachine*) host;
   const Settings* settings = host->settings;

   if (settings->cgroupAwareMeters && lhost->cgroupMem.active) {
      /* cgroup v2 mode: total = limit; used = current - file (anon+kernel); cache = file. */
      unsigned long long limit = lhost->cgroupMem.limit;
      unsigned long long current = lhost->cgroupMem.current;
      unsigned long long file = lhost->cgroupMem.file;
      unsigned long long used = (current > file) ? (current - file) : 0;

      this->total = limit;
      this->values[MEMORY_CLASS_USED]       = used;
      this->values[MEMORY_CLASS_SHARED]     = 0;
      this->values[MEMORY_CLASS_COMPRESSED] = 0;
      this->values[MEMORY_CLASS_BUFFERS]    = 0;
      this->values[MEMORY_CLASS_CACHE]      = file;
      this->values[MEMORY_CLASS_AVAILABLE]  = (limit > current) ? (limit - current) : 0;

      if (!String_eq(this->caption, "Cgm"))
         Meter_setCaption(this, "Cgm");
      return;
   }

   if (!String_eq(this->caption, "Mem"))
      Meter_setCaption(this, "Mem");

   this->total = host->totalMem;
   this->values[MEMORY_CLASS_USED]       = lhost->usedMem;
   this->values[MEMORY_CLASS_SHARED]     = lhost->sharedMem;
   this->values[MEMORY_CLASS_COMPRESSED] = 0; /* compressed */
   this->values[MEMORY_CLASS_BUFFERS]    = lhost->buffersMem;
   this->values[MEMORY_CLASS_CACHE]      = lhost->cachedMem;
   this->values[MEMORY_CLASS_AVAILABLE]  = lhost->availableMem;

   if (lhost->zfs.enabled != 0 && !Running_containerized) {
      // ZFS does not shrink below the value of zfs_arc_min.
      unsigned long long int shrinkableSize = 0;
      if (lhost->zfs.size > lhost->zfs.min)
         shrinkableSize = lhost->zfs.size - lhost->zfs.min;
      this->values[MEMORY_CLASS_USED] -= shrinkableSize;
      this->values[MEMORY_CLASS_CACHE] += shrinkableSize;
      this->values[MEMORY_CLASS_AVAILABLE] += shrinkableSize;
   }

   if (lhost->zswap.usedZswapOrig > 0 || lhost->zswap.usedZswapComp > 0) {
      this->values[MEMORY_CLASS_USED] -= lhost->zswap.usedZswapComp;
      this->values[MEMORY_CLASS_COMPRESSED] += lhost->zswap.usedZswapComp;
   }
}

Note: MEMORY_CLASS_SHARED/COMPRESSED count as "used"; setting them to 0 (not NAN) keeps the MemoryMeter_updateValues used-sum finite. The cgroup branch runs before and instead of the ZFS/zswap adjustments, so there is no double-counting. Ensure #include "XUtils.h" is in the include block (for String_eq); add it to the program-header group if absent.

• Step 2: Build

Run: make -j"$(nproc)" && make check
Expected: clean build; All 28 checks passed.

• Step 3: Manual verification on the host (no limit → unchanged)

Run: ./htop
Expected: Memory meter caption is Mem; totals match the host (compare with free -m). Quit with q.

• Step 4: Manual verification under a container limit (the core behavior)

Run (requires Docker on a cgroup v2 host; mounts the freshly built binary):

docker run --rm -it --memory=512m -v "$PWD/htop:/usr/bin/htop:ro" debian:bookworm-slim /usr/bin/htop

Expected: Memory meter caption reads Cgm; the total shows 512M (not the host RAM); the bar fills with used (current − file) + cache (file). Toggle the setting off via F2 → Display options → uncheck "Show cgroup limits …" and confirm it reverts to host totals + Mem caption.

• Step 5: Commit

git add linux/Platform.c
git commit -s -m "linux: make Memory meter cgroup v2 limit-aware

Assisted-by: Claude <noreply@anthropic.com>"

---

Task 11: Swap meter cgroup branch

Files:

• Modify: linux/Platform.c (Platform_setSwapValues)

Interfaces:

• Consumes: lhost->cgroupMem.swapActive/swapLimit/swapCurrent (Task 8), settings->cgroupAwareMeters (Task 9).

• Step 1: Add the cgroup branch at the top of Platform_setSwapValues

Insert immediately after the const LinuxMachine* lhost = ...; line (before this->total = host->totalSwap;):

   const Settings* settings = host->settings;
   if (settings->cgroupAwareMeters && lhost->cgroupMem.swapActive) {
      /* cgroup v2 swap: total = memory.swap.max (may be 0 = disabled → empty bar). */
      this->total = lhost->cgroupMem.swapLimit;
      this->values[SWAP_METER_USED] = lhost->cgroupMem.swapCurrent;
      this->values[SWAP_METER_CACHE] = NAN;       /* not represented per-cgroup */
      this->values[SWAP_METER_FRONTSWAP] = NAN;
      if (!String_eq(this->caption, "Cgs"))
         Meter_setCaption(this, "Cgs");
      return;
   }
   if (!String_eq(this->caption, "Swp"))
      Meter_setCaption(this, "Swp");

(String_eq comes from XUtils.h, included in Task 10.)

• Step 2: Build

Run: make -j"$(nproc)" && make check
Expected: clean build; All 28 checks passed.

• Step 3: Manual verification under a container swap limit

Run (cgroup v2 host with swap accounting):

docker run --rm -it --memory=512m --memory-swap=768m -v "$PWD/htop:/usr/bin/htop:ro" debian:bookworm-slim /usr/bin/htop

Expected: Swap meter caption reads Cgs; total reflects the cgroup swap limit (--memory-swap minus --memory = 256M of swap), not host swap. With --memory-swap=512m (swap disabled, memory.swap.max=0) the swap bar renders empty without error.

• Step 4: Commit

git add linux/Platform.c
git commit -s -m "linux: make Swap meter cgroup v2 limit-aware

Assisted-by: Claude <noreply@anthropic.com>"

---

Final: push & open the PR

• Step 1: Rebase/verify the three commit groups are clean

Run: git log --oneline main..HEAD — expect the 11 commits grouping into helpers / memory / swap.

• Step 2: Push and open the PR (after the human confirms sign-off was applied)

git push -u origin feat/cgroup-v2-memory
gh pr create --repo htop-dev/htop --title "linux: cgroup v2-aware Memory & Swap meters" --body-file <(cat <<'BODY'
...summary referencing issue context, the v2-only scope, the caption marker + default-on cgroupAwareMeters toggle, and the new make check test...
BODY
)

Note: target htop-dev/htop from the Oblynx fork. Reference upstream htop-dev#1538/htop-dev#1020. Disclose AI assistance in the PR body. Do not request review until CI (build + clang-analyzer + sanitizer) is green.

---

Self-Review notes (addressed in this plan)

• Spec coverage: auto-detect (Task 8 scan + Task 10/11 branches); v2-only (parsers + readNode); caption unambiguity (Tasks 10/11 via Meter_setCaption); default-ON toggle (Task 9); used=current−file/cache=file/available=limit−current (Task 10); swap v2 + swap.max=0 guard (Tasks 6/11); no shared-file cgroup logic (caption via existing public API; only the generic Settings/Panel edits touch shared files); ENOENT tolerance (CGroupMem_readFile returns false → fields stay 0/inactive); cgroup-mode skips ZFS/zswap (Task 10 early return). Host-context suffix intentionally not implemented (deferred per spec).
• Test reality: htop has no C unit harness; Task 1 adds a self-contained check_PROGRAMS + TESTS target (libc-only test, droppable if upstream objects).
• Type consistency: CGroupMemData field names (active, swapActive, limit, current, file, swapLimit, swapCurrent) are used identically across Tasks 6, 8, 10, 11; all kB. cgroupAwareMeters spelled consistently across Tasks 9–11. Captions Mem/Cgm/Swp/Cgs used consistently.

[Oblynx]

✅ Implementation complete — draft PR opened upstream: htop-dev#2031

12 signed commits on feat/cgroup-v2-memory (helpers + memory + swap, cgroup v2). Verified: clean -Wall build, make check unit tests pass, and real-container functional checks (512m→512M, 256m→256M/128M swap, unlimited→host fallback). Screenshots for all three cases are embedded in the PR. Opened as draft pending CI; will mark ready for review once green.