Standard library · System and tools

os/process

Running other programs, capturing their output, waiting for them and stopping them.

import os.process

On this page

Types
Functions

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.

If you need the program's output, run it with StartCaptured, wait for it to finish and then read the output. Call Cleanup when you are done.

Types

`Process`

struct Process

A process, running or finished.

Name	Type	Description
`pid`	`int = 0`	The process id.
`handle`	`void*`	The process handle on Windows.
`running`	`bool = false`	True while it is still running.
`exit_code`	`int = 0`	The exit code, once it has finished.
`stdout_path`	`str = ""`	The temporary file holding the captured output.
`stderr_path`	`str = ""`	The temporary file holding the captured error output.

os-process-Start.salam

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

Outputtrue 0 0 false hello from the child process []

Functions

`Start`

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

Runs a program with its arguments and does not wait; its output goes straight to your own program's output.

The example for this item is shown with the ones above: os-process-Start.salam

`StartCaptured`

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

Like Start, but captures the program's output and error output for you to read later.

The example for this item is shown with the ones above: os-process-Start.salam

`WaitPid`

func WaitPid(pid: int): int

Waits for the process with this id to finish and returns its exit code.

os-process-Kill.salam

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

Outputtrue false both have stopped

`Wait`

func Wait(p &: Process): int

Waits for the process to finish and returns its exit code.

The example for this item is shown with the ones above: os-process-Start.salam

`Fork`

func Fork(): int

Splits the current process in two: it returns zero in the child and the child's id in the parent. On Unix systems only; its example is not run here.

os-process-Fork.salam

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

`ExitNow`

func ExitNow(code: int)

Ends the process immediately with no cleanup at all, for finishing a child after Fork.

The example for this item is shown with the ones above: os-process-Fork.salam

`Kill`

func Kill(p &: Process): int

Kills the process at once (SIGKILL).

The example for this item is shown with the ones above: os-process-Kill.salam

`Terminate`

func Terminate(p &: Process): int

Asks the process to finish gracefully (SIGTERM) so it has a chance to clean up. On Windows it is the same as Kill.

The example for this item is shown with the ones above: os-process-Kill.salam

`ReadStdout`

func ReadStdout(p: Process): str

Reads the captured output once the process has finished.

The example for this item is shown with the ones above: os-process-Start.salam

`ReadStderr`

func ReadStderr(p: Process): str

Reads the captured error output.

The example for this item is shown with the ones above: os-process-Start.salam

`Cleanup`

func Cleanup(p &: Process)

Removes the temporary capture files.

The example for this item is shown with the ones above: os-process-Start.salam

`ExitCode`

func ExitCode(p: Process): int

The process's exit code.

The example for this item is shown with the ones above: os-process-Start.salam

`Pid`

func Pid(p: Process): int

The process id.

The example for this item is shown with the ones above: os-process-Start.salam

`IsRunning`

func IsRunning(p: Process): bool

True while the process is still running.

The example for this item is shown with the ones above: os-process-Start.salam