Wado

core:process

Run a host program as a child of the guest.

A host offers spawning or not, and [availability] says which, with an answer fixed for the guest's lifetime. Every other function requires it to answer Available, and traps otherwise.

Children

Errors

[ProcessError] names the program, as FsError names its path. The host reports why a child did not run as an [ErrorCode]. Only read fails on how the child ended, since it returns stdout alone and has nowhere else to report it: output and status return the [ExitStatus] as a value.

The wado Host

wado run, wado serve and wado test offer spawning, and confine each child so that spawning never extends the guest's authority.

Synopsis

if availability() != Availability::Available {
    return;
}
let out = cmd`echo hello`.read().unwrap();
assert out == b"hello\n";

Globals

pub global DEFAULT_CAPTURE_LIMIT: i32

How many bytes output and read keep of each stream unless a [Command::capture_limit] says otherwise.

Functions

pub fn availability() -> Availability with Process

Whether this host spawns. The answer is fixed for the guest's lifetime.

pub fn cmd<T: ReflectTemplate<Holes = [..V]>, ..V: CmdArg>(t: T) -> Command

A Command from an argument vector, built without a shell.

Literal text splits on whitespace. A hole is exactly one argument, whatever it holds, and a List<String> hole one per element. Parts with no whitespace between them join into one argument; a List<String> hole joined to anything is a contract violation. So is literal text holding a character a shell would treat specially (quotes, \, |, &, ;, <, >, parentheses, braces, $, a backtick, ~, *, ?, brackets, #): here it would mean nothing. A value holding one goes through a hole.

Traits

pub trait CmdArg with ()

What a value is as a [cmd] hole.

fn cmd_args(&self) -> CmdArgs

Effects

pub interface Process

Running a host program as a child of the guest.

A host may offer it or not, and confines a child as its own policy says. Every function but get-availability requires it to answer available, and traps otherwise.

fn get_availability() -> Availability

#[cm("core:process/process@0.1.0#get-availability")]

Whether spawning is offered, with no side effect.

fn spawn(cmd: Command, cwd: Option<&Descriptor>) -> Result<Spawned, ErrorCode>

#[cm("core:process/process@0.1.0#spawn")] #[cm_params("cmd", "cwd")]

Start cmd in cwd, or in the first preopened directory with none.

Structs

pub struct Command

A program to run and how: its arguments, environment and streams. output and read pipe what they read themselves.

Fields are private.

pub fn new(program: String) -> Command

pub fn grant_read(&self, path: String) -> Command

Let the child read and execute beneath path. The first grant_* takes away every directory the guest holds, so the child reaches only what is granted, and the host's own additions. path is relative to where the child starts, and must name what the guest may read, or the spawn fails with NotPermitted.

pub fn grant_write(&self, path: String) -> Command

Let the child read, write, create and remove beneath path, as [Command::grant_read] lets it read. The guest must be able to write path.

pub fn arg(&self, arg: String) -> Command

pub fn args(&self, args: List<String>) -> Command

pub fn env(&self, key: String, value: String) -> Command

Set key in the child's environment, over what the host gives it.

pub fn stdin_piped(&self) -> Command

spawn hands the guest the child's stdin as Child::stdin.

pub fn stdout_piped(&self) -> Command

spawn hands the guest the child's stdout as Child::stdout.

pub fn stderr_piped(&self) -> Command

spawn hands the guest the child's stderr as Child::stderr.

pub fn inherit_stdin(&self) -> Command with Stdin

The child reads the guest's own stdin, which the guest passes on only where it holds it.

pub fn inherit_stdout(&self) -> Command with Stdout

The child writes to the guest's own stdout.

pub fn inherit_stderr(&self) -> Command with Stderr

The child writes to the guest's own stderr.

pub fn inherit_stdio(&self) -> Command with (Stdin, Stdout, Stderr)

All three of the guest's own streams.

pub fn capture_limit(&self, bytes: i32) -> Command

The bytes output and read keep of each stream. Past it, stderr keeps its tail, and stdout is an OutputTooLarge error, since output with its middle cut out is wrong rather than short: the child is killed the moment stdout passes it.

pub fn spawn(&self) -> Result<Child, ProcessError> with Process

Start the child and hand back its piped streams.

pub fn output(&self) -> Result<Output, ProcessError> with Process

Run the child to its end, reading stdout and stderr together, so a child filling one pipe never blocks against a guest reading the other.

pub fn status(&self) -> Result<ExitStatus, ProcessError> with Process

Run the child to its end and return how it ended.

pub fn read(&self) -> Result<ByteList, ProcessError> with Process

Run the child to its end and return its stdout. Any end but Exited(0) is Failed, with the stderr read beside it.

pub affine struct Child

A running child.

stdin: Option<StreamWritable<u8>>

Where Command::stdin_piped asked for it. Dropping it closes the child's stdin.

stdout: Option<Stream<u8>>

Where Command::stdout_piped asked for it.

stderr: Option<Stream<u8>>

Where Command::stderr_piped asked for it.

pub fn wait(self) -> Result<ExitStatus, ProcessError> with Process

Wait for the child to end. Nothing can reach a stream still left in the Child once it is waited on, so wait closes each first: take a piped stream out to use it.

pub fn wait_timeout(&mut self, how_long: Duration) -> Result<Option<ExitStatus>, ProcessError> with (Process, MonotonicClock)

Wait at most how_long for the child to end: None where it has not. The streams stay open, so a child blocked on a pipe nobody reads waits out the time.

pub fn terminate(&self) with Process

Ask the child and every process it started to end. A child may ignore it, so [Child::stop] follows it with a kill.

pub fn kill(&self) with Process

End the child and every process it started, now.

pub fn stop(self, grace: Duration) -> Result<ExitStatus, ProcessError> with (Process, MonotonicClock)

Ask the child to end, and end it if it has not after grace.

pub struct Output

What Command::output read, and how the child ended.

status: ExitStatus

stdout: ByteList

stderr: ByteList

pub struct ProcessError

Why a program did not run, or did not run as asked. Names the program, as FsError names its path.

program: String

kind: ProcessErrorKind

impl Display for ProcessError

fn fmt(&self, f: &mut Formatter)

Variants

pub variant ProcessErrorKind

Spawn(ErrorCode)

The host did not run the child, or lost it, for this reason.

Failed([ExitStatus, ByteList])

read only: the child ended other than Exited(0), with what it wrote to stderr.

OutputTooLarge

Stdout passed the capture limit, and the child was killed.

pub variant CmdArgs

One hole of a [cmd] template: one argument, or one per element.

One(String)

Each(List<String>)

pub variant ExitStatus

How a child ended.

Exited(i32)

It exited with this status, as the host's OS reports it.

Signaled(i32)

The host's OS ended it with this signal.

pub variant ErrorCode

NotFound

No program by that name, or nothing at the path given.

NotPermitted

The host's policy does not let a child run this program.

NotExecutable

What the name or path leads to is not a program the host can run.

InvalidArgument

program, an argument, or an environment variable is not one the host can pass: it holds a NUL, or a variable's name is empty or holds =.

ArgumentListTooLong

The arguments and the environment together are more than the host can pass.

NotDirectory

cwd is not a directory.

ResourceExhausted

The host lacks a resource that running a child takes.

Other(Option<String>)

Anything else, with a message for a person where the host has one.

Enums

pub enum Availability

Whether this host spawns. Fixed when the host starts.

Available

Denied

The host turned spawning off.

Unsupported

The host cannot run a child as its policy requires.