Chapter 38

process.ss: Process and Shell-Command Execution

To load: (require (lib "process.ss"))

This library builds on MzScheme's subprocess procedure; see also section 15.2 in PLT MzScheme: Language Manual. In contrast to subprocess, there is no restriction on the ports that are used by these functions (either explicit arguments, or implicit as the current-...-port parameters): they need not be file-stream ports.

(system command-string) executes a Unix, Mac OS X, or Windows shell command synchronously (i.e., the call to system does not return until the subprocess has ended). The command-string argument is a string containing no null characters. If the command succeeds, the return value is #t, #f otherwise.

(system* command-string arg-string ···) is like system, except that command-string is a filename that is executed directly (instead of through a shell command), and the arg-strings are the arguments. The executed file is passed the specified string arguments (which must contain no null characters). Under Windows, the first arg-string can be 'exact where the second arg-string is a complete command line; see section 15.2 in PLT MzScheme: Language Manual for details.

(system/exit-code command-string) is like system, except that it returns the exit-code returned by the subprocess instead of a boolean (a result of 0 indicates success).

(system*/exit-code command-string) is like system*, except that it returns the exit-code like system/exit-code does.

(process command-string) executes a shell command asynchronously. If the subprocess is launched successfully, the result is a list of five values:

• an input port piped from the subprocess's standard output,

• an output port piped to the subprocess standard input,

• the system process id of the subprocess,

• an input port piped from the subprocess's standard error,⁹ and

• a procedure of one argument, either 'status, 'wait, 'interrupt, or 'kill:

  • 'status returns the status of the subprocess as one of 'running, 'done-ok, or 'done-error.

  • 'exit-code returns the integer exit code of the subprocess or #f if it is still running.

  • 'wait blocks execution in the current thread until the subprocess has completed.

  • 'interrupt sends the subprocess an interrupt signal under Unix and Mac OS X, and takes no action under Windows. The result is void.

  • 'kill terminates the subprocess and returns void.

Important: All three ports returned from process must be explicitly closed with close-input-port and close-output-port.

(process* command-string arg-string ···) is like process, except that command-string is a filename that is executed directly, and the arg-strings are the arguments. Under Windows, as for system*, the first arg-string can be 'exact.

(process/ports output-port input-port error-output-port command-string) is like process, except that output-port is used for the process's standard output, input-port is used for the process's standard input, and error-output-port is used for the process's standard error. Any of the ports can be #f, in which case a system pipe is created and returned, as in process. For each port that is provided, no pipe is created and the corresponding returned value is #f.

(process*/ports output-port input-port error-output-port command-string arg-string ···) is like process*, but with the port handling of process/ports.