All Manuals > LispWorks User Guide and Reference Manual > 49 The SYSTEM Package

NextPrevUpTopContentsIndex

run-shell-command

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


LispWorks User Guide and Reference Manual - 13 Feb 2015

NextPrevUpTopContentsIndex