std/os

Types

ExitError

pub type ExitError = {
    // private fields omitted
}

Carries a process exit status through fail and ?; when it reaches the entry of a hosted program the process exits with code after every scope has cleaned up, printing nothing. Build it with ExitError.new; 0 is not a valid code because success is a plain return.

ExitError.status

pub pure noalloc fn ExitError.status(self) -> u8

The exit status this error asks for, 1 to 255.

ExitError.message

pub fn ExitError.message(self) -> String

ExitError.new

pub pure fn ExitError.new(code: Int) -> Result[ExitError, ExitCodeError]

An ExitError for code; fails with the rejected code unless it is in 1 to 255.

ExitCodeError

pub type ExitCodeError = {
    pub code Int
}

The failure of ExitError.new for a code outside 1 to 255.

ExitCodeError.message

pub fn ExitCodeError.message(self) -> String

Host

@unsafeGuarantee(Copy, Send, Sync)
pub type Host

The process environment; host is the predeclared instance in the entry file. Safety: a stateless capability marker; every call it makes is independent, so sharing or duplicating it is free.

Host.shell

pub fn Host.shell(self) -> shell.Shell

Shell for running external commands.

Host.args

pub fn Host.args(self) -> Args

Command line arguments of the process.

Host.envOsString

pub fn Host.envOsString(self, name: String) -> OsString?

Value of the environment variable name exactly as the OS holds it, valid UTF-8 or not; None only when it is unset or name contains NUL.

Host.files

pub fn Host.files(self) -> fs.Files

File system access.

Host.net

pub fn Host.net(self) -> net.Net

Network access.

Host.stdin

pub fn Host.stdin(self) -> Stdin

Standard input.

Host.stdout

pub fn Host.stdout(self) -> Stdout

Standard output.

Host.stderr

pub fn Host.stderr(self) -> Stderr

Standard error.

Host.dl

pub fn Host.dl(self) -> dl.Loader

The dynamic loader.

Host.entropy

pub fn Host.entropy(self) -> entropy.Entropy

The CSPRNG; see std/entropy.

Host.exit

pub fn Host.exit(self, code: u8) -> Never

Ends the process at once with status code: no defer, drop or child task cancellation runs and no application buffer is flushed. Return an ExitError instead to let every scope clean up first. It is not a panic.

Host.env

pub fn Host.env(self, name: String) -> String?

Value of the environment variable name, or None when it is unset or not valid UTF-8; envOsString keeps every value and tells the two cases apart.

Host.signals

pub fn Host.signals(self) -> Signals

Signal handling.

Args

@unsafeGuarantee(Copy, Send, Sync)
pub type Args

Command line arguments; index 0 is the program path. Safety: a read-only view of the process argv; duplicating or sharing it touches nothing.

Args.get

pub pure noalloc fn Args.get(self, index: usize) -> String?

Argument at index, or None when there are fewer arguments or it is not valid UTF-8; getOsString keeps every argument and tells the two cases apart.

Args.getOsString

pub pure fn Args.getOsString(self, index: usize) -> OsString?

Argument at index exactly as the OS passed it, valid UTF-8 or not; None only when there are fewer arguments. A native argv cannot hold NUL, so the value never does there.

Args.len

pub pure noalloc fn Args.len(self) -> usize

Number of arguments, the program path included.

Stdin

@unsafeGuarantee(Send)
pub type Stdin

Standard input of the process, obtained from host.stdin(). Safety: holds no state of its own; it may be handed off to one other thread at a time (reads through a shared reference are not coordinated, so Sync is not claimed).

Stdin.readAll

pub fn Stdin.readAll(self) -> String!

Everything left on stdin as UTF-8 text; fails when it is not valid UTF-8 or on a real read error (a signal arriving mid-read is retried, not reported).

Stdin.readLine

pub fn Stdin.readLine(self) -> String?!

Next line without its line break, or None at end of input; fails on a real read error or invalid UTF-8, matching readAll.

Stdin.read

pub fn Stdin.read(mut self, into: &mut Array[u8], max: usize) -> usize!

Reads up to max bytes from stdin into into, returning how many; 0 with no error is end of input, matching std/io's Reader (POSIX read semantics; a signal arriving mid-read is retried, not reported).

Stdin.readSome

pub fn Stdin.readSome(self, timeoutMs: Int) -> Bytes!

Waits up to timeoutMs milliseconds for stdin to have data and returns whatever is there (up to a fixed buffer); empty Bytes on timeout, fails when stdin is closed.

Stdout

@unsafeGuarantee(Send)
pub type Stdout

Standard output of the process, obtained from host.stdout(). Safety: holds no state of its own; it may be handed off to one other thread at a time (writes through a shared reference are not coordinated, so Sync is not claimed).

Stdout.write

pub fn Stdout.write(mut self, data: Bytes) -> usize!

Writes data to standard output as-is: no newline is added and nothing is buffered, so ANSI escapes and partial lines reach the terminal exactly as given; may send fewer bytes than given (a short write), matching write(2) and std/io's Writer (writeAll loops for the rest). Unlike C stdio called through FFI, this writes straight to the descriptor: call fflush(NULL) through FFI before it to keep both outputs in order.

Stderr

@unsafeGuarantee(Send)
pub type Stderr

Standard error of the process, obtained from host.stderr(). Safety: holds no state of its own; it may be handed off to one other thread at a time (writes through a shared reference are not coordinated, so Sync is not claimed).

Stderr.write

pub fn Stderr.write(mut self, data: Bytes) -> usize!

Writes data to standard error as-is, on the same terms as Stdout.write.

OsString

pub type OsString = resource {
    // private fields omitted
}

An owned OS string: on Unix any byte sequence, NUL and invalid UTF-8 included; the encoding is not a contract. Not Copy (duplicate with clone); reaches String only through intoString, checkedString or toStringLossy.

OsString.fromString

pub pure fn OsString.fromString(s: String) -> OsString

The OS string holding exactly the text of s.

OsString.fromUnixBytes

pub pure fn OsString.fromUnixBytes(bytes: Bytes) -> OsString

The OS string holding exactly these bytes; this form exists on Unix targets only.

OsString.toUnixBytes

pub pure fn OsString.toUnixBytes(self) -> Bytes

The bytes of the OS string, a copy; this form exists on Unix targets only.

OsString.len

pub pure noalloc fn OsString.len(self) -> usize

Length in native units: bytes on Unix.

OsString.isEmpty

pub pure noalloc fn OsString.isEmpty(self) -> Bool

Whether the OS string has no units.

OsString.clone

pub pure fn OsString.clone(self) -> OsString

An independent copy.

OsString.tryClone

pub pure fn OsString.tryClone(self) -> Result[OsString, AllocError]

An independent copy, or AllocError when the allocator refuses (clone panics instead).

OsString.equals

pub pure noalloc fn OsString.equals(self, other: &OsString) -> Bool

Byte-wise equality; satisfies Eq.

OsString.hash

pub pure noalloc fn OsString.hash(self) -> u64

Hash of the units; satisfies Hash.

OsString.compareTo

pub pure noalloc fn OsString.compareTo(self, other: &OsString) -> Ordering

Byte-wise lexicographic comparison, a total order that is not a text collation.

OsString.isUnicode

pub pure noalloc fn OsString.isUnicode(self) -> Bool

Whether the units are valid UTF-8, so that checkedString and intoString succeed.

OsString.checkedString

pub pure fn OsString.checkedString(self) -> String?

The text, or None when the units are not valid UTF-8; self stays usable.

OsString.intoString

pub pure fn OsString.intoString(move self) -> Result[String, OsString]

The text, or the unchanged OS string when the units are not valid UTF-8.

OsString.toStringLossy

pub pure fn OsString.toStringLossy(self) -> String

Text for display with U+FFFD in place of every byte that does not start a valid UTF-8 sequence; the result cannot be converted back.

OsString.tryToStringLossy

pub pure fn OsString.tryToStringLossy(self) -> Result[String, AllocError]

Same as toStringLossy, or AllocError when the allocator refuses (toStringLossy panics instead).

Signal

pub type Signal = Interrupt | Terminate | WindowChange

OS signals the process can watch for.

Signals

@unsafeGuarantee(Copy, Send, Sync)
pub type Signals

Signal delivery, obtained from host.signals(). Safety: a stateless capability marker; every call it makes targets process-wide signal state, so sharing or duplicating the handle is free.

Signals.watch

pub fn Signals.watch(self, which: Signal) -> Void!

Starts watching which; a later delivery sets its pending flag until pending reads and clears it. The C handler only sets that flag (rt_signal.c), so it never re-enters this refcounted runtime.

Signals.pending

pub fn Signals.pending(self, which: Signal) -> Bool

Whether which was delivered since the last call; clears the flag.

Functions

rt_sys_write

export(C) {
    pub fn rt_sys_write(fd: i32, p: *const u8, n: usize)
}

rt_sys_exit

export(C) {
    pub fn rt_sys_exit(code: i32) -> Never
}

rt_sys_close

export(C) {
    pub fn rt_sys_close(fd: i32) -> i32
}