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
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
A string, a list of strings, a simple-vector of strings, or
nil
.
nil
,
:stream
or a file designator. Default value
nil
.
nil
,
:stream
or a file designator. Default value
nil
.
nil
,
:stream,
:output
or a file designator. Default value
nil
.
A boolean. True value not currently supported.
A boolean, default value
t
.
:error
,
:create
or
nil
. Default value
:error
.
:error
,
:overwrite
,
:append
,
:supersede
or
nil
. Default value
:error
.
:error
,
:overwrite
,
:append
,
:supersede
or
nil
. Default value
:error
.
A boolean. True value not currently supported.
An alist of strings naming environment variables and values. Default value
nil
.
Default value
base-char
.
A boolean, default value
nil
.
The exit status of the process running command, or a process ID
A stream, or
nil
.
A stream, or
nil
.
A process ID.
The function
run-shell-command
allows 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 is
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
is
nil
and neither of
input
or
output
have the value
:stream
then the first return value,
stream
, is
nil
.
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:
If any of
input
,
output
or
error-output
are streams, then they must be
file-stream
s 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 enviroment 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 pid-exit-status.
Note:
run-shell-command
is implemented only for Unix/Linux/Mac OS X.
(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"