rt+lib/os+test: capture envp; add os.getenv

Capture envp from the kernel-supplied stack into a DATAW slot during
_start's prologue (before CALL main), and expose it via a `rt_envp`
TEXT getter. lib/os.getenv binds the getter as `@symbol("rt_envp")
fn rtenvp() **u8` — the getter-fn pattern works around @symbol-on-let
not being supported by the compiler yet (silent miscompile otherwise).

`os.getenv(name: str) (str | void)` matches Hare's os::getenv surface:
walks the NUL-terminated envp table, "name=" prefix-matches with an
explicit `=` boundary check so prefixes don't false-match longer
names, returns the value as a borrowed str view. Empty value (env
"FOO=") returns len=0 str, not void — void is reserved for "name
not present at all".

Cohort coverage in lib/os/ostest.ww + test/wcc/974_getenv_run.c:
set / empty / unset / prefix-no-match (4 @test fns).

Makefile

@@ -234,7 +234,7 @@ TESTS	= $(BIN)/test_smoke $(BIN)/test_lex $(BIN)/test_parse $(BIN)/test_check \
 	  $(BIN)/test_w6c_ww $(BIN)/test_ww_ww $(BIN)/test_self_rebuild \
 	  $(BIN)/test_dyn_ww $(BIN)/test_selfcheck $(BIN)/test_at_test_ww \
 	  $(BIN)/test_fmt_run $(BIN)/test_log_run $(BIN)/test_fnmatch_run \
-	  $(BIN)/test_shlex_run \
+	  $(BIN)/test_shlex_run $(BIN)/test_getenv_run \
 	  $(BIN)/test_memio_run $(BIN)/test_temp_run $(BIN)/test_getopt_run \
 	  $(BIN)/test_base32_run $(BIN)/test_base64_run \
 	  $(BIN)/test_adler32_run $(BIN)/test_crc16_run \
@@ -448,6 +448,10 @@ $(BIN)/test_shlex_run: test/wcc/973_shlex_run.c $(BIN)/ww $(BIN)/w6c \
 		$(BIN)/w6a $(BIN)/w6l $(LIB)/libwwrt.a | $(BIN)
 	$(CC) $(CFLAGS) -o $@ $<
 
+$(BIN)/test_getenv_run: test/wcc/974_getenv_run.c $(BIN)/ww $(BIN)/w6c \
+		$(BIN)/w6a $(BIN)/w6l $(LIB)/libwwrt.a | $(BIN)
+	$(CC) $(CFLAGS) -o $@ $<
+
 $(BIN)/test_memio_run: test/wcc/980_memio_run.c $(BIN)/ww $(BIN)/w6c \
 		$(BIN)/w6a $(BIN)/w6l $(LIB)/libwwrt.a | $(BIN)
 	$(CC) $(CFLAGS) -o $@ $<

lib/os/os.ww

@@ -241,3 +241,63 @@ export fn getcwd(buf: *u8, n: u64) i64 = {
 export fn getdents64(fd: i32, buf: *u8, n: u64) i64 = {
 	return syscall3(nr.GETDENTS64, fd: i64, buf: i64, n: i64);
 };
+
+// ---- environment ------------------------------------------------------
+
+// rt_envp — runtime-side getter. rt/start.s captures envp into a DATAW
+// slot before calling main; this binding lifts the captured pointer
+// into ww. Same FFI shape as rt_syscall / rt_alloc / rt_abort: a TEXT
+// symbol the linker resolves. The returned `**u8` is a NUL-terminated
+// table of `*u8` entries, each pointing at a NUL-terminated
+// "NAME=VALUE" byte sequence.
+//
+// We don't expose `rtenvp` directly; [[getenv]] is the only consumer.
+@symbol("rt_envp") fn rtenvp() **u8;
+
+// getenv — POSIX getenv. Returns a borrowed `str` view over the value
+// bytes of the named environment variable, or void if the name is not
+// present. The view is valid for the process lifetime — the bytes
+// live in the kernel-supplied envp table at process entry. A future
+// `setenv` (separate task) that grows the table behind the scenes
+// would invalidate prior views; v1 has no setenv, so callers can
+// hold the view indefinitely.
+//
+// Mirrors Hare's os::tryenv shape (returns void rather than panicking
+// on missing). Hare also ships os::getenv (`(str | void)`) and
+// os::mustenv (panic-on-missing); ww collapses to the single
+// `(str | void)` form for now — consumers wanting "must" semantics
+// abort at the call site.
+//
+// Algorithm: walk the NUL-pointer-terminated `environ` table doing a
+// "name=" prefix match against each entry, byte-wise. NUL inside
+// `name` would never match a real env var (env var names cannot
+// contain '\0'), so we don't filter — POSIX puts that responsibility
+// on the caller.
+export fn getenv(name: str) (str | void) = {
+	let envp: **u8 = rtenvp();
+	let i: i32 = 0;
+	for (true) {
+		let entry: *u8 = envp[i];
+		if (entry == nil: *u8) { return; };
+		let j: i32 = 0;
+		let matched: bool = true;
+		for (j < name.len) {
+			if (entry[j] == 0u8) { matched = false; break; };
+			if (entry[j] != name[j]) { matched = false; break; };
+			j += 1;
+		};
+		if (matched) {
+			if (entry[name.len] == 61u8) {	// '='
+				let val: *u8 = entry + ((name.len + 1): u64);
+				let n: i32 = 0;
+				for (val[n] != 0u8) { n += 1; };
+				let r: str;
+				r.ptr = val;
+				r.len = n;
+				return r;
+			};
+		};
+		i += 1;
+	};
+	return;
+};

lib/os/ostest.ww

@@ -0,0 +1,98 @@
+// ostest — exercises lib/os surface that doesn't have a dedicated
+// test elsewhere. v1 covers [[os.getenv]] only, against an env state
+// pre-arranged by the C driver (test/wcc/974_getenv_run.c).
+//
+// Convention follows the stdlib `_run` test fixtures: hand-rolled
+// @test fns dispatched from `main()` in numeric order, with a
+// `signalled` global the main fn bumps so a failing case exits with
+// `WEXITSTATUS = signalled + 10` — the harness then knows which
+// scenario tripped. Same shape as temptest / shlextest / fnmatchtest.
+//
+// Pre-arranged env state (set by 974_getenv_run.c via setenv/unsetenv
+// before exec'ing `ww run lib/os/ostest.ww`):
+//
+//   WW_TEST_GETENV     = "hello-world"
+//   WW_TEST_EMPTY      = ""           (set, but value is empty)
+//   WW_TEST_NOT_SET    unset
+//
+// Don't `use io;` here — lib/os and lib/io both export read/write/
+// close as C symbols that collide under the driver's flat-scope
+// concat (task #17). os alone is sufficient: getenv + exit are the
+// only primitives needed.
+
+use os;
+
+let signalled: i32 = 0;
+
+fn fail() void = { os.exit(signalled + 10); };
+
+fn streq(a: str, b: str) bool = {
+	if (a.len != b.len) { return false; };
+	let i: i32 = 0;
+	for (i < a.len) {
+		if (a[i] != b[i]) { return false; };
+		i += 1;
+	};
+	return true;
+};
+
+// ---- getenv: set var → matching value -------------------------------
+
+@test fn test_getenv_set() void = {
+	let r = os.getenv("WW_TEST_GETENV");
+	match (r) {
+	case void => fail();
+	case let s: str => {
+		if (!streq(s, "hello-world")) { fail(); };
+	};
+	};
+};
+
+// ---- getenv: empty value (set but zero-length) ----------------------
+//
+// POSIX permits an env var with an empty value (`name=` in environ).
+// getenv must return the empty str, NOT void — void is reserved for
+// "name not present at all". This row exercises the boundary.
+
+@test fn test_getenv_empty() void = {
+	let r = os.getenv("WW_TEST_EMPTY");
+	match (r) {
+	case void => fail();
+	case let s: str => {
+		if (s.len != 0) { fail(); };
+	};
+	};
+};
+
+// ---- getenv: unset var → void ---------------------------------------
+
+@test fn test_getenv_unset() void = {
+	let r = os.getenv("WW_TEST_NOT_SET");
+	match (r) {
+	case void => {};
+	case let s: str => fail();
+	};
+};
+
+// ---- getenv: prefix-collision guard ---------------------------------
+//
+// Probes that "WW_TEST_GETEN" (a prefix of WW_TEST_GETENV) doesn't
+// match. Without the explicit `entry[name.len] == '='` check in
+// getenv, a naive prefix matcher would return the value of any
+// longer-named var that starts with the queried name.
+
+@test fn test_getenv_prefix_no_match() void = {
+	let r = os.getenv("WW_TEST_GETEN");
+	match (r) {
+	case void => {};
+	case let s: str => fail();
+	};
+};
+
+export fn main() i32 = {
+	signalled = 1; test_getenv_set();
+	signalled = 2; test_getenv_empty();
+	signalled = 3; test_getenv_unset();
+	signalled = 4; test_getenv_prefix_no_match();
+	return 0;
+};

rt/start.s

@@ -1,16 +1,48 @@
 // rt/start.s — process entry. Linux sets up the stack so that on
 // entry [SP] holds argc, [SP+8] starts argv (NULL-terminated array
-// of *u8), [SP+8+(argc+1)*8] starts envp.
+// of *u8), [SP+8+(argc+1)*8] starts envp (also NULL-terminated).
 //
 // We pull argc into DI and the argv pointer into SI, then jump to
 // `main`. ww programs that declare `fn main(argc: i32, argv: **u8)
 // i32` see them; programs declaring `fn main() i32` simply ignore
 // the regs. Either way, main's return value is fed to the exit
 // syscall.
+//
+// envp is captured into the rt_envp_slot DATAW cell before CALL main
+// so lib/os.getenv (via the rt_envp getter below) can walk it. We
+// compute envp = SP + 16 + argc*8 in AX using three doublings and
+// adds — w6a's syntax doesn't ship SIB-style indexed addressing
+// (no `LEAQ 16(SP)(DI*8), AX`), so the explicit shift-by-three is
+// the portable form. AX/DI/SI are scratch on entry; no callee-
+// saved discipline applies until we reach main.
 TEXT _start,$0
-	MOVQ	(SP), DI
-	LEAQ	8(SP), SI
+	MOVQ	(SP), DI		// argc → DI (1st arg to main)
+	LEAQ	8(SP), SI		// &argv[0] → SI (2nd arg to main)
+	MOVQ	DI, AX			// AX = argc
+	ADDQ	AX, AX			// AX = argc * 2
+	ADDQ	AX, AX			// AX = argc * 4
+	ADDQ	AX, AX			// AX = argc * 8
+	ADDQ	SP, AX			// AX = SP + argc*8
+	ADDQ	$16, AX			// AX = SP + argc*8 + 16 = &argv[argc+1] = envp
+	MOVQ	AX, rt_envp_slot(SB)
 	CALL	main(SB)
 	MOVQ	AX, DI
 	MOVQ	$60, AX
 	SYSCALL
+
+// rt_envp — getter that returns the envp pointer captured at process
+// entry. Bound from lib/os via `@symbol("rt_envp") fn rtenvp() **u8;`,
+// matching the rt_syscall / rt_alloc / rt_abort pattern. Read-only
+// view of the kernel-supplied table; the bytes live for the process
+// lifetime. A future setenv that grows the table re-points the slot
+// (separate task).
+TEXT rt_envp,$0
+	MOVQ	rt_envp_slot(SB), AX
+	RET
+
+// rt_envp_slot — 8-byte writable cell holding the envp pointer.
+// Initialised to zero in .data; _start overwrites it before
+// transferring control to main. DATAW gives us the writable .data
+// slot (w6a has no GLOBL; same shape as lib/log's silent/default/
+// global cells in lib/log/log.s).
+DATAW	rt_envp_slot(SB),"\x00\x00\x00\x00\x00\x00\x00\x00"

test/wcc/974_getenv_run.c

@@ -0,0 +1,65 @@
+/*
+ * 974_getenv_run — execute the lib/os getenv smoke fixture under the
+ * C-side `ww run` driver and assert exit 0.
+ *
+ * Pre-arranges the environment that lib/os/ostest.ww asserts against:
+ *
+ *   WW_TEST_GETENV   = "hello-world"   (set, non-empty)
+ *   WW_TEST_EMPTY    = ""              (set, empty value)
+ *   WW_TEST_NOT_SET  unset             (unsetenv-cleared)
+ *
+ * The child `ww run` process inherits this env, so ostest.ww's
+ * `os.getenv` calls see exactly the state we configured here. This
+ * is the "C-side env arrangement" pattern (parent sets, child reads)
+ * — proper POSIX shape for stdlib testing without a `setenv` ww
+ * primitive (deferred per drew/rob).
+ *
+ * Same wrapper shape as 970_fmt_run / 971_log_run / 972_fnmatch_run
+ * / 973_shlex_run.
+ */
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <sys/wait.h>
+
+static int
+runwait(const char *cmd)
+{
+	int rc = system(cmd);
+	if (rc == -1) return -1;
+	if (WIFEXITED(rc)) return WEXITSTATUS(rc);
+	return 1;
+}
+
+int
+main(void)
+{
+	const char *bin = getenv("BIN");
+	if (!bin) bin = "out/bin";
+	char absbin[1024];
+	if (bin[0] != '/') {
+		char cwd[1024];
+		if (getcwd(cwd, sizeof cwd) == NULL) return 1;
+		snprintf(absbin, sizeof absbin, "%s/%s", cwd, bin);
+		bin = absbin;
+	}
+	char cwd[1024];
+	if (getcwd(cwd, sizeof cwd) == NULL) return 1;
+
+	/* Pre-arrange the env state ostest.ww asserts against. */
+	setenv("WW_TEST_GETENV", "hello-world", 1);
+	setenv("WW_TEST_EMPTY", "", 1);
+	unsetenv("WW_TEST_NOT_SET");
+
+	const char *src = "lib/os/ostest.ww";
+	char path[1024], cmd[2048];
+	snprintf(path, sizeof path, "%s/%s", cwd, src);
+	snprintf(cmd, sizeof cmd, "%s/ww run %s", bin, path);
+	int rc = runwait(cmd);
+	if (rc != 0) {
+		fprintf(stderr, "getenv_run FAIL: %s exited %d\n", src, rc);
+		return 1;
+	}
+	printf("getenv_run: %s ok\n", src);
+	return 0;
+}