ProcContext

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

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

Remarks

ProcContext is the single API surface bins use to interact with the system. It provides process identity, I/O streams, filesystem access via ProcFS, process lifecycle control (spawn, exec, exit, signal, wait), namespace manipulation, and optional capabilities (catalog install, service registration, srv posting).

Optional members (catalogInstall?, registerExec?, registerService?, etc.) are present only when the system was built with the corresponding capability. Bins must check for their existence before calling.

Example

const myBin: BinFunction = async (proc) => {
  const name = proc.argv[1] ?? 'world'
  await proc.stdout.write(`Hello, ${name}!\n`)
  const content = await proc.fs.readFile('/etc/motd')
  await proc.stderr.write(content)
  return exitCode(0)
}

Properties

abortSignal

readonly abortSignal: AbortSignal

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

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:463

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

---

catalogInstall?

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

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

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:467

Current working directory (absolute path).

---

env

env: Record<string, string>

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

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

---

fs

readonly fs: ProcFS

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

Filesystem operations routed through this process’s namespace.

---

getServer?

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

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

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:458

Process identifier for this process.

---

postServer?

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

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

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:460

Parent process identifier (0 = kernel-spawned).

---

registerExec?

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

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

Register a bin function on the filesystem exec table. Present when the system supports runtime package installation.

Parameters

binName

string

fn

BinFunction

Returns

void

---

registerService?

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

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

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:551

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:542

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:566

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:474

Standard error stream.

---

stdin

readonly stdin: Readable

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

Standard input stream.

---

stdout

readonly stdout: Writable

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

Standard output stream.

Methods

bind()

bind(oldPath, newPath, flags?): void

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

Parameters

oldPath

string

newPath

string

flags?

BindFlags

Returns

void

---

chdir()

chdir(path): Promise<void>

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

Parameters

path

string

Returns

Promise<void>

---

exec()

exec(bin, argv): never

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

Replace the current process image with a new bin. Throws an ExecSentinel that the kernel catches — code after exec() never runs. Same pid, same fds, same namespace. Used by login → shell transition.

Parameters

bin

string | BinFunction

argv

string[]

Returns

never

---

exit()

exit(code?): never

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

Parameters

code?

ExitCode

Returns

never

---

getTermSize()?

optional getTermSize(): TerminalSize

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

Return current terminal dimensions, if a controlling terminal exists.

Returns

TerminalSize

---

mount()

mount(server, path): void

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

Parameters

server

Fileserver

path

string

Returns

void

---

off()

off(signal): void

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

Parameters

signal

Signal

Returns

void

---

on()

on(signal, handler): void

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

Parameters

signal

Signal

handler

() => void

Returns

void

---

resolveServer()

resolveServer(path): Fileserver | undefined

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

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:505

Returns

Pid

---

setuid()

setuid(uid): void

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

Parameters

uid

Uid

Returns

void

---

signal()

signal(pid, sig): void

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

Parameters

pid

Pid

sig

Signal

Returns

void

---

spawn()

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

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

Spawn a child process.

Parameters

bin

string | BinFunction

A BinFunction or a 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.

---

unmount()

unmount(path): void

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

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:500

Parameters

pid

Pid

Returns

Promise<ExitCode>

---

waitAny()

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

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

Returns

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