14.4 Subprocesses🔗ℹ

If program is a pathless file name (i.e., Path.parent(program) produces #'relative), then a non-#false result of find_executable_path(program) is used in place of program.

The new process’s input, output, or error output can be captured in a pipe using #'pipe for in, out, or err, respectively; the other end of the pipe is then accessible using Subprocess.in, Subprocess.out, or Subprocess.err, respectively. Otherwise, the new process’s input and output use the given ports, which default to the current ports. In the case of err, #'out is allowed to indicate that error output should use the same pipe or port as non-error output.

If group is #'same, the process group of the current process is used for the new subprocess. If group is #'new, the new subprocess is created in a fresh process group; the resulting Subprocess object then satisfies Subprocess.NewGroup. If group is a Subprocess.NewGroup, then the new subprocess is in the same group as that previously created subprocess.

When pipes are created for a subprocess, the local end of the pipe must be closed explicitly, perhaps using Subprocess.close. See also Closeable.let.

On Unix and Mac OS variants, "/bin/sh" is run as the shell. On Windows, "cmd.com" or "command.exe" is used.

The shell function is a shorthand to combine run_shell and Subprocess.wait_ok as run_shell(command).wait_ok().

Accessing the Subprocess.in, Subprocess.out, or Subprocess.err, property raises an exception if the subprocess does not have a pipe for the corresponding subprocess stream. Accessing the Subprocess.maybe_in, Subprocess.maybe_out, or Subprocess.maybe_err property either produces the same result as Subprocess.in, Subprocess.out, or Subprocess.err, or it returns #false.

The Subprocess.wait method waits for the subprocess and it returns its exit code. An exit code of 0 typically indicates success, and Subprocess.wait_ok(subp) is equivalent to Subprocess.wait(subp) == 0.

The Subprocess.poll method immediately returns #false if the subprocess has not completed, or it returns the same result as Subprocess.wait.

If program is a pathless name (i.e., Path.parent(program) produces #'relative), find_executable_path gets the value of the PATH environment variable; if this environment variable is defined, find_executable_path tries each path in PATH as a prefix for program. On Windows, the current directory is always implicitly the first item in PATH, so find_executable_path checks the current directory first on Windows. If the PATH environment variable is not defined or if program is not pathless, program is prefixed with the current directory.

On Windows, if program is not found and it has no file suffix, then the search starts over with ".exe" added to program, and the result is #false only if the path with ".exe" also cannot be found. The result includes the suffix ".exe" if only program with the suffix is found.