# gizlang:system

The program's authority: files, network, arguments and environment. A process receives it as `main(sys: System)`; library code can use only what it is passed, and every value here has private fields, so none can be forged. Directories, streams, listeners and sockets belong to the task that opened them and close when it ends; using one after it closed is fault 14. Reads, writes, connects, accepts and receives suspend only the calling task. Failures a program should handle are `IoError` values.

```gizlang
import * as System from "gizlang:system";
```

## Types

### `System`

```gizlang
type System
```

The handle of the running system: its files, clock, processes and network.

Opaque: create and use it through this module's functions.

### `DirectoryEntries`

```gizlang
type DirectoryEntries
```

A directory that is being listed, entry by entry.

Opaque: create and use it through this module's functions.

### `Dir`

```gizlang
type Dir
```

An open directory: files and folders are opened below it.

Opaque: create and use it through this module's functions.

### `Stream`

```gizlang
type Stream
```

An open byte stream, such as a file or a pipe.

Opaque: create and use it through this module's functions.

### `Listener`

```gizlang
type Listener
```

A listening socket that accepts connections.

Opaque: create and use it through this module's functions.

### `Socket`

```gizlang
type Socket
```

A connected socket.

Opaque: create and use it through this module's functions.

### `Ready`

```gizlang
type Ready
```

Connections waiting without a task, reported when bytes arrive (Ready.wait).

Opaque: create and use it through this module's functions.

### `Signals`

```gizlang
type Signals
```

Process signals a task reads one at a time (System.signals).

Opaque: create and use it through this module's functions.

### `Datagram`

```gizlang
type Datagram = { data: bytes; host: string; port: i64; }
```

One received UDP datagram and the address and port it came from.

- `data`: `bytes`
- `host`: `string`
- `port`: `i64`

### `IoError`

```gizlang
type IoError = { code: i64; }
```

A platform error code (negative, as libuv reports it) or a Gizlang one.

- `code`: `i64`

### `ProcessUsage`

```gizlang
type ProcessUsage = { residentBytes: i64; peakBytes: i64; userMicros: i64; systemMicros: i64; readBytes: i64; writtenBytes: i64; }
```

The resources that the process used: resident and peak memory (the peak since this program started, not its parent
before exec), CPU time and bytes read and written.

- `residentBytes`: `i64`
- `peakBytes`: `i64`
- `userMicros`: `i64`
- `systemMicros`: `i64`
- `readBytes`: `i64`
- `writtenBytes`: `i64`

### `CgroupUsage`

```gizlang
type CgroupUsage = { path: string; memoryBytes: Option<i64>; cpuMicros: i64; readBytes: Option<i64>; writtenBytes: Option<i64>; }
```

The resources of the control group that the process runs in; a limit that the system does not report is none.

- `path`: `string`
- `memoryBytes`: `_gizlang_sdk_core.Option<i64>`
- `cpuMicros`: `i64`
- `readBytes`: `_gizlang_sdk_core.Option<i64>`
- `writtenBytes`: `_gizlang_sdk_core.Option<i64>`

### `Usage`

```gizlang
type Usage = { process: ProcessUsage; cgroup: Option<CgroupUsage>; }
```

The resource use of the process, and of its control group when there is one.

- `process`: `gizlang_system.ProcessUsage`
- `cgroup`: `_gizlang_sdk_core.Option<gizlang_system.CgroupUsage>`

### `FileInfo`

```gizlang
type FileInfo = { size: i64; modified: i64; kind: string; mode: i64; }
```

What a file is: its size, the time it was modified (ms), its kind and its mode bits.

- `size`: `i64`
- `modified`: `i64`
- `kind`: `string`
- `mode`: `i64`

### `FileClone`

```gizlang
type FileClone = | { kind: "reflink"; } | { kind: "hardLink"; }
```

How a file is cloned: a copy-on-write reflink, or a hard link.

- `reflink`
- `hardLink`

### `ProcessMemory`

```gizlang
type ProcessMemory = { residentBytes: i64; peakBytes: i64; }
```

The resident memory of process PID and its peak, on every OS.

- `residentBytes`: `i64`
- `peakBytes`: `i64`

### `EnvironmentVariable`

```gizlang
type EnvironmentVariable = { name: string; value: string; }
```

One environment variable.

- `name`: `string`
- `value`: `string`

### `StreamPair`

```gizlang
type StreamPair = { first: Stream; second: Stream; }
```

Two connected streams inside this process: what one writes the other
reads, until either closes. A loop watching `first` in its Ready set is
woken by a write to `second` (from a task, a ticker, or itself).

- `first`: `gizlang_system.Stream`
- `second`: `gizlang_system.Stream`

### `Watch`

```gizlang
type Watch = { stream: Stream; rest: bytes; }
```

The changes to the entries of folder `path` ("" is this one) as they happen, until it is closed: Linux inotify.

- `stream`: `gizlang_system.Stream`
- `rest`: `bytes`

### `WatchEvent`

```gizlang
type WatchEvent = { wd: i64; mask: i64; name: string; }
```

One change: the watch number of the folder, what happened (the WATCH_ bits, Linux inotify's) and the entry's name
("" for the folder itself).

- `wd`: `i64`
- `mask`: `i64`
- `name`: `string`

### `ProxyHeader`

```gizlang
type ProxyHeader = { size: i64; address: string; }
```

The PROXY protocol header (HAProxy, versions 1 and 2) that a load balancer writes first on a connection it forwards:
`size` bytes, and the client `address` (without port; IPv6 as eight groups of four hex digits), or "" for a LOCAL or UNKNOWN connection
(the balancer's own health check), whose peer stays the socket's.

- `size`: `i64`
- `address`: `string`

### `Stdio`

```gizlang
type Stdio = | { kind: "inherit" } | { kind: "pipe" } | { kind: "ignore" } | { kind: "stream"; stream: Stream; }
```

Standard streams and child processes use the same task-owned Stream handles.

- `inherit`
- `pipe`
- `ignore`
- `stream`

### `Limits`

```gizlang
type Limits = { memory: i64; cpu: i64; processes: i64; }
```

At most MEMORY bytes (over it the whole process tree is killed), CPU in
thousandths of a core (1000: one core), PROCESSES processes and threads;
0 leaves that one unlimited. A Gizlang program stops itself with R011 at four
fifths of MEMORY, before the kernel kills it.

- `memory`: `i64`
- `cpu`: `i64`
- `processes`: `i64`

### `ProcessGrant`

```gizlang
type ProcessGrant = | { kind: "listener"; value: Listener; } | { kind: "stream"; value: Stream; }
```

Explicit process resources. Both variants use the same inherited descriptor slots.

- `listener`
- `stream`

### `SpawnOptions`

```gizlang
type SpawnOptions = { stdin: Stdio; stdout: Stdio; stderr: Stdio; cwd: Option<string>; environment: Vec<string>; inheritEnvironment: bool; isolated: bool; handed: Vec<ProcessGrant>; limits: Limits; }
```

The options of a started process: its three streams, working folder, environment and isolation.

- `stdin`: `gizlang_system.Stdio`
- `stdout`: `gizlang_system.Stdio`
- `stderr`: `gizlang_system.Stdio`
- `cwd`: `_gizlang_sdk_core.Option<string>`
- `environment`: `Vec<string>`
- `inheritEnvironment`: `bool` — False starts with only environment additions and runtime resource
grants. Host secrets and unmentioned environment entries are absent.
- `isolated`: `bool` — Confined to `cwd` as its whole filesystem, with no network or other
process in reach (Linux); a Gizlang program only.
- `handed`: `Vec<gizlang_system.ProcessGrant>` — Resources inherited as descriptors 3, 4, ... (at most 16): listeners, and streams with an OS descriptor (a file
grant, an imported descriptor, a sys.streamPair end). Listener grants are received through sys.handed(index); a
stream through sys.importDescriptor(3 + index, ...); native programs use the descriptor ABI.
- `limits`: `gizlang_system.Limits` — Resource limits (Linux cgroup v2, below a delegated cgroup of the
spawner's); a Gizlang program only, which exits 71
rather than run without them.

### `Child`

```gizlang
type Child
```

A started process.

Opaque: create and use it through this module's functions.

### `ExitStatus`

```gizlang
type ExitStatus = | { kind: "code"; code: i64 } | { kind: "signal"; signal: i64 }
```

How a process ended: with an exit code, or by a signal.

- `code`
- `signal`

### `Output`

```gizlang
type Output = { status: ExitStatus; stdout: bytes; stderr: bytes; }
```

What a process printed and how it ended.

- `status`: `gizlang_system.ExitStatus`
- `stdout`: `bytes`
- `stderr`: `bytes`

### `Ran`

```gizlang
type Ran = { code: i64; out: string; err: string; }
```

A finished process as text: its exit code (`ExitStatus.exitCode`) and its two outputs. Tools that run programs and
read their output as text use it (the CLI, the test harness, the fleet tools).

- `code`: `i64`
- `out`: `string`
- `err`: `string`

### `CaptureBudget`

```gizlang
type CaptureBudget = { milliseconds: i64; outputBytes: i64; }
```

Capture bounds are independent of SpawnOptions' OS resource limits.

- `milliseconds`: `i64`
- `outputBytes`: `i64`

### `CapturedOutput`

```gizlang
type CapturedOutput = { output: Output; outputLimit: bool; }
```

The output of a process, and whether it was cut at the output limit.

- `output`: `gizlang_system.Output`
- `outputLimit`: `bool`

### `Stat`

```gizlang
type Stat = { dev: i64; mode: i64; nlink: i64; uid: i64; gid: i64; rdev: i64; blksize: i64; ino: i64; size: i64; blocks: i64; atimeSec: i64; atimeNsec: i64; mtimeSec: i64; mtimeNsec: i64; ctimeSec: i64; ctimeNsec: i64; birthSec: i64; birthNsec: i64; }
```

Everything stat(2) reports (statx on Linux), times as seconds and nanoseconds. birth is ctime when the file
system does not keep a birth time, as libuv reports it.

- `dev`: `i64`
- `mode`: `i64`
- `nlink`: `i64`
- `uid`: `i64`
- `gid`: `i64`
- `rdev`: `i64`
- `blksize`: `i64`
- `ino`: `i64`
- `size`: `i64`
- `blocks`: `i64`
- `atimeSec`: `i64`
- `atimeNsec`: `i64`
- `mtimeSec`: `i64`
- `mtimeNsec`: `i64`
- `ctimeSec`: `i64`
- `ctimeNsec`: `i64`
- `birthSec`: `i64`
- `birthNsec`: `i64`

### `StatFs`

```gizlang
type StatFs = { type: i64; bsize: i64; blocks: i64; bfree: i64; bavail: i64; files: i64; ffree: i64; }
```

The numbers of a file system, as `statfs` reports them.

- `type`: `i64`
- `bsize`: `i64`
- `blocks`: `i64`
- `bfree`: `i64`
- `bavail`: `i64`
- `files`: `i64`
- `ffree`: `i64`

### `DirEntry`

```gizlang
type DirEntry = { name: string; kind: i64; }
```

A directory entry and its kind: the UV_DIRENT values (0 unknown, 1 file, 2 dir, 3 link, 4 fifo, 5 socket, 6 char, 7 block).

- `name`: `string`
- `kind`: `i64`

### `Ring`

```gizlang
type Ring
```

An io_uring of 128-byte submissions for passthrough commands (IORING_OP_URING_CMD): the ublk control and queue
commands, NVMe passthrough. Each command carries USER_DATA, and its completion comes back with it. Linux only:
elsewhere System.ring fails. Close it with close.

Opaque: create and use it through this module's functions.

### `Completion`

```gizlang
type Completion = { userData: i64; result: i64; }
```

A completed command: the USER_DATA it was queued with and its result (negative: -errno).

- `userData`: `i64`
- `result`: `i64`

### `TerminalSize`

```gizlang
type TerminalSize = { columns: i64; rows: i64; }
```

The size of a terminal in columns and rows.

- `columns`: `i64`
- `rows`: `i64`

### `OsInfo`

```gizlang
type OsInfo = { sysname: string; release: string; version: string; machine: string; }
```

The operating system: its name, release, version and machine type.

- `sysname`: `string`
- `release`: `string`
- `version`: `string`
- `machine`: `string`

### `MemoryInfo`

```gizlang
type MemoryInfo = { total: i64; available: i64; }
```

Physical memory in bytes: all of it, and what the OS can give without swapping (Linux MemAvailable, macOS free and
inactive pages, Windows available physical memory; Node's os.totalmem and os.freemem).

- `total`: `i64`
- `available`: `i64`

### `CpuInfo`

```gizlang
type CpuInfo = { model: string; speed: i64; user: i64; nice: i64; sys: i64; idle: i64; irq: i64; }
```

The time of one CPU: its model, speed and the time it spent in each mode.

- `model`: `string`
- `speed`: `i64`
- `user`: `i64`
- `nice`: `i64`
- `sys`: `i64`
- `idle`: `i64`
- `irq`: `i64`

### `Interface`

```gizlang
type Interface = { name: string; address: string; netmask: string; family: string; mac: string; internal: bool; scopeId: i64; }
```

A network interface: its name, address, netmask, family, MAC address, whether it is internal, and its scope id.

- `name`: `string`
- `address`: `string`
- `netmask`: `string`
- `family`: `string`
- `mac`: `string`
- `internal`: `bool`
- `scopeId`: `i64`

### `UserInfo`

```gizlang
type UserInfo = { uid: i64; gid: i64; username: string; homedir: string; shell: string; }
```

A user of the system: ids, name, home folder and shell.

- `uid`: `i64`
- `gid`: `i64`
- `username`: `string`
- `homedir`: `string`
- `shell`: `string`

### `Credentials`

```gizlang
type Credentials = { uid: i64; euid: i64; gid: i64; egid: i64; groups: Vec<i64>; }
```

The user and group ids that the process runs with; -1 and no groups on Windows.

- `uid`: `i64`
- `euid`: `i64`
- `gid`: `i64`
- `egid`: `i64`
- `groups`: `Vec<i64>`

## Functions

### `osError`

```gizlang
function osError(code: i64): IoError
```

The IoError of CODE, a code the runtime or the OS gave: the Linux number of its name on every OS, so that it
compares with NOT_FOUND and the other names.

### `ioMessage`

```gizlang
function ioMessage<T>(result: Result<T, IoError>, what: string): T throws string
```

RESULT with its error as WHAT, a colon and the error's message, for a caller that reports plain text.

### `publicAddress`

```gizlang
function publicAddress(address: string): bool
```

Whether `address` (as System.addresses returns it) is on the public
internet: false for loopback, private, carrier-grade NAT, link-local,
documentation, benchmarking, multicast and reserved IPv4 ranges, and for
their IPv6 counterparts (::1, unique local, link- and site-local,
multicast, documentation) and IPv6 forms that carry an IPv4 address
(mapped, compatible, NAT64, 6to4, Teredo) unless that address is public.
Not an address at all is false.

Effects: fail.

### `serveThreads`

```gizlang
function serveThreads<F>(self: System, count: i64, work: F): i64 throws IoError effects { work, io, fail }
```

work(own, i) for every i in 0..count: i = 0 on the calling thread with this System, each other i on an OS thread of its own (Task.thread)
with its own System. The requests they served, or the first error (a thread that faults is IO_FAILURE). A server that listens in each call
on one port (listenShared) has a reactor for each thread, and the kernel spreads the connections among them. What `work` captures is
shared read-only; state that every thread sees lives in a database, not in a thread's memory.

### `serveConnections`

```gizlang
function serveConnections(set: Ready, turnConnection: (stream: Stream) => i64): i64 throws IoError
```

The one scheduler of a server of any protocol: it answers the connections that the Ready set reports. `turn(stream)` reads
what the connection has sent, answers it, and returns the number of requests it served; it gives the connection back with
`set.watch(stream)` or closes it. A fault in a turn ends only its connection. Fill the set with `set.accept(listener)` (or let
a TLS layer fill it). It returns the sum of the counts when the set stops (the listener is closed; requests in flight
finish), or the error that stopped it. HTTP (gizlang:http) is a turn on this; so is a protocol you write.

Effects: fail, read, write, console, io.

### `ready`

```gizlang
function ready(idleMs: i64): Ready throws IoError
```

A set of connections that wait without a task, as epoll does: those it
accepts or is given to watch are reported once each by wait() when bytes
arrive or they end (bytes put back with unread do not count). A connection
watched and silent for idleMs (0: no limit) is reported too, and its read
fails with TIMED_OUT. It grants nothing: connections come from a Listener
or a Stream the caller holds.

Effects: fail, io.

### `peerClosed`

```gizlang
function peerClosed(descriptor: i64): bool
```

Whether the peer of socket DESCRIPTOR (Stream.descriptor) has closed its side, without taking any of its bytes, on any
thread; false for a socket still open or for another descriptor. A server's thread asks it during a long statement,
whose client may have left.

Effects: fail, io.

### `proxyHeader`

```gizlang
function proxyHeader(data: bytes): Option<ProxyHeader>
```

The PROXY header at the start of `data`, if it has a whole one.

Effects: fail.

### `spawnOptions`

```gizlang
function spawnOptions(): SpawnOptions
```

The default options of System.spawn: inherited standard streams and environment, no handed descriptors.

### `direntKind`

```gizlang
function direntKind(mode: i64): i64
```

The kind of a Stat's mode, as a DIRENT value.

Effects: fail.

## Methods

### `System.temporaryDir`

```gizlang
function System.temporaryDir(self: System): Dir throws IoError
```

A private fresh directory under $TMPDIR (else /tmp), recursively removed on
close or task termination.

Effects: fail, io.

### `Dir.temporaryPath`

```gizlang
function Dir.temporaryPath(self: Dir): string throws IoError
```

A new path in this directory that no file has, for a temporary file that the caller makes.

Effects: fail, io.

### `System.exit`

```gizlang
function System.exit(self: System, code: i64): bool throws IoError
```

End the process without printing main's result. Codes are 0..255.

Effects: fail, io.

### `IoError.message`

```gizlang
function IoError.message(self: IoError): string
```

The text of the error, as the operating system describes its code.

Effects: fail, io.

### `System.time`

```gizlang
function System.time(self: System): i64
```

The working directory.
Milliseconds since 1970-01-01 UTC by the system clock (gizlang:time reads them).

Effects: fail, io.

### `System.availableMemory`

```gizlang
function System.availableMemory(self: System): i64 throws IoError
```

The bytes the host can still give this process before it runs out: the machine's available memory, and on Linux the
room left in the process's cgroup and its ancestors (the allocator's own measure, Memory.roomBytes). This observation
is not a reservation. NOT_SUPPORTED where the OS does not tell.

Effects: fail, read.

### `System.processUsage`

```gizlang
function System.processUsage(self: System): ProcessUsage throws IoError
```

The process's resident memory, its peak, its CPU time and the bytes it read from and wrote to storage, on every OS.

Effects: fail, io.

### `System.usage`

```gizlang
function System.usage(self: System): Usage throws IoError
```

processUsage, and on Linux the totals of the process's cgroup. Cgroup totals include every process in the cgroup;
they are not allocator credit or a per-process reservation.

Effects: fail, io.

### `System.memoryOf`

```gizlang
function System.memoryOf(self: System, pid: i64): ProcessMemory throws IoError
```

The resident and peak memory of the process PID, in bytes.

Effects: fail, io.

### `System.entropy`

```gizlang
function System.entropy(self: System): u64
```

64 unpredictable bits from the operating system, to seed gizlang:random.

Effects: fail, io.

### `System.randomBytes`

```gizlang
function System.randomBytes(self: System, n: i64): bytes throws IoError
```

Secure bytes directly from the OS; zero is empty, negative lengths are EINVAL.

Effects: fail, io.

### `System.randomBelow`

```gizlang
function System.randomBelow(self: System, below: i64): i64 throws IoError requires below> 0 { const first = try self.randomBytes(RANDOM_WORD_BYTES)
```

Secure uniform integer in [below), with a fresh OS draw on each rejection.

Effects: fail, io.

### `System.files`

```gizlang
function System.files(self: System): Dir throws IoError
```

The working directory.

Effects: fail, io.

### `System.currentDirectory`

```gizlang
function System.currentDirectory(self: System): string throws IoError
```

Physical process working directory; never trust the mutable PWD environment.
OS namespace confinement applies to the existing realpath primitive.

Effects: fail, io.

### `System.absolute`

```gizlang
function System.absolute(self: System, path: string): string throws IoError
```

`path` unchanged when it is absolute, else read against currentDirectory.

Effects: fail, io.

### `System.copyFile`

```gizlang
function System.copyFile(self: System, from: string, to: string): i64 throws IoError
```

A bounded file copy, published through the same durable staging owner.

Effects: fail, read, write, console, io.

### `System.copyTree`

```gizlang
function System.copyTree(self: System, from: string, to: string): bool throws IoError
```

Copy an entry without following links; publish the completed tree once.

Effects: fail, read, write, console, io.

### `System.rename`

```gizlang
function System.rename(self: System, from: string, to: string): bool throws IoError
```

Rename between independently confined parent grants. EXDEV is explicit;
callers may copy regular files, but directory publication stays atomic.

Effects: fail, io.

### `System.move`

```gizlang
function System.move(self: System, from: string, to: string): bool throws IoError
```

Cross-device moves copy beside TO, rename the copy into place, and remove the source after that publication: a
reader of TO sees all of it or nothing. A copy straight into TO let another process read half of a shared cache
entry when the build folder was on another file system.

Effects: fail, read, write, console, io.

### `System.touch`

```gizlang
function System.touch(self: System, path: string): bool throws IoError
```

Dir.touch at PATH.

Effects: fail, io.

### `System.readFile`

```gizlang
function System.readFile(self: System, path: string): bytes throws IoError
```

The path forms of Dir.readFile, Dir.readBounded, Dir.replaceFile, Dir.appendFile and Dir.info: the
entry's directory is opened, used once and closed. One owner, so callers keep no
`directory(dirname)` wrappers of their own.

Effects: fail, io.

### `System.readBounded`

```gizlang
function System.readBounded(self: System, path: string, limit: i64): bytes throws IoError
```

The contents of the file PATH, failing when it is larger than LIMIT bytes.

Effects: fail, io.

### `System.replaceFile`

```gizlang
function System.replaceFile(self: System, path: string, data: bytes): i64 throws IoError
```

Atomic: a reader sees the old file or the new one, never part of it.

Effects: fail, read, write, console, io.

### `System.appendFile`

```gizlang
function System.appendFile(self: System, path: string, data: bytes): i64 throws IoError
```

Appends DATA to the file PATH, made when it is missing; the number of bytes written.

Effects: fail, io.

### `System.info`

```gizlang
function System.info(self: System, path: string): FileInfo throws IoError
```

The size, modification time, kind and mode of PATH.

Effects: fail, io.

### `System.exists`

```gizlang
function System.exists(self: System, path: string): bool
```

Whether PATH exists (`info` finds it).

Effects: fail, io.

### `System.realPath`

```gizlang
function System.realPath(self: System, path: string): string throws IoError
```

Resolve a path through the process namespace under the caller's System authority.

Effects: fail, io.

### `System.makeDirectories`

```gizlang
function System.makeDirectories(self: System, path: string): bool throws IoError
```

Create parents using physical path traversal, without lexical dot reduction.

Effects: fail, io.

### `System.removeTree`

```gizlang
function System.removeTree(self: System, path: string): bool throws IoError
```

Remove one caller-selected tree. Child links are removed, never traversed.

Effects: fail, io.

### `System.directory`

```gizlang
function System.directory(self: System, path: string): Dir throws IoError
```

A directory the program is given, relative to the working directory or
absolute (a path from the command line): everything opened through it stays
below it.

Effects: fail, io.

### `System.executable`

```gizlang
function System.executable(self: System): string throws IoError
```

This process's executable path from the OS, independent of argv[0] and
environment. The same path/encoding bounds apply as for realPath.

Effects: fail, io.

### `System.arguments`

```gizlang
function System.arguments(self: System): Vec<string>
```

The command-line arguments after the program name.

Effects: fail, io.

### `System.environment`

```gizlang
function System.environment(self: System, name: string): Option<string>
```

The value of the environment variable NAME, or none when it is not set.

Effects: fail, io.

### `System.environmentVariables`

```gizlang
function System.environmentVariables(self: System): Vec<EnvironmentVariable>
```

Every environment variable of this process, in the OS's order.

Effects: fail, io.

### `System.importDescriptor`

```gizlang
function System.importDescriptor(self: System, descriptor: i64, mode: i64): Stream throws IoError
```

Duplicate a descriptor returned by a native OS ABI into task-owned I/O.
The original remains caller-owned. Only READ/WRITE modes are accepted;
positionless devices/pipes use read/write, not readAt/writeAt.

Effects: fail, io.

### `Stream.duplicate`

```gizlang
function Stream.duplicate(self: Stream, mode: i64): Stream throws IoError
```

Duplicate a file/native-descriptor stream with independently owned I/O.
READ/WRITE permissions may only narrow. The logical file cursor is copied;
the OS open-file description (including flock ownership) remains shared.
TCP, TLS and in-process streams do not expose descriptor duplication.

Effects: fail, io.

### `Stream.release`

```gizlang
function Stream.release(self: Stream): i64 throws IoError
```

The connection as a descriptor of its own, for another thread of this process to take (System.adopt), and the
stream closed. A stream a Ready set holds, with TLS, or with bytes it read ahead is refused (EBUSY).

Effects: fail, io.

### `System.adopt`

```gizlang
function System.adopt(self: System, descriptor: i64): Stream throws IoError
```

The connected TCP socket at DESCRIPTOR (Stream.release on another thread of this process) as this thread's stream,
which a Ready set can watch. On an error the descriptor is closed.

Effects: fail, io.

### `System.streamPair`

```gizlang
function System.streamPair(self: System): StreamPair throws IoError
```

Two connected streams: what one writes, the other reads.

Effects: fail, io.

### `System.socket`

```gizlang
function System.socket(self: System): Stream throws IoError
```

Allocate an unconnected TCP stream in the current task. A deadline child may
connect/use it while this owner retains the handle and closes on uncertainty.

Effects: fail, io.

### `Stream.connect`

```gizlang
function Stream.connect(self: Stream, host: string, port: i64): bool throws IoError
```

Connects this stream to HOST and PORT.

Effects: fail, io.

### `System.connect`

```gizlang
function System.connect(self: System, host: string, port: i64): Stream throws IoError
```

A TCP connection to HOST and PORT.

Effects: fail, io.

### `System.connectUnix`

```gizlang
function System.connectUnix(self: System, path: string): Stream throws IoError
```

A connection to the unix-domain socket at `path` (at most 107 bytes): a
local server such as a database, and an isolated process's way to one
placed in its folder.

Effects: fail, io.

### `System.addresses`

```gizlang
function System.addresses(self: System, host: string): Vec<string> throws IoError
```

The IPv4 and IPv6 addresses of `host`: an address as it is (IPv4 in
dotted decimal without leading zeros, IPv6 with or without brackets), else
the addresses /etc/hosts lists for it, else the A and AAAA answers of the first name server in /etc/resolv.conf to
answer within RESOLVE_MS, asking the name as written (no search domains).
A program that must know where it connects, as a server fetching URLs it is
given, checks these (publicAddress) and connects to one of them, so no
second lookup can answer differently. UNKNOWN_HOST when no address is found.

Effects: fail, io.

### `System.texts`

```gizlang
function System.texts(self: System, host: string): Vec<string> throws IoError
```

The TXT records of `host` (the strings of each one joined), from the first name server in /etc/resolv.conf that has
any within RESOLVE_MS, asking the name as written. A domain's owner proves control with one (a verification token,
an ACME DNS-01 challenge). UNKNOWN_HOST when there is none.

Effects: fail, io.

### `System.textsFrom`

```gizlang
function System.textsFrom(self: System, server: string, port: i64, host: string): Vec<string> throws IoError
```

The TXT records of `host` as the name server at `server` (an address) and `port` answers them within RESOLVE_MS:
a domain's own (authoritative) server, which no cache holds back. UNKNOWN_HOST when there is none.

Effects: fail, io.

### `System.listen`

```gizlang
function System.listen(self: System, host: string, port: i64): Listener throws IoError
```

Listen for TCP connections; port 0 picks a free port (Listener.port).

Effects: fail, io.

### `System.listenUnix`

```gizlang
function System.listenUnix(self: System, path: string): Listener throws IoError
```

Listen at the unix-domain socket `path` (at most 107 bytes; nothing may be
there yet; closing the listener removes it). Its connections are Streams
as TCP ones are; `port()` is 0.

Effects: fail, io.

### `System.listenShared`

```gizlang
function System.listenShared(self: System, host: string, port: i64): Listener throws IoError
```

Listen on a port other listeners share: each Task.thread (or worker
process) of a server listens on it and the kernel spreads connections among
them (SO_REUSEPORT). Every listener on the port must be shared, and a second
program run by the same user could share it too, so plain `listen` is the
default: binding a port in use is an error there.

Effects: fail, io.

### `System.bind`

```gizlang
function System.bind(self: System, host: string, port: i64): Socket throws IoError
```

A UDP socket on a local address; port 0 picks a free port (Socket.port).

Effects: fail, io.

### `Dir.open`

```gizlang
function Dir.open(self: Dir, path: string, mode: i64): Stream throws IoError
```

A file below this directory; paths are relative and never leave it.

Effects: fail, io.

### `Dir.readFile`

```gizlang
function Dir.readFile(self: Dir, path: string): bytes throws IoError
```

The whole file. Up to its size is read at once, then anything past it (a file of /proc or /sys tells a size that is not
its length: /sys/devices/system/cpu/possible is 4,096 bytes for 5). readAll's 64 KiB reads were copied
again at each doubling of its buffer, a fifth of the reads of a 10M-row COPY's commit (2026-10-17).

Effects: fail, io.

### `Dir.readBounded`

```gizlang
function Dir.readBounded(self: Dir, path: string, limit: i64): bytes throws IoError
```

Read a regular file through one confined handle, admitting its size before
allocating. Negative limits and files above the limit are INVALID_ARGUMENT;
shrinkage or growth during the read is IO_FAILURE. Every outcome closes the
opened handle. A same-size concurrent rewrite requires a caller's digest.

Effects: fail, io.

### `Dir.writeFile`

```gizlang
function Dir.writeFile(self: Dir, path: string, data: bytes): i64 throws IoError
```

Writes DATA as the whole file PATH (made or truncated); the number of bytes written.

Effects: fail, io.

### `Dir.appendFile`

```gizlang
function Dir.appendFile(self: Dir, path: string, data: bytes): i64 throws IoError
```

POSIX O_APPEND interoperates with other writers without cooperative locks.

Effects: fail, io.

### `Dir.copyFileTo`

```gizlang
function Dir.copyFileTo(self: Dir, from: string, target: Dir, to: string): i64 throws IoError
```

Copies the file FROM of this directory to TO in TARGET, with its mode; the number of bytes copied.

Effects: fail, read, write, console, io.

### `Dir.cloneFile`

```gizlang
function Dir.cloneFile(self: Dir, from: string, target: Dir, to: string, immutable: bool): FileClone throws IoError
```

Create an exclusive, durable clone with no byte-copy fallback. A hard link is permitted
only when immutable is true: neither namespace may write or truncate that inode for its
entire lifetime. Atomic replacement and unlink are permitted. Mutable files require CoW.
Hard-link fallback also requires WRITE on the source directory grant.

Effects: fail, io.

### `Dir.readLink`

```gizlang
function Dir.readLink(self: Dir, path: string): string throws IoError
```

Read the stored link text without resolving it.

Effects: fail, io.

### `Dir.makeLink`

```gizlang
function Dir.makeLink(self: Dir, path: string, target: string): bool throws IoError
```

Store link text; confined operations never follow the newly created link.

Effects: fail, io.

### `Dir.attribute`

```gizlang
function Dir.attribute(self: Dir, path: string, name: string): string throws IoError
```

The extended attribute `name` (a "user." one) of the entry at `path`, without following a link at its end: "" when
it has none. A value is at most 4096 bytes of UTF-8.

Effects: fail, io.

### `Dir.setAttribute`

```gizlang
function Dir.setAttribute(self: Dir, path: string, name: string, value: string): bool throws IoError
```

Set the extended attribute `name` (a "user." one) of the entry at `path` to `value`; "" removes it.

Effects: fail, io.

### `Dir.watch`

```gizlang
function Dir.watch(self: Dir, path: string): Watch throws IoError
```

Watch folder `path` below this one ("" is this one): its entries made, removed, moved, written, or given other
attributes, and the folder itself removed or moved. Other systems refuse (not supported).

Effects: fail, io.

### `Watch.add`

```gizlang
function Watch.add(self: Watch, dir: Dir, path: string): i64 throws IoError
```

Watch folder `path` below `dir` ("" is `dir`) on this watch as well, with the same events: its watch number, which
the events name (the folder Dir.watch named is 1). A folder watched already keeps its number.

Effects: fail, io.

### `Watch.events`

```gizlang
function Watch.events(self: mut Watch): Vec<WatchEvent> throws IoError
```

The changes since the last call, in order, waiting for at least one. Each wait is limited by Stream.timeout on
`stream`.

Effects: fail, io.

### `Watch.next`

```gizlang
function Watch.next(self: mut Watch): Vec<string> throws IoError
```

The names of the entries that changed since the last call, each once, waiting for at least one: "" names the folder
itself (removed or moved away), or changes that came faster than they were read (the whole folder may have changed).
Each wait is limited by Stream.timeout on `stream`.

Effects: fail, io.

### `Watch.close`

```gizlang
function Watch.close(self: Watch): bool
```

Stops the watch.

Effects: fail, io.

### `Dir.makeDir`

```gizlang
function Dir.makeDir(self: Dir, path: string): bool throws IoError
```

A new directory below this one.

Effects: fail, io.

### `Dir.makeDirectories`

```gizlang
function Dir.makeDirectories(self: Dir, path: string): bool throws IoError
```

Relative parent creation stays under this capability. Traverse physically
through sub grants, never through symlinks or lexical parent reduction.
Every created directory is synced itself and in its actual parent; directories that exist are not synced.

Effects: fail, io.

### `Dir.makeDirectoriesUnsynced`

```gizlang
function Dir.makeDirectoriesUnsynced(self: Dir, path: string): bool throws IoError
```

makeDirectories with no syncs: for a writer whose owner makes the whole tree durable at once (publishTree).

Effects: fail, io.

### `Dir.touch`

```gizlang
function Dir.touch(self: Dir, path: string): bool throws IoError
```

Set an existing entry's times to now, through this directory (it needs write authority). No descriptor holds the
entry open for writing, so a program that another process runs at the same time still starts (ETXTBSY).

Effects: fail, io.

### `Dir.remove`

```gizlang
function Dir.remove(self: Dir, path: string): bool throws IoError
```

Remove a file or an empty directory.

Effects: fail, io.

### `Dir.removeTree`

```gizlang
function Dir.removeTree(self: Dir, path: string): bool throws IoError
```

Missing entries are already removed. Retained cursors close on every failure.

Effects: fail, io.

### `Dir.entries`

```gizlang
function Dir.entries(self: Dir, path: string): DirectoryEntries throws IoError
```

A bounded unsorted traversal of entries, excluding dot entries. The retained
directory survives closing its parent. Concurrent mutations have OS iterator
semantics; a cursor is not a namespace snapshot.

Effects: fail, io.

### `DirectoryEntries.read`

```gizlang
function DirectoryEntries.read(self: DirectoryEntries, limit: i64): Vec<string> throws IoError
```

The next names of the listing, at most LIMIT; empty at the end.

Effects: fail, io.

### `DirectoryEntries.close`

```gizlang
function DirectoryEntries.close(self: DirectoryEntries): bool
```

Ends the listing.

Effects: fail, io.

### `Dir.list`

```gizlang
function Dir.list(self: Dir, path: string): Vec<string> throws IoError
```

Sorted complete listing; callers needing bounded memory use entries().

Effects: fail, io.

### `Dir.info`

```gizlang
function Dir.info(self: Dir, path: string): FileInfo throws IoError
```

Inspect the entry itself (including links); "" is this directory.

Effects: fail, io.

### `Dir.exists`

```gizlang
function Dir.exists(self: Dir, path: string): bool
```

Whether PATH exists (`info` finds it).

Effects: fail, io.

### `Dir.isDirectory`

```gizlang
function Dir.isDirectory(self: Dir, path: string): bool
```

Whether PATH is a directory (a link to one is not: as `info`).

Effects: fail, io.

### `Dir.rename`

```gizlang
function Dir.rename(self: Dir, from: string, to: string): bool throws IoError
```

Renames FROM to TO in this directory, replacing TO.

Effects: fail, io.

### `Dir.renameTo`

```gizlang
function Dir.renameTo(self: Dir, destination: Dir, from: string, to: string): bool throws IoError
```

Moves FROM of this directory to TO in DESTINATION, replacing TO.

Effects: fail, io.

### `Dir.renameToNoReplace`

```gizlang
function Dir.renameToNoReplace(self: Dir, destination: Dir, from: string, to: string): bool throws IoError
```

Atomically refuse an existing destination, including files, directories
and links. Unsupported host filesystems fail rather than race or replace.

Effects: fail, io.

### `Dir.setMode`

```gizlang
function Dir.setMode(self: Dir, path: string, mode: i64): bool throws IoError
```

Sets the permission bits of PATH to MODE.

Effects: fail, io.

### `Dir.sub`

```gizlang
function Dir.sub(self: Dir, path: string): Dir throws IoError
```

Delegate an existing subdirectory; the grant survives closing its parent.

Effects: fail, io.

### `Dir.walk`

```gizlang
function Dir.walk(self: Dir, path: string): Vec<string> throws IoError
```

Every entry below PATH, at any depth, as paths from this directory.

Effects: fail, io.

### `Dir.replaceFile`

```gizlang
function Dir.replaceFile(self: Dir, path: string, data: bytes): i64 throws IoError
```

One staging file in the target's directory: write, fsync, close, rename.
A failure after rename is uncertain publication and never rolls the namespace back.

Effects: fail, read, write, console, io.

### `Dir.publishFile`

```gizlang
function Dir.publishFile(self: Dir, path: string, data: bytes): i64 throws IoError
```

Publish an immutable file only if its final name is absent. Existing files,
directories and links are never overwritten. Uses the same durable staging
and no-replace rename owner as publishTree.

Effects: fail, read, write, console, io.

### `Dir.replaceWith`

```gizlang
function Dir.replaceWith(self: Dir, path: string, write: (stream: Stream) => Result<i64, IoError>): i64 throws IoError
```

The single atomic publication owner accepts an admitted streaming writer.
The callback owns its bounded buffers; this owner owns staging and durability.

Effects: fail, read, write, console, io.

### `Dir.publishWith`

```gizlang
function Dir.publishWith(self: Dir, path: string, write: (stream: Stream) => Result<i64, IoError>): i64 throws IoError
```

The streaming form of publishFile; the writer owns its bounded buffers.

Effects: fail, read, write, console, io.

### `Dir.replaceTree`

```gizlang
function Dir.replaceTree(self: Dir, source: Dir, from: string, path: string): bool throws IoError
```

A tree uses the same rename/sync publication owner as a streamed file.
Each directory retains only a cursor page; child links are copied as links.

Effects: fail, read, write, console, io.

### `Dir.publishTree`

```gizlang
function Dir.publishTree(self: Dir, path: string, write: (stage: Dir) => Result<bool, IoError>): bool throws IoError
```

Assemble an immutable tree in an exclusively owned sibling stage, then
atomically expose it only if path is absent. The writer writes plainly
(writeFile, makeDirectoriesUnsynced) and closes its handles; this owner makes the
tree durable with one file system sync (syncFilesystem), then syncs the parent.
A sync for each file and directory of a 146-file compiler snapshot (replaceFile,
makeDirectories) was ~1000 syncs one after another, 0.2 s of each live edit; on
a build host its 146 file syncs alone took 0.65 s one after another, 0.24 s 16 at a time
and 0.02-0.05 s as one syncfs (2026-10-15).
Failure after rename is uncertain publication, never namespace rollback.

Effects: fail, read, write, console, io.

### `Dir.sync`

```gizlang
function Dir.sync(self: Dir): bool throws IoError
```

Makes the directory's entries durable: files created, renamed or removed in it
survive a crash once this returns. The calling task waits; others run.

Effects: fail, io.

### `Dir.syncFilesystem`

```gizlang
function Dir.syncFilesystem(self: Dir): bool throws IoError
```

Makes all data written to the file system that holds this directory durable, with the entries
of its directories: one call (syncfs) for many files, not one sync for each. It needs write
authority. The calling task waits; others run.

Effects: fail, io.

### `Dir.close`

```gizlang
function Dir.close(self: Dir): bool
```

Closes the directory handle.

Effects: fail, io.

### `Stream.peer`

```gizlang
function Stream.peer(self: Stream): string
```

The address of the peer of a connection, as text (empty for a unix socket or a connection that is gone).

Effects: fail, io.

### `Stream.fixPeer`

```gizlang
function Stream.fixPeer(self: Stream, address: string): bool
```

Make `address` the peer of this connection (Stream.peer), once: false when a PROXY header gave it before.

Effects: fail, io.

### `Listener.proxyProtocol`

```gizlang
function Listener.proxyProtocol(self: Listener, on: bool): void
```

The connections of this listener start with a PROXY header (`proxyHeader`), which Http reads and fixes as the peer. Turn it on only for
a port that nothing but a balancer that always sends the header can reach: a client could write one itself. Call it before a set accepts.

Effects: fail, io.

### `Ready.proxied`

```gizlang
function Ready.proxied(self: Ready): bool
```

Whether the connection came through a PROXY protocol header.

Effects: fail, io.

### `Stream.read`

```gizlang
function Stream.read(self: Stream, limit: i64): bytes throws IoError
```

Up to LIMIT bytes from the stream; empty at its end.

Effects: fail, io.

### `Stream.readReady`

```gizlang
function Stream.readReady(self: Stream, limit: i64): bytes throws IoError
```

Up to `limit` bytes that a socket, pipe or POLLED device has now, without waiting: empty bytes when it has none,
and always for a file stream (its reads wait in read).

Effects: fail, io.

### `Stream.descriptor`

```gizlang
function Stream.descriptor(self: Stream): i64
```

The descriptor of a socket stream, -1 for another stream or one of another thread. It stays the stream's while the
stream is open; peerClosed takes it on any thread.

Effects: fail, io.

### `Stream.readAll`

```gizlang
function Stream.readAll(self: Stream): bytes throws IoError
```

Everything until the end of the stream.

Effects: fail, io.

### `Stream.readExact`

```gizlang
function Stream.readExact(self: Stream, count: i64): bytes throws IoError
```

Exactly count bytes, consuming no following bytes. Negative count is
INVALID_ARGUMENT; premature EOF is IO_FAILURE. Read errors are preserved,
partial data is discarded on failure, and the caller retains the stream.
Each read asks for all that remains (the runtime bounds one read to 1 MiB),
so a large message is a few reads, not one per 64 KiB: each read is a task
switch and a copy, and 16 of them took about 2 ms of a storage node's
1 MiB request (2026-10-15). The caller must admit the requested output size.

Effects: fail, io.

### `Stream.unread`

```gizlang
function Stream.unread(self: Stream, data: bytes): i64 throws IoError
```

Put bytes back before what the next read returns, as a parser does with
the start of a message it cannot finish yet; if the stream ends with
nothing after them, reads report the end instead. Not on a TLS stream.

Effects: fail, io.

### `Stream.write`

```gizlang
function Stream.write(self: Stream, data: bytes): i64 throws IoError
```

Write all of `data`; the number of bytes written.

Effects: fail, io.

### `Stream.shutdown`

```gizlang
function Stream.shutdown(self: Stream): bool throws IoError
```

Ends a connection's write side: the peer reads its end, and reads here go on (a TCP FIN; a pipe ends at its close).

Effects: fail, io.

### `Stream.copyTo`

```gizlang
function Stream.copyTo(self: Stream, to: Stream): i64 throws IoError
```

Checked bounded copy; neither stream is closed.

Effects: fail, io.

### `Stream.relay`

```gizlang
function Stream.relay(self: Stream, other: Stream): void
```

Copies bytes both ways between two connections until either side ends, then stops the other way too; neither is closed.

Effects: fail, io.

### `Stream.setMode`

```gizlang
function Stream.setMode(self: Stream, mode: i64): bool throws IoError
```

Change permission bits on the held writable inode, before publication.

Effects: fail, io.

### `Stream.touch`

```gizlang
function Stream.touch(self: Stream): bool throws IoError
```

Sets the modification time of the open file to now.

Effects: fail, io.

### `Stream.close`

```gizlang
function Stream.close(self: Stream): bool
```

Closes the stream.

Effects: fail, io.

### `Stream.handle`

```gizlang
function Stream.handle(self: Stream): i64
```

A number naming this open stream among the open ones, for tables of connections (a closed one's may be reused).

### `Stream.info`

```gizlang
function Stream.info(self: Stream): FileInfo throws IoError
```

An open file's size in bytes and last modification in milliseconds since
1970 UTC; fails on a stream that is not a file.

Effects: fail, io.

### `Stream.timeout`

```gizlang
function Stream.timeout(self: Stream, milliseconds: i64): i64 throws IoError
```

Limit how long each read or write of a socket, pipe or POLLED stream may wait, in
milliseconds (0, the start, waits forever); a wait past it fails with a
timed-out IoError and the stream should be closed.

Effects: fail, io.

### `Stream.detach`

```gizlang
function Stream.detach(self: Stream): i64 throws IoError
```

Give a TCP stream to no task, so it outlives the task that owns it (a
client pool keeps an idle connection so); `adopt` gives it to the calling
task, which closes it when it ends. A stream in a Ready set is refused.

Effects: fail, io.

### `Stream.adopt`

```gizlang
function Stream.adopt(self: Stream): i64 throws IoError
```

Gives the stream to the calling task, which closes it when it ends. See `detach`.

Effects: fail, io.

### `Stream.sync`

```gizlang
function Stream.sync(self: Stream): bool throws IoError
```

Makes what was written to the file durable (its data and size, as fdatasync):
it survives a crash once this returns. The calling task waits; others run.

Effects: fail, io.

### `Stream.lock`

```gizlang
function Stream.lock(self: Stream): bool throws IoError
```

Takes the file's exclusive lock without waiting: true when this process now
holds it, false when another process does. It lasts while the file is open,
however the process ends, so one server owns a data folder at a time.

Effects: fail, io.

### `Stream.truncate`

```gizlang
function Stream.truncate(self: Stream, length: i64): i64 throws IoError
```

Cuts the file to `length` bytes, or extends it with zeros.

Effects: fail, io.

### `Stream.readAt`

```gizlang
function Stream.readAt(self: Stream, offset: i64, count: i64): bytes throws IoError
```

`count` bytes of the file from `offset`, fewer only at its end (pread). It
neither uses nor moves the position of `read` and `write`, and several run at once.

Effects: fail, io.

### `Stream.readMany`

```gizlang
function Stream.readMany(self: Stream, parts: Vec<i64>): bytes throws IoError
```

The bytes of each part of `parts` (an offset, then a size, for each part), in their order in one value: the reads
of rows that sit apart in a file, in one call. A part past the end of the file is an error. Like readAt, it does
not use or move the position.

Effects: fail, io.

### `Stream.writeAt`

```gizlang
function Stream.writeAt(self: Stream, offset: i64, data: bytes): i64 throws IoError
```

Writes all of `data` at `offset` of the file (pwrite). It neither uses nor
moves the position of `read` and `write`, and several run at once.

Effects: fail, io.

### `Stream.seek`

```gizlang
function Stream.seek(self: Stream, offset: i64): i64 throws IoError
```

Move a file's read and write position to `offset` bytes from its start.

Effects: fail, io.

### `Ready.accept`

```gizlang
function Ready.accept(self: Ready, listener: Listener): i64 throws IoError
```

Accept the listener's connections into the set; each is watched.

Effects: fail, io.

### `Ready.watch`

```gizlang
function Ready.watch(self: Ready, stream: Stream): i64 throws IoError
```

Report the connection once more when it is ready. Until then the set holds
it, not the task: give it back after answering what it sent.

Effects: fail, io.

### `Ready.channel`

```gizlang
function Ready.channel<T>(self: Ready, channel: Task.Channel<T>): Stream
```

A crossing channel in the set, with no socket: watch() the returned stream, and wait() returns it, once per watch,
when another thread sent a value (or closed the channel). Drain it with Task.tryReceive, then watch it again. One
set watches a channel. Close the stream to remove it.

### `Ready.wait`

```gizlang
function Ready.wait(self: Ready): Stream throws IoError
```

The next ready connection, which now belongs to the calling task (it closes
when the task ends); fails once the listener fails or the set is closed.
Reading it returns what arrived at once.

Effects: fail, io.

### `Ready.idle`

```gizlang
function Ready.idle(self: Ready): i64
```

How many tasks are waiting in wait() now; 0 after a task took a connection
means the next one would wait for a task to finish (add one, if wanted).

Effects: fail, io.

### `Ready.queued`

```gizlang
function Ready.queued(self: Ready): bool
```

Whether a connection is ready now, so wait() returns it at once: a server that answers after one write for all the
requests of a pass (a log write) makes that write when none is.

Effects: fail, io.

### `Ready.time`

```gizlang
function Ready.time(self: Ready): i64
```

The wall clock (milliseconds since 1970 UTC) for a set that serves a listener or connections of a System, else 0:
the Date of gizlang:http's responses.

Effects: fail, io.

### `Ready.close`

```gizlang
function Ready.close(self: Ready): bool
```

Close the set and the connections waiting in it.

Effects: fail, io.

### `System.signals`

```gizlang
function System.signals(self: System, ids: Vec<i64>): Signals throws IoError
```

The signals in `ids` (TERM, INT, HUP, QUIT, USR1, USR2) as a stream a task
reads with next(), not as handlers: a program that subscribes to TERM no
longer ends on it, and ends when it decides to (after a checkpoint, for
example). A signal that comes while no task reads is kept for the next
read; the same signal sent twice before a read can arrive once, as the
kernel keeps one pending. The subscription closes when the task that opened
it ends.

Effects: fail, io.

### `Signals.next`

```gizlang
function Signals.next(self: Signals): i64 throws IoError
```

The next signal not read yet (TERM, ...); it waits for one. Signals that
wait together come in the order of their numbers.

Effects: fail, io.

### `Signals.close`

```gizlang
function Signals.close(self: Signals): bool
```

Stop the subscription; a task waiting in next() gets an error.

Effects: fail, io.

### `Listener.port`

```gizlang
function Listener.port(self: Listener): i64
```

The port that the listener is bound to.

Effects: fail, io.

### `Listener.backlog`

```gizlang
function Listener.backlog(self: Listener, capacity: i64): bool throws IoError
```

Set the pending connection bound (1..2147483647). The kernel may clamp it
to its system maximum. Existing connections and listener authority remain.

Effects: fail, io.

### `Listener.accept`

```gizlang
function Listener.accept(self: Listener): Stream throws IoError
```

Waits for the next connection and gives it.

Effects: fail, io.

### `Listener.close`

```gizlang
function Listener.close(self: Listener): bool
```

Closes the listener. Connections that it accepted stay open.

Effects: fail, io.

### `Socket.port`

```gizlang
function Socket.port(self: Socket): i64
```

The local port that the socket is bound to.

Effects: fail, io.

### `Socket.send`

```gizlang
function Socket.send(self: Socket, host: string, port: i64, data: bytes): i64 throws IoError
```

Send `data` as one datagram; the number of bytes sent. Delivery is not confirmed.

Effects: fail, io.

### `Socket.receive`

```gizlang
function Socket.receive(self: Socket, limit: i64): Datagram throws IoError
```

The next datagram, waiting for one; at most `limit` bytes of it.

Effects: fail, io.

### `Socket.close`

```gizlang
function Socket.close(self: Socket): bool
```

Closes the socket.

Effects: fail, io.

### `ExitStatus.exitCode`

```gizlang
function ExitStatus.exitCode(self: ExitStatus): i64
```

The status as one exit code, as a shell gives it: the code, or 128 + N for signal N.

Effects: fail.

### `Output.ran`

```gizlang
function Output.ran(self: Output): Ran
```

The output as text.

Effects: fail.

### `System.stdin`

```gizlang
function System.stdin(self: System): Stream throws IoError
```

The standard input of this process.

Effects: fail, io.

### `System.stdout`

```gizlang
function System.stdout(self: System): Stream throws IoError
```

The standard output of this process.

Effects: fail, io.

### `System.stderr`

```gizlang
function System.stderr(self: System): Stream throws IoError
```

The standard error of this process.

Effects: fail, io.

### `System.printError`

```gizlang
function System.printError(self: System, line: string): void
```

LINE and a newline on standard error: diagnostics, kept apart from the output of the program.

Effects: fail, io.

### `System.handed`

```gizlang
function System.handed(self: System, index: i64): Listener throws IoError
```

The listener the parent handed this process at INDEX (its SpawnOptions.handed),
taken once: still bound to the parent's address and network.

Effects: fail, io.

### `System.spawn`

```gizlang
function System.spawn(self: System, program: string, args: Vec<string>, options: SpawnOptions): Child throws IoError
```

Starts PROGRAM with ARGS and OPTIONS. The child runs until it ends; Child.wait gives its status.

Effects: fail, io.

### `System.exec`

```gizlang
function System.exec(self: System, program: string, args: Vec<string>, environment: Vec<string>): IoError
```

This process becomes PROGRAM (found on PATH, as spawn finds it) with ARGS and this environment plus ENVIRONMENT
(NAME=VALUE; the last of a name wins): its PID, signals, handed listeners and exit status are then the program's
own. Use it when nothing is left to do after the program, so that killing this process stops the program (a
spawned child that is waited on outlives a killed parent). It returns only on a failure.

Effects: fail, io.

### `Child.stdin`

```gizlang
function Child.stdin(self: Child): Option<Stream>
```

The pipe to the standard input of the child, when the options asked for a pipe.

Effects: fail, io.

### `Child.stdout`

```gizlang
function Child.stdout(self: Child): Option<Stream>
```

The pipe from the standard output of the child, when the options asked for a pipe.

Effects: fail, io.

### `Child.stderr`

```gizlang
function Child.stderr(self: Child): Option<Stream>
```

The pipe from the standard error of the child, when the options asked for a pipe.

Effects: fail, io.

### `Child.pid`

```gizlang
function Child.pid(self: Child): i64
```

The process id of the child.

Effects: fail, io.

### `Child.wait`

```gizlang
function Child.wait(self: Child): ExitStatus throws IoError
```

Waits until the child ends; its exit code or the signal that stopped it.

Effects: fail, io.

### `System.kill`

```gizlang
function System.kill(self: System, pid: i64, signal: i64): bool throws IoError
```

Sends SIGNAL to the process PID, any this user may signal (Child.kill signals a child by its handle). Signal 0
checks only that the process exists.

Effects: fail, io.

### `Child.kill`

```gizlang
function Child.kill(self: Child, signal: i64): bool throws IoError
```

Sends SIGNAL to the child.

Effects: fail, io.

### `Child.close`

```gizlang
function Child.close(self: Child): bool
```

Closing a running child terminates and reaps it, like task cleanup.

Effects: fail, io.

### `System.run`

```gizlang
function System.run(self: System, program: string, args: Vec<string>): Output throws IoError
```

Drain both pipes concurrently before waiting: neither child's output buffer
can keep it from exiting. Captured bytes are grown in place by readAll.

Effects: fail, read, write, io.

### `System.runWith`

```gizlang
function System.runWith(self: System, program: string, args: Vec<string>, options: SpawnOptions, input: Option<bytes>): Output throws IoError
```

The same with `options`' working directory and environment, and `input`
(when given) written to standard input, which is then closed. Its streams
are always captured, whatever `options` say.

Effects: fail, read, write, io.

### `System.ranBounded`

```gizlang
function System.ranBounded(self: System, program: string, args: Vec<string>, options: SpawnOptions, input: Option<bytes>, budget: CaptureBudget): Ran
```

runBounded as text (`Output.ran`): a program that cannot start or ends past the budget gives code 127 and the reason.

Effects: fail, read, write, io.

### `System.runBounded`

```gizlang
function System.runBounded(self: System, program: string, args: Vec<string>, options: SpawnOptions, input: Option<bytes>, budget: CaptureBudget): Result<CapturedOutput, IoError>
```

Runs a child with a hard wall-clock deadline and one combined byte cap for
stdout and stderr. No shell or retry is introduced. Timeouts return TIMED_OUT;
reaching the byte cap kills/reaps the child and returns the bounded output
with outputLimit=true. Child/task teardown removes its cgroup and descendants.

Effects: fail, read, write, io.

### `System.runStreams`

```gizlang
function System.runStreams(self: System, program: string, args: Vec<string>, options: SpawnOptions, input: bytes, milliseconds: i64, outputBytes: i64): Result<CapturedOutput, IoError>
```

Runs PROGRAM to its end with OPTIONS' streams as they are, as Node's spawnSync does: a pipe is captured (stdin a pipe
gets INPUT, or nothing, then closes), any other stream is the child's own. At most MILLISECONDS (0: no limit; then
TIMED_OUT) and OUTPUTBYTES captured (-1: no cap; past it the child is killed and outputLimit is set).

Effects: fail, read, write, io.

### `System.stat`

```gizlang
function System.stat(self: System, path: string, follow: bool): Stat throws IoError
```

stat(2) or, when FOLLOW is false, lstat(2).

Effects: fail, io.

### `System.statFd`

```gizlang
function System.statFd(self: System, fd: i64): Stat throws IoError
```

fstat(2).

Effects: fail, io.

### `System.statFs`

```gizlang
function System.statFs(self: System, path: string): StatFs throws IoError
```

statfs(2).

Effects: fail, io.

### `System.openFd`

```gizlang
function System.openFd(self: System, path: string, flags: i64, mode: i64): i64 throws IoError
```

open(2) with Linux's flags (O_RDONLY, O_CREAT, ...; O_CLOEXEC is added; the runtime maps them on macOS), giving
the descriptor.

Effects: fail, io.

### `System.closeFd`

```gizlang
function System.closeFd(self: System, fd: i64): bool throws IoError
```

Closes the file descriptor FD (close).

Effects: fail, io.

### `System.readFd`

```gizlang
function System.readFd(self: System, fd: i64, count: i64, position: i64): bytes throws IoError requires count> = 0 { let out: bytes = filled(count, 0u)
```

Up to COUNT bytes from FD, at POSITION (pread) or, when it is negative, at the descriptor's own offset. Empty at the end.

Effects: fail, io.

### `System.writeFd`

```gizlang
function System.writeFd(self: System, fd: i64, data: bytes, position: i64): i64 throws IoError
```

DATA to FD at POSITION (pwrite) or, when it is negative, at the descriptor's own offset; the bytes taken.

Effects: fail, io.

### `System.syncFd`

```gizlang
function System.syncFd(self: System, fd: i64, dataOnly: bool): bool throws IoError
```

Flushes FD to its device: its data only (fdatasync) when DATAONLY, else data and metadata (fsync).

Effects: fail, io.

### `System.truncateFd`

```gizlang
function System.truncateFd(self: System, fd: i64, length: i64): bool throws IoError
```

Sets the length of the file of FD (ftruncate).

Effects: fail, io.

### `System.access`

```gizlang
function System.access(self: System, path: string, mode: i64): bool throws IoError
```

Whether the process may access PATH in MODE (access).

Effects: fail, io.

### `System.processId`

```gizlang
function System.processId(self: System): i64
```

This process's id (getpid).

### `System.parentProcessId`

```gizlang
function System.parentProcessId(self: System): i64
```

The id of the process that started this one.

Effects: io.

### `System.pageSize`

```gizlang
function System.pageSize(self: System): i64
```

The size of a memory page in bytes (getpagesize).

### `System.mapShared`

```gizlang
function System.mapShared(self: System, fd: i64, offset: i64, length: i64, writable: bool = false, alignment: i64 = 1): u64 throws IoError
```

LENGTH bytes of the descriptor FD from OFFSET, mapped shared and read-only (writable when WRITABLE), at an address that
is a multiple of ALIGNMENT (a power of two; 1 for any): their address, which Native.read reads. Unmap it with unmap.

Effects: fail, io.

### `System.unmap`

```gizlang
function System.unmap(self: System, address: u64, length: i64): bool throws IoError
```

Unmaps LENGTH bytes at ADDRESS (munmap).

Effects: fail, io.

### `System.ring`

```gizlang
function System.ring(self: System, entries: i64): Ring throws IoError
```

A ring of ENTRIES submissions (1 to 32768).

Effects: fail, io.

### `Ring.command`

```gizlang
function Ring.command(self: Ring, fd: i64, op: u64, userData: i64, w0: u64, w1: u64, w2: u64, w3: u64): bool
```

Queues command OP on the descriptor FD with USER_DATA (0 to 2^31 - 1) and 32 bytes of command data, the four
little-endian words W0 to W3. False when the ring is full: enter, then queue it again.

Effects: fail, io.

### `Ring.enter`

```gizlang
function Ring.enter(self: Ring, wait: i64): i64 throws IoError
```

Submits the queued commands and waits until WAIT completions are ready (0: no wait): the number submitted. An
interrupted wait fails with EINTR; call it again.

Effects: fail, io.

### `Ring.next`

```gizlang
function Ring.next(self: Ring): Option<Completion>
```

The oldest completion, consumed, or none when none is ready.

Effects: fail, io.

### `Ring.close`

```gizlang
function Ring.close(self: Ring): void
```

Closes the ring and its mappings.

Effects: fail, io.

### `System.unlink`

```gizlang
function System.unlink(self: System, path: string): bool throws IoError
```

Removes the file PATH (unlink).

Effects: fail, io.

### `System.removeDir`

```gizlang
function System.removeDir(self: System, path: string): bool throws IoError
```

Removes the empty directory PATH (rmdir).

Effects: fail, io.

### `System.makeDir`

```gizlang
function System.makeDir(self: System, path: string, mode: i64): bool throws IoError
```

Makes the directory PATH with MODE (mkdir).

Effects: fail, io.

### `System.makeTempDir`

```gizlang
function System.makeTempDir(self: System, prefix: string): string throws IoError
```

mkdtemp(3): PREFIX plus six random characters, the directory made; its path.

Effects: fail, io.

### `System.renamePath`

```gizlang
function System.renamePath(self: System, from: string, to: string): bool throws IoError
```

Renames FROM to TO, replacing TO (rename).

Effects: fail, io.

### `System.linkPath`

```gizlang
function System.linkPath(self: System, from: string, to: string): bool throws IoError
```

Makes TO a hard link of FROM (link).

Effects: fail, io.

### `System.symlinkPath`

```gizlang
function System.symlinkPath(self: System, target: string, path: string): bool throws IoError
```

Makes PATH a symbolic link to TARGET (symlink).

Effects: fail, io.

### `System.readSymlink`

```gizlang
function System.readSymlink(self: System, path: string): string throws IoError
```

The target of the symbolic link PATH (readlink).

Effects: fail, io.

### `System.resolvePath`

```gizlang
function System.resolvePath(self: System, path: string): string throws IoError
```

realpath(3): the canonical absolute path of an existing PATH.

Effects: fail, io.

### `System.changeMode`

```gizlang
function System.changeMode(self: System, path: string, mode: i64): bool throws IoError
```

Sets the permission bits of PATH to MODE (chmod).

Effects: fail, io.

### `System.changeModeFd`

```gizlang
function System.changeModeFd(self: System, fd: i64, mode: i64): bool throws IoError
```

Sets the permission bits of the file of FD to MODE (fchmod).

Effects: fail, io.

### `System.changeOwner`

```gizlang
function System.changeOwner(self: System, path: string, uid: i64, gid: i64, follow: bool): bool throws IoError
```

chown(2), or lchown(2) when FOLLOW is false; -1 leaves an id unchanged.

Effects: fail, io.

### `System.changeOwnerFd`

```gizlang
function System.changeOwnerFd(self: System, fd: i64, uid: i64, gid: i64): bool throws IoError
```

Sets the owner and group of the file of FD; -1 leaves an id unchanged (fchown).

Effects: fail, io.

### `System.setTimes`

```gizlang
function System.setTimes(self: System, path: string, atimeNs: i64, mtimeNs: i64, follow: bool): bool throws IoError
```

utimensat(2): the access and modification times in nanoseconds since 1970 (TIME_OMIT keeps one), on the link
itself when FOLLOW is false.

Effects: fail, io.

### `System.setTimesFd`

```gizlang
function System.setTimesFd(self: System, fd: i64, atimeNs: i64, mtimeNs: i64): bool throws IoError
```

Sets the access and modification times of the file of FD, in nanoseconds since 1970 (futimens).

Effects: fail, io.

### `System.readDir`

```gizlang
function System.readDir(self: System, path: string): Vec<DirEntry> throws IoError
```

The entries of directory PATH (without . and ..), in the order the OS gives them.

Effects: fail, io.

### `System.copyFd`

```gizlang
function System.copyFd(self: System, from: string, to: string, exclusive: bool): bool throws IoError
```

A copy of FROM at TO: the bytes, then the mode. With EXCLUSIVE an existing TO is EEXIST.

Effects: fail, io.

### `System.isTerminal`

```gizlang
function System.isTerminal(self: System, fd: i64): bool
```

Whether FD is a terminal.

Effects: fail, io.

### `System.terminalSize`

```gizlang
function System.terminalSize(self: System, fd: i64): TerminalSize throws IoError
```

The columns and rows of the terminal on FD.

Effects: fail, io.

### `System.terminalState`

```gizlang
function System.terminalState(self: System, fd: i64): bytes throws IoError
```

The terminal's current mode (opaque bytes: a termios, or a Windows console mode), to give back to terminalRestore.

Effects: fail, io.

### `System.terminalRestore`

```gizlang
function System.terminalRestore(self: System, fd: i64, state: bytes): bool throws IoError
```

Gives the terminal on FD back the state that a raw-mode call returned.

Effects: fail, io.

### `System.terminalRaw`

```gizlang
function System.terminalRaw(self: System, fd: i64): bool throws IoError
```

Raw mode as libuv sets it: no echo, no canonical lines, no signals, no input translation; output stays cooked.

Effects: fail, io.

### `System.hostname`

```gizlang
function System.hostname(self: System): string throws IoError
```

The host name of this machine.

Effects: fail, io.

### `System.loadAverage`

```gizlang
function System.loadAverage(self: System): Vec<f64>
```

The load averages of the last 1, 5 and 15 minutes; zeros on Windows, which has none.

Effects: fail, io.

### `System.osInfo`

```gizlang
function System.osInfo(self: System): OsInfo throws IoError
```

The name, release, version and machine of the operating system (uname).

Effects: fail, io.

### `System.uptime`

```gizlang
function System.uptime(self: System): f64
```

Seconds since boot; 0 when the OS does not tell.

Effects: fail, io.

### `System.memoryInfo`

```gizlang
function System.memoryInfo(self: System): MemoryInfo
```

The total and free memory of the machine, in bytes.

Effects: fail, io.

### `System.cpuInfo`

```gizlang
function System.cpuInfo(self: System): Vec<CpuInfo>
```

Each CPU: its model, its MHz and its times in milliseconds (libuv uv_cpu_info, Node's os.cpus).

Effects: fail, io.

### `System.availableParallelism`

```gizlang
function System.availableParallelism(self: System): i64
```

The CPUs this process may run on, as Node reports them (libuv: the affinity mask, then the cgroup quota): TFB
clustered.mjs forks one worker per CPU, so the online count forked 32 workers onto a 4-CPU taskset.

Effects: fail, io.

### `System.interfaces`

```gizlang
function System.interfaces(self: System): Vec<Interface> throws IoError
```

The network interfaces with an address, IPv4 and IPv6, each with the MAC of its interface (libuv, as Node's
os.networkInterfaces).

Effects: fail, io.

### `System.userInfo`

```gizlang
function System.userInfo(self: System, uid: i64): UserInfo throws IoError
```

The user UID (-1: the effective user): libuv's passwd entry. On Windows only the current user, with uid and gid -1
and no shell.

Effects: fail, io.

### `System.homeDirectory`

```gizlang
function System.homeDirectory(self: System): string throws IoError
```

$HOME, else the user's home folder (libuv: USERPROFILE on Windows, else the passwd entry).

Effects: fail, io.

### `System.priority`

```gizlang
function System.priority(self: System, pid: i64): i64 throws IoError
```

The scheduling priority (nice) of PID (0: this process); libuv maps Windows' priority classes to it.

Effects: fail, io.

### `System.setPriority`

```gizlang
function System.setPriority(self: System, pid: i64, priority: i64): bool throws IoError
```

Sets the scheduling priority of the process PID (-20 to 19; lower runs first).

Effects: fail, io.

### `System.credentials`

```gizlang
function System.credentials(self: System): Credentials
```

The user, group and supplementary group ids that the process runs with.

Effects: fail, io.

### `System.userId`

```gizlang
function System.userId(self: System, name: string, group: bool): i64 throws IoError
```

The numeric user or group id of NAME, or NAME itself when it is a number.

Effects: fail, io.

### `System.setCredential`

```gizlang
function System.setCredential(self: System, which: string, id: i64): bool throws IoError
```

setuid and the like: WHICH is "uid", "euid", "gid" or "egid".

Effects: fail, io.

### `System.setGroups`

```gizlang
function System.setGroups(self: System, ids: Vec<i64>): bool throws IoError
```

Sets the supplementary groups of the process to IDS (setgroups); it needs the privilege to do so.

Effects: fail, io.

### `System.initGroups`

```gizlang
function System.initGroups(self: System, user: string, group: i64): bool throws IoError
```

Sets the supplementary groups of the process to those of USER, plus GROUP (initgroups).

Effects: fail, io.

## Constants

### `INVALID_ARGUMENT`

```gizlang
const INVALID_ARGUMENT = -22
```

The error code -22: invalid argument.

### `HUP`

```gizlang
const HUP = 1
```

Signal numbers for System.signals, as Linux numbers them (the runtime maps them on other platforms).

### `INT`

```gizlang
const INT = 2
```

The signal SIGINT (2).

### `QUIT`

```gizlang
const QUIT = 3
```

The signal SIGQUIT (3).

### `USR1`

```gizlang
const USR1 = 10
```

The signal SIGUSR1 (10).

### `USR2`

```gizlang
const USR2 = 12
```

The signal SIGUSR2 (12).

### `TERM`

```gizlang
const TERM = 15
```

The signal SIGTERM (15).

### `WINCH`

```gizlang
const WINCH = 28
```

The signal SIGWINCH (28).

### `READ`

```gizlang
const READ = 1
```

Opening modes, combined with |.

### `WRITE`

```gizlang
const WRITE = 2
```

The open flag WRITE (2).

### `CREATE`

```gizlang
const CREATE = 4
```

The open flag CREATE (4).

### `TRUNCATE`

```gizlang
const TRUNCATE = 8
```

The open flag TRUNCATE (8).

### `APPEND`

```gizlang
const APPEND = 16
```

An open modifier, requiring WRITE; every write appends atomically at the OS.

### `POLLED`

```gizlang
const POLLED = 32
```

An importDescriptor modifier: a device that polls (such as /dev/fuse) reads and writes as a stream on the event
loop, each read when the device is ready, not by a file-pool thread that blocks in it.

### `NOT_FOUND`

```gizlang
const NOT_FOUND = -2
```

IoError codes a caller tells apart: no such file or directory, a path that
is refused (not a regular file, or no permission), a path that would leave
the directory or is malformed, a wait past a stream's timeout, and a host
name with no address (System.addresses; connect gives it too).

### `IO_FAILURE`

```gizlang
const IO_FAILURE = -5
```

The error code -5: io failure.

### `OUT_OF_MEMORY`

```gizlang
const OUT_OF_MEMORY = -12
```

The error code -12: out of memory.

### `NO_SPACE`

```gizlang
const NO_SPACE = -28
```

The error code -28: no space.

### `CORRUPT_DATA`

```gizlang
const CORRUPT_DATA = -74
```

The error code -74: corrupt data.

### `STALE_RESOURCE`

```gizlang
const STALE_RESOURCE = -116
```

The error code -116: stale resource.

### `DENIED`

```gizlang
const DENIED = -40301
```

The error code -40301: denied.

### `BAD_PATH`

```gizlang
const BAD_PATH = -40302
```

The error code -40302: bad path.

### `TIMED_OUT`

```gizlang
const TIMED_OUT = -110
```

The error code -110: timed out.

### `CONNECTION_REFUSED`

```gizlang
const CONNECTION_REFUSED = -111
```

The error code -111: connection refused (nothing was sent).

### `UNKNOWN_HOST`

```gizlang
const UNKNOWN_HOST = -3008
```

The error code -3008: unknown host.

### `NOT_SUPPORTED`

```gizlang
const NOT_SUPPORTED = -38
```

The error code -38: the operating system does not support the call.

### `RESOLVE_MS`

```gizlang
const RESOLVE_MS = 2000
```

How long System.addresses waits for each name server's answer.

### `WORKERS`

```gizlang
const WORKERS = 16
```

Tasks running turns: serveConnections starts WORKERS and adds one whenever a connection is taken while none waits (a turn
waiting on a timer, a file or an upstream holds its task), up to MOST_WORKERS.

### `MOST_WORKERS`

```gizlang
const MOST_WORKERS = 65536
```

The most worker tasks that serveConnections starts.

### `WATCH_CLOSE_WRITE`

```gizlang
const WATCH_CLOSE_WRITE = 8
```

A file open for writing was closed.

### `WATCH_MOVED_FROM`

```gizlang
const WATCH_MOVED_FROM = 64
```

An entry was moved out of the folder.

### `WATCH_MOVED_TO`

```gizlang
const WATCH_MOVED_TO = 128
```

An entry was moved into the folder.

### `WATCH_CREATE`

```gizlang
const WATCH_CREATE = 256
```

An entry was made in the folder.

### `WATCH_DELETE`

```gizlang
const WATCH_DELETE = 512
```

An entry of the folder was removed.

### `WATCH_DELETE_SELF`

```gizlang
const WATCH_DELETE_SELF = 1024
```

The folder itself was removed.

### `WATCH_MOVE_SELF`

```gizlang
const WATCH_MOVE_SELF = 2048
```

The folder itself was moved.

### `WATCH_OVERFLOW`

```gizlang
const WATCH_OVERFLOW = 16384
```

Changes came faster than they were read: some were lost.

### `WATCH_IGNORED`

```gizlang
const WATCH_IGNORED = 32768
```

The folder's watch ended (the folder is gone): its number is free.

### `WATCH_FOLDER`

```gizlang
const WATCH_FOLDER = 1073741824
```

The entry is a folder.

### `TIME_OMIT`

```gizlang
const TIME_OMIT = 1073741822
```

The time value that leaves a time unchanged.

### `DIRENT_UNKNOWN`

```gizlang
const DIRENT_UNKNOWN = 0
```

The directory entry kind: unknown, 0.

### `DIRENT_FILE`

```gizlang
const DIRENT_FILE = 1
```

The directory entry kind: file, 1.

### `DIRENT_DIR`

```gizlang
const DIRENT_DIR = 2
```

The directory entry kind: dir, 2.

### `DIRENT_LINK`

```gizlang
const DIRENT_LINK = 3
```

The directory entry kind: link, 3.

### `DIRENT_FIFO`

```gizlang
const DIRENT_FIFO = 4
```

The directory entry kind: fifo, 4.

### `DIRENT_SOCKET`

```gizlang
const DIRENT_SOCKET = 5
```

The directory entry kind: socket, 5.

### `DIRENT_CHAR`

```gizlang
const DIRENT_CHAR = 6
```

The directory entry kind: char, 6.

### `DIRENT_BLOCK`

```gizlang
const DIRENT_BLOCK = 7
```

The directory entry kind: block, 7.

gizlang:system

The program's authority: files, network, arguments and environment. A process receives it as main(sys: System); library code can use only what it is passed, and every value here has private fields, so none can be forged. Directories, streams, listeners and sockets belong to the task that opened them and close when it ends; using one after it closed is fault 14. Reads, writes, connects, accepts and receives suspend only the calling task. Failures a program should handle are IoError values.

gizlang

import * as System from "gizlang:system";

Types

`System`

gizlang

type System

The handle of the running system: its files, clock, processes and network.

Opaque: create and use it through this module's functions.

`DirectoryEntries`

gizlang

type DirectoryEntries

A directory that is being listed, entry by entry.

Opaque: create and use it through this module's functions.

`Dir`

gizlang

type Dir

An open directory: files and folders are opened below it.

Opaque: create and use it through this module's functions.

`Stream`

gizlang

type Stream

An open byte stream, such as a file or a pipe.

Opaque: create and use it through this module's functions.

`Listener`

gizlang

type Listener

A listening socket that accepts connections.

Opaque: create and use it through this module's functions.

`Socket`

gizlang

type Socket

A connected socket.

Opaque: create and use it through this module's functions.

`Ready`

gizlang

type Ready

Connections waiting without a task, reported when bytes arrive (Ready.wait).

Opaque: create and use it through this module's functions.

`Signals`

gizlang

type Signals

Process signals a task reads one at a time (System.signals).

Opaque: create and use it through this module's functions.

`Datagram`

gizlang

type Datagram = { data: bytes; host: string; port: i64; }

One received UDP datagram and the address and port it came from.

data: bytes
host: string
port: i64

`IoError`

gizlang

type IoError = { code: i64; }

A platform error code (negative, as libuv reports it) or a Gizlang one.

code: i64

`ProcessUsage`

gizlang

type ProcessUsage = { residentBytes: i64; peakBytes: i64; userMicros: i64; systemMicros: i64; readBytes: i64; writtenBytes: i64; }

The resources that the process used: resident and peak memory (the peak since this program started, not its parent before exec), CPU time and bytes read and written.

residentBytes: i64
peakBytes: i64
userMicros: i64
systemMicros: i64
readBytes: i64
writtenBytes: i64

`CgroupUsage`

gizlang

type CgroupUsage = { path: string; memoryBytes: Option<i64>; cpuMicros: i64; readBytes: Option<i64>; writtenBytes: Option<i64>; }

The resources of the control group that the process runs in; a limit that the system does not report is none.

path: string
memoryBytes: _gizlang_sdk_core.Option<i64>
cpuMicros: i64
readBytes: _gizlang_sdk_core.Option<i64>
writtenBytes: _gizlang_sdk_core.Option<i64>

`Usage`

gizlang

type Usage = { process: ProcessUsage; cgroup: Option<CgroupUsage>; }

The resource use of the process, and of its control group when there is one.

process: gizlang_system.ProcessUsage
cgroup: _gizlang_sdk_core.Option<gizlang_system.CgroupUsage>

`FileInfo`

gizlang

type FileInfo = { size: i64; modified: i64; kind: string; mode: i64; }

What a file is: its size, the time it was modified (ms), its kind and its mode bits.

size: i64
modified: i64
kind: string
mode: i64

`FileClone`

gizlang

type FileClone = | { kind: "reflink"; } | { kind: "hardLink"; }

How a file is cloned: a copy-on-write reflink, or a hard link.

reflink
hardLink

`ProcessMemory`

gizlang

type ProcessMemory = { residentBytes: i64; peakBytes: i64; }

The resident memory of process PID and its peak, on every OS.

residentBytes: i64
peakBytes: i64

`EnvironmentVariable`

gizlang

type EnvironmentVariable = { name: string; value: string; }

One environment variable.

name: string
value: string

`StreamPair`

gizlang

type StreamPair = { first: Stream; second: Stream; }

Two connected streams inside this process: what one writes the other reads, until either closes. A loop watching first in its Ready set is woken by a write to second (from a task, a ticker, or itself).

first: gizlang_system.Stream
second: gizlang_system.Stream

`Watch`

gizlang

type Watch = { stream: Stream; rest: bytes; }

The changes to the entries of folder path ("" is this one) as they happen, until it is closed: Linux inotify.

stream: gizlang_system.Stream
rest: bytes

`WatchEvent`

gizlang

type WatchEvent = { wd: i64; mask: i64; name: string; }

One change: the watch number of the folder, what happened (the WATCH_ bits, Linux inotify's) and the entry's name ("" for the folder itself).

wd: i64
mask: i64
name: string

`ProxyHeader`

gizlang

type ProxyHeader = { size: i64; address: string; }

The PROXY protocol header (HAProxy, versions 1 and 2) that a load balancer writes first on a connection it forwards: size bytes, and the client address (without port; IPv6 as eight groups of four hex digits), or "" for a LOCAL or UNKNOWN connection (the balancer's own health check), whose peer stays the socket's.

size: i64
address: string

`Stdio`

gizlang

type Stdio = | { kind: "inherit" } | { kind: "pipe" } | { kind: "ignore" } | { kind: "stream"; stream: Stream; }

Standard streams and child processes use the same task-owned Stream handles.

inherit
pipe
ignore
stream

`Limits`

gizlang

type Limits = { memory: i64; cpu: i64; processes: i64; }

At most MEMORY bytes (over it the whole process tree is killed), CPU in thousandths of a core (1000: one core), PROCESSES processes and threads; 0 leaves that one unlimited. A Gizlang program stops itself with R011 at four fifths of MEMORY, before the kernel kills it.

memory: i64
cpu: i64
processes: i64

`ProcessGrant`

gizlang

type ProcessGrant = | { kind: "listener"; value: Listener; } | { kind: "stream"; value: Stream; }

Explicit process resources. Both variants use the same inherited descriptor slots.

listener
stream

`SpawnOptions`

gizlang

type SpawnOptions = { stdin: Stdio; stdout: Stdio; stderr: Stdio; cwd: Option<string>; environment: Vec<string>; inheritEnvironment: bool; isolated: bool; handed: Vec<ProcessGrant>; limits: Limits; }

The options of a started process: its three streams, working folder, environment and isolation.

stdin: gizlang_system.Stdio
stdout: gizlang_system.Stdio
stderr: gizlang_system.Stdio
cwd: _gizlang_sdk_core.Option<string>
environment: Vec<string>
inheritEnvironment: bool — False starts with only environment additions and runtime resource grants. Host secrets and unmentioned environment entries are absent.
isolated: bool — Confined to cwd as its whole filesystem, with no network or other process in reach (Linux); a Gizlang program only.
handed: Vec<gizlang_system.ProcessGrant> — Resources inherited as descriptors 3, 4, ... (at most 16): listeners, and streams with an OS descriptor (a file grant, an imported descriptor, a sys.streamPair end). Listener grants are received through sys.handed(index); a stream through sys.importDescriptor(3 + index, ...); native programs use the descriptor ABI.
limits: gizlang_system.Limits — Resource limits (Linux cgroup v2, below a delegated cgroup of the spawner's); a Gizlang program only, which exits 71 rather than run without them.

`Child`

gizlang

type Child

A started process.

Opaque: create and use it through this module's functions.

`ExitStatus`

gizlang

type ExitStatus = | { kind: "code"; code: i64 } | { kind: "signal"; signal: i64 }

How a process ended: with an exit code, or by a signal.

code
signal

`Output`

gizlang

type Output = { status: ExitStatus; stdout: bytes; stderr: bytes; }

What a process printed and how it ended.

status: gizlang_system.ExitStatus
stdout: bytes
stderr: bytes

`Ran`

gizlang

type Ran = { code: i64; out: string; err: string; }

A finished process as text: its exit code (ExitStatus.exitCode) and its two outputs. Tools that run programs and read their output as text use it (the CLI, the test harness, the fleet tools).

code: i64
out: string
err: string

`CaptureBudget`

gizlang

type CaptureBudget = { milliseconds: i64; outputBytes: i64; }

Capture bounds are independent of SpawnOptions' OS resource limits.

milliseconds: i64
outputBytes: i64

`CapturedOutput`

gizlang

type CapturedOutput = { output: Output; outputLimit: bool; }

The output of a process, and whether it was cut at the output limit.

output: gizlang_system.Output
outputLimit: bool

`Stat`

gizlang

type Stat = { dev: i64; mode: i64; nlink: i64; uid: i64; gid: i64; rdev: i64; blksize: i64; ino: i64; size: i64; blocks: i64; atimeSec: i64; atimeNsec: i64; mtimeSec: i64; mtimeNsec: i64; ctimeSec: i64; ctimeNsec: i64; birthSec: i64; birthNsec: i64; }

Everything stat(2) reports (statx on Linux), times as seconds and nanoseconds. birth is ctime when the file system does not keep a birth time, as libuv reports it.

dev: i64
mode: i64
nlink: i64
uid: i64
gid: i64
rdev: i64
blksize: i64
ino: i64
size: i64
blocks: i64
atimeSec: i64
atimeNsec: i64
mtimeSec: i64
mtimeNsec: i64
ctimeSec: i64
ctimeNsec: i64
birthSec: i64
birthNsec: i64

`StatFs`

gizlang

type StatFs = { type: i64; bsize: i64; blocks: i64; bfree: i64; bavail: i64; files: i64; ffree: i64; }

The numbers of a file system, as statfs reports them.

type: i64
bsize: i64
blocks: i64
bfree: i64
bavail: i64
files: i64
ffree: i64

`DirEntry`

gizlang

type DirEntry = { name: string; kind: i64; }

A directory entry and its kind: the UV_DIRENT values (0 unknown, 1 file, 2 dir, 3 link, 4 fifo, 5 socket, 6 char, 7 block).

name: string
kind: i64

`Ring`

gizlang

type Ring

An io_uring of 128-byte submissions for passthrough commands (IORING_OP_URING_CMD): the ublk control and queue commands, NVMe passthrough. Each command carries USER_DATA, and its completion comes back with it. Linux only: elsewhere System.ring fails. Close it with close.

Opaque: create and use it through this module's functions.

`Completion`

gizlang

type Completion = { userData: i64; result: i64; }

A completed command: the USER_DATA it was queued with and its result (negative: -errno).

userData: i64
result: i64

`TerminalSize`

gizlang

type TerminalSize = { columns: i64; rows: i64; }

The size of a terminal in columns and rows.

columns: i64
rows: i64

`OsInfo`

gizlang

type OsInfo = { sysname: string; release: string; version: string; machine: string; }

The operating system: its name, release, version and machine type.

sysname: string
release: string
version: string
machine: string

`MemoryInfo`

gizlang

type MemoryInfo = { total: i64; available: i64; }

Physical memory in bytes: all of it, and what the OS can give without swapping (Linux MemAvailable, macOS free and inactive pages, Windows available physical memory; Node's os.totalmem and os.freemem).

total: i64
available: i64

`CpuInfo`

gizlang

type CpuInfo = { model: string; speed: i64; user: i64; nice: i64; sys: i64; idle: i64; irq: i64; }

The time of one CPU: its model, speed and the time it spent in each mode.

model: string
speed: i64
user: i64
nice: i64
sys: i64
idle: i64
irq: i64

`Interface`

gizlang

type Interface = { name: string; address: string; netmask: string; family: string; mac: string; internal: bool; scopeId: i64; }

A network interface: its name, address, netmask, family, MAC address, whether it is internal, and its scope id.

name: string
address: string
netmask: string
family: string
mac: string
internal: bool
scopeId: i64

`UserInfo`

gizlang

type UserInfo = { uid: i64; gid: i64; username: string; homedir: string; shell: string; }

A user of the system: ids, name, home folder and shell.

uid: i64
gid: i64
username: string
homedir: string
shell: string

`Credentials`

gizlang

type Credentials = { uid: i64; euid: i64; gid: i64; egid: i64; groups: Vec<i64>; }

The user and group ids that the process runs with; -1 and no groups on Windows.

uid: i64
euid: i64
gid: i64
egid: i64
groups: Vec<i64>

Functions

`osError`

gizlang

function osError(code: i64): IoError

The IoError of CODE, a code the runtime or the OS gave: the Linux number of its name on every OS, so that it compares with NOT_FOUND and the other names.

`ioMessage`

gizlang

function ioMessage<T>(result: Result<T, IoError>, what: string): T throws string

RESULT with its error as WHAT, a colon and the error's message, for a caller that reports plain text.

`publicAddress`

gizlang

function publicAddress(address: string): bool

Whether address (as System.addresses returns it) is on the public internet: false for loopback, private, carrier-grade NAT, link-local, documentation, benchmarking, multicast and reserved IPv4 ranges, and for their IPv6 counterparts (::1, unique local, link- and site-local, multicast, documentation) and IPv6 forms that carry an IPv4 address (mapped, compatible, NAT64, 6to4, Teredo) unless that address is public. Not an address at all is false.

Effects: fail.

`serveThreads`

gizlang

function serveThreads<F>(self: System, count: i64, work: F): i64 throws IoError effects { work, io, fail }

work(own, i) for every i in 0..count: i = 0 on the calling thread with this System, each other i on an OS thread of its own (Task.thread) with its own System. The requests they served, or the first error (a thread that faults is IO_FAILURE). A server that listens in each call on one port (listenShared) has a reactor for each thread, and the kernel spreads the connections among them. What work captures is shared read-only; state that every thread sees lives in a database, not in a thread's memory.

`serveConnections`

gizlang

function serveConnections(set: Ready, turnConnection: (stream: Stream) => i64): i64 throws IoError

The one scheduler of a server of any protocol: it answers the connections that the Ready set reports. turn(stream) reads what the connection has sent, answers it, and returns the number of requests it served; it gives the connection back with set.watch(stream) or closes it. A fault in a turn ends only its connection. Fill the set with set.accept(listener) (or let a TLS layer fill it). It returns the sum of the counts when the set stops (the listener is closed; requests in flight finish), or the error that stopped it. HTTP (gizlang:http) is a turn on this; so is a protocol you write.

Effects: fail, read, write, console, io.

`ready`

gizlang

function ready(idleMs: i64): Ready throws IoError

A set of connections that wait without a task, as epoll does: those it accepts or is given to watch are reported once each by wait() when bytes arrive or they end (bytes put back with unread do not count). A connection watched and silent for idleMs (0: no limit) is reported too, and its read fails with TIMED_OUT. It grants nothing: connections come from a Listener or a Stream the caller holds.

Effects: fail, io.

`peerClosed`

gizlang

function peerClosed(descriptor: i64): bool

Whether the peer of socket DESCRIPTOR (Stream.descriptor) has closed its side, without taking any of its bytes, on any thread; false for a socket still open or for another descriptor. A server's thread asks it during a long statement, whose client may have left.

Effects: fail, io.

`proxyHeader`

gizlang

function proxyHeader(data: bytes): Option<ProxyHeader>

The PROXY header at the start of data, if it has a whole one.

Effects: fail.

`spawnOptions`

gizlang

function spawnOptions(): SpawnOptions

The default options of System.spawn: inherited standard streams and environment, no handed descriptors.

`direntKind`

gizlang

function direntKind(mode: i64): i64

The kind of a Stat's mode, as a DIRENT value.

Effects: fail.

Methods

`System.temporaryDir`

gizlang

function System.temporaryDir(self: System): Dir throws IoError

A private fresh directory under $TMPDIR (else /tmp), recursively removed on close or task termination.

Effects: fail, io.

`Dir.temporaryPath`

gizlang

function Dir.temporaryPath(self: Dir): string throws IoError

A new path in this directory that no file has, for a temporary file that the caller makes.

Effects: fail, io.

`System.exit`

gizlang

function System.exit(self: System, code: i64): bool throws IoError

End the process without printing main's result. Codes are 0..255.

Effects: fail, io.

`IoError.message`

gizlang

function IoError.message(self: IoError): string

The text of the error, as the operating system describes its code.

Effects: fail, io.

`System.time`

gizlang

function System.time(self: System): i64

The working directory. Milliseconds since 1970-01-01 UTC by the system clock (gizlang:time reads them).

Effects: fail, io.

`System.availableMemory`

gizlang

function System.availableMemory(self: System): i64 throws IoError

The bytes the host can still give this process before it runs out: the machine's available memory, and on Linux the room left in the process's cgroup and its ancestors (the allocator's own measure, Memory.roomBytes). This observation is not a reservation. NOT_SUPPORTED where the OS does not tell.

Effects: fail, read.

`System.processUsage`

gizlang

function System.processUsage(self: System): ProcessUsage throws IoError

The process's resident memory, its peak, its CPU time and the bytes it read from and wrote to storage, on every OS.

Effects: fail, io.

`System.usage`

gizlang

function System.usage(self: System): Usage throws IoError

processUsage, and on Linux the totals of the process's cgroup. Cgroup totals include every process in the cgroup; they are not allocator credit or a per-process reservation.

Effects: fail, io.

`System.memoryOf`

gizlang

function System.memoryOf(self: System, pid: i64): ProcessMemory throws IoError

The resident and peak memory of the process PID, in bytes.

Effects: fail, io.

`System.entropy`

gizlang

function System.entropy(self: System): u64

64 unpredictable bits from the operating system, to seed gizlang:random.

Effects: fail, io.

`System.randomBytes`

gizlang

function System.randomBytes(self: System, n: i64): bytes throws IoError

Secure bytes directly from the OS; zero is empty, negative lengths are EINVAL.

Effects: fail, io.

`System.randomBelow`

gizlang

function System.randomBelow(self: System, below: i64): i64 throws IoError requires below> 0 { const first = try self.randomBytes(RANDOM_WORD_BYTES)

Secure uniform integer in [below), with a fresh OS draw on each rejection.

Effects: fail, io.

`System.files`

gizlang

function System.files(self: System): Dir throws IoError

The working directory.

Effects: fail, io.

`System.currentDirectory`

gizlang

function System.currentDirectory(self: System): string throws IoError

Physical process working directory; never trust the mutable PWD environment. OS namespace confinement applies to the existing realpath primitive.

Effects: fail, io.

`System.absolute`

gizlang

function System.absolute(self: System, path: string): string throws IoError

path unchanged when it is absolute, else read against currentDirectory.

Effects: fail, io.

`System.copyFile`

gizlang

function System.copyFile(self: System, from: string, to: string): i64 throws IoError

A bounded file copy, published through the same durable staging owner.

Effects: fail, read, write, console, io.

`System.copyTree`

gizlang

function System.copyTree(self: System, from: string, to: string): bool throws IoError

Copy an entry without following links; publish the completed tree once.

Effects: fail, read, write, console, io.

`System.rename`

gizlang

function System.rename(self: System, from: string, to: string): bool throws IoError

Rename between independently confined parent grants. EXDEV is explicit; callers may copy regular files, but directory publication stays atomic.

Effects: fail, io.

`System.move`

gizlang

function System.move(self: System, from: string, to: string): bool throws IoError

Cross-device moves copy beside TO, rename the copy into place, and remove the source after that publication: a reader of TO sees all of it or nothing. A copy straight into TO let another process read half of a shared cache entry when the build folder was on another file system.

Effects: fail, read, write, console, io.

`System.touch`

gizlang

function System.touch(self: System, path: string): bool throws IoError

Dir.touch at PATH.

Effects: fail, io.

`System.readFile`

gizlang

function System.readFile(self: System, path: string): bytes throws IoError

The path forms of Dir.readFile, Dir.readBounded, Dir.replaceFile, Dir.appendFile and Dir.info: the entry's directory is opened, used once and closed. One owner, so callers keep no directory(dirname) wrappers of their own.

Effects: fail, io.

`System.readBounded`

gizlang

function System.readBounded(self: System, path: string, limit: i64): bytes throws IoError

The contents of the file PATH, failing when it is larger than LIMIT bytes.

Effects: fail, io.

`System.replaceFile`

gizlang

function System.replaceFile(self: System, path: string, data: bytes): i64 throws IoError

Atomic: a reader sees the old file or the new one, never part of it.

Effects: fail, read, write, console, io.

`System.appendFile`

gizlang

function System.appendFile(self: System, path: string, data: bytes): i64 throws IoError

Appends DATA to the file PATH, made when it is missing; the number of bytes written.

Effects: fail, io.

`System.info`

gizlang

function System.info(self: System, path: string): FileInfo throws IoError

The size, modification time, kind and mode of PATH.

Effects: fail, io.

`System.exists`

gizlang

function System.exists(self: System, path: string): bool

Whether PATH exists (info finds it).

Effects: fail, io.

`System.realPath`

gizlang

function System.realPath(self: System, path: string): string throws IoError

Resolve a path through the process namespace under the caller's System authority.

Effects: fail, io.

`System.makeDirectories`

gizlang

function System.makeDirectories(self: System, path: string): bool throws IoError

Create parents using physical path traversal, without lexical dot reduction.

Effects: fail, io.

`System.removeTree`

gizlang

function System.removeTree(self: System, path: string): bool throws IoError

Remove one caller-selected tree. Child links are removed, never traversed.

Effects: fail, io.

`System.directory`

gizlang

function System.directory(self: System, path: string): Dir throws IoError

A directory the program is given, relative to the working directory or absolute (a path from the command line): everything opened through it stays below it.

Effects: fail, io.

`System.executable`

gizlang

function System.executable(self: System): string throws IoError

This process's executable path from the OS, independent of argv[0] and environment. The same path/encoding bounds apply as for realPath.

Effects: fail, io.

`System.arguments`

gizlang

function System.arguments(self: System): Vec<string>

The command-line arguments after the program name.

Effects: fail, io.

`System.environment`

gizlang

function System.environment(self: System, name: string): Option<string>

The value of the environment variable NAME, or none when it is not set.

Effects: fail, io.

`System.environmentVariables`

gizlang

function System.environmentVariables(self: System): Vec<EnvironmentVariable>

Every environment variable of this process, in the OS's order.

Effects: fail, io.

`System.importDescriptor`

gizlang

function System.importDescriptor(self: System, descriptor: i64, mode: i64): Stream throws IoError

Duplicate a descriptor returned by a native OS ABI into task-owned I/O. The original remains caller-owned. Only READ/WRITE modes are accepted; positionless devices/pipes use read/write, not readAt/writeAt.

Effects: fail, io.

`Stream.duplicate`

gizlang

function Stream.duplicate(self: Stream, mode: i64): Stream throws IoError

Duplicate a file/native-descriptor stream with independently owned I/O. READ/WRITE permissions may only narrow. The logical file cursor is copied; the OS open-file description (including flock ownership) remains shared. TCP, TLS and in-process streams do not expose descriptor duplication.

Effects: fail, io.

`Stream.release`

gizlang

function Stream.release(self: Stream): i64 throws IoError

The connection as a descriptor of its own, for another thread of this process to take (System.adopt), and the stream closed. A stream a Ready set holds, with TLS, or with bytes it read ahead is refused (EBUSY).

Effects: fail, io.

`System.adopt`

gizlang

function System.adopt(self: System, descriptor: i64): Stream throws IoError

The connected TCP socket at DESCRIPTOR (Stream.release on another thread of this process) as this thread's stream, which a Ready set can watch. On an error the descriptor is closed.

Effects: fail, io.

`System.streamPair`

gizlang

function System.streamPair(self: System): StreamPair throws IoError

Two connected streams: what one writes, the other reads.

Effects: fail, io.

`System.socket`

gizlang

function System.socket(self: System): Stream throws IoError

Allocate an unconnected TCP stream in the current task. A deadline child may connect/use it while this owner retains the handle and closes on uncertainty.

Effects: fail, io.

`Stream.connect`

gizlang

function Stream.connect(self: Stream, host: string, port: i64): bool throws IoError

Connects this stream to HOST and PORT.

Effects: fail, io.

`System.connect`

gizlang

function System.connect(self: System, host: string, port: i64): Stream throws IoError

A TCP connection to HOST and PORT.

Effects: fail, io.

`System.connectUnix`

gizlang

function System.connectUnix(self: System, path: string): Stream throws IoError

A connection to the unix-domain socket at path (at most 107 bytes): a local server such as a database, and an isolated process's way to one placed in its folder.

Effects: fail, io.

`System.addresses`

gizlang

function System.addresses(self: System, host: string): Vec<string> throws IoError

The IPv4 and IPv6 addresses of host: an address as it is (IPv4 in dotted decimal without leading zeros, IPv6 with or without brackets), else the addresses /etc/hosts lists for it, else the A and AAAA answers of the first name server in /etc/resolv.conf to answer within RESOLVE_MS, asking the name as written (no search domains). A program that must know where it connects, as a server fetching URLs it is given, checks these (publicAddress) and connects to one of them, so no second lookup can answer differently. UNKNOWN_HOST when no address is found.

Effects: fail, io.

`System.texts`

gizlang

function System.texts(self: System, host: string): Vec<string> throws IoError

The TXT records of host (the strings of each one joined), from the first name server in /etc/resolv.conf that has any within RESOLVE_MS, asking the name as written. A domain's owner proves control with one (a verification token, an ACME DNS-01 challenge). UNKNOWN_HOST when there is none.

Effects: fail, io.

`System.textsFrom`

gizlang

function System.textsFrom(self: System, server: string, port: i64, host: string): Vec<string> throws IoError

The TXT records of host as the name server at server (an address) and port answers them within RESOLVE_MS: a domain's own (authoritative) server, which no cache holds back. UNKNOWN_HOST when there is none.

Effects: fail, io.

`System.listen`

gizlang

function System.listen(self: System, host: string, port: i64): Listener throws IoError

Listen for TCP connections; port 0 picks a free port (Listener.port).

Effects: fail, io.

`System.listenUnix`

gizlang

function System.listenUnix(self: System, path: string): Listener throws IoError

Listen at the unix-domain socket path (at most 107 bytes; nothing may be there yet; closing the listener removes it). Its connections are Streams as TCP ones are; port() is 0.

Effects: fail, io.

`System.listenShared`

gizlang

function System.listenShared(self: System, host: string, port: i64): Listener throws IoError

Listen on a port other listeners share: each Task.thread (or worker process) of a server listens on it and the kernel spreads connections among them (SO_REUSEPORT). Every listener on the port must be shared, and a second program run by the same user could share it too, so plain listen is the default: binding a port in use is an error there.

Effects: fail, io.

`System.bind`

gizlang

function System.bind(self: System, host: string, port: i64): Socket throws IoError

A UDP socket on a local address; port 0 picks a free port (Socket.port).

Effects: fail, io.

`Dir.open`

gizlang

function Dir.open(self: Dir, path: string, mode: i64): Stream throws IoError

A file below this directory; paths are relative and never leave it.

Effects: fail, io.

`Dir.readFile`

gizlang

function Dir.readFile(self: Dir, path: string): bytes throws IoError

The whole file. Up to its size is read at once, then anything past it (a file of /proc or /sys tells a size that is not its length: /sys/devices/system/cpu/possible is 4,096 bytes for 5). readAll's 64 KiB reads were copied again at each doubling of its buffer, a fifth of the reads of a 10M-row COPY's commit (2026-10-17).

Effects: fail, io.

`Dir.readBounded`

gizlang

function Dir.readBounded(self: Dir, path: string, limit: i64): bytes throws IoError

Read a regular file through one confined handle, admitting its size before allocating. Negative limits and files above the limit are INVALID_ARGUMENT; shrinkage or growth during the read is IO_FAILURE. Every outcome closes the opened handle. A same-size concurrent rewrite requires a caller's digest.

Effects: fail, io.

`Dir.writeFile`

gizlang

function Dir.writeFile(self: Dir, path: string, data: bytes): i64 throws IoError

Writes DATA as the whole file PATH (made or truncated); the number of bytes written.

Effects: fail, io.

`Dir.appendFile`

gizlang

function Dir.appendFile(self: Dir, path: string, data: bytes): i64 throws IoError

POSIX O_APPEND interoperates with other writers without cooperative locks.

Effects: fail, io.

`Dir.copyFileTo`

gizlang

function Dir.copyFileTo(self: Dir, from: string, target: Dir, to: string): i64 throws IoError

Copies the file FROM of this directory to TO in TARGET, with its mode; the number of bytes copied.

Effects: fail, read, write, console, io.

`Dir.cloneFile`

gizlang

function Dir.cloneFile(self: Dir, from: string, target: Dir, to: string, immutable: bool): FileClone throws IoError

Create an exclusive, durable clone with no byte-copy fallback. A hard link is permitted only when immutable is true: neither namespace may write or truncate that inode for its entire lifetime. Atomic replacement and unlink are permitted. Mutable files require CoW. Hard-link fallback also requires WRITE on the source directory grant.

Effects: fail, io.

`Dir.readLink`

gizlang

function Dir.readLink(self: Dir, path: string): string throws IoError

Read the stored link text without resolving it.

Effects: fail, io.

`Dir.makeLink`

gizlang

function Dir.makeLink(self: Dir, path: string, target: string): bool throws IoError

Store link text; confined operations never follow the newly created link.

Effects: fail, io.

`Dir.attribute`

gizlang

function Dir.attribute(self: Dir, path: string, name: string): string throws IoError

The extended attribute name (a "user." one) of the entry at path, without following a link at its end: "" when it has none. A value is at most 4096 bytes of UTF-8.

Effects: fail, io.

`Dir.setAttribute`

gizlang

function Dir.setAttribute(self: Dir, path: string, name: string, value: string): bool throws IoError

Set the extended attribute name (a "user." one) of the entry at path to value; "" removes it.

Effects: fail, io.

`Dir.watch`

gizlang

function Dir.watch(self: Dir, path: string): Watch throws IoError

Watch folder path below this one ("" is this one): its entries made, removed, moved, written, or given other attributes, and the folder itself removed or moved. Other systems refuse (not supported).

Effects: fail, io.

`Watch.add`

gizlang

function Watch.add(self: Watch, dir: Dir, path: string): i64 throws IoError

Watch folder path below dir ("" is dir) on this watch as well, with the same events: its watch number, which the events name (the folder Dir.watch named is 1). A folder watched already keeps its number.

Effects: fail, io.

`Watch.events`

gizlang

function Watch.events(self: mut Watch): Vec<WatchEvent> throws IoError

The changes since the last call, in order, waiting for at least one. Each wait is limited by Stream.timeout on stream.

Effects: fail, io.

`Watch.next`

gizlang

function Watch.next(self: mut Watch): Vec<string> throws IoError

The names of the entries that changed since the last call, each once, waiting for at least one: "" names the folder itself (removed or moved away), or changes that came faster than they were read (the whole folder may have changed). Each wait is limited by Stream.timeout on stream.

Effects: fail, io.

`Watch.close`

gizlang

function Watch.close(self: Watch): bool

Stops the watch.

Effects: fail, io.

`Dir.makeDir`

gizlang

function Dir.makeDir(self: Dir, path: string): bool throws IoError

A new directory below this one.

Effects: fail, io.

`Dir.makeDirectories`

gizlang

function Dir.makeDirectories(self: Dir, path: string): bool throws IoError

Relative parent creation stays under this capability. Traverse physically through sub grants, never through symlinks or lexical parent reduction. Every created directory is synced itself and in its actual parent; directories that exist are not synced.

Effects: fail, io.

`Dir.makeDirectoriesUnsynced`

gizlang

function Dir.makeDirectoriesUnsynced(self: Dir, path: string): bool throws IoError

makeDirectories with no syncs: for a writer whose owner makes the whole tree durable at once (publishTree).

Effects: fail, io.

`Dir.touch`

gizlang

function Dir.touch(self: Dir, path: string): bool throws IoError

Set an existing entry's times to now, through this directory (it needs write authority). No descriptor holds the entry open for writing, so a program that another process runs at the same time still starts (ETXTBSY).

Effects: fail, io.

`Dir.remove`

gizlang

function Dir.remove(self: Dir, path: string): bool throws IoError

Remove a file or an empty directory.

Effects: fail, io.

`Dir.removeTree`

gizlang

function Dir.removeTree(self: Dir, path: string): bool throws IoError

Missing entries are already removed. Retained cursors close on every failure.

Effects: fail, io.

`Dir.entries`

gizlang

function Dir.entries(self: Dir, path: string): DirectoryEntries throws IoError

A bounded unsorted traversal of entries, excluding dot entries. The retained directory survives closing its parent. Concurrent mutations have OS iterator semantics; a cursor is not a namespace snapshot.

Effects: fail, io.

`DirectoryEntries.read`

gizlang

function DirectoryEntries.read(self: DirectoryEntries, limit: i64): Vec<string> throws IoError

The next names of the listing, at most LIMIT; empty at the end.

Effects: fail, io.

`DirectoryEntries.close`

gizlang

function DirectoryEntries.close(self: DirectoryEntries): bool

Ends the listing.

Effects: fail, io.

`Dir.list`

gizlang

function Dir.list(self: Dir, path: string): Vec<string> throws IoError

Sorted complete listing; callers needing bounded memory use entries().

Effects: fail, io.

`Dir.info`

gizlang

function Dir.info(self: Dir, path: string): FileInfo throws IoError

Inspect the entry itself (including links); "" is this directory.

Effects: fail, io.

`Dir.exists`

gizlang

function Dir.exists(self: Dir, path: string): bool

Whether PATH exists (info finds it).

Effects: fail, io.

`Dir.isDirectory`

gizlang

function Dir.isDirectory(self: Dir, path: string): bool

Whether PATH is a directory (a link to one is not: as info).

Effects: fail, io.

`Dir.rename`

gizlang

function Dir.rename(self: Dir, from: string, to: string): bool throws IoError

Renames FROM to TO in this directory, replacing TO.

Effects: fail, io.

`Dir.renameTo`

gizlang

function Dir.renameTo(self: Dir, destination: Dir, from: string, to: string): bool throws IoError

Moves FROM of this directory to TO in DESTINATION, replacing TO.

Effects: fail, io.

`Dir.renameToNoReplace`

gizlang

function Dir.renameToNoReplace(self: Dir, destination: Dir, from: string, to: string): bool throws IoError

Atomically refuse an existing destination, including files, directories and links. Unsupported host filesystems fail rather than race or replace.

Effects: fail, io.

`Dir.setMode`

gizlang

function Dir.setMode(self: Dir, path: string, mode: i64): bool throws IoError

Sets the permission bits of PATH to MODE.

Effects: fail, io.

`Dir.sub`

gizlang

function Dir.sub(self: Dir, path: string): Dir throws IoError

Delegate an existing subdirectory; the grant survives closing its parent.

Effects: fail, io.

`Dir.walk`

gizlang

function Dir.walk(self: Dir, path: string): Vec<string> throws IoError

Every entry below PATH, at any depth, as paths from this directory.

Effects: fail, io.

`Dir.replaceFile`

gizlang

function Dir.replaceFile(self: Dir, path: string, data: bytes): i64 throws IoError

One staging file in the target's directory: write, fsync, close, rename. A failure after rename is uncertain publication and never rolls the namespace back.

Effects: fail, read, write, console, io.

`Dir.publishFile`

gizlang

function Dir.publishFile(self: Dir, path: string, data: bytes): i64 throws IoError

Publish an immutable file only if its final name is absent. Existing files, directories and links are never overwritten. Uses the same durable staging and no-replace rename owner as publishTree.

Effects: fail, read, write, console, io.

`Dir.replaceWith`

gizlang

function Dir.replaceWith(self: Dir, path: string, write: (stream: Stream) => Result<i64, IoError>): i64 throws IoError

The single atomic publication owner accepts an admitted streaming writer. The callback owns its bounded buffers; this owner owns staging and durability.

Effects: fail, read, write, console, io.

`Dir.publishWith`

gizlang

function Dir.publishWith(self: Dir, path: string, write: (stream: Stream) => Result<i64, IoError>): i64 throws IoError

The streaming form of publishFile; the writer owns its bounded buffers.

Effects: fail, read, write, console, io.

`Dir.replaceTree`

gizlang

function Dir.replaceTree(self: Dir, source: Dir, from: string, path: string): bool throws IoError

A tree uses the same rename/sync publication owner as a streamed file. Each directory retains only a cursor page; child links are copied as links.

Effects: fail, read, write, console, io.

`Dir.publishTree`

gizlang

function Dir.publishTree(self: Dir, path: string, write: (stage: Dir) => Result<bool, IoError>): bool throws IoError

Assemble an immutable tree in an exclusively owned sibling stage, then atomically expose it only if path is absent. The writer writes plainly (writeFile, makeDirectoriesUnsynced) and closes its handles; this owner makes the tree durable with one file system sync (syncFilesystem), then syncs the parent. A sync for each file and directory of a 146-file compiler snapshot (replaceFile, makeDirectories) was ~1000 syncs one after another, 0.2 s of each live edit; on a build host its 146 file syncs alone took 0.65 s one after another, 0.24 s 16 at a time and 0.02-0.05 s as one syncfs (2026-10-15). Failure after rename is uncertain publication, never namespace rollback.

Effects: fail, read, write, console, io.

`Dir.sync`

gizlang

function Dir.sync(self: Dir): bool throws IoError

Makes the directory's entries durable: files created, renamed or removed in it survive a crash once this returns. The calling task waits; others run.

Effects: fail, io.

`Dir.syncFilesystem`

gizlang

function Dir.syncFilesystem(self: Dir): bool throws IoError

Makes all data written to the file system that holds this directory durable, with the entries of its directories: one call (syncfs) for many files, not one sync for each. It needs write authority. The calling task waits; others run.

Effects: fail, io.

`Dir.close`

gizlang

function Dir.close(self: Dir): bool

Closes the directory handle.

Effects: fail, io.

`Stream.peer`

gizlang

function Stream.peer(self: Stream): string

The address of the peer of a connection, as text (empty for a unix socket or a connection that is gone).

Effects: fail, io.

`Stream.fixPeer`

gizlang

function Stream.fixPeer(self: Stream, address: string): bool

Make address the peer of this connection (Stream.peer), once: false when a PROXY header gave it before.

Effects: fail, io.

`Listener.proxyProtocol`

gizlang

function Listener.proxyProtocol(self: Listener, on: bool): void

The connections of this listener start with a PROXY header (proxyHeader), which Http reads and fixes as the peer. Turn it on only for a port that nothing but a balancer that always sends the header can reach: a client could write one itself. Call it before a set accepts.

Effects: fail, io.

`Ready.proxied`

gizlang

function Ready.proxied(self: Ready): bool

Whether the connection came through a PROXY protocol header.

Effects: fail, io.

`Stream.read`

gizlang

function Stream.read(self: Stream, limit: i64): bytes throws IoError

Up to LIMIT bytes from the stream; empty at its end.

Effects: fail, io.

`Stream.readReady`

gizlang

function Stream.readReady(self: Stream, limit: i64): bytes throws IoError

Up to limit bytes that a socket, pipe or POLLED device has now, without waiting: empty bytes when it has none, and always for a file stream (its reads wait in read).

Effects: fail, io.

`Stream.descriptor`

gizlang

function Stream.descriptor(self: Stream): i64

The descriptor of a socket stream, -1 for another stream or one of another thread. It stays the stream's while the stream is open; peerClosed takes it on any thread.

Effects: fail, io.

`Stream.readAll`

gizlang

function Stream.readAll(self: Stream): bytes throws IoError

Everything until the end of the stream.

Effects: fail, io.

`Stream.readExact`

gizlang

function Stream.readExact(self: Stream, count: i64): bytes throws IoError

Exactly count bytes, consuming no following bytes. Negative count is INVALID_ARGUMENT; premature EOF is IO_FAILURE. Read errors are preserved, partial data is discarded on failure, and the caller retains the stream. Each read asks for all that remains (the runtime bounds one read to 1 MiB), so a large message is a few reads, not one per 64 KiB: each read is a task switch and a copy, and 16 of them took about 2 ms of a storage node's 1 MiB request (2026-10-15). The caller must admit the requested output size.

Effects: fail, io.

`Stream.unread`

gizlang

function Stream.unread(self: Stream, data: bytes): i64 throws IoError

Put bytes back before what the next read returns, as a parser does with the start of a message it cannot finish yet; if the stream ends with nothing after them, reads report the end instead. Not on a TLS stream.

Effects: fail, io.

`Stream.write`

gizlang

function Stream.write(self: Stream, data: bytes): i64 throws IoError

Write all of data; the number of bytes written.

Effects: fail, io.

`Stream.shutdown`

gizlang

function Stream.shutdown(self: Stream): bool throws IoError

Ends a connection's write side: the peer reads its end, and reads here go on (a TCP FIN; a pipe ends at its close).

Effects: fail, io.

`Stream.copyTo`

gizlang

function Stream.copyTo(self: Stream, to: Stream): i64 throws IoError

Checked bounded copy; neither stream is closed.

Effects: fail, io.

`Stream.relay`

gizlang

function Stream.relay(self: Stream, other: Stream): void

Copies bytes both ways between two connections until either side ends, then stops the other way too; neither is closed.

Effects: fail, io.

`Stream.setMode`

gizlang

function Stream.setMode(self: Stream, mode: i64): bool throws IoError

Change permission bits on the held writable inode, before publication.

Effects: fail, io.

`Stream.touch`

gizlang

function Stream.touch(self: Stream): bool throws IoError

Sets the modification time of the open file to now.

Effects: fail, io.

`Stream.close`

gizlang

function Stream.close(self: Stream): bool

Closes the stream.

Effects: fail, io.

`Stream.handle`

gizlang

function Stream.handle(self: Stream): i64

A number naming this open stream among the open ones, for tables of connections (a closed one's may be reused).

`Stream.info`

gizlang

function Stream.info(self: Stream): FileInfo throws IoError

An open file's size in bytes and last modification in milliseconds since 1970 UTC; fails on a stream that is not a file.

Effects: fail, io.

`Stream.timeout`

gizlang

function Stream.timeout(self: Stream, milliseconds: i64): i64 throws IoError

Limit how long each read or write of a socket, pipe or POLLED stream may wait, in milliseconds (0, the start, waits forever); a wait past it fails with a timed-out IoError and the stream should be closed.

Effects: fail, io.

`Stream.detach`

gizlang

function Stream.detach(self: Stream): i64 throws IoError

Give a TCP stream to no task, so it outlives the task that owns it (a client pool keeps an idle connection so); adopt gives it to the calling task, which closes it when it ends. A stream in a Ready set is refused.

Effects: fail, io.

`Stream.adopt`

gizlang

function Stream.adopt(self: Stream): i64 throws IoError

Gives the stream to the calling task, which closes it when it ends. See detach.

Effects: fail, io.

`Stream.sync`

gizlang

function Stream.sync(self: Stream): bool throws IoError

Makes what was written to the file durable (its data and size, as fdatasync): it survives a crash once this returns. The calling task waits; others run.

Effects: fail, io.

`Stream.lock`

gizlang

function Stream.lock(self: Stream): bool throws IoError

Takes the file's exclusive lock without waiting: true when this process now holds it, false when another process does. It lasts while the file is open, however the process ends, so one server owns a data folder at a time.

Effects: fail, io.

`Stream.truncate`

gizlang

function Stream.truncate(self: Stream, length: i64): i64 throws IoError

Cuts the file to length bytes, or extends it with zeros.

Effects: fail, io.

`Stream.readAt`

gizlang

function Stream.readAt(self: Stream, offset: i64, count: i64): bytes throws IoError

count bytes of the file from offset, fewer only at its end (pread). It neither uses nor moves the position of read and write, and several run at once.

Effects: fail, io.

`Stream.readMany`

gizlang

function Stream.readMany(self: Stream, parts: Vec<i64>): bytes throws IoError

The bytes of each part of parts (an offset, then a size, for each part), in their order in one value: the reads of rows that sit apart in a file, in one call. A part past the end of the file is an error. Like readAt, it does not use or move the position.

Effects: fail, io.

`Stream.writeAt`

gizlang

function Stream.writeAt(self: Stream, offset: i64, data: bytes): i64 throws IoError

Writes all of data at offset of the file (pwrite). It neither uses nor moves the position of read and write, and several run at once.

Effects: fail, io.

`Stream.seek`

gizlang

function Stream.seek(self: Stream, offset: i64): i64 throws IoError

Move a file's read and write position to offset bytes from its start.

Effects: fail, io.

`Ready.accept`

gizlang

function Ready.accept(self: Ready, listener: Listener): i64 throws IoError

Accept the listener's connections into the set; each is watched.

Effects: fail, io.

`Ready.watch`

gizlang

function Ready.watch(self: Ready, stream: Stream): i64 throws IoError

Report the connection once more when it is ready. Until then the set holds it, not the task: give it back after answering what it sent.

Effects: fail, io.

`Ready.channel`

gizlang

function Ready.channel<T>(self: Ready, channel: Task.Channel<T>): Stream

A crossing channel in the set, with no socket: watch() the returned stream, and wait() returns it, once per watch, when another thread sent a value (or closed the channel). Drain it with Task.tryReceive, then watch it again. One set watches a channel. Close the stream to remove it.

`Ready.wait`

gizlang

function Ready.wait(self: Ready): Stream throws IoError

The next ready connection, which now belongs to the calling task (it closes when the task ends); fails once the listener fails or the set is closed. Reading it returns what arrived at once.

Effects: fail, io.

`Ready.idle`

gizlang

function Ready.idle(self: Ready): i64

How many tasks are waiting in wait() now; 0 after a task took a connection means the next one would wait for a task to finish (add one, if wanted).

Effects: fail, io.

`Ready.queued`

gizlang

function Ready.queued(self: Ready): bool

Whether a connection is ready now, so wait() returns it at once: a server that answers after one write for all the requests of a pass (a log write) makes that write when none is.

Effects: fail, io.

`Ready.time`

gizlang

function Ready.time(self: Ready): i64

The wall clock (milliseconds since 1970 UTC) for a set that serves a listener or connections of a System, else 0: the Date of gizlang:http's responses.

Effects: fail, io.

`Ready.close`

gizlang

function Ready.close(self: Ready): bool

Close the set and the connections waiting in it.

Effects: fail, io.

`System.signals`

gizlang

function System.signals(self: System, ids: Vec<i64>): Signals throws IoError

The signals in ids (TERM, INT, HUP, QUIT, USR1, USR2) as a stream a task reads with next(), not as handlers: a program that subscribes to TERM no longer ends on it, and ends when it decides to (after a checkpoint, for example). A signal that comes while no task reads is kept for the next read; the same signal sent twice before a read can arrive once, as the kernel keeps one pending. The subscription closes when the task that opened it ends.

Effects: fail, io.

`Signals.next`

gizlang

function Signals.next(self: Signals): i64 throws IoError

The next signal not read yet (TERM, ...); it waits for one. Signals that wait together come in the order of their numbers.

Effects: fail, io.

`Signals.close`

gizlang

function Signals.close(self: Signals): bool

Stop the subscription; a task waiting in next() gets an error.

Effects: fail, io.

`Listener.port`

gizlang

function Listener.port(self: Listener): i64

The port that the listener is bound to.

Effects: fail, io.

`Listener.backlog`

gizlang

function Listener.backlog(self: Listener, capacity: i64): bool throws IoError

Set the pending connection bound (1..2147483647). The kernel may clamp it to its system maximum. Existing connections and listener authority remain.

Effects: fail, io.

`Listener.accept`

gizlang

function Listener.accept(self: Listener): Stream throws IoError

Waits for the next connection and gives it.

Effects: fail, io.

`Listener.close`

gizlang

function Listener.close(self: Listener): bool

Closes the listener. Connections that it accepted stay open.

Effects: fail, io.

`Socket.port`

gizlang

function Socket.port(self: Socket): i64

The local port that the socket is bound to.

Effects: fail, io.

`Socket.send`

gizlang

function Socket.send(self: Socket, host: string, port: i64, data: bytes): i64 throws IoError

Send data as one datagram; the number of bytes sent. Delivery is not confirmed.

Effects: fail, io.

`Socket.receive`

gizlang

function Socket.receive(self: Socket, limit: i64): Datagram throws IoError

The next datagram, waiting for one; at most limit bytes of it.

Effects: fail, io.

`Socket.close`

gizlang

function Socket.close(self: Socket): bool

Closes the socket.

Effects: fail, io.

`ExitStatus.exitCode`

gizlang

function ExitStatus.exitCode(self: ExitStatus): i64

The status as one exit code, as a shell gives it: the code, or 128 + N for signal N.

Effects: fail.

`Output.ran`

gizlang

function Output.ran(self: Output): Ran

The output as text.

Effects: fail.

`System.stdin`

gizlang

function System.stdin(self: System): Stream throws IoError

The standard input of this process.

Effects: fail, io.

`System.stdout`

gizlang

function System.stdout(self: System): Stream throws IoError

The standard output of this process.

Effects: fail, io.

`System.stderr`

gizlang

function System.stderr(self: System): Stream throws IoError

The standard error of this process.

Effects: fail, io.

`System.printError`

gizlang

function System.printError(self: System, line: string): void

LINE and a newline on standard error: diagnostics, kept apart from the output of the program.

Effects: fail, io.

`System.handed`

gizlang

function System.handed(self: System, index: i64): Listener throws IoError

The listener the parent handed this process at INDEX (its SpawnOptions.handed), taken once: still bound to the parent's address and network.

Effects: fail, io.

`System.spawn`

gizlang

function System.spawn(self: System, program: string, args: Vec<string>, options: SpawnOptions): Child throws IoError

Starts PROGRAM with ARGS and OPTIONS. The child runs until it ends; Child.wait gives its status.

Effects: fail, io.

`System.exec`

gizlang

function System.exec(self: System, program: string, args: Vec<string>, environment: Vec<string>): IoError

This process becomes PROGRAM (found on PATH, as spawn finds it) with ARGS and this environment plus ENVIRONMENT (NAME=VALUE; the last of a name wins): its PID, signals, handed listeners and exit status are then the program's own. Use it when nothing is left to do after the program, so that killing this process stops the program (a spawned child that is waited on outlives a killed parent). It returns only on a failure.

Effects: fail, io.

`Child.stdin`

gizlang

function Child.stdin(self: Child): Option<Stream>

The pipe to the standard input of the child, when the options asked for a pipe.

Effects: fail, io.

`Child.stdout`

gizlang

function Child.stdout(self: Child): Option<Stream>

The pipe from the standard output of the child, when the options asked for a pipe.

Effects: fail, io.

`Child.stderr`

gizlang

function Child.stderr(self: Child): Option<Stream>

The pipe from the standard error of the child, when the options asked for a pipe.

Effects: fail, io.

`Child.pid`

gizlang

function Child.pid(self: Child): i64

The process id of the child.

Effects: fail, io.

`Child.wait`

gizlang

function Child.wait(self: Child): ExitStatus throws IoError

Waits until the child ends; its exit code or the signal that stopped it.

Effects: fail, io.

`System.kill`

gizlang

function System.kill(self: System, pid: i64, signal: i64): bool throws IoError

Sends SIGNAL to the process PID, any this user may signal (Child.kill signals a child by its handle). Signal 0 checks only that the process exists.

Effects: fail, io.

`Child.kill`

gizlang

function Child.kill(self: Child, signal: i64): bool throws IoError

Sends SIGNAL to the child.

Effects: fail, io.

`Child.close`

gizlang

function Child.close(self: Child): bool

Closing a running child terminates and reaps it, like task cleanup.

Effects: fail, io.

`System.run`

gizlang

function System.run(self: System, program: string, args: Vec<string>): Output throws IoError

Drain both pipes concurrently before waiting: neither child's output buffer can keep it from exiting. Captured bytes are grown in place by readAll.

Effects: fail, read, write, io.

`System.runWith`

gizlang

function System.runWith(self: System, program: string, args: Vec<string>, options: SpawnOptions, input: Option<bytes>): Output throws IoError

The same with options' working directory and environment, and input (when given) written to standard input, which is then closed. Its streams are always captured, whatever options say.

Effects: fail, read, write, io.

`System.ranBounded`

gizlang

function System.ranBounded(self: System, program: string, args: Vec<string>, options: SpawnOptions, input: Option<bytes>, budget: CaptureBudget): Ran

runBounded as text (Output.ran): a program that cannot start or ends past the budget gives code 127 and the reason.

Effects: fail, read, write, io.

`System.runBounded`

gizlang

function System.runBounded(self: System, program: string, args: Vec<string>, options: SpawnOptions, input: Option<bytes>, budget: CaptureBudget): Result<CapturedOutput, IoError>

Runs a child with a hard wall-clock deadline and one combined byte cap for stdout and stderr. No shell or retry is introduced. Timeouts return TIMED_OUT; reaching the byte cap kills/reaps the child and returns the bounded output with outputLimit=true. Child/task teardown removes its cgroup and descendants.

Effects: fail, read, write, io.

`System.runStreams`

gizlang

function System.runStreams(self: System, program: string, args: Vec<string>, options: SpawnOptions, input: bytes, milliseconds: i64, outputBytes: i64): Result<CapturedOutput, IoError>

Runs PROGRAM to its end with OPTIONS' streams as they are, as Node's spawnSync does: a pipe is captured (stdin a pipe gets INPUT, or nothing, then closes), any other stream is the child's own. At most MILLISECONDS (0: no limit; then TIMED_OUT) and OUTPUTBYTES captured (-1: no cap; past it the child is killed and outputLimit is set).

Effects: fail, read, write, io.

`System.stat`

gizlang

function System.stat(self: System, path: string, follow: bool): Stat throws IoError

stat(2) or, when FOLLOW is false, lstat(2).

Effects: fail, io.

`System.statFd`

gizlang

function System.statFd(self: System, fd: i64): Stat throws IoError

fstat(2).

Effects: fail, io.

`System.statFs`

gizlang

function System.statFs(self: System, path: string): StatFs throws IoError

statfs(2).

Effects: fail, io.

`System.openFd`

gizlang

function System.openFd(self: System, path: string, flags: i64, mode: i64): i64 throws IoError

open(2) with Linux's flags (O_RDONLY, O_CREAT, ...; O_CLOEXEC is added; the runtime maps them on macOS), giving the descriptor.

Effects: fail, io.

`System.closeFd`

gizlang

function System.closeFd(self: System, fd: i64): bool throws IoError

Closes the file descriptor FD (close).

Effects: fail, io.

`System.readFd`

gizlang

function System.readFd(self: System, fd: i64, count: i64, position: i64): bytes throws IoError requires count> = 0 { let out: bytes = filled(count, 0u)

Up to COUNT bytes from FD, at POSITION (pread) or, when it is negative, at the descriptor's own offset. Empty at the end.

Effects: fail, io.

`System.writeFd`

gizlang

function System.writeFd(self: System, fd: i64, data: bytes, position: i64): i64 throws IoError

DATA to FD at POSITION (pwrite) or, when it is negative, at the descriptor's own offset; the bytes taken.

Effects: fail, io.

`System.syncFd`

gizlang

function System.syncFd(self: System, fd: i64, dataOnly: bool): bool throws IoError

Flushes FD to its device: its data only (fdatasync) when DATAONLY, else data and metadata (fsync).

Effects: fail, io.

`System.truncateFd`

gizlang

function System.truncateFd(self: System, fd: i64, length: i64): bool throws IoError

Sets the length of the file of FD (ftruncate).

Effects: fail, io.

`System.access`

gizlang

function System.access(self: System, path: string, mode: i64): bool throws IoError

Whether the process may access PATH in MODE (access).

Effects: fail, io.

`System.processId`

gizlang

function System.processId(self: System): i64

This process's id (getpid).

`System.parentProcessId`

gizlang

function System.parentProcessId(self: System): i64

The id of the process that started this one.

Effects: io.

`System.pageSize`

gizlang

function System.pageSize(self: System): i64

The size of a memory page in bytes (getpagesize).

`System.mapShared`

gizlang

function System.mapShared(self: System, fd: i64, offset: i64, length: i64, writable: bool = false, alignment: i64 = 1): u64 throws IoError

LENGTH bytes of the descriptor FD from OFFSET, mapped shared and read-only (writable when WRITABLE), at an address that is a multiple of ALIGNMENT (a power of two; 1 for any): their address, which Native.read reads. Unmap it with unmap.

Effects: fail, io.

`System.unmap`

gizlang

function System.unmap(self: System, address: u64, length: i64): bool throws IoError

Unmaps LENGTH bytes at ADDRESS (munmap).

Effects: fail, io.

`System.ring`

gizlang

function System.ring(self: System, entries: i64): Ring throws IoError

A ring of ENTRIES submissions (1 to 32768).

Effects: fail, io.

`Ring.command`

gizlang

function Ring.command(self: Ring, fd: i64, op: u64, userData: i64, w0: u64, w1: u64, w2: u64, w3: u64): bool

Queues command OP on the descriptor FD with USER_DATA (0 to 2^31 - 1) and 32 bytes of command data, the four little-endian words W0 to W3. False when the ring is full: enter, then queue it again.

Effects: fail, io.

`Ring.enter`

gizlang

function Ring.enter(self: Ring, wait: i64): i64 throws IoError

Submits the queued commands and waits until WAIT completions are ready (0: no wait): the number submitted. An interrupted wait fails with EINTR; call it again.

Effects: fail, io.

`Ring.next`

gizlang

function Ring.next(self: Ring): Option<Completion>

The oldest completion, consumed, or none when none is ready.

Effects: fail, io.

`Ring.close`

gizlang

function Ring.close(self: Ring): void

Closes the ring and its mappings.

Effects: fail, io.

`System.unlink`

gizlang

function System.unlink(self: System, path: string): bool throws IoError

Removes the file PATH (unlink).

Effects: fail, io.

`System.removeDir`

gizlang

function System.removeDir(self: System, path: string): bool throws IoError

Removes the empty directory PATH (rmdir).

Effects: fail, io.

`System.makeDir`

gizlang

function System.makeDir(self: System, path: string, mode: i64): bool throws IoError

Makes the directory PATH with MODE (mkdir).

Effects: fail, io.

`System.makeTempDir`

gizlang

function System.makeTempDir(self: System, prefix: string): string throws IoError

mkdtemp(3): PREFIX plus six random characters, the directory made; its path.

Effects: fail, io.

`System.renamePath`

gizlang

function System.renamePath(self: System, from: string, to: string): bool throws IoError

Renames FROM to TO, replacing TO (rename).

Effects: fail, io.

`System.linkPath`

gizlang

function System.linkPath(self: System, from: string, to: string): bool throws IoError

Makes TO a hard link of FROM (link).

Effects: fail, io.

`System.symlinkPath`

gizlang

function System.symlinkPath(self: System, target: string, path: string): bool throws IoError

Makes PATH a symbolic link to TARGET (symlink).

Effects: fail, io.

`System.readSymlink`

gizlang

function System.readSymlink(self: System, path: string): string throws IoError

The target of the symbolic link PATH (readlink).

Effects: fail, io.

`System.resolvePath`

gizlang

function System.resolvePath(self: System, path: string): string throws IoError

realpath(3): the canonical absolute path of an existing PATH.

Effects: fail, io.

`System.changeMode`

gizlang

function System.changeMode(self: System, path: string, mode: i64): bool throws IoError

Sets the permission bits of PATH to MODE (chmod).

Effects: fail, io.

`System.changeModeFd`

gizlang

function System.changeModeFd(self: System, fd: i64, mode: i64): bool throws IoError

Sets the permission bits of the file of FD to MODE (fchmod).

Effects: fail, io.

`System.changeOwner`

gizlang

function System.changeOwner(self: System, path: string, uid: i64, gid: i64, follow: bool): bool throws IoError

chown(2), or lchown(2) when FOLLOW is false; -1 leaves an id unchanged.

Effects: fail, io.

`System.changeOwnerFd`

gizlang

function System.changeOwnerFd(self: System, fd: i64, uid: i64, gid: i64): bool throws IoError

Sets the owner and group of the file of FD; -1 leaves an id unchanged (fchown).

Effects: fail, io.

`System.setTimes`

gizlang

function System.setTimes(self: System, path: string, atimeNs: i64, mtimeNs: i64, follow: bool): bool throws IoError

utimensat(2): the access and modification times in nanoseconds since 1970 (TIME_OMIT keeps one), on the link itself when FOLLOW is false.

Effects: fail, io.

`System.setTimesFd`

gizlang

function System.setTimesFd(self: System, fd: i64, atimeNs: i64, mtimeNs: i64): bool throws IoError

Sets the access and modification times of the file of FD, in nanoseconds since 1970 (futimens).

Effects: fail, io.

`System.readDir`

gizlang

function System.readDir(self: System, path: string): Vec<DirEntry> throws IoError

The entries of directory PATH (without . and ..), in the order the OS gives them.

Effects: fail, io.

`System.copyFd`

gizlang

function System.copyFd(self: System, from: string, to: string, exclusive: bool): bool throws IoError

A copy of FROM at TO: the bytes, then the mode. With EXCLUSIVE an existing TO is EEXIST.

Effects: fail, io.

`System.isTerminal`

gizlang

function System.isTerminal(self: System, fd: i64): bool

Whether FD is a terminal.

Effects: fail, io.

`System.terminalSize`

gizlang

function System.terminalSize(self: System, fd: i64): TerminalSize throws IoError

The columns and rows of the terminal on FD.

Effects: fail, io.

`System.terminalState`

gizlang

function System.terminalState(self: System, fd: i64): bytes throws IoError

The terminal's current mode (opaque bytes: a termios, or a Windows console mode), to give back to terminalRestore.

Effects: fail, io.

`System.terminalRestore`

gizlang

function System.terminalRestore(self: System, fd: i64, state: bytes): bool throws IoError

Gives the terminal on FD back the state that a raw-mode call returned.

Effects: fail, io.

`System.terminalRaw`

gizlang

function System.terminalRaw(self: System, fd: i64): bool throws IoError

Raw mode as libuv sets it: no echo, no canonical lines, no signals, no input translation; output stays cooked.

Effects: fail, io.

`System.hostname`

gizlang

function System.hostname(self: System): string throws IoError

The host name of this machine.

Effects: fail, io.

`System.loadAverage`

gizlang

function System.loadAverage(self: System): Vec<f64>

The load averages of the last 1, 5 and 15 minutes; zeros on Windows, which has none.

Effects: fail, io.

`System.osInfo`

gizlang

function System.osInfo(self: System): OsInfo throws IoError

The name, release, version and machine of the operating system (uname).

Effects: fail, io.

`System.uptime`

gizlang

function System.uptime(self: System): f64

Seconds since boot; 0 when the OS does not tell.

Effects: fail, io.

`System.memoryInfo`

gizlang

function System.memoryInfo(self: System): MemoryInfo

The total and free memory of the machine, in bytes.

Effects: fail, io.

`System.cpuInfo`

gizlang

function System.cpuInfo(self: System): Vec<CpuInfo>

Each CPU: its model, its MHz and its times in milliseconds (libuv uv_cpu_info, Node's os.cpus).

Effects: fail, io.

`System.availableParallelism`

gizlang

function System.availableParallelism(self: System): i64

The CPUs this process may run on, as Node reports them (libuv: the affinity mask, then the cgroup quota): TFB clustered.mjs forks one worker per CPU, so the online count forked 32 workers onto a 4-CPU taskset.

Effects: fail, io.

`System.interfaces`

gizlang

function System.interfaces(self: System): Vec<Interface> throws IoError

The network interfaces with an address, IPv4 and IPv6, each with the MAC of its interface (libuv, as Node's os.networkInterfaces).

Effects: fail, io.

`System.userInfo`

gizlang

function System.userInfo(self: System, uid: i64): UserInfo throws IoError

The user UID (-1: the effective user): libuv's passwd entry. On Windows only the current user, with uid and gid -1 and no shell.

Effects: fail, io.

`System.homeDirectory`

gizlang

function System.homeDirectory(self: System): string throws IoError

$HOME, else the user's home folder (libuv: USERPROFILE on Windows, else the passwd entry).

Effects: fail, io.

`System.priority`

gizlang

function System.priority(self: System, pid: i64): i64 throws IoError

The scheduling priority (nice) of PID (0: this process); libuv maps Windows' priority classes to it.

Effects: fail, io.

`System.setPriority`

gizlang

function System.setPriority(self: System, pid: i64, priority: i64): bool throws IoError

Sets the scheduling priority of the process PID (-20 to 19; lower runs first).

Effects: fail, io.

`System.credentials`

gizlang

function System.credentials(self: System): Credentials

The user, group and supplementary group ids that the process runs with.

Effects: fail, io.

`System.userId`

gizlang

function System.userId(self: System, name: string, group: bool): i64 throws IoError

The numeric user or group id of NAME, or NAME itself when it is a number.

Effects: fail, io.

`System.setCredential`

gizlang

function System.setCredential(self: System, which: string, id: i64): bool throws IoError

setuid and the like: WHICH is "uid", "euid", "gid" or "egid".

Effects: fail, io.

`System.setGroups`

gizlang

function System.setGroups(self: System, ids: Vec<i64>): bool throws IoError

Sets the supplementary groups of the process to IDS (setgroups); it needs the privilege to do so.

Effects: fail, io.

`System.initGroups`

gizlang

function System.initGroups(self: System, user: string, group: i64): bool throws IoError

Sets the supplementary groups of the process to those of USER, plus GROUP (initgroups).

Effects: fail, io.

Constants

`INVALID_ARGUMENT`

gizlang

const INVALID_ARGUMENT = -22

The error code -22: invalid argument.

`HUP`

gizlang

const HUP = 1

Signal numbers for System.signals, as Linux numbers them (the runtime maps them on other platforms).

`INT`

gizlang

const INT = 2

The signal SIGINT (2).

`QUIT`

gizlang

const QUIT = 3

The signal SIGQUIT (3).

`USR1`

gizlang

const USR1 = 10

The signal SIGUSR1 (10).

`USR2`

gizlang

const USR2 = 12

The signal SIGUSR2 (12).

`TERM`

gizlang

const TERM = 15

The signal SIGTERM (15).

`WINCH`

gizlang

const WINCH = 28

The signal SIGWINCH (28).

`READ`

gizlang

const READ = 1

Opening modes, combined with |.

`WRITE`

gizlang

const WRITE = 2

The open flag WRITE (2).

`CREATE`

gizlang

const CREATE = 4

The open flag CREATE (4).

`TRUNCATE`

gizlang

const TRUNCATE = 8

The open flag TRUNCATE (8).

`APPEND`

gizlang

const APPEND = 16

An open modifier, requiring WRITE; every write appends atomically at the OS.

`POLLED`

gizlang

const POLLED = 32

An importDescriptor modifier: a device that polls (such as /dev/fuse) reads and writes as a stream on the event loop, each read when the device is ready, not by a file-pool thread that blocks in it.

`NOT_FOUND`

gizlang

const NOT_FOUND = -2

IoError codes a caller tells apart: no such file or directory, a path that is refused (not a regular file, or no permission), a path that would leave the directory or is malformed, a wait past a stream's timeout, and a host name with no address (System.addresses; connect gives it too).

`IO_FAILURE`

gizlang

const IO_FAILURE = -5

The error code -5: io failure.

`OUT_OF_MEMORY`

gizlang

const OUT_OF_MEMORY = -12

The error code -12: out of memory.

`NO_SPACE`

gizlang

const NO_SPACE = -28

The error code -28: no space.

`CORRUPT_DATA`

gizlang

const CORRUPT_DATA = -74

The error code -74: corrupt data.

`STALE_RESOURCE`

gizlang

const STALE_RESOURCE = -116

The error code -116: stale resource.

`DENIED`

gizlang

const DENIED = -40301

The error code -40301: denied.

`BAD_PATH`

gizlang

const BAD_PATH = -40302

The error code -40302: bad path.

`TIMED_OUT`

gizlang

const TIMED_OUT = -110

The error code -110: timed out.

`CONNECTION_REFUSED`

gizlang

const CONNECTION_REFUSED = -111

The error code -111: connection refused (nothing was sent).

`UNKNOWN_HOST`

gizlang

const UNKNOWN_HOST = -3008

The error code -3008: unknown host.

`NOT_SUPPORTED`

gizlang

const NOT_SUPPORTED = -38

The error code -38: the operating system does not support the call.

`RESOLVE_MS`

gizlang

const RESOLVE_MS = 2000

How long System.addresses waits for each name server's answer.

`WORKERS`

gizlang

const WORKERS = 16

Tasks running turns: serveConnections starts WORKERS and adds one whenever a connection is taken while none waits (a turn waiting on a timer, a file or an upstream holds its task), up to MOST_WORKERS.

`MOST_WORKERS`

gizlang

const MOST_WORKERS = 65536

The most worker tasks that serveConnections starts.

`WATCH_CLOSE_WRITE`

gizlang

const WATCH_CLOSE_WRITE = 8

A file open for writing was closed.

`WATCH_MOVED_FROM`

gizlang

const WATCH_MOVED_FROM = 64

An entry was moved out of the folder.

`WATCH_MOVED_TO`

gizlang

const WATCH_MOVED_TO = 128

An entry was moved into the folder.

`WATCH_CREATE`

gizlang

const WATCH_CREATE = 256

An entry was made in the folder.

`WATCH_DELETE`

gizlang

const WATCH_DELETE = 512

An entry of the folder was removed.

`WATCH_DELETE_SELF`

gizlang

const WATCH_DELETE_SELF = 1024

The folder itself was removed.

`WATCH_MOVE_SELF`

gizlang

const WATCH_MOVE_SELF = 2048

The folder itself was moved.

`WATCH_OVERFLOW`

gizlang

const WATCH_OVERFLOW = 16384

Changes came faster than they were read: some were lost.

`WATCH_IGNORED`

gizlang

const WATCH_IGNORED = 32768

The folder's watch ended (the folder is gone): its number is free.

`WATCH_FOLDER`

gizlang

const WATCH_FOLDER = 1073741824

The entry is a folder.

`TIME_OMIT`

gizlang

const TIME_OMIT = 1073741822

The time value that leaves a time unchanged.

`DIRENT_UNKNOWN`

gizlang

const DIRENT_UNKNOWN = 0

The directory entry kind: unknown, 0.

`DIRENT_FILE`

gizlang

const DIRENT_FILE = 1

The directory entry kind: file, 1.

`DIRENT_DIR`

gizlang

const DIRENT_DIR = 2

The directory entry kind: dir, 2.

`DIRENT_LINK`

gizlang

const DIRENT_LINK = 3

The directory entry kind: link, 3.

`DIRENT_FIFO`

gizlang

const DIRENT_FIFO = 4

The directory entry kind: fifo, 4.

`DIRENT_SOCKET`

gizlang

const DIRENT_SOCKET = 5

The directory entry kind: socket, 5.

`DIRENT_CHAR`

gizlang

const DIRENT_CHAR = 6

The directory entry kind: char, 6.

`DIRENT_BLOCK`

gizlang

const DIRENT_BLOCK = 7

The directory entry kind: block, 7.