14.4 Processes

The command argument is a path to a program executable, and the args are command-line arguments for the program. Under Unix and Mac OS X, command-line arguments are passed as byte strings using the current locale’s encoding (see Encodings and Locales).

Under Windows, the first arg can be replaced with 'exact, which triggers a Windows-specific behavior: the sole arg is used exactly as the command-line for the subprocess. Otherwise, under Windows, a command-line string is constructed from command and arg so that a typical Windows console application can parse it back to an array of arguments. If 'exact is provided on a non-Windows platform, the exn:fail:contract exception is raised.

For information on the Windows command-line conventions, search for “command line parsing” at http://msdn.microsoft.com/.

Unless it is #f, stdout is used for the launched process’s standard output, stdin is used for the process’s standard input, and stderr 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 by subprocess. For each port that is provided, no pipe is created and the corresponding returned value is #f.

The subprocess procedure returns four values:

• a subprocess value representing the created process;

• an input port piped from the process’s standard output, or #f if stdout-output-port was a port;

• an output port piped to the process standard input, or #f if stdin-input-port was a port;

• an input port piped from the process’s standard error, or #f if stderr-output-port was a port.

Important: All ports returned from subprocess must be explicitly closed with close-input-port or close-output-port.

The returned ports are file-stream ports (see File Ports), and they are placed into the management of the current custodian (see Custodians). The exn:fail exception is raised when a low-level error prevents the spawning of a process or the creation of operating system pipes for process communication.

If force? is #f under Unix and Mac OS X, the subprocess is sent an interrupt signal instead of a kill signal (and the subprocess might handle the signal without terminating). Under Windows, no action is taken when force? is #f.

(shell-execute   verb             target             parameters             dir             show-mode)   →   #f

verb : (or/c string? #f)

target : string?

parameters : string?

dir : path-string?

show-mode : symbol?

Performs the action specified by verb on target in Windows. For platforms other than Windows, the exn:fail:unsupported exception is raised.

For example,

(shell-execute #f "http://www.racket-lang.org" ""

(current-directory) 'sw_shownormal)

Opens the Racket home page in a browser window.

The verb can be #f, in which case the operating system will use a default verb. Common verbs include "open", "edit", "find", "explore", and "print".

The target is the target for the action, usually a filename path. The file could be executable, or it could be a file with a recognized extension that can be handled by an installed application.

The parameters argument is passed on to the system to perform the action. For example, in the case of opening an executable, the parameters is used as the command line (after the executable name).

The dir is used as the current directory when performing the action.

The show-mode sets the display mode for a Window affected by the action. It must be one of the following symbols; the description of each symbol’s meaning is taken from the Windows API documentation.

• 'sw_hide or 'SW_HIDE – Hides the window and activates another window.

• 'sw_maximize or 'SW_MAXIMIZE – Maximizes the window.

• 'sw_minimize or 'SW_MINIMIZE – Minimizes the window and activates the next top-level window in the z-order.

• 'sw_restore or 'SW_RESTORE – Activates and displays the window. If the window is minimized or maximized, Windows restores it to its original size and position.

• 'sw_show or 'SW_SHOW – Activates the window and displays it in its current size and position.

• 'sw_showdefault or 'SW_SHOWDEFAULT – Uses a default.

• 'sw_showmaximized or 'SW_SHOWMAXIMIZED – Activates the window and displays it as a maximized window.

• 'sw_showminimized or 'SW_SHOWMINIMIZED – Activates the window and displays it as a minimized window.

• 'sw_showminnoactive or 'SW_SHOWMINNOACTIVE – Displays the window as a minimized window. The active window remains active.

• 'sw_showna or 'SW_SHOWNA – Displays the window in its current state. The active window remains active.

• 'sw_shownoactivate or 'SW_SHOWNOACTIVATE – Displays a window in its most recent size and position. The active window remains active.

• 'sw_shownormal or 'SW_SHOWNORMAL – Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position.

If the action fails, the exn:fail exception is raised. If the action succeeds, the result is #f.

In future versions of Racket, the result may be a subprocess value if the operating system did returns a process handle (but if a subprocess value is returned, its process ID will be 0 instead of the real process ID).

14.4.1 Simple Subprocesses

Under Windows, the first argument after command can be 'exact, and the final arg is a complete command line. See subprocess for details.

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

  • '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>. Note that the immediate process created by process is a shell process that may run another program; terminating the shell process may not terminate processes that the shell starts, particularly under Windows.

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