Chapter 24

process.ss: Process and Shell-Command Execution

This library builds on MzScheme's subprocess procedure; see also section 15.2 in PLT MzScheme: Language Manual.

(system command-string) executes a Unix, Windows, or BeOS shell command synchronously (i.e., the call to system does not return until the subprocess has ended), or launches a MacOS application by its creator signature (and returns immediately). The command-string argument is a string (of four characters for MacOS) containing no null characters. If the command succeeds, the return value is #t, #f otherwise. Under MacOS, if command-string is not four characters, the exn:application:mismatch exception is raised.

(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 or through a MacOS creator signature), and the arg-strings are the arguments. Under Unix, Windows and BeOS, the executed file is passed the specified string arguments (which must contain no null characters). Under MacOS, no arguments can be supplied, otherwise the exn:misc:unsupported exception is raised. 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.

(process command-string) executes a shell command asynchronously under Unix, Windows, and BeOS. (This procedure is not supported for MacOS.) 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.

  • '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 under Unix for all of Unix, Windows, and BeOS, except that command-string is a filename that is executed directly, and the arg-strings are the arguments. (This procedure is not supported for MacOS.) 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. All provided ports must be file-stream ports. 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.