process

process.Run

process.Run(commandLine) -> int

Runs a command line on the system shell, waits for it to finish, and returns the exit code.

The process's exit code (0 = success).

printf("%d\n", process.Run("true"));
printf("%d\n", process.Run("exit 3"));

0
3

process.RunEx

process.RunEx(workDir, envText, commandLine) -> int

Like Run, but you can also set a working directory and environment variables.

The process's exit code.

// runs in the /tmp directory
printf("%d\n", process.RunEx("/tmp", "", "pwd > /dev/null"));

0

process.RunArgv

process.RunArgv(program, ...) -> int

Runs a program with the given arguments (no shell), waits for it to finish, and returns the exit code.

The process's exit code.

// no shell interpretation; the arguments pass through exactly
printf("%d\n", process.RunArgv("echo", "hi"));

0

process.RunArgvEx

process.RunArgvEx(workDir, envText, program, ...) -> int

Like RunArgv, but with a working directory and environment variables.

The process's exit code.

printf("%d\n", process.RunArgvEx("/tmp", "", "echo", "hi"));

0

process.Start

process.Start(commandLine) -> int

Starts a command in the background and returns a handle.

The process handle (a positive integer).

i32 $h;
$h = process.Start("sleep 1");
// the script keeps running meanwhile...
process.Wait($h);
process.Close($h);

(you manage it later via the handle)

process.StartEx

process.StartEx(workDir, envText, commandLine) -> int

Like Start, but with a working directory and environment variables.

The process handle.

i32 $h;
$h = process.StartEx("/tmp", "", "sleep 1");
process.Wait($h);
process.Close($h);

(you manage it later via the handle)

process.StartArgv

process.StartArgv(program, ...) -> int

Starts a program in the background with the given arguments (no shell), and returns a handle.

The process handle.

i32 $h;
$h = process.StartArgv("sleep", "1");
process.Wait($h);
process.Close($h);

(you manage it later via the handle)

process.StartArgvEx

process.StartArgvEx(workDir, envText, program, ...) -> int

Like StartArgv, but with a working directory and environment variables.

The process handle.

i32 $h;
$h = process.StartArgvEx("/tmp", "", "sleep", "1");
process.Wait($h);
process.Close($h);

(you manage it later via the handle)

process.StartCapture

process.StartCapture(commandLine) -> int

Starts a command in the background and CAPTURES its output; returns a handle.

The process handle (a positive integer).

i32 $h;
string $out[256];
$h = process.StartCapture("echo captured-line");
process.Wait($h);
$out = process.OutputText($h);
printf("%s", $out);
process.Close($h);

captured-line

process.StartCaptureEx

process.StartCaptureEx(workDir, envText, commandLine) -> int

Like StartCapture, but with a working directory and environment variables.

The process handle.

i32 $h;
$h = process.StartCaptureEx("/tmp", "", "pwd");
process.Wait($h);
printf("%s", process.OutputText($h));
process.Close($h);

/tmp

process.StartCaptureArgv

process.StartCaptureArgv(program, ...) -> int

Starts a program in the background with arguments (no shell), and captures its output.

The process handle.

i32 $h;
$h = process.StartCaptureArgv("echo", "hi");
process.Wait($h);
printf("%s", process.OutputText($h));
process.Close($h);

hi

process.StartCaptureArgvEx

process.StartCaptureArgvEx(workDir, envText, program, ...) ->
int

Like StartCaptureArgv, but with a working directory and environment variables.

The process handle.

i32 $h;
$h = process.StartCaptureArgvEx("/tmp", "", "echo", "hi");
process.Wait($h);
printf("%s", process.OutputText($h));
process.Close($h);

hi

process.IsRunning

process.IsRunning(handle) -> int

Tells whether the process is still running.

1 if it is still running; 0 if it has already finished.

i32 $h;
$h = process.StartCapture("echo x");
process.Wait($h);
printf("%d\n", process.IsRunning($h));
process.Close($h);

0

process.Wait

process.Wait(handle) -> int

Waits until the process finishes and returns its exit code.

The process's exit code.

i32 $h;
$h = process.StartCapture("echo x");
printf("%d\n", process.Wait($h));
process.Close($h);

0

process.WaitMs

process.WaitMs(handle, milliseconds) -> int

Waits at most the given time for the process to finish (does not block forever).

1 if the process finished within the time limit; 0 if it is still running.

i32 $h;
$h = process.StartCapture("echo x");
process.Wait($h);
printf("%d\n", process.WaitMs($h, 0));
process.Close($h);

1

process.ExitCode

process.ExitCode(handle) -> int

Returns the exit code of an already-finished process.

The exit code. If the process is still running, a runtime error.

i32 $h;
$h = process.StartCapture("echo x");
process.Wait($h);
printf("%d\n", process.ExitCode($h));
process.Close($h);

0

process.OutputText

process.OutputText(handle) -> string

Returns the captured output of a finished process started with StartCapture*, as text.

The captured output as text. Output containing a NUL byte (binary) causes a runtime error.

i32 $h;
$h = process.StartCapture("echo captured-line");
process.Wait($h);
printf("%s", process.OutputText($h));
process.Close($h);

captured-line

process.OutputBlob

process.OutputBlob(handle) -> blob

Returns the captured output of a finished process started with StartCapture*, as a raw blob.

The captured output as a blob (the 0 byte is preserved).

i32 $h;
blob $out[256];
$h = process.StartCapture("echo hi");
process.Wait($h);
$out = process.OutputBlob($h);
printf("%d\n", $out.Length);
process.Close($h);

3

process.Terminate

process.Terminate(handle) -> int

Forcibly stops a still-running process.

Always 1.

i32 $h;
$h = process.Start("sleep 30");
printf("%d\n", process.Terminate($h));
process.Close($h);

1

process.Close

process.Close(handle) -> int

Frees the process handle and its associated resources (such as the temporary file of the captured output).

Always 1.

i32 $h;
$h = process.StartCapture("echo x");
process.Wait($h);
printf("%d\n", process.Close($h));

1

process.QuoteArg

process.QuoteArg(text) -> string

Puts the text into a safe form with quoting/escaping so it can be embedded as a single argument in a command line (per platform-specific rules).

The quoted text (POSIX shell on Linux, cmd rules on Windows).

printf("%s\n", process.QuoteArg("a b"));

'a b'

Practical notes

What the process plugin is good for

• Running external tools and commands from the script (a build step, a system command, a utility).

• Managing background processes: starting, state-watching, awaiting, stopping.

• Capturing and processing a program's output (a command's result, generated data).

• Safe command assembly from user data with the …Argv form or QuoteArg.

Which form to choose

If you only care about success (the exit code) and do not need the output, Run* is the simplest. If the script must run in parallel with the process, Start* is appropriate. If you also need the program's output, StartCapture* is the choice. In all three families: if you pass user data, the …Argv form is safer (no shell injection), and …Ex gives control of the working directory and environment.

Lifecycle

Background processes (Start*/StartCapture*) return a handle that must be freed with Close at the end. The typical order: start → (perhaps IsRunning/WaitMs for the state) → Wait to await → ExitCode and/or OutputText/OutputBlob for the result → Close. In a long-running script, close every handle so resources do not pile up.

Text vs blob output

OutputText is for textual output, and it rejects output containing a NUL byte (binary). If the program writes binary data (or you are not sure it is textual), OutputBlob is correct, since it returns the raw bytes, including the 0 byte.

Error handling

A wrong argument count or type, a non-existent or already-closed handle, ExitCode called on a still-running process, and OutputText called on output containing a NUL byte are reported by the runtime as a runtime error, and the script stops. The usual states are signaled by a neutral return value: IsRunning and WaitMs give 0/1, Run* gives the exit code. Check a command's success by the exit code (Run*/ExitCode).

The tls encrypted-connection plugin

TLS client, server, and certificate handling (OpenSSL) — complete function reference