#
Chapter 35
`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.

`(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-string`s 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,9 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-string`s 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. The provided ports need not 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``.

9 The standard error port is placed after the process id for compatibility with other Scheme implementations. For the same reason, ``process`` returns a list instead of multiple values.