Next: Operating System Environment Variables Up: System Utilities Previous: Timing Execution

# Operating System Processes

`(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.

`(execute command-string)` does not return unless there was an error executing command-string. If it returns, the result is void. Under Unix, it is like `system` followed by `exit` when the command succeeds. For MacOS, this procedure is `system` followed by an immediate exit if the target application launches successfully. (This procedure is not supported for Windows or BeOS, although `execute*` is supported for Windows and BeOS.)

`(execute* command-string arg-string )` is like `execute` for Unix and MacOS, except that command-string is a filename that is executed directly, and the arg-strings are the arguments. Under Unix, when the current exit handler is MzScheme's default exit handler, the execution of command-string replaces the MzScheme process. Under MacOS, no arguments can be supplied, otherwise the `exn:misc:unsupported` exception is raised. Under Windows and BeOS, this procedure is like `system*` except that `exit` is called immediately if the specified program launches successfully, otherwise void is returned.

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

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.)

`(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`.

The ports returned by `process`, `process*`, `process/ports`, and `process*/ports` are placed into the management of the current custodian (see section 9.5). The `exn:misc:process` exception is raised when a low-level error prevents the spawning of a process or the creation of operating system pipes for process communication.

`(send-event receiver-string event-class-string event-id-string [direct-argument-v argument-list])` sends an AppleEvent under MacOS. (This procedure is not supported for Unix, Windows, or BeOS.) The receiver-string, event-class-string, and event-id-string arguments specify the signature of the receiving application, the class of the AppleEvent, and the ID of the AppleEvent. Each of these must be a four-character string, otherwise the `exn:application:mismatch` exception is raised. The direct-argument-v value is converted (see below) and passed as the main argument of the event; if direct-argument-v is void, no main argument is sent in the event. The argument-list argument is a list of two-element lists containing a typestring and value; each typestring is used ad the keyword name of an AppleEvent argument for the associated converted value. Each typestring must be a four-character string, otherwise the `exn:application:mismatch` exception is raised. The default values for direct-argument and arguments are void and `null`, respectively.

The following types of MzScheme values can be converted to AppleEvent values passed to the receiver:

If other types of values are passed to `send-event` for conversion, the `exn:misc:unsupported` exception is raised.

The `send-event` procedure does not return until the receiver of the AppleEvent replies. The result of `send-event` is the reverse-converted reply value (see below), or the `exn:misc` exception is raised if there is an error. If there is no error or return value, `send-event` returns void.

The following types of AppleEvent values can be reverse-converted into a MzScheme value returned by `send-event`:

If the AppleEvent reply contains a value that cannot be reverse-converted, the `exn:misc` exception is raised.

Next: Operating System Environment Variables Up: System Utilities Previous: Timing Execution