Skip to content

std::process

Processes: how the running program ends, and the programs it starts.

A main that returns Err(Exit{code: 2, message: "usage: count <file>"}) prints the message to stderr and exits with status 2. There is no function that exits on the spot: returning Exit through ? ends the program the way returning from main does, so defers run and supervisors drain first.

A Command names a program and its arguments, with no shell between: nothing in an argument is expanded, split or quoted, so an argument holding a space or a * reaches the program as it is. output runs it to the end and returns what it wrote. run runs it with its output going to the program’s own. spawn starts it with its three streams to read and write, and defer Child.kill(child) stops it when the function that started it ends. A program that ends with a non-zero code is a Status to inspect, not an error; an Err means it could not be started.

import
    std::io.Error
    std::process.{self, Command, Status}
end

fn main() -> Result<Unit, Error>
    listed = process.output(Command{program: "git", args: ["status", "--short"]})?
    dbg Status.is_success(listed.status)
    Ok(Unit)
end

Tests run commands against std::process::testing’s fake, which starts nothing. A WebAssembly target has no processes: nomi build for js/wasm or wasip1 refuses a program that starts one.

Import with import std::process.

struct Exit
    code: ExitCode = 1
    message: String = ""
end

What a main or an entry boot returns in its Err to end the program with a status of its choosing. The program prints message and a newline to stderr when it is not empty, with no error: before it, and exits with code. An Exit with code 0 ends the program successfully, its message printed all the same.

import std::process.Exit

fn main() -> Result<Unit, Exit>
    Err(Exit{code: 2, message: "usage: count <file>"})
end
failed = Exit{message: "no input"}
assert failed.code == 1
assert Exit{} == Exit{code: 1, message: ""}

impl Debug for Exit

fn inspect(value: Exit) -> String

impl Debug.inspect

subtype ExitCode Int when fn code -> code >= 0 and code <= 255

A status a program can exit with: 0 to 255. A literal outside it does not compile; a computed code goes through ExitCode.try_from.

subtype: ExitCode is a subtype of Int. A literal where a ExitCode is expected is checked when the program is compiled; ExitCode.try_from(...) checks a value when it runs.

assert ExitCode.try_from(255) == Some(255)
assert ExitCode.try_from(256) == None
assert ExitCode.try_from(-1) == None
fn try_from(value: Int) -> Maybe<ExitCode>

type function on ExitCode

Some of the value when it satisfies ExitCode’s rules, None when it does not.

struct Command
    program: String
    args: List<String> = []
    env: Map<String, String> = {}
    clear_env: Bool = False
    dir: Maybe<String> = None
    stdin: Stdin = Stdin.Null
end

A program to start and how: an immutable value, so one command can be run any number of times.

command = Command{program: "git", args: ["log", "-1"], dir: Some("repo")}
assert command.env == {}
assert not command.clear_env

impl Debug for Command

fn inspect(value: Command) -> String

impl Debug.inspect

enum Stdin
    Null
    Inherit
    Text String
    Bytes Bytes
    From Reader
end

What a started program reads on its standard input.

Variants

  • Null

    Nothing: the program reads the end of its input at once.

  • Inherit

    The running program’s own standard input.

  • Text

    The text, then the end of the input.

  • Bytes

    The bytes, then the end of the input.

  • From

    What the reader reads, to its end.

impl Debug for Stdin

fn inspect(value: Stdin) -> String

impl Debug.inspect

enum Status
    Exited { code: Int }
    Signaled { signal: Int }
end

How a started program ended.

Variants

  • Exited

    It exited with code, 0 for success.

  • Signaled

    A signal ended it (on Unix), as a kill does.

fn is_success(status: Status) -> Bool

type function on Status

Whether the program exited with code 0.

assert Status.is_success(Status.Exited{code: 0})
assert not Status.is_success(Status.Exited{code: 1})
assert not Status.is_success(Status.Signaled{signal: 9})
fn code(status: Status) -> Maybe<Int>

type function on Status

The exit code, or None when a signal ended the program.

assert Status.code(Status.Exited{code: 3}) == Some(3)
assert Status.code(Status.Signaled{signal: 9}) == None

impl Display for Status

fn to_string(status: Status) -> String

impl Display.to_string

assert "${Status.Exited{code: 2}}" == "exited with code 2"
assert "${Status.Signaled{signal: 9}}" == "ended by signal 9"

impl Debug for Status

fn inspect(value: Status) -> String

impl Debug.inspect

impl Equatable for Status

fn equal(a: Status, b: Status) -> Bool

impl Equatable.equal

struct Output
    status: Status
    stdout: Bytes
    stderr: Bytes
end

What output returns: how the program ended and everything it wrote.

impl Debug for Output

fn inspect(value: Output) -> String

impl Debug.inspect

impl Equatable for Output

fn equal(a: Output, b: Output) -> Bool

impl Equatable.equal

fn output(command: Command) -> Result<Output, Error>

Runs command to its end and returns its status and everything it wrote to its standard output and error. A non-zero exit is in the status; an Err means the program could not be started (NotFound when nothing on the PATH has its name). A task that is cancelled, or whose deadline passes, while it waits kills the program.

import std::process::testing.{self, Answer}

ran = testing.run([Answer{program: "echo", stdout: "hi\n"}], fn ->
    output(Command{program: "echo", args: ["hi"]})
end)

assert ran.value == Ok(
    Output{
        status: Status.Exited{code: 0},
        stdout: String.to_bytes("hi\n"),
        stderr: String.to_bytes(""),
    }
)
fn run(command: Command) -> Result<Status, Error>

Runs command to its end with its standard output and error going to the running program’s own (and so to an io.capture in force), and returns its status.

import std::process::testing.{self, Answer}
import std::io

ran = testing.run([Answer{program: "make", stdout: "built\n"}], fn ->
    io.capture("", fn -> run(Command{program: "make"}))
end)

assert ran.value.value == Ok(Status.Exited{code: 0})
assert ran.value.output == "built\n"
fn spawn(command: Command) -> Result<Child, Error>

Starts command with the program’s standard input to write and its standard output and error to read (Child.stdin, Child.stdout, Child.stderr; the command’s stdin is not used). Defer Child.kill on the next line, so a program still running when the function ends, returns, traps or is cancelled, is killed and none outlives it. Child.wait closes the input and waits for the program to end. An Err means the program could not be started.

child = process.spawn(Command{program: "sort"})?

defer Child.kill(child)
import std::process::testing.{self, Answer, Call}

fn sorted(text: String) -> Result<String, Error>
    child = spawn(Command{program: "sort"})?
    defer Child.kill(child)
    Writer.write_text(Child.stdin(child), text)?
    _ = Child.wait(child)?
    Reader.read_all_text(Child.stdout(child))
end

ran = testing.run([Answer{program: "sort", stdout: "a\nb\n"}], fn -> sorted("b\na\n"))

assert ran.value == Ok("a\nb\n")
assert ran.calls == [Call{program: "sort", input: String.to_bytes("b\na\n")}]
struct Child

opaque — construction surface is private to its defining module

A program spawn started.

fn kill(child: Child) -> Unit

type function on Child

Kills the program if it is still running, and does nothing once it has ended: the form for a defer after process.spawn.

fn stdin(child: Child) -> Writer

type function on Child

The writer to the program’s standard input. Writes are buffered: Writer.flush sends them on, and Child.wait or Writer.close ends the input.

fn stdout(child: Child) -> Reader

type function on Child

The reader over the program’s standard output. Read it before waiting when the program writes more than a pipe holds, or it stops until something reads.

fn stderr(child: Child) -> Reader

type function on Child

The reader over the program’s standard error.

fn wait(child: Child) -> Result<Status, Error>

type function on Child

Ends the program’s standard input and waits for it to end. A second wait returns the first’s status.

impl Release for Child

fn release(child: Child) -> Unit

impl Release.release

impl Debug for Child

fn inspect(value: Child) -> String

impl Debug.inspect