On this page:
subprocess
subprocess-wait
subprocess-status
subprocess-kill
subprocess-pid
subprocess?
shell-execute
14.4.1 Simple Subprocesses
system
system*
system/ exit-code
system*/ exit-code
process
process*
process/ ports
process*/ ports

14.4 Processes

(subprocess stdout 
  stdin 
  stderr 
  command 
  arg ...) 
  
subprocess?
(or/c (and/c input-port? file-stream-port?) #f)
(or/c (and/c output-port? file-stream-port?) #f)
(or/c (and/c input-port? file-stream-port?) #f)
  stdout : (or/c (and/c output-port? file-stream-port?) #f)
  stdin : (or/c (and/c input-port? file-stream-port?) #f)
  stderr : (or/c (and/c output-port? file-stream-port?) #f)
  command : path-string?
  arg : string?
(subprocess stdout 
  stdin 
  stderr 
  command 
  exact 
  arg) 
  
subprocess?
(or/c (and/c input-port? file-stream-port?) #f)
(or/c (and/c output-port? file-stream-port?) #f)
(or/c (and/c input-port? file-stream-port?) #f)
  stdout : (or/c (and/c output-port? file-stream-port?) #f)
  stdin : (or/c (and/c input-port? file-stream-port?) #f)
  stderr : (or/c (and/c output-port? file-stream-port?) #f)
  command : path-string?
  exact : 'exact
  arg : string?
Creates a new process in the underlying operating system to execute command asynchronously. See also system and process from racket/system.

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:

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.

(subprocess-wait subproc)  void?
  subproc : subprocess?
Blocks until the process represented by subproc terminates. The subproc value also can be used with sync and sync/timeout.

(subprocess-status subproc)  
(or/c 'running
      exact-nonnegative-integer?)
  subproc : subprocess?
Returns 'running if the process represented by subproc is still running, or its exit code otherwise. The exit code is an exact integer, and 0 typically indicates success. If the process terminated due to a fault or signal, the exit code is non-zero.

(subprocess-kill subproc force?)  void?
  subproc : subprocess?
  force? : any/c
Terminates the subprocess represented by subproc if force? is true and if the process still running. If an error occurs during termination, the exn:fail exception is raised.

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.

(subprocess-pid subproce)  exact-nonnegative-integer?
  subproce : subprocess?
Returns the operating system’s numerical ID (if any) for the process represented by subproc, valid only as long as the process is running.

(subprocess? v)  boolean?
  v : any/c
Returns #t if v is a subprocess value, #f otherwise.

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

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

The bindings documented in this section are provided by the racket/system and racket libraries, but not racket/base.

(system command)  boolean?
  command : string?
Executes a Unix, Mac OS X, or Windows shell command synchronously (i.e., the call to system does not return until the subprocess has ended). The command argument is a string containing no nul characters. If the command succeeds, the return value is #t, #f otherwise.

(system* command arg ...)  boolean?
  command : path-string?
  arg : string?
(system* command exact arg)  boolean?
  command : path-string?
  exact : 'exact
  arg : string?
Like system, except that command is a filename that is executed directly (instead of through a shell command), and the args are the arguments. The executed file is passed the specified string arguments (which must contain no nul characters).

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

(system/exit-code command)  (integer-in 0 255)
  command : string?
Like system, except that the result is the exit code returned by the subprocess. A 0 result normally indicates success.

(system*/exit-code command arg ...)  (integer-in 0 255)
  command : path-string?
  arg : string?
(system*/exit-code command exact arg)  (integer-in 0 255)
  command : path-string?
  exact : 'exact
  arg : string?
Like system*, but returns the exit code like system/exit-code.

(process command)
  
(list input-port?
      output-port?
      exact-nonnegative-integer?
      input-port?
      ((or/c 'status 'wait 'interrupt 'kill) . -> . any))
  command : string?
Executes a shell command asynchronously. The result is a list of five values:

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

(process* command arg ...)  list?
  command : path-string?
  arg : string?
(process* command exact arg)  list?
  command : path-string?
  exact : 'exact
  arg : string?
Like process, except that command is a filename that is executed directly, and the args are the arguments. Under Windows, as for system*, the first arg can be replaced with 'exact.

(process/ports out in error-out command)  list?
  out : (or/c #f output-port?)
  in : (or/c #f input-port?)
  error-out : (or/c #f output-port?)
  command : string?
Like process, except that out is used for the process’s standard output, in is used for the process’s standard input, and error-out is used for the process’s standard error. 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 value in the returned list is #f.

(process*/ports out    
  in    
  error-out    
  command    
  arg ...)  list?
  out : (or/c #f output-port?)
  in : (or/c #f input-port?)
  error-out : (or/c #f output-port?)
  command : path-string?
  arg : string?
(process*/ports out    
  in    
  error-out    
  command    
  exact    
  arg)  list?
  out : (or/c #f output-port?)
  in : (or/c #f input-port?)
  error-out : (or/c #f output-port?)
  command : path-string?
  exact : 'exact
  arg : string?
Like process*, but with the port handling of process/ports.