Next: Saving a Core Image, Previous: Simple Streams, Up: Design Choices and Extensions [Contents][Index]
It is possible to run programs from Lisp by using the following function.
:env
:wait
:pty
:input
:if-input-does-not-exist
:output
:if-output-exists
:error
:if-error-exists
:status-hook
:external-format
:element-type
¶run-program
runs program in a child process.
Program should be a pathname or string naming the program.
Args should be a list of strings which this passes to
program as normal Unix parameters. For no arguments, specify
args as nil
. The value returned is either a process
structure or nil
. The process interface follows the description of
run-program
. If run-program
fails to fork the child
process, it returns nil
.
Except for sharing file descriptors as explained in keyword argument
descriptions, run-program
closes all file descriptors in the
child process before running the program. When you are done using a
process, call process-close
to reclaim system resources. You
only need to do this when you supply :stream
for one of
:input
, :output
, or :error
, or you supply :pty
non-nil
. You can call process-close
regardless of whether
you must to reclaim resources without penalty if you feel safer.
run-program
accepts the following keyword arguments:
:env
This is an a-list mapping keywords and
simple-strings. The default is ext:*environment-list*
. If
:env
is specified, run-program
uses the value given
and does not combine the environment passed to Lisp with the one
specified.
:wait
If non-nil
(the default), wait until the child
process terminates. If nil
, continue running Lisp while the
child process runs.
:pty
This should be one of t
, nil
, or a stream. If
specified non-nil
, the subprocess executes under a Unix PTY.
If specified as a stream, the system collects all output to this
pty and writes it to this stream. If specified as t
, the
process-pty
slot contains a stream from which you can read
the program’s output and to which you can write input for the
program. The default is nil
.
:input
This specifies how the program gets its input.
If specified as a string, it is the name of a file that contains
input for the child process. run-program
opens the file as
standard input. If specified as nil
(the default), then
standard input is the file /dev/null. If specified as
t
, the program uses the current standard input. This may
cause some confusion if :wait
is nil
since two processes
may use the terminal at the same time. If specified as
:stream
, then the process-input
slot contains an
output stream. Anything written to this stream goes to the
program as input. :input
may also be an input stream that
already contains all the input for the process. In this case
run-program
reads all the input from this stream before
returning, so this cannot be used to interact with the process.
If :input
is a string stream, it is up to the caller to call
string-encode
or other function to convert the string to
the appropriate encoding. In either case, the least significant 8
bits of the char-code
of each character
is
sent to the program.
:if-input-does-not-exist
This specifies what to do if
the input file does not exist. The following values are valid:
nil
(the default) causes run-program
to return nil
without doing anything; :create
creates the named file; and
:error
signals an error.
:output
This specifies what happens with the program’s
output. If specified as a pathname, it is the name of a file that
contains output the program writes to its standard output. If
specified as nil
(the default), all output goes to
/dev/null. If specified as t
, the program writes to
the Lisp process’s standard output. This may cause confusion if
:wait
is nil
since two processes may write to the terminal
at the same time. If specified as :stream
, then the
process-output
slot contains an input stream from which you
can read the program’s output. :output
can also be a stream
in which case all output from the process is written to this
stream. If :output
is a string-stream, each octet read from
the program is converted to a character using code-char
.
It is up to the caller to convert this using the appropriate
external format to create the desired encoded string.
:if-output-exists
This specifies what to do if the
output file already exists. The following values are valid:
nil
causes run-program
to return nil
without doing
anything; :error
(the default) signals an error;
:supersede
overwrites the current file; and :append
appends all output to the file.
:error
This is similar to :output
, except the file
becomes the program’s standard error. Additionally, :error
can be :output
in which case the program’s error output is
routed to the same place specified for :output
. If specified
as :stream
, the process-error
contains a stream
similar to the process-output
slot when specifying the
:output
argument.
:if-error-exists
This specifies what to do if the error
output file already exists. It accepts the same values as
:if-output-exists
.
:status-hook
This specifies a function to call whenever
the process changes status. This is especially useful when
specifying :wait
as nil
. The function takes the process as
a required argument.
:external-format
This specifies the external format to
use for streams created for run-program
. This does not
apply to string streams passed in as :input
or :output
parameters.
:element-type
If streams are created run-program
,
use this as the :element-type
for the stream. Defaults to
BASE-CHAR
.
Next: Saving a Core Image, Previous: Simple Streams, Up: Design Choices and Extensions [Contents][Index]