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
programholding a/is a path, relative to where the child starts. Any other is a name the host looks up.- A child starts in the guest's first preopened directory, the one
core:fsresolves paths against. Where the guest has none, the host picks one. - A child's environment is what the host gives every child, with
[
Command::env] laid over it. The guest's own is never passed on. - A child gets no stream of the guest's unless asked: stdin reads nothing,
and stdout and stderr go nowhere.
inherit_*passes on a stream the guest holds, so each declares that stream's effect. - [
Child] isaffine. Dropping it, or [Child::kill], ends the child and every process it started, and the host ends every child when the guest exits, so none outlives the guest. [Child::terminate] asks instead, and the child may ignore it. - A timeout is the guest's: [
Child::wait_timeout] waits a bounded time, and [Child::stop] asks, waits a grace period, then kills. - A child's output is bytes, so it comes back as a
ByteList, never decoded.
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.
- A child reads and writes only beneath the directories the guest was granted, plus a fixed system baseline: the loader, shared libraries, installed programs and the system configuration. It reaches the network only where the guest does.
- [
Command::grant_read] and [Command::grant_write] put the paths they name in place of the guest's directories. The host opens each once and confines the child through that descriptor, so a link swapped in later reaches nothing more. --process-read <path>lets a child read and executepathas well, and so doesreadunder[process]in the user config. The guest itself gains nothing.--deny-processturns spawning off (Denied). A host whose OS cannot confine a child answersUnsupported: Linux needs Landlock ABI 6 (Linux 6.12), and macOS confines throughsandbox-exec.- A name is looked up on the host's
PATH, skipping empty and relative entries. - Every child gets
PATH, a privateHOMEandTMPDIRremoved once it exits,LANGandLC_*, andTERMwhere it inherits a stream. A guest with no preopened directory starts its children in thatHOME. terminatesends the child's process groupSIGTERM, andkillSIGKILL.- A child that inherits the terminal holds it while it runs, as a shell's
job does: it reads it and sets its mode. Ctrl-C ends the child alone, and
Ctrl-Z stops
wadowith it. One child holds the terminal at a time. - A child that fails after the sandbox refused it something is reported on
wado's stderr, with the grant that would allow it.--process-tracealso names each file refused, on Linux.
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
contract bytes >= 0
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.
