ProcContext

Defined in: packages/core/src/kernel/types.ts:1024

The system-call surface available to every bin. Every running process receives a ProcContext.

Role

Consumed by bin functions — the kernel builds one at spawn time and passes it to the bin. Not an interface user code implements.

Remarks

Single API surface for process identity, I/O streams, filesystem (ProcFS), lifecycle control (spawn/exec/exit/signal/wait), namespace manipulation, and optional capabilities (catalogInstall?, registerExec?, registerService?, srv posting). Optional members are present only when the system was built with the corresponding capability; bins MUST check for existence before calling.

Lifecycle: valid for the duration of the bin’s execution. After the bin returns or throws, the kernel reaps the process and the context becomes inert.

Caveat

Streams are wrapped with zombie/abort guards — once the process is a zombie or its abort signal fires, reads return empty and writes return 0. A bin polling proc.stdin after proc.exit() sees EOF, not an error.

Caveat

env is a mutable reference. Mutations propagate to children spawned AFTER the mutation, not to already-running children (each child snapshots its env on spawn).

Example

import { exitCode, type BinFunction } from '@fishnet/core'
const myBin: BinFunction = async (proc) => {
  await proc.stdout.write(`hi ${proc.argv[1] ?? 'world'}\n`)
  return exitCode(0)
}

See

Properties

abortSignal

readonly abortSignal: AbortSignal

Defined in: packages/core/src/kernel/types.ts:1046

Abort signal — aborted when the process is killed. Bins can check abortSignal.aborted or pass it to fetch/AbortController-aware APIs.

argv

readonly argv: string[]

Defined in: packages/core/src/kernel/types.ts:1031

Command-line arguments. argv[0] is the command name.

catalogInstall?

optional catalogInstall?: (name) => Promise<CatalogInstallResult | undefined>

Defined in: packages/core/src/kernel/types.ts:1162

Install a package from the pre-bundled catalog. Present only when the system was built with .catalog() entries. Returns install info or undefined if the package is not in the catalog.

Parameters

name

string

Returns

Promise<CatalogInstallResult | undefined>

cwd

readonly cwd: AbsPath

Defined in: packages/core/src/kernel/types.ts:1035

Current working directory (absolute path).

env

env: Record<string, string>

Defined in: packages/core/src/kernel/types.ts:1033

Environment variables. Mutable — changes are visible to child processes.

fs

readonly fs: ProcFS

Defined in: packages/core/src/kernel/types.ts:1049

Filesystem operations routed through this process’s namespace.

getServer?

optional getServer?: (name) => Fileserver | undefined

Defined in: packages/core/src/kernel/types.ts:1189

Retrieve a posted Fileserver from /srv by name.

Parameters

name

string

Returns

Fileserver | undefined

pid

readonly pid: Pid

Defined in: packages/core/src/kernel/types.ts:1026

Process identifier for this process.

postServer?

optional postServer?: (name, server) => void

Defined in: packages/core/src/kernel/types.ts:1186

Post a Fileserver to /srv for other processes to discover and mount.

Parameters

name

string

server

Fileserver

Returns

void

ppid

readonly ppid: Pid

Defined in: packages/core/src/kernel/types.ts:1028

Parent process identifier (0 = kernel-spawned).

registerExec?

optional registerExec?: (binName, fn) => void

Defined in: packages/core/src/kernel/types.ts:1168

Parameters

binName

string

fn

BinFunction

Returns

void

registerService?

optional registerService?: (def) => Promise<void>

Defined in: packages/core/src/kernel/types.ts:1176

Register and start a service at runtime (post-boot). Present when init is running with a supervisor. Validates bin is resolvable before registering. Services go through existing supervisor machinery (restart policies, backoff).

Parameters

def

ServiceDef

Returns

Promise<void>

removeServer?

optional removeServer?: (name) => void

Defined in: packages/core/src/kernel/types.ts:1192

Remove a posted Fileserver from /srv.

Parameters

name

string

Returns

void

resolveBin?

optional resolveBin?: (name) => Promise<BinFunction | undefined>

Defined in: packages/core/src/kernel/types.ts:1183

Resolve a bin name to a BinFunction via the kernel’s exec resolution (namespace/ExecCapable/$PATH lookup). Used by the shell to discover promoted builtins (e.g. pkg) at runtime without a static import.

Parameters

name

string

Returns

Promise<BinFunction | undefined>

shellOpts?

optional shellOpts?: ShellOpts

Defined in: packages/core/src/kernel/types.ts:1207

Shell option flags (e.g. xtrace). Present when the process is running inside a shell interpreter; undefined in non-shell contexts.

stderr

readonly stderr: Writable

Defined in: packages/core/src/kernel/types.ts:1042

Standard error stream.

stdin

readonly stdin: Readable

Defined in: packages/core/src/kernel/types.ts:1038

Standard input stream.

stdout

readonly stdout: Writable

Defined in: packages/core/src/kernel/types.ts:1040

Standard output stream.

Methods

bind()

bind(oldPath, newPath, flags?): void

Defined in: packages/core/src/kernel/types.ts:1143

Bind a fileserver-backed subtree from one path onto another.

Parameters

oldPath

string

newPath

string

flags?

BindFlags

Returns

void

Invariant

flags default 'replace'; 'before' prepends to the union stack (new front), 'after' appends (new back)

chdir()

chdir(path): Promise<void>

Defined in: packages/core/src/kernel/types.ts:1126

Change the current working directory.

Parameters

path

string

Returns

Promise<void>

Invariant

Throws ENOTDIR when path is not a directory — validation happens before cwd is updated, so a failed chdir leaves cwd unchanged

exec()

exec(bin, argv): never

Defined in: packages/core/src/kernel/types.ts:1072

Replace the current process image with a new bin. Never returns.

Parameters

bin

string | BinFunction

argv

string[]

Returns

never

Invariant

Throws an ExecSentinel the kernel catches — treat as a control-flow primitive; the bin MUST NOT catch it

Invariant

Same pid, same fds, same namespace; env preserved, argv replaced

exit()

exit(code?): never

Defined in: packages/core/src/kernel/types.ts:1079

Terminate the current process with an exit code. Never returns.

Parameters

code?

ExitCode

Returns

never

Invariant

Throws an ExitError the kernel catches; code after proc.exit() never runs even under try/finally that swallows the error

getTermSize()?

optional getTermSize(): TerminalSize

Defined in: packages/core/src/kernel/types.ts:1201

Return current terminal dimensions, if a controlling terminal exists.

Returns

TerminalSize

mount()

mount(server, path): void

Defined in: packages/core/src/kernel/types.ts:1136

Mount a Fileserver at an absolute path in THIS process’s namespace.

Parameters

server

Fileserver

path

string

Returns

void

Invariant

Mutates only the calling process’s namespace — siblings and already-spawned children do NOT see the mount (snapshot-on-fork)

Invariant

Replaces any existing mount at path; use bind() for union stacks

off()

off(signal): void

Defined in: packages/core/src/kernel/types.ts:1155

Remove any handler for signal. No-op if none was registered.

Parameters

signal

Signal

Returns

void

on()

on(signal, handler): void

Defined in: packages/core/src/kernel/types.ts:1153

Parameters

signal

Signal

handler

() => void

Returns

void

Invariant

Per-process, one handler per signal — re-registering replaces

Invariant

Fires synchronously during signal() delivery; uncaught handler exceptions propagate to the signaler’s call site

resolveServer()

resolveServer(path): Fileserver | undefined

Defined in: packages/core/src/kernel/types.ts:1195

Resolve a path to the Fileserver mounted at that point (for post/srv).

Parameters

path

string

Returns

Fileserver | undefined

setsid()

setsid(): Pid

Defined in: packages/core/src/kernel/types.ts:1118

Create a new session, making this process the session leader.

Returns

Pid

Invariant

Returns the new sid which equals this process’s pid

setuid()

setuid(uid): void

Defined in: packages/core/src/kernel/types.ts:1112

Change the process’s uid and euid. Restricted to uid=0.

Parameters

uid

Uid

Returns

void

Invariant

Throws EPERM for non-root callers — no capability mask or setuid-bit emulation at this layer

signal()

signal(pid, sig): void

Defined in: packages/core/src/kernel/types.ts:1087

Send a signal to another process.

Parameters

pid

Pid

sig

Signal

Returns

void

Invariant

Fires synchronously — target’s abort signal is set and any registered handler invoked before signal() returns

Invariant

Silently no-op when pid is not live (no ESRCH at this layer)

spawn()

spawn(bin, argv, opts?): Promise<ChildHandle>

Defined in: packages/core/src/kernel/types.ts:1064

Spawn a child process.

Parameters

bin

string | BinFunction

A BinFunction or string path resolved via $PATH.

argv

string[]

Arguments for the child. argv[0] is conventionally the command name.

opts?

SpawnOpts

Optional I/O redirects, env overrides, cwd.

Returns

Promise<ChildHandle>

A ChildHandle with the child’s pid and I/O streams.

Invariant

Child inherits parent’s uid/gid/sid/pgid unless overridden

Invariant

Numeric stdin/stdout/stderr in opts refer to the PARENT’S fd table (dup semantics); stream objects are taken as-is

Invariant

opts.env is MERGED into the parent’s env, not replacement

unmount()

unmount(path): void

Defined in: packages/core/src/kernel/types.ts:1198

Remove a mount point from this process’s namespace.

Parameters

path

string

Returns

void

wait()

wait(pid): Promise<ExitCode>

Defined in: packages/core/src/kernel/types.ts:1095

Await the exit of a specific child.

Parameters

pid

Pid

Returns

Promise<ExitCode>

Invariant

Rejects with ProcError('ESRCH') if the pid is not (or no longer) live

Invariant

Safe to call after the child has zombied — the exit code is held until the parent reaps it here

waitAny()

waitAny(): Promise<{ code: ExitCode; pid: Pid; }>

Defined in: packages/core/src/kernel/types.ts:1103

Await any child’s exit.

Returns

Promise<{ code: ExitCode; pid: Pid; }>

Invariant

Rejects with ProcError('ECHILD') when the caller has no remaining children — init’s supervision loop uses this to detect “all children reaped”