os/process

The os.process package runs another program directly, with no shell in between. The program's path and its arguments are given separately, so nothing has to be quoted and spaces or special characters in an argument cause no trouble. Use it to call tools such as git, ffmpeg or a compiler with file names that came from a user. For a quick one-line shell command use os (Run, RunCapture) or os.shell; when a program cannot start at all, the reason is recorded in os.error.

A run has up to four steps: Start or StartCaptured launches the program and returns at once, Wait blocks until it exits and returns the exit code, ReadStdout and ReadStderr read what a captured run printed, and Cleanup deletes the two temporary files that held it. A captured program gets an empty standard input.

What people get wrong:

• Treating IsRunning as a live check. It reports a flag that Start sets and only Wait, Kill or Terminate clear; it stays true after the program has exited on its own.
• Killing without waiting. Kill and Terminate only send the signal. Call Wait afterwards, or the finished process stays in the process table as a zombie.
• Expecting a timeout. Wait waits as long as the program runs. To give up after a while, wait in a thread and Kill from the main one.
• Forgetting Cleanup. Each captured run leaves two files in the temporary folder until you call it.

Pass arguments exactly as they are

Each element of the argument vector reaches the program as one argument, byte for byte. Spaces, quotes, a $ or a ; mean nothing special, because no shell reads them. That makes this package the safe way to pass file names and other text that came from a user.

import os.process

func main:
    mut args := Vector {} as Vector<str>
    defer args.free()
    args.push("[%s]\n")
    args.push("two words")
    args.push("it's quoted")
    args.push("$HOME")
    args.push("*.txt; rm -rf x")
    mut p := process.StartCaptured("printf", args)
    process.Wait(p)
    print process.ReadStdout(p)
    process.Cleanup(p)
end

The program name is looked up on the PATH like in a terminal, so printf works without a full path. The vector does not include the program name itself; the package adds it. This exactness holds on Linux and macOS; see the note above for Windows.

Exit code, output and error output

A program reports success with exit code zero and anything else on failure, and it writes its complaints to the error output. After Wait, read both: ReadStdout for the results and ReadStderr for the reason it failed. Call Cleanup after reading, because the captured output is kept in temporary files until then.

import os.process

func main:
    mut args := Vector {} as Vector<str>
    defer args.free()
    args.push("-c")
    args.push("echo copying files; echo disk is full >&2; exit 3")
    mut p := process.StartCaptured("sh", args)
    code := process.Wait(p)
    out := process.ReadStdout(p).trim()
    err := process.ReadStderr(p).trim()
    process.Cleanup(p)
    println "output:", out
    if code != 0:
        println "failed with code", code, "and said:", err
        ret 0
    end
    println "all good"
end

Run several programs at once

StartCaptured returns as soon as the program has started, so you can start several and wait for them afterwards. The total time is about that of the slowest one rather than the sum of all. Waiting in the order you started them keeps the output in a fixed order, even when a later job finished first.

import os.process

func job(name: str, seconds: str): process.Process:
    mut args := Vector {} as Vector<str>
    defer args.free()
    args.push("-c")
    args.push("sleep " + seconds + "; echo " + name + " done")
    ret process.StartCaptured("sh", args)
end

func main:
    mut jobs := Vector {} as Vector<process.Process>
    defer jobs.free()
    jobs.push(job("thumbnails", "0.3"))
    jobs.push(job("search index", "0.1"))
    jobs.push(job("sitemap", "0.2"))
    println "started", jobs.len(), "jobs"
    repeat jobs.len() in i:
        mut p := jobs.get(i)
        code := process.Wait(p)
        println code, process.ReadStdout(p).trim()
        process.Cleanup(p)
    end
end

Keep the number of programs you run at once reasonable; os.platform's CpuCount is a good limit for work that keeps the processor busy.

A helper that runs a program and returns its output

Most programs need the same few lines every time: start, check that it started, wait, read, clean up. Put them in one function. A defer right after the start makes sure Cleanup runs on every way out of the function, and an out-parameter tells the caller whether the program succeeded.

import os.error
import os.process

func capture(program: str, args: Vector<str>, ok &: bool): str:
    error.Clear()
    mut p := process.StartCaptured(program, args)
    if error.HasError():
        ok = false
        ret ""
    end
    defer process.Cleanup(p)
    ok = process.Wait(p) == 0
    ret process.ReadStdout(p)
end

func main:
    mut args := Vector {} as Vector<str>
    defer args.free()
    args.push("-c")
    args.push("printf 'pear\\napple\\nfig\\n' | sort")
    mut ok := false
    out := capture("sh", args, ok)
    println "worked:", ok
    print out
    capture("/no/such/tool", args, ok)
    println "missing tool worked:", ok
end

Stop a program

Terminate sends SIGTERM, which a well-behaved program catches to save its work and exit; Kill sends SIGKILL, which cannot be caught. Either way, Wait collects the program afterwards. A program ended by a signal reports 128 plus the signal number as its exit code, so 143 means SIGTERM and 137 means SIGKILL, the same numbers a shell shows.

import os.process

func main:
    mut args := Vector {} as Vector<str>
    defer args.free()
    args.push("30")
    mut worker := process.Start("sleep", args)
    println "started, running:", process.IsRunning(worker)
    if process.Terminate(worker) != 0:
        println "could not signal it"
        ret 1
    end
    code := process.Wait(worker)
    println "stopped with exit code", code, "= 128 + signal", code - 128
    println "running:", process.IsRunning(worker)
    ret 0
end

Types

struct Process

import os.process

func main:
    mut args := Vector {} as Vector<str>
    defer args.free()
    args.push("hello from the child process")
    mut p := process.StartCaptured("/bin/echo", args)
    println process.Pid(p) > 0
    code := process.Wait(p)
    println code, process.ExitCode(p), process.IsRunning(p)
    print process.ReadStdout(p)
    println "[" + process.ReadStderr(p) + "]"
    process.Cleanup(p)
end

Functions

func Start(path: str, args: Vector<str>): Process

func StartCaptured(path: str, args: Vector<str>): Process

func WaitPid(pid: int): int

import os.process

func main:
    mut args := Vector {} as Vector<str>
    defer args.free()
    args.push("30")
    mut p := process.Start("/bin/sleep", args)
    println process.IsRunning(p)
    process.Terminate(p)
    process.Wait(p)
    println process.IsRunning(p)
    mut p2 := process.Start("/bin/sleep", args)
    process.Kill(p2)
    process.WaitPid(process.Pid(p2))
    println "both have stopped"
end

func Wait(p &: Process): int

func Fork(): int

import os.process

func main:
    pid := process.Fork()
    if pid == 0:
        println "I am the child"
        process.ExitNow(0)
    end
    process.WaitPid(pid)
    println "the child has finished"
end

func ExitNow(code: int)

func Kill(p &: Process): int

func Terminate(p &: Process): int

func ReadStdout(p: Process): str

func ReadStderr(p: Process): str

func Cleanup(p &: Process)

func ExitCode(p: Process): int

func Pid(p: Process): int

func IsRunning(p: Process): bool