15.4 Processes

On Unix and Mac OS, subprocess creation is separate from starting the program indicated by command. In particular, if command refers to a non-existent or non-executable file, an error will be reported (via standard error and a non-0 exit code) in the subprocess, not in the creating process.

The command argument is a path to a program executable, and the args are command-line arguments for the program. See find-executable-path for locating an executable based on the PATH environment variable. On Unix and Mac OS, command-line arguments are passed as byte strings, and string args are converted using the current locale’s encoding (see Encodings and Locales). On Windows, command-line arguments are passed as strings, and byte strings are converted using UTF-8.

On 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, on 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/.

When provided as a port, 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. The stderr argument can be 'stdout, in which case the same file-stream port or system pipe that is supplied as standard output is also used for standard error. For each port or 'stdout that is provided, no pipe is created and the corresponding returned value is #f. If stdout or stderr is a port for which port-waiting-peer? returns true, then subprocess waits for the port to become ready for writing before proceeding with the subprocess creation.

If group is 'new, then the new process is created as a new OS-level process group. In that case, subprocess-kill attempts to terminate all processes within the group, which may include additional processes created by the subprocess. Beware that creating a group may interfere with the job control in an interactive shell, since job control is based on process groups. See subprocess-kill for details. If group is a subprocess, then that subprocess must have been created with 'new, and the new subprocess will be added to the group; adding to the group will succeed only on Unix and Mac OS, and only in the same cases that subprocess-kill would have an effect (i.e., the subprocess is not known to have terminated), otherwise it will fail silently.

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 was a port;

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

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

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

A file-stream port for communicating with a subprocess is normally a pipe with a limited capacity. Beware of creating deadlock by serializing a write to a subprocess followed by a read, while the subprocess does the same, so that both processes end up blocking on a write because the other end must first read to make room in the pipe. Beware also of waiting for a subprocess to finish without reading its output, because the subprocess may be blocked attempting to write output into a full pipe.

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.

The current-subprocess-custodian-mode parameter determines whether the subprocess itself is registered with the current custodian so that a custodian shutdown calls subprocess-kill for the subprocess.

The current-subprocess-keep-file-descriptors parameter determines how file descriptors and handles in the current process are shared with the subprocess. File descriptors (on Unix and Mac OS) or handles (on Windows) represented by stdin, stdout, and stderr are always shared with the subprocess. With the default parameter value of 'inherited, handles that are inherited on Windows are also shared, while no other file descriptors are shared on Unix and Mac OS. The parameter value 'all is equivalent to 'inherited on Windows, but on Unix and Mac OS, all file descriptors from the current process are shared with the subprocess—except for file descriptors 0, 1, and 2 as replaced by newly created pipes when the corresponding stdin, stdout, and stderr argument is #f. The parameter value '() is the same as 'inherited on Unix and Mac OS , but it prevents sharing of inheritable handles on Windows. (A future extension may support a list of specific file descriptors or handles to share.)

A subprocess can be used as a synchronizable event (see Events). A subprocess value is ready for synchronization when subprocess-wait would not block; the synchronization result of a subprocess value is the subprocess value itself.

Example:

(define-values (sp out in err)

(subprocess #f #f #f "/bin/ls" "-l"))

(printf "stdout:\n~a" (port->string out))

(printf "stderr:\n~a" (port->string err))

(close-input-port out)

(close-output-port in)

(close-input-port err)

(subprocess-wait sp)

Changed in version 6.11.0.1 of package base: Added the group argument.
Changed in version 7.4.0.5: Added waiting for a fifo without a reader as stdout and/or stderr.
Changed in version 8.3.0.4: Added current-subprocess-custodian-mode support.

• force? is true, not a group, all platforms: Terminates the process if the process still running.

• force? is false, not a group, on Unix or Mac OS: Sends the process an interrupt signal instead of a kill signal.

• force? is false, not a group, on Windows: No action is taken.

• force? is true, a group, on Unix or Mac OS: Terminates all processes in the group, but only if subprocess-status has never produced a non-'running result for the subprocess and only if functions like subprocess-wait and sync have not detected the subprocess’s completion. Otherwise, no action is taken (because the immediate process is known to have terminated while the continued existence of the group is unknown).

• force? is true, a group, on Windows: Terminates the process if the process still running.

• force? is false, a group, on Unix or Mac OS: The same as when force? is #t, but when the group is sent a signal, it is an interrupt signal instead of a kill signal.

• force? is false, a group, on Windows: All processes in the group receive a CTRL-BREAK signal (independent of whether the immediate subprocess has terminated).

If an error occurs during termination, the exn:fail exception is raised.

Custodian-triggered shutdown is limited by details of process handling in the host system. For example, process and system may create an intermediate shell process to run a program, in which case custodian-based termination shuts down the shell process and probably not the process started by the shell. See also subprocess-kill. Process groups (see subprocess-group-enabled) can address some limitations, but not all of them.

Added in version 8.3.0.4 of package base.

For example,

(shell-execute #f "http://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).

15.4.1 Simple Subprocesses

See also subprocess for notes about error handling and the limited buffer capacity of subprocess pipes.

If set-pwd? is true, then the PWD environment variable is set to the value of (current-directory) when starting the shell process.

See also current-subprocess-custodian-mode and subprocess-group-enabled, which affect the subprocess used to implement system.

The resulting process writes to (current-output-port), reads from (current-input-port), and logs errors to (current-error-port). To gather the process’s non-error output to a string, for example, use with-output-to-string, which sets current-output-port while calling the given function:

(with-output-to-string (lambda () (system "date")))

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

See also subprocess for notes about error handling and the limited buffer capacity of subprocess pipes.

• an input port piped from the subprocess’s standard output,

• an output port piped to the subprocess’s 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, 'exit-code 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 on Unix and Mac OS, and takes no action on Windows. The result is #<void>.

    On Unix and Mac OS, if command runs a single program, then sh typically runs the program in such a way that it replaces sh in the same process. For reliable and precise control over process creation, however, use process*.

  • '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 on Windows.

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

If set-pwd? is true, then PWD is set in the same way as system.

See also current-subprocess-custodian-mode and subprocess-group-enabled, which affect the subprocess used to implement process. In particular, the 'interrupt and 'kill process-control messages are implemented via subprocess-kill, so they can affect a process group instead of a single process.

The contracts of system and related functions may signal a contract error with references to the following functions.