Process

Process module: OS process interaction.

run/2 runs a command and waits for it to finish, returning the exit code and captured stdout. run_stream/2 returns a Seq(String) of output lines for pipeline-style processing without buffering the whole output.

The command is looked up in PATH. A command that cannot be executed (not found, not executable) is an Err from the spawning call itself ("cannot execute <cmd>: <reason>"), never an Ok with exit code 127. The child inherits the current working directory and environment (including set_env), starts with no signals blocked and every signal at its default action.

env/1 and set_env/2 read and write OS environment variables. cwd/0, argv/0, pid/0 expose the current process context. exit/1 terminates the VM with the given exit code.

Types

typeProcessResultProcessResult = ProcessResult(Int, String, String)#

Result of a completed subprocess. ProcessResult(exit_code, stdout, stderr)

typeLiveProcessLiveProcess = LiveProcess(Int, Int)#

Handle for an asynchronously-spawned subprocess (non-blocking). LiveProcess(pid, stream_id) — both fields are opaque implementation details.

Functions

fnargvargv()#

Returns the command-line arguments as List(String) (argv[0] is the executable).

fncwdcwd()#

Returns the current working directory.

fnenvenv(name)#

Get the value of an environment variable. Returns Some(value) or None.

fnexitexit(code)#

Terminate the process with the given exit code.

fnexit_codeexit_code(r)#

Extract the exit code from a ProcessResult.

fnkillkill(p)#

Send SIGTERM to the live process.

fnokok(r)#

True if the command exited with code 0.

fnpidpid()#

Returns the OS-level PID of the current process.

fnread_lineread_line(p)#

Read one line from the live process's stdout. Returns Some(line) for each output line, or None when the process has closed its stdout (typically on exit). Blocks until a full line is available.

fnrunrun(command, args)#

Run command with args, wait for it to finish. Returns Ok(ProcessResult) with the exit code and captured stdout/stderr, or Err(msg) when the command could not be started: "cannot execute <cmd>: <reason>" for a missing or non-executable program. A program that runs and fails is still Ok, with its non-zero exit code.

match Process.run("git", ["status"]) do
  Ok(r)    -> println(Process.stdout(r))
  Err(msg) -> println(msg)   -- e.g. "cannot execute git: No such file or directory"
end

fnrun_streamrun_stream(command, args)#

Run command and return its stdout as a Seq(String) of lines. Returns Ok(Seq), or Err(msg) when the command cannot be executed (as for run). The command runs to completion and its stdout is read in full before the Seq is returned; the Seq is not a live stream of the running process.

fnset_envset_env(name, value)#

Set an environment variable.

fnspawn_asyncspawn_async(command, args)#

Spawn a command asynchronously (non-blocking). Returns Ok(LiveProcess) immediately — the child process starts running in the background. Use read_line to consume its stdout, kill to terminate it, and wait_proc to reap its exit code. Returns Err(msg) when the command cannot be executed: "cannot execute <cmd>: <reason>".

fnstderrstderr(r)#

Extract captured stderr from a ProcessResult.

fnstdoutstdout(r)#

Extract captured stdout from a ProcessResult.

fnwait_procwait_proc(p)#

Wait for the live process to exit and return its exit code. Also closes the stdout channel. Should be called after the process exits (read_line returned None) or after kill.

fnwritewrite(p, data)#

Write raw bytes to the live process's stdin. The data is flushed immediately so the child process sees it without delay. Include a trailing newline if the child reads line-by-line.