Function

Package

system

Summary

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

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 => result

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 => stream, error-stream, process

Arguments

command

A string, a list of strings, a simple-vector of strings, or nil.

input

nil, :stream or a file designator. Default value nil.

output

nil, :stream or a file designator. Default value nil.

error-output

nil, :stream, :output or a file designator. Default value nil.

separate-streams

A boolean. True value not currently supported.

wait

A boolean, default value t.

if-input-does-not-exist

:error, :create or nil. Default value :error.

if-output-exists

:error, :overwrite, :append, :supersede or nil. Default value :error.

if-error-output-exists

:error, :overwrite, :append, :supersede or nil. Default value :error.

show-window

A boolean. True value not currently supported.

environment

An alist of strings naming environment variables and values. Default value nil.

element-type

Default value base-char.

save-exit-status

A boolean, default value nil.

Values

result

The exit status of the process running command, or a process ID

stream

A stream, or nil.

error-stream

A stream, or nil.

process

A process ID.

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 is the exit status of the process that ran command.

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 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: 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. error-stream is 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, 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, 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. stream is determined by the arguments input and output as described above. 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, error-stream, is nil. If error-output is :output, then stderr goes to the same place as stdout.

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:

The streams created by run-shell-command

Arguments	stream	error-stream
input is :stream output is :stream error-output is :stream	An I/O stream connected to stdin and stdout	An input stream connected to stderr
input is not :stream output is :stream error-output is :stream	An input stream connected to stdout	An input stream connected to stderr
input is :stream output is not :stream error-output is :stream	An output stream connected to stdin	An input stream connected to stderr
input is not :stream output is not :stream error-output is :stream	nil	An input stream connected to stderr
input is :stream output is :stream error-output is :output	An I/O stream connected to stdin, stdout and stderr	nil
input is not :stream output is :stream error-output is :output	An input stream connected to stdout and stderr	nil
input is :stream output is not :stream error-output is :output	An output stream connected to stdin	nil
input is not :stream output is not :stream error-output is :output	nil	nil
input is :stream output is :stream error-output is not :stream or :output	An I/O stream connected to stdin and stdout	nil
input is not :stream output is :stream error-output is not :stream or :output	An input stream connected to stdout	nil
input is :stream output is not :stream error-output is not :stream or :output	An output stream connected to stdin	nil
input is not :stream output is not :stream error-output is not :stream or :output	nil	nil

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 stream or error-stream if either of these is a stream.

Example

(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