run-shell-command Function

Summary

Allows executables and DOS or Unix shell commands to be called from Lisp code.

Package

system

Signature

run-shell-command command &key input output error-output separate-streams wait if-input-does-not-exist if-output-exists if-error-output-exists show-window environment element-type save-exit-status external-format => result-or-stream, signal-number-or-error-stream, process

Arguments

Values

Description

The function run-shell-command allows executables and DOS or Unix shell commands to be called from Lisp code with redirection of the stdout, stdin and stderr to Lisp streams. It creates a subprocess which executes the command command.

The argument command is interpreted as by call-system. In the cases where a shell is run, the shell to use is determined by the environment variable SHELL, or defaults to /bin/csh or /bin/sh if that does not exist.

If wait is true, then run-shell-command executes command and does not return until the process has exited. In this case none of input, output or error-output may have the value :stream, and the single value result-or-stream is the exit status of the process that ran command. On non-Windows platforms, signal-number-or-error-stream is the integer signal number if the process was terminated by a signal, otherwise nil. signal-number-or-error-stream is always nil on Microsoft Windows.

If wait and save-exit-status are nil and none of input, output or error-output have the value :stream then run-shell-command executes command and returns a single value result-or-stream which is the process ID of the process running command.

If wait is nil and either of input or output have the value :stream then run-shell-command executes command and returns three values: result-or-stream is a Lisp stream which acts as the stdout of the process if output is :stream, and is the stdin of the process if input is :stream. signal-number-or-error-stream is a Lisp stream or nil, determined by the argument error-output as described below. process is the process ID of the process.

If wait and save-exit-status are nil and neither of input or output have the value :stream then the first return value, result-or-stream, is nil.

If wait is nil, save-exit-status is true and neither of input or output have the value :stream then the first return value, result-or-stream, is a dummy stream that can only be used with pipe-exit-status (see save-exit-status below).

If wait is nil and error-output has the value :stream then run-shell-command executes command and returns three values. result-or-stream is determined by the arguments input and output as described above. signal-number-or-error-stream is a Lisp stream which acts as the stderr of the process. process is the process ID of the process.

If wait is nil and error-output is not :stream then the second return value, signal-number-or-error-stream, is nil. If error-output is :output, then stderr goes to the same place as stdout.

Any streams returned in result-or-stream or signal-number-or-error-stream have element type element-type, which defaults to base-char if not supplied.

If input is a pathname or string, then open is called with :if-does-not-exist if-input-does-not-exist. The resulting file-stream acts as the stdin of the process.

If output is a pathname or string, then open is called with :if-exists if-output-exists. The resulting file-stream acts as the stdout of the process.

If error-output is a pathname or string, then open is called with :if-exists if-error-output-exists. The resulting file-stream acts as the stderr of the process.

This table describes the streams created, for each combination of stream arguments:

If any of input, output or error-output are streams, then they must be file-streams or socket-streams capable of acting as the stdin, stdout or stderr of the process.

environment should be an alist of strings naming environment variables and their values. The process runs in an environment inherited from the Lisp process, augmented by environment.

If save-exit-status is true then the system stores the exit status of the process, so that it can be recovered by calling pipe-exit-status on result-or-stream or signal-number-or-error-stream if either of these is a stream.

external-format is used as in the description of open-pipe.

separate-streams and show-window must be nil.

On non-Windows platforms, the command line arguments and environment variables are encoded as specfied in 27.14.1 Encoding of file names and strings in OS interface functions.

Examples

(multiple-value-bind (out err pid)
    (sys:run-shell-command "sh -c 'echo foo >&2; echo bar'"
                           :wait nil
                           :output :stream
                           :error-output :stream)
  (with-open-stream (out out)
    (with-open-stream (err err)
      (values (read-line out) (read-line err)))))
=> 
"bar", "foo"

See also

call-system
call-system-showing-output
open-pipe
pipe-exit-status