# 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; cpuMicros: i64; readBytes: Option; writtenBytes: Option; } ``` 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` - `cpuMicros`: `i64` - `readBytes`: `_gizlang_sdk_core.Option` - `writtenBytes`: `_gizlang_sdk_core.Option` ### `Usage` ```gizlang type Usage = { process: ProcessUsage; cgroup: Option; } ``` The resource use of the process, and of its control group when there is one. - `process`: `gizlang_system.ProcessUsage` - `cgroup`: `_gizlang_sdk_core.Option` ### `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; environment: Vec; inheritEnvironment: bool; isolated: bool; handed: Vec; 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` - `environment`: `Vec` - `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` — 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; } ``` 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` ## 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(result: Result, 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(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 ``` 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 ``` The command-line arguments after the program name. Effects: fail, io. ### `System.environment` ```gizlang function System.environment(self: System, name: string): Option ``` 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 ``` 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 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 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 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 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 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 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 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 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 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 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 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): 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(self: Ready, channel: Task.Channel): 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): 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, 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, environment: Vec): 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 ``` 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 ``` 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 ``` 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): 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, options: SpawnOptions, input: Option): 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, options: SpawnOptions, input: Option, 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, options: SpawnOptions, input: Option, budget: CaptureBudget): Result ``` 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, options: SpawnOptions, input: bytes, milliseconds: i64, outputBytes: i64): Result ``` 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 ``` 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 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 ``` 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 ``` 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 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): 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.