@amritk/nish-x86_64-linux 0.24.0 → 0.26.0

package/docs/AI.md

@@ -2133,13 +2133,27 @@ a `\u` escape `nish/json` decodes) is one unit per byte, and counts its bytes.
 **Files and the system.** `readFileSync(path)` (exits 1 on failure),
 `readFileSyncOrNull(path)` (`string | null`), `readFileBytesSync(path)`
 (`u8[] | null`, the bytes as they are on disk), `writeFileSync(path, data)`,
-`appendFileSync(path, data)`, `mkdirSync(path)` (one level, `boolean`),
+`appendFileSync(path, data)`, `writeFileBytesSync(path, bytes)` (a `u8[]` as
+it is; `i32`: the length, or a negative errno), `renameSync(from, to)` (`0` or
+a negative errno; atomic on one filesystem, `-18` across two, so write the
+temporary beside the target), `unlinkSync(path)` (`0` or a negative errno; a
+directory is refused), `writeFileSyncMode(path, data, mode)` (the file left
+at exactly `mode` (`0..0o777`), set before the first byte, written in place; a symbolic link refused; the
+length or a negative errno), `createFileExclusiveSync(path, data, mode)` (the
+same, but `-17` when the name exists: a lock file), `mkdirSyncMode(path, mode)`
+(`0`, `-17` when it exists, the umask applies), `writeBytes(bytes, off, len)` (a `u8[]` range to stdout
+as it is, the length or a negative errno; the range panics like
+`netWrite`'s), `mkdirSync(path)` (one level, `boolean`),
 `isDirectorySync(path)`, `readdirSync(path)` (`string[] | null`, sorted by
 bytes, no `.`/`..`), `spawnSync(argv)`, `spawnSyncTo(argv, outPath, errPath)`,
+`spawnPiped(argv, stdin, stdout, stderr)` (stdin from a `u8[]`, both outputs
+appended to `u8[]`s, the status; `-2` past 16 MiB; the way to hand a child a
+secret, never argv or the environment),
 `getenv(name)` (`string | null` — unset and empty are different answers),
 `realpathSync(path)` (`string | null`; symbolic links resolved, absolute, and
 `null` when it does not resolve),
-`monotonicNanos()` (`i64`; elapsed time only), and, for checking a path before
+`monotonicNanos()` (`i64`; elapsed time only), `wallClockNanos()` (`i64`,
+nanoseconds since the Unix epoch; the wall clock, which can step), and, for checking a path before
 trusting it, `lstatOwnerModeSync(path)` (an `i64`: the owner's uid in the high
 32 bits, `st_mode` in the low 32, `-1` when it does not resolve; a symbolic
 link answers for itself), `geteuid()` (`i64`) and `isExecutableSync(path)`
@@ -2167,6 +2181,12 @@ also watches the signal fd. None of `spawn`, `kill`, `waitPid` may be called in
 a task or a parallel body; the two host facts may. `availableParallelism()` (`i32`, at least 1, no `--threads` needed) and
 `totalMemory()` (`i64` bytes, or `-1`) size a program to the machine. None of
 the five exists on a wasm target, and `spawn` and `waitPid` throw under Node.
+`setNice(n)` sets the nice value (clamped to -20..19; lowering it unprivileged
+is `-13`) and `setIdlePriority()` moves the program to Linux's `SCHED_IDLE`
+(`-95` on Darwin); each answers 0 or a negative errno. Call them at the top of
+`main`, never in a task. An unprivileged process can never leave `SCHED_IDLE`
+and an idle one can starve on a saturated machine, so keep a normal-priority
+fallback. Neither exists on wasm; both throw under Node.
 
 **Sockets** (`nish:net`, or the same names as globals). `tcpListen(host, port,
 backlog)`, `tcpAccept(fd, peer)`, `netRead(fd, buf, off, len)`,
@@ -2179,7 +2199,8 @@ and there is no `async` and no callback: your `main` is the loop. A client calls
 `tcpConnect(addr)`, which answers the descriptor while it is still connecting;
 wait for it to be writable, then `connectResult(fd)` is 0 or the failure. Buffers
 are `u8[]` only; an address is 18 bytes of one (IPv4 as `::ffff:a.b.c.d`, then
-the port big-endian); hosts are numeric literals, because there is no DNS.
+the port big-endian); hosts are numeric literals; to reach a name, resolve it first with
+`nish/net/dns` (`DnsClient` on your loop, or the blocking `resolveHost`).
 `netRead` / `netWrite` panic on a range outside the buffer.
 `tcpListenFlags(host, port, backlog, flags)` is `tcpListen` with flag 1
 `SO_REUSEPORT`, so several listeners, in one process or many, share a port (Linux
@@ -2198,7 +2219,13 @@ loop, `pollAdd(loop, fd, events, token)` / `pollModify(...)` watch `fd` for
 for `-1`), fills `ready: i32[]` with pairs — `ready[2k]` a token,
 `ready[2k + 1]` its events, 4 added for a hang-up or error — and answers how
 many, **0 on a timeout or a signal**. It is level-triggered, so what you leave
-unread is reported again. Add `signalFd()` to the loop to wake on SIGTERM. None
+unread is reported again. Add `signalFd()` to the loop to wake on SIGTERM.
+`netSetOption(fd, option, value)` sets one socket option from a whitelist:
+`NET_TCP_NODELAY`, `NET_TCP_QUICKACK` (Linux; `-95` on Darwin),
+`NET_SO_KEEPALIVE`, `NET_SO_SNDBUF` and `NET_SO_RCVBUF`, `i32` ids exported
+beside it; any other id is `-22`. Linux drops quick-ACK mode on its own, so set
+it again after each response. The ids are not module constants: pass them
+directly. None
 exists on a wasm target, and under Node each throws.
 
 **Arena.** `Arena.mark()`, `Arena.used()` and `using a = arena()` — see below.
@@ -2605,6 +2632,20 @@ the array open: end it and send the rest in the next statement. Every other
 guide's [PostgreSQL page](guide/using-nish/postgres.md#array-parameters) its
 walk-through.)
 
+**Read PostgreSQL ids, counts and times without parsing them** — there is no
+driver option for binary results: in `nish/net/postgres`, open the bind with
+`bindStartBinary(name)` instead of `bindStart(name)`, and every result column
+of that execution comes in binary. Read an `int2`/`int4`/`int8` with
+`binaryInt(c)`, a `bool` with `binaryBool(c)`, a `float8` with
+`binaryFloat(c)`, a `timestamptz` with `conn.binary.timestamp(conn.inputBuffer(),
+conn.colStart(c), conn.colLength(c), out, at)` (or its microseconds since 2000
+with `binaryInt(c)`, written out by `conn.binary.iso(micros, out, at)`), and a
+`text` column with `columnText(c)` as before. Cast anything else (`numeric`,
+`text[]`) to `text` in the SQL. (No block, as for `nish/text`;
+`tests/postgres/live`'s `binary` scenario runs it against a server, and the
+user guide's [PostgreSQL page](guide/using-nish/postgres.md#binary-results)
+its walk-through.)
+
 **Batch a server's keyed reads into one PostgreSQL query** — there is no
 DataLoader and no `setTimeout` to collect a tick's keys: in `nish/net/postgres`,
 a `PgBatcher` built from a `PgBatchConfig` (`name`, `select` reading the key as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/nish-x86_64-linux",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "The nish native compiler for Linux on x86_64",
   "license": "MIT",
   "os": [

package/runtime/browser.mjs

@@ -10,9 +10,9 @@
  *   - `exit(code)` throws a `NishExit` carrying the code, since a page cannot
  *     end itself; the caller that started the program catches it, and does
  *     not call the module again (docs/security/runtime-browser.md, BROWSER-2).
- *   - `monotonicNanos` reads `performance.now()`, `getenv` answers `null`,
- *     `isTerminal` answers `false` and `terminalSize` `[-25, 0]`, and `argv()`
- *     is the program alone.
+ *   - `monotonicNanos` reads `performance.now()`, `wallClockNanos` `Date.now()`,
+ *     `getenv` answers `null`, `isTerminal` answers `false` and `terminalSize`
+ *     `[-25, 0]`, and `argv()` is the program alone.
  *   - Every file-system, process and machine call panics, naming itself and
  *     the browser.
  */
@@ -69,6 +69,7 @@ installHost({
   call(name) {
     if (name === "getenv") return null;
     if (name === "monotonicNanos") return BigInt(Math.round(performance.now() * 1e6));
+    if (name === "wallClockNanos") return BigInt(Date.now()) * 1000000n;
     // A page has no terminal, which `nish:term` answers as a pipe does.
     if (name === "isTerminal") return false;
     if (name === "terminalSize") return [-25, 0];

package/runtime/core/host.d.ts

@@ -35,6 +35,7 @@ export declare function log(x: unknown): void;
 export declare function error(x: unknown): void;
 export declare function write(s: string): void;
 export declare function writeError(s: string): void;
+export declare function writeBytes(bytes: readonly u8[], off: i32, len: i32): i32;
 export declare function panic(message: string): never;
 export declare function exit(code: i32): never;
 export declare function argv(): string[];
@@ -43,6 +44,12 @@ export declare function readFileSyncOrNull(path: string): string | null;
 export declare function readFileBytesSync(path: string): u8[] | null;
 export declare function writeFileSync(path: string, data: string): void;
 export declare function appendFileSync(path: string, data: string): void;
+export declare function writeFileBytesSync(path: string, bytes: readonly u8[]): i32;
+export declare function renameSync(from: string, to: string): i32;
+export declare function unlinkSync(path: string): i32;
+export declare function writeFileSyncMode(path: string, data: string, mode: i32): i32;
+export declare function createFileExclusiveSync(path: string, data: string, mode: i32): i32;
+export declare function mkdirSyncMode(path: string, mode: i32): i32;
 export declare function mkdirSync(path: string): boolean;
 export declare function isDirectorySync(path: string): boolean;
 export declare function readdirSync(path: string): string[] | null;
@@ -52,10 +59,12 @@ export declare function arch(): string;
 export declare function getenv(name: string): string | null;
 export declare function spawnSync(argv: string[]): number;
 export declare function spawnSyncTo(argv: string[], stdoutPath: string, stderrPath: string): number;
+export declare function spawnPiped(argv: string[], stdin: readonly u8[], stdout: u8[], stderr: u8[]): i32;
 export declare function kill(pid: i32, sig: i32): i32;
 export declare function availableParallelism(): i32;
 export declare function totalMemory(): i64;
 export declare function monotonicNanos(): i64;
+export declare function wallClockNanos(): i64;
 export declare function statMtimeSync(path: string): f64;
 export declare function lstatOwnerModeSync(path: string): i64;
 export declare function geteuid(): i64;
@@ -69,6 +78,9 @@ export declare function spawn(argv: string[]): i32;
 export declare function waitPid(pid: i32, flags: i32): i32[];
 export declare function signalFd(): i32;
 export declare function readSignal(fd: i32): i32;
+/** These two have no reading under Node: each throws, naming itself. */
+export declare function setNice(n: i32): i32;
+export declare function setIdlePriority(): i32;
 /** What each `nish:net` function is under the core: a throw naming `name`. */
 export declare function noNetReading(name: string): never;
 /** What `readStdin`, `waitStdin`, `setRawMode` and `setTerminalRestore` are under the core: a throw naming `name`. */

package/runtime/core/host.mjs

@@ -15,9 +15,11 @@
  * its own fails loudly rather than writing nowhere.
  *
  * The functions that have no synchronous reading under Node (`spawn`,
- * `waitPid`, `signalFd`, `readSignal`, the `nish:net` set) throw here without
- * asking any host.
+ * `waitPid`, `signalFd`, `readSignal`, the `nish:net` set), and `setNice` and
+ * `setIdlePriority`, which have none at all, throw here without asking any
+ * host.
  */
+import { panicSlice, toIndex } from "./checks.mjs";
 
 /** What every member of the default host throws: no adapter has been imported. */
 export class NishNoHost extends Error {
@@ -86,6 +88,18 @@ export function writeError(s) {
   host.writeErr(s);
 }
 
+/**
+ * `writeBytes(bytes, off, len)`: the range checked as the compiled call checks
+ * it, `0 <= off <= off + len <= bytes.length`, through the slice panic, then
+ * the host's write of those bytes to stdout.
+ */
+export function writeBytes(bytes, off, len) {
+  const from = toIndex(off);
+  const to = from + toIndex(len);
+  if (!(from >= 0 && from <= to && to <= bytes.length)) panicSlice(from, to, bytes.length);
+  return host.call("writeBytes", [bytes, from, to]);
+}
+
 /** `panic(message)`: the message on stderr, then exit 1. */
 export function panic(message) {
   host.writeErr(`${message}\n`);
@@ -131,6 +145,30 @@ export function appendFileSync(path, data) {
   return host.call("appendFileSync", [path, data]);
 }
 
+export function writeFileBytesSync(path, bytes) {
+  return host.call("writeFileBytesSync", [path, bytes]);
+}
+
+export function renameSync(from, to) {
+  return host.call("renameSync", [from, to]);
+}
+
+export function unlinkSync(path) {
+  return host.call("unlinkSync", [path]);
+}
+
+export function writeFileSyncMode(path, data, mode) {
+  return host.call("writeFileSyncMode", [path, data, mode]);
+}
+
+export function createFileExclusiveSync(path, data, mode) {
+  return host.call("createFileExclusiveSync", [path, data, mode]);
+}
+
+export function mkdirSyncMode(path, mode) {
+  return host.call("mkdirSyncMode", [path, mode]);
+}
+
 export function mkdirSync(path) {
   return host.call("mkdirSync", [path]);
 }
@@ -167,6 +205,18 @@ export function spawnSyncTo(argv, out, err) {
   return host.call("spawnSyncTo", [argv, out, err]);
 }
 
+/**
+ * `spawnPiped(argv, stdin, stdout, stderr)`: the host runs the child and hands
+ * back its status and both streams' bytes, and they are appended here, as the
+ * runtime appends them to the caller's arrays.
+ */
+export function spawnPiped(argv, input, out, err) {
+  const [status, outBytes, errBytes] = host.call("spawnPiped", [argv, input]);
+  for (const b of outBytes) out.push(b);
+  for (const b of errBytes) err.push(b);
+  return status;
+}
+
 export function kill(pid, sig) {
   return host.call("kill", [pid, sig]);
 }
@@ -183,6 +233,10 @@ export function monotonicNanos() {
   return host.call("monotonicNanos", []);
 }
 
+export function wallClockNanos() {
+  return host.call("wallClockNanos", []);
+}
+
 export function statMtimeSync(path) {
   return host.call("statMtimeSync", [path]);
 }
@@ -259,6 +313,24 @@ export function waitPid() {
   return noProcessReading("waitPid");
 }
 
+/**
+ * `setNice(n)` and `setIdlePriority()` have no reading under Node: Node has one
+ * of the nice value (`os.setPriority`) but none of `SCHED_IDLE`, and a reading
+ * of one without the other would differ from the native build on the same host.
+ * Each throws, naming itself, as `runtime/nish.mjs` does.
+ */
+function noSchedulingReading(name) {
+  throw new Error(`\`${name}\` has no reading under Node: it changes how the kernel schedules the native program`);
+}
+
+export function setNice() {
+  return noSchedulingReading("setNice");
+}
+
+export function setIdlePriority() {
+  return noSchedulingReading("setIdlePriority");
+}
+
 /**
  * `signalFd()` and `readSignal(fd)` have no faithful reading under Node, and
  * these say so rather than answer something else. Node delivers a signal to

package/runtime/nish.d.ts

@@ -227,6 +227,12 @@ declare function readCString(p: CPtr): string;
 declare function write(s: string): void;
 /** `s` to stderr, likewise. */
 declare function writeError(s: string): void;
+/**
+ * `bytes[off .. off + len)` to stdout, every byte as it is, partial writes and
+ * interruptions retried: the count, or a negative errno. A range outside
+ * `bytes` panics, as `dst.set` does. The shape is `netWrite`'s.
+ */
+declare function writeBytes(bytes: readonly u8[], off: i32, len: i32): i32;
 /**
  * `message` and a newline to stderr, then exit 1. Terminates control flow, so
  * it is `never`: that is what lets `tsc` agree that a function ending in a
@@ -257,6 +263,46 @@ declare function readFileBytesSync(path: string): u8[] | null;
 declare function writeFileSync(path: string, data: string): void;
 /** `data` added at the end of the file, with the same refusal of a symbolic link. */
 declare function appendFileSync(path: string, data: string): void;
+/**
+ * The file's contents replaced by `bytes`, created at 0644 when missing, with
+ * the same refusal of a symbolic link: the byte count, or a negative errno.
+ * Never an exit.
+ */
+declare function writeFileBytesSync(path: string, bytes: readonly u8[]): i32;
+/**
+ * `from` moved to `to`, replacing a file there in one step on one file system:
+ * 0, or a negative errno (-18 across file systems, -2 for a missing `from`).
+ */
+declare function renameSync(from: string, to: string): i32;
+/** The name `path` removed: 0, or a negative errno. A directory is refused, not removed. */
+declare function unlinkSync(path: string): i32;
+/**
+ * `writeFileSync` with an explicit `mode`: the file is exactly `mode`
+ * (`0o600` for a secret) before a byte of `data` is in it, whatever the umask
+ * or a file already there had, and a symbolic link at the path is refused
+ * (-40). The byte count, or a negative errno: -22 for a mode outside
+ * 0..0o777, the setuid, setgid and sticky bits included. The file is
+ * truncated and written in place, so a crash or a failed write leaves it
+ * empty or partial, and a file this process may write but does not own is
+ * emptied before the mode change answers -1 (`EPERM`). For a file that must
+ * be the old one or the new one, write a temporary name with this and move it
+ * with `renameSync`. Never an exit.
+ */
+declare function writeFileSyncMode(path: string, data: string, mode: i32): i32;
+/**
+ * `data` in a new file of exactly `mode`, created only if nothing is at `path`:
+ * -17 when something is, a dangling symbolic link included. Of several
+ * processes racing for one path exactly one succeeds, so it takes a lock. The
+ * byte count, or a negative errno; a write that fails after the create
+ * removes the file, so the lock is not left taken. Never an exit.
+ */
+declare function createFileExclusiveSync(path: string, data: string, mode: i32): i32;
+/**
+ * One directory made with `mode` less the umask (`0o700` is exact under any
+ * umask that leaves the owner's bits): 0, or a negative errno. A path already
+ * there is -17 and its mode is not changed; -22 for a mode outside 0..0o777.
+ */
+declare function mkdirSyncMode(path: string, mode: i32): i32;
 /** One directory, not recursive; whether a directory is there afterwards. */
 declare function mkdirSync(path: string): boolean;
 /** Whether a directory is at `path` right now. One `stat`, and never an exit. */
@@ -280,6 +326,13 @@ declare function spawnSync(argv: string[]): number;
  * either path is refused, as `writeFileSync` refuses one, and the answer is -1.
  */
 declare function spawnSyncTo(argv: string[], stdoutPath: string, stderrPath: string): number;
+/**
+ * The same run with all three streams on pipes: `stdin` is written to the
+ * child and closed, and what it prints is appended to `stdout` and `stderr`.
+ * The status as `spawnSync` answers it, or -2 when a stream passed 16 MiB:
+ * the child is then killed and each array keeps at most the first 16 MiB.
+ */
+declare function spawnPiped(argv: string[], stdin: readonly u8[], stdout: u8[], stderr: u8[]): i32;
 /**
  * Start `argv[0]` through `PATH` without waiting: the child's pid, or a
  * negative errno. The child is the program's until `waitPid` reaps it. No
@@ -302,6 +355,21 @@ declare function waitPid(pid: i32, flags: i32): i32[];
 declare function availableParallelism(): i32;
 /** Bytes of physical memory, or -1 when the host does not say. */
 declare function totalMemory(): i64;
+/**
+ * Set this process's nice value to `n`: 0, or a negative errno. The kernel
+ * clamps `n` to -20..19, and lowering it below the current value needs the
+ * privilege to (-13 without it on Linux). Children started afterwards inherit
+ * it. Throws under Node.
+ */
+declare function setNice(n: i32): i32;
+/**
+ * Move this process to `SCHED_IDLE`, which runs it only when nothing else wants
+ * the CPU: 0, or a negative errno, and -95 where the host has no such policy
+ * (Darwin). An unprivileged process can never leave `SCHED_IDLE` again, and an
+ * idle process can starve on a saturated machine, so a caller keeps a
+ * normal-priority fallback for work that must finish. Throws under Node.
+ */
+declare function setIdlePriority(): i32;
 /** One environment variable, or `null` when it is unset (an empty value is a set variable). */
 declare function getenv(name: string): string | null;
 /**
@@ -309,6 +377,11 @@ declare function getenv(name: string): string | null;
  * origin is arbitrary, so only the difference between two reads is meaningful.
  */
 declare function monotonicNanos(): i64;
+/**
+ * The wall clock in nanoseconds since the Unix epoch, for dating an event. It
+ * steps when the system time is set, so a duration is `monotonicNanos`'s.
+ */
+declare function wallClockNanos(): i64;
 /**
  * The modification time of `path` in milliseconds since the epoch, with the
  * sub-millisecond fraction the file system keeps (Node's `mtimeMs`), or NaN
@@ -381,6 +454,26 @@ declare function pollModify(loop: i32, fd: i32, events: i32, token: i32): i32;
 declare function pollRemove(loop: i32, fd: i32): i32;
 /** Wait up to `timeoutMs` (negative: forever); pairs `ready[2k]` token, `ready[2k + 1]` events (4: hang-up or error). */
 declare function pollWait(loop: i32, ready: i32[], timeoutMs: i32): i32;
+/**
+ * Set one socket option from a whitelist: `option` is one of the `NET_*` ids
+ * below, and any other is -22; there is no raw level and option number. 0, or
+ * a negative errno (-9 a closed descriptor, -88 not a socket).
+ */
+declare function netSetOption(fd: i32, option: i32, value: i32): i32;
+/** `TCP_NODELAY`: `value` 1 sends a small write at once, 0 lets Nagle batch it. */
+declare const NET_TCP_NODELAY: i32;
+/**
+ * `TCP_QUICKACK` (Linux; -95 elsewhere): `value` 1 acknowledges at once, 0
+ * delays. Linux does not keep quick-ACK mode: the kernel leaves it on its own,
+ * so a server that wants a mode sets it again after every response.
+ */
+declare const NET_TCP_QUICKACK: i32;
+/** `SO_KEEPALIVE`: `value` 1 probes an idle connection, 0 does not. */
+declare const NET_SO_KEEPALIVE: i32;
+/** `SO_SNDBUF`: the send buffer, `value` in bytes; Linux doubles the value it stores. */
+declare const NET_SO_SNDBUF: i32;
+/** `SO_RCVBUF`: the receive buffer, `value` in bytes; Linux doubles the value it stores. */
+declare const NET_SO_RCVBUF: i32;
 
 // ---- `nish:term` ------------------------------------------------------------------
 //
@@ -433,6 +526,9 @@ declare var crypto: {
 //
 // `docs/LANGUAGE.md` -> Builtins -> Builtin modules is the normative list.
 
+// Every negative errno a file call answers is the platform's own, untranslated:
+// the numbers shown here are Linux's (-2 ENOENT, -17 EEXIST, -18 EXDEV, -22
+// EINVAL, -40 ELOOP), and Darwin's differ (ELOOP is -62 there).
 declare module "nish:fs" {
   export function readFileSync(path: string): string;
   export function readFileSyncOrNull(path: string): string | null;
@@ -441,6 +537,18 @@ declare module "nish:fs" {
   export function writeFileSync(path: string, data: string): void;
   /** Refuses a symbolic link as the last component of the path, as the global does. */
   export function appendFileSync(path: string, data: string): void;
+  /** The byte count, or a negative errno; refuses a symbolic link as `writeFileSync` does. */
+  export function writeFileBytesSync(path: string, bytes: readonly u8[]): i32;
+  /** 0, or a negative errno: -18 across file systems. */
+  export function renameSync(from: string, to: string): i32;
+  /** 0, or a negative errno: a directory is refused, not removed. */
+  export function unlinkSync(path: string): i32;
+  /** The byte count, or a negative errno; the file is exactly `mode` (0..0o777) before it holds a byte, a link refused, written in place. */
+  export function writeFileSyncMode(path: string, data: string, mode: i32): i32;
+  /** As `writeFileSyncMode`, but -17 when anything is at `path`: one racer wins; a failed write removes the file. */
+  export function createFileExclusiveSync(path: string, data: string, mode: i32): i32;
+  /** 0, or a negative errno: -17 for a path already there, whose mode is left alone. */
+  export function mkdirSyncMode(path: string, mode: i32): i32;
   /** `true` when the directory was created, `false` when it already existed. */
   export function mkdirSync(path: string): boolean;
   export function isDirectorySync(path: string): boolean;
@@ -465,6 +573,11 @@ declare module "nish:process" {
    * at either path is refused, and the answer is -1.
    */
   export function spawnSyncTo(argv: string[], stdoutPath: string, stderrPath: string): number;
+  /**
+   * The same run with `stdin` written to the child and its stdout and stderr
+   * appended to the two arrays: the status, or -2 past 16 MiB on a stream.
+   */
+  export function spawnPiped(argv: string[], stdin: readonly u8[], stdout: u8[], stderr: u8[]): i32;
   /** Start a child without waiting: its pid, or a negative errno. */
   export function spawn(argv: string[]): i32;
   /** Send 0, 2, 9 or 15 to `pid`: 0, or a negative errno; any other signal is -22. */
@@ -475,11 +588,21 @@ declare module "nish:process" {
   export function availableParallelism(): i32;
   /** Bytes of physical memory, or -1. */
   export function totalMemory(): i64;
+  /** Set this process's nice value (clamped to -20..19): 0, or a negative errno. */
+  export function setNice(n: i32): i32;
+  /**
+   * Move this process to `SCHED_IDLE`: 0, a negative errno, or -95 off Linux.
+   * An unprivileged process can never leave it, and an idle process can starve
+   * on a saturated machine, so a caller keeps a normal-priority fallback.
+   */
+  export function setIdlePriority(): i32;
   /**
    * A monotonic clock in nanoseconds. The origin is arbitrary, so only the
    * difference between two reads is meaningful.
    */
   export function monotonicNanos(): i64;
+  /** The wall clock in nanoseconds since the Unix epoch; it steps when the system time is set. */
+  export function wallClockNanos(): i64;
   /** A descriptor readable when SIGTERM or SIGINT arrives; the same one every call, or -1. */
   export function signalFd(): i32;
   /** Block until SIGTERM or SIGINT arrives: 15 or 2, or -1 for a descriptor that is not `signalFd()`'s. */
@@ -538,6 +661,26 @@ declare module "nish:net" {
   export function pollRemove(loop: i32, fd: i32): i32;
   /** Wait up to `timeoutMs` (negative: forever); pairs `ready[2k]` token, `ready[2k + 1]` events (4: hang-up or error). */
   export function pollWait(loop: i32, ready: i32[], timeoutMs: i32): i32;
+  /**
+   * Set one socket option from a whitelist: `option` is one of the `NET_*` ids
+   * below, and any other is -22; there is no raw level and option number. 0, or
+   * a negative errno (-9 a closed descriptor, -88 not a socket).
+   */
+  export function netSetOption(fd: i32, option: i32, value: i32): i32;
+  /** `TCP_NODELAY`: `value` 1 sends a small write at once, 0 lets Nagle batch it. */
+  export const NET_TCP_NODELAY: i32;
+  /**
+   * `TCP_QUICKACK` (Linux; -95 elsewhere): `value` 1 acknowledges at once, 0
+   * delays. Linux does not keep quick-ACK mode: the kernel leaves it on its own,
+   * so a server that wants a mode sets it again after every response.
+   */
+  export const NET_TCP_QUICKACK: i32;
+  /** `SO_KEEPALIVE`: `value` 1 probes an idle connection, 0 does not. */
+  export const NET_SO_KEEPALIVE: i32;
+  /** `SO_SNDBUF`: the send buffer, `value` in bytes; Linux doubles the value it stores. */
+  export const NET_SO_SNDBUF: i32;
+  /** `SO_RCVBUF`: the receive buffer, `value` in bytes; Linux doubles the value it stores. */
+  export const NET_SO_RCVBUF: i32;
 }
 
 declare module "nish:unsafe" {
@@ -560,6 +703,11 @@ declare module "nish:io" {
   export function write(s: string): void;
   /** The same, on stderr. */
   export function writeError(s: string): void;
+  /**
+   * `bytes[off .. off + len)` to stdout, every byte as it is: the count, or a
+   * negative errno. A range outside `bytes` panics, as `dst.set` does.
+   */
+  export function writeBytes(bytes: readonly u8[], off: i32, len: i32): i32;
   /** `message` to stderr, then exit 1. A terminator, as `process.exit` is. */
   export function panic(message: string): never;
 }

package/runtime/nish.h

@@ -396,6 +396,36 @@ nish_array *nish_readdir(const nish_str *path);
  * and the bytes live in the arena, so copy what you keep before the next reset
  * or release. */
 nish_array *nish_read_file_bytes(const nish_str *path);
+/* `renameSync(from, to)`, `unlinkSync(path)` and `writeFileBytesSync(path,
+ * bytes)`: rename(2), unlink(2), and every element of a `u8[]` written to a
+ * file opened as `nish_write_file` opens it (`O_TRUNC`, 0644, a link refused).
+ * None exits: each answers 0 (the write, the length written) or a negative
+ * errno — -EXDEV for a rename across file systems, which moves nothing, and
+ * -EISDIR or -EPERM for a directory handed to `nish_unlink`, which never calls
+ * rmdir. A path holding a NUL answers -EINVAL, not -ENOENT, so a program can
+ * tell a malformed path from a missing file. The numbers are the platform's
+ * errno values, untranslated: -ELOOP is -40 on Linux and -62 on Darwin. */
+int32_t nish_rename(const nish_str *from, const nish_str *to);
+int32_t nish_unlink(const nish_str *path);
+int32_t nish_write_file_bytes(const nish_str *path, const nish_array *bytes);
+/* `writeFileSyncMode(path, data, mode)`, `createFileExclusiveSync(path, data,
+ * mode)` and `mkdirSyncMode(path, mode)`: a file written, or created only if
+ * nothing is at the path (`O_EXCL`), then `fchmod`ed to exactly `mode` before a
+ * byte is written; a directory made with `mode & ~umask`. A link at a file's
+ * path is refused. The file writers answer the byte count and `nish_mkdir_mode`
+ * 0, or a negative platform errno: -EEXIST for an exclusive create or a mkdir
+ * that finds the path taken (a directory's mode is then left alone), -EINVAL
+ * for a mode outside 0..0777 (the setuid, setgid and sticky bits included) or
+ * a path holding a NUL, -ENOSYS under WASI. A failed exclusive create leaves
+ * no file behind. */
+int32_t nish_write_file_mode(const nish_str *path, const nish_str *data, int32_t mode);
+int32_t nish_create_file_exclusive(const nish_str *path, const nish_str *data, int32_t mode);
+int32_t nish_mkdir_mode(const nish_str *path, int32_t mode);
+/* `writeBytes(bytes, off, len)` (nish:io), in runtime-os.c: the bytes
+ * `[off, off + len)` of a `u8[]` on stdout, a short write finished and `EINTR`
+ * retried. The caller has range-checked `off` and `len`. Answers `len`, or the
+ * negative errno of the write that failed; never exits. */
+int32_t nish_write_bytes(const nish_array *bytes, int64_t off, int64_t len);
 /* `spawnSync(argv)`: run element 0 of `argv` (searched on `PATH`) with `argv`
  * as its argument vector, wait for it, and answer its exit status, or
  * `128 + n` when signal `n` killed it. -1 when `argv` is empty, when the
@@ -422,6 +452,17 @@ int32_t nish_spawn_to(const nish_array *argv, const nish_str *out, const nish_st
  * own error otherwise, and -ENOSYS under WASI. The child is reaped by
  * `nish_wait_pid`. */
 int32_t nish_spawn_child(const nish_array *argv);
+/* `spawnPiped(argv, stdin, stdout, stderr)`: start element 0 of `argv` as
+ * `nish_spawn` does, with the bytes of `stdin` (a `u8[]`) on its standard input
+ * and its standard output and error appended to `stdout` and `stderr`, wait for
+ * it, and answer `nish_spawn`'s status. -1 is `nish_spawn`'s -1, a pipe or
+ * `poll` that fails included, and always under WASI. -2 is a stream that passed
+ * 16 MiB: the child is killed with SIGKILL and reaped, and that array holds the
+ * stream's first 16 MiB. The two output arrays grow as `push` grows them, so
+ * the compiler treats both as pushed. `stdin` is read in place and never
+ * copied; SIGPIPE is blocked on the calling thread for the call, a SIGPIPE the
+ * call raised is consumed, and the thread's mask is restored after it. */
+int32_t nish_spawn_piped(const nish_array *argv, const nish_array *in, nish_array *out, nish_array *err);
 /* `kill(pid, sig)`: send `sig` to `pid` and answer 0, or a negative errno. Only
  * 0, 2 (SIGINT), 9 (SIGKILL) and 15 (SIGTERM) are sent; any other signal, and
  * a pid of 0 or below, is -EINVAL. -ESRCH when no process has the pid, -EPERM
@@ -438,6 +479,15 @@ nish_array *nish_wait_pid(int32_t pid, int32_t flags);
 /* `totalMemory()`: bytes of physical memory (Linux: `_SC_PHYS_PAGES` times the
  * page size; Darwin: `hw.memsize`), or -1 where the host does not say. */
 int64_t nish_total_memory(void);
+/* `setNice(n)`: this process's nice value set to `n` (`setpriority`), 0 or a
+ * negative errno. The kernel clamps `n` to -20..19; lowering it below the
+ * current value without the privilege is -EACCES (or -EPERM). -ENOSYS under
+ * WASI. */
+int32_t nish_set_nice(int32_t n);
+/* `setIdlePriority()`: this process moved to `SCHED_IDLE` (Linux), 0 or a
+ * negative errno; -95 (Linux's EOPNOTSUPP) elsewhere, -ENOSYS under WASI. An
+ * unprivileged process cannot leave the policy again. */
+int32_t nish_set_idle_priority(void);
 
 /* ---- The environment (WP19 R1) ------------------------------------------
  * `getenv(name)`: the value of environment variable `name`, copied into the
@@ -485,6 +535,10 @@ const nish_str *nish_arch(void);
  * purpose: `readnone` would let LLVM fold the two reads around a measured
  * region into one and measure zero. */
 int64_t nish_monotonic_nanos(void);
+/* `wallClockNanos()`: `CLOCK_REALTIME` in nanoseconds since the epoch, the
+ * clock `Date.now` reads at a millisecond's grain. It steps when the system
+ * time is set, so it dates an event and measures nothing. */
+int64_t nish_wall_clock_nanos(void);
 
 /* ---- The host (WP34 N3), runtime/runtime-host.c --------------------------
  * `Date.now()`: the wall clock, `CLOCK_REALTIME`, in whole milliseconds since
@@ -542,6 +596,10 @@ bool nish_is_executable(const nish_str *path);
  * len)` of `buf`, which the compiled call has range-checked; a write to a
  * gone peer is -32, never SIGPIPE. `nish_net_shutdown(fd, how)`: 0 read, 1
  * write, 2 both. `nish_net_close(fd)`.
+ * `nish_net_set_option(fd, option, value)`: one socket option from a
+ * whitelist, by the runtime's own id (1 `TCP_NODELAY`, 2 `TCP_QUICKACK`, 3
+ * `SO_KEEPALIVE`, 4 `SO_SNDBUF`, 5 `SO_RCVBUF`); any other id is -22, and
+ * `TCP_QUICKACK` off Linux is -95.
  * `nish_tcp_connect(addr)`: a new socket connecting to `addr`, answered at
  * once; its `EINPROGRESS` is not a failure, and any other closes it.
  * `nish_connect_result(fd)`: `SO_ERROR` once the socket is writable, 0 when
@@ -576,6 +634,7 @@ int32_t nish_net_read(int32_t fd, nish_array *buf, int64_t off, int64_t len);
 int32_t nish_net_write(int32_t fd, const nish_array *buf, int64_t off, int64_t len);
 int32_t nish_net_shutdown(int32_t fd, int32_t how);
 int32_t nish_net_close(int32_t fd);
+int32_t nish_net_set_option(int32_t fd, int32_t option, int32_t value);
 int32_t nish_tcp_connect(const nish_array *addr);
 int32_t nish_connect_result(int32_t fd);
 int32_t nish_udp_bind(const nish_str *host, int32_t port, int32_t flags);