Operating System Processes

(system command) executes a Unix or Windows 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 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 is not four characters, the exn:application:macos-typestring exception is raised.

(system* command argument ) is like system, except that command is a filename that is executed directly (instead of through a shell command or through a MacOS creator signature). Under Unix and Windows, 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) does not return unless there was an error executing command. 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, although execute* is supported for Windows.)

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

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

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

(process* command argument ) is like process under Unix for both Unix and Windows, except that command is a filename that is executed directly. (This procedure is not supported for MacOS.)

The ports returned by process and process* 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 event-class event-id [direct-parameter parameters]) sends an AppleEvent under MacOS. (This procedure is not supported for Unix or Windows.) The receiver, event-class, and event-id arguments are strings that 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:macos-typestring exception is raised. The direct-parameter value is converted (see below) and passed as the main argument of the event; if direct-parameter is void, no main argument is sent in the event. The parameters argument is a list of two-element lists containing a typestring and value; each typestring is used ad the keyword name of an AppleEvent parameter for the associated converted value. Each typestring must be a four-character string, otherwise the exn:application:macos-typestring exception is raised. The default values for direct-parameter and parameters 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 reverese-converted reply value (see below), or the exn:misc:send-event 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 connot be reverse-converted, the exn:misc:send-event exception is raised.