process/io.matthewnelson.kmp.process/Process/Builder

Builder

class Builder(val command: String)(source)

Creates a new Process.

e.g. (Shell commands on a Unix system)

val out = Process.Builder("sh")
    .args("-c")
    .args("sleep 1; exit 5")
    .destroySignal(Signal.SIGKILL)
    .stdin(Stdio.Null)
    .output { timeoutMillis = 1_500 }

assertEquals(5, out.processInfo.exitCode)

e.g. (Executable file)

val p = Process.Builder(myExecutableFile)
    .args("--some-flag")
    .args("someValue")
    .args("--another-flag", "anotherValue")
    .environment {
        remove("HOME")
        // ...
    }
    .stdin(Stdio.Null)
    .stdout(Stdio.File.of("logs/myExecutable.log", append = true))
    .stderr(Stdio.File.of("logs/myExecutable.err"))
    .spawn()

Parameters

command

The command to run. On Native Linux, macOS and iOS, if command is a relative file path or program name (e.g. ping) then posix_spawnp is utilized. If it is an absolute file path (e.g. /usr/bin/ping), then posix_spawn is utilized.

Constructors

Builder

constructor(executable: File)

Alternate constructor for an executable File. Will take the absolute + normalized path to use for command.

constructor(command: String)

Properties

command

@JvmField

val command: String

Functions

args

fun args(vararg args: String): Process.Builder

fun args(args: List<String>): Process.Builder

Add multiple arguments

fun args(arg: String): Process.Builder

Add a single argument

changeDir

fun Process.Builder.changeDir(directory: File?): Process.Builder

Changes the working directory of the spawned process.

destroySignal

fun destroySignal(signal: Signal): Process.Builder

Set the Signal to use when Process.destroy is called.

detached

fun Process.Builder.detached(enable: Boolean): Process.Builder

Configures the detached option for spawn.

environment

fun environment(block: MutableMap<String, String>.() -> Unit): Process.Builder

Modify the environment via lambda

fun environment(key: String, value: String): Process.Builder

Set/overwrite an environment variable

onError

fun onError(handler: ProcessException.Handler?): Process.Builder

Set a ProcessException.Handler to manage internal Process errors for spawned processes.

output

fun output(): Output

fun output(block: Output.Options.Builder.() -> Unit): Output

Blocks the current thread until Process completion, Output.Options.Builder.timeoutMillis is exceeded, or Output.Options.Builder.maxBuffer is exceeded.

shell

fun Process.Builder.shell(enable: Boolean): Process.Builder

Configures the shell option for spawn and spawnSync

fun Process.Builder.shell(shell: String): Process.Builder

Configures the shell option for spawn and spawnSync.

spawn

fun spawn(): Process

Spawns the Process

stderr

fun stderr(destination: Stdio): Process.Builder

Modify the standard error output destination

stdin

fun stdin(source: Stdio): Process.Builder

Modify the standard input source

stdout

fun stdout(destination: Stdio): Process.Builder

Modify the standard output destination

usePosixSpawn

fun Process.Builder.usePosixSpawn(use: Boolean): Process.Builder

By default, posix_spawn and posix_spawnp are always preferred when spawning processes, given that the necessary API availability is present (e.g. Android Native requires a device API of 28+, or 34+ if changing the process' working directory via changeDir). If API availability is not present, then an alternative implementation using fork and execve is fallen back to. This option allows you to skip over posix_spawn, regardless of its API availability, and go directly to the alternative implementation using fork and execve.

useSpawn

inline fun <T> useSpawn(block: (process: Process) -> T): T

Spawns the Process and calls Process.destroy upon block closure.

windowsHide

fun Process.Builder.windowsHide(enable: Boolean): Process.Builder

Configures the windowsHide option for spawn and spawnSync

windowsVerbatimArguments

fun Process.Builder.windowsVerbatimArguments(enable: Boolean): Process.Builder

Configures the windowsVerbatimArguments option for spawn and spawnSync