Process

Splits a command line into words: the pieces between spaces, where a piece in double quotes may hold spaces and loses its quotes.

words := break_command_into_strings(" maple   \"red tree\" cedar ");
assert(words.count == 3);
assert(words[0] == "maple" && words[1] == "red tree" && words[2] == "cedar");

Joins args into one command line with a space between them, each quoted as append_quoted does. The string is new, from context.allocator, and the caller frees it. Use it to show or log a command, or to build a Windows command line.

line := get_quoted_command_string(.["plain", "two words", "say\"hi"]);
assert(line == "plain \"two words\" \"say\\\"hi\"");
free(line);

Appends s to builder, in double quotes when it has to be: when it is empty or holds a space, a tab or a double quote. A quote inside is escaped with a backslash, and backslashes before a quote or before the closing quote are doubled, which are the rules of the Windows command line, so the program at the other end splits it back into the same text.

builder: String_Builder;
append_quoted(*builder, "plain");
append(*builder, " ");
append_quoted(*builder, "two words");
append(*builder, " ");
append_quoted(*builder, "");
text := builder_to_string(*builder);
assert(text == "plain \"two words\" \"\"");
free(text);

Runs a program to its end and returns how it ended: (process_result, output_string, error_string, timeout_reached).

result, out, err, timed_out := run_command("/bin/sh", "-c", "printf copper; printf blue >&2; exit 7", capture_and_return_output = true, timeout_ms = 5000);
assert(!timed_out && result.type == .EXITED && result.exit_code == 7);
assert(out == "copper" && err == "blue");
free(out);
free(err);

result, out, err, timed_out = run_command("/bin/sleep", "30", timeout_ms = 20);
assert(timed_out && result.type == .SIGNALED && result.signal == 9);

result, out, err, timed_out = run_command("/jai-doc-no-such-program");
assert(result.type == .FAILED_TO_LAUNCH);

Starts the program args[0] with the arguments args[1..] and returns true once it is running; the result comes later from get_process_result. process must be a fresh Process.

Releases a Process: closes its pipes and handles and leaves it as a fresh record. Unlike on Unix it does not wait for the child. A child started with kill_process_if_parent_exits (the default) is killed when its job handle closes here; one started without it keeps running. Always call it once per successful create_process.

Writes data to the child's standard input and returns (success, bytes_written). It waits until the pipe has taken everything. It fails with the number of bytes that did go in when the pipe is closed, or the child has closed its end. Empty data succeeds with 0.

Waits up to timeout_ms for the child's output or error and reads what arrived into the two buffers: (success, output_bytes, error_bytes).

Terminates the child with exit code 1 and returns whether that was done: false for a process that was never started, and true without doing anything for one that has already ended. The result then reads EXITED; collect it with get_process_result.

The state of the child as (success, result), waiting up to timeout_ms for it to finish. 0 only checks and -1 (the default) waits for ever. While it runs the result is STILL_RUNNING; afterwards EXITED with the exit code. A process never started is UNSTARTED. success is false when the system could not tell.

Reads what is available now from one pipe of a process into buffer, and returns (success, bytes_read). 0 bytes with success means nothing is there yet, or the end: check pipe.eof. It fails with a closed pipe or an empty buffer. Use read_from_process to wait for data on both pipes.

Sets up pipe as one end of a new named pipe and returns the other end for the child, as (success, client_handle). is_input says which way the data flows: true for a pipe the parent writes. The child's handle is inheritable; the caller passes it to the child and closes it. Windows only; create_process uses it, and callers rarely need it.

A child process and its pipes. Make an empty one (process: Process;), start it with create_process, and release it with deinit.

The system part of a Process: the job object that holds the child (so it can be killed with its descendants), and the PROCESS_INFORMATION with its handles and ids.

The system part of a Process.Pipe: the pipe handle (INVALID_HANDLE_VALUE when there is none) and the overlapped record its reads and writes use. Read it, but let the procedures of this module do the closing.

Whether create_process and run_command put quotes around the arguments they are given. Windows starts a program from one command-line string, so the arguments are joined into it.

How far a process has got, as Process_Result.type: UNSTARTED (nothing was created), STILL_RUNNING, FAILED_TO_LAUNCH (run_command could not start the program) and EXITED with its exit_code. SIGNALED is never produced on Windows; a process that was killed is EXITED.

How a process ended: the type, the exit_code when it .EXITED (-1 otherwise) and the signal, which is always 0 on Windows.