Command arguments and encoding

• create consumes one non-empty command sequence whose first item is the program path.
• create also accepts one single String-like command value and treats it as a one-item command sequence.
• create2 accepts the same command sequence together with one options object.
• Each command item is converted through String view semantics before process creation.
• On Linux and macOS, linux/Process and macos/Process both re-export the shared posix/Process implementation (PosixProcess as Process, toPosixProcess as toProcess); the items become the separate argv entries of execvp.
• On Windows, process creation consumes one command-line string; create uses CommandEncoder.crt and UTF-16 conversion follows the encoding.
• create2 and toProcess2 may select another encoder through options.encodeCommand.

Windows command line

The items are joined into one command line by an encoder with effect (commands -- buffer). It receives the entire command sequence and returns UTF-8 command-line bytes in a Nat8 Array or another object with span.stringView; a String works, but a Text alone does not. The result is converted to a zero-terminated UTF-16 buffer for CreateProcessW. windows/Process exports CommandEncoder with two encoders: CommandEncoder.crt (the default) writes the program and every argument in double quotes, escapes an embedded " as \", and doubles the backslashes that precede a quote or end an argument; the program itself must not contain ". CommandEncoder.plain joins the items with single spaces and quotes nothing. An options Dict without encodeCommand selects the default; for example, {encodeCommand: [CommandEncoder.plain];} selects the plain encoder.

Process

Methods

Remarks

• Destroying a created Process waits without requesting the exit status.

Helper constructors

Lifecycle and results

• A newly constructed Process is uninitialized.
• A successful create or create2 call initializes the Process wrapper.
• A created Process owns one process resource until wait completes or the wrapper is destroyed.
• kill leaves the created state unchanged until wait completes.
• wait clears the created state after the process terminates.
• kill and wait use assertion-based preconditions. Failures of POSIX kill/waitpid or Windows TerminateProcess/WaitForSingleObject/GetExitCodeProcess print <function> failed, result=<error code> followed by a line feed and exit the calling process with status 1. On Windows, a CloseHandle failure is only reported; wait still clears the wrapper's created state.
• FALSE @process.wait waits for termination and returns no exit status.
• TRUE @process.wait returns one Int32 exit-status value.
• On Windows, that value is the process exit code converted to Int32.
• On Linux and macOS, a normal exit returns the normal exit status and any other termination form returns the negated raw wait status.

POSIX implementation (Linux and macOS)

• The shared POSIX implementation uses fork, execvp, pipe, waitpid, and kill.
• The child process executes the command through execvp; the parent reads the child pipe to distinguish creation failure from a successful execvp.

Examples

Linux exit-status example

"String"        use
"control"       use
"linux/Process" use

{} Int32 {} [
  process: result: ("/bin/sh" "-c" "exit 7") toProcess;;
  [result.size 0 =] "create failed" ensure
  (TRUE @process.wait toString LF) printList
  0
] "main" exportFunction

Expected Output

7

macOS exit-status example

"String"        use
"control"       use
"macos/Process" use

{} Int32 {} [
  process: result: ("/bin/sh" "-c" "exit 7") toProcess;;
  [result.size 0 =] "create failed" ensure
  (TRUE @process.wait toString LF) printList
  0
] "main" exportFunction

Expected Output

7

Linux failure-result example

"String"        use
"control"       use
"linux/Process" use

{} Int32 {} [
  process: result: "/definitely/not/found/command" toProcess;;
  (result.size 0 > toString " " @process.isCreated ~ toString LF) printList
  0
] "main" exportFunction

Expected Output

TRUE TRUE

See also

• String: UTF-8 string views, owned strings, formatting helpers, and text conversion utilities.
• CommandLine: Command-line argument view construction and printing.
• linux/runningTime · macos/runningTime · windows/runningTime: Elapsed-time helper built on platform timing APIs.