#
Chapter 36
`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, 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:fail:contract` 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-string`s 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:fail: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.

`(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 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,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`` under Unix for all of Unix, Windows, and BeOS, except that `command-string` is a filename that is executed directly, and the `arg-string`s 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. 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.