Running external programs in OpenMCL
Overview
OpenMCL provides primitives to run external Linux programs, to
select and connect Lisp streams to their input and output
sources, to (optionally) wait for their completion and to check
their execution and exit status.
All of the global symbols described below are exported from the
CCL package.
This implementation is modeled on - and uses some code from -
similar facilities in CMUCL.
Functional Reference
run-program [Function]
Syntax |
run-program program args &key (wait t) pty input
if-input-does-not-exist output (if-output-exists :error)
(error :output) (if-error-exists :error) status-hook |
Description
|
Runs the specified program in an external (Linux) process,
returning an object of type EXTERNAL-PROCESS if successful.
|
Arguments |
program
- A string or pathname which denotes an executable file.
The PATH environment variable is used
to find programs whose name doesn't contain a directory
component.
args
- A list of simple-strings
wait
- Indicates whether or not
run-program
should wait for the EXTERNAL-PROCESS to
complete or should return immediately.
pty
- This option is accepted but currently ignored; it's
intended to make it easier to run external programs
that need to interact with a terminal device.
input
- Selects the input source used by the
EXTERNAL-PROCESS . May be any of the following:
NIL
- Specifies that a null input stream (e.g.,
/dev/null ) should be used.
T
- Specifies that the
EXTERNAL-PROCESS
should use the input source with which OpenMCL
was invoked.
- A
string or pathname .
- Specifies that the
EXTERNAL-PROCESS
should receive its input from the named existing
file.
:STREAM
- Creates a Lisp stream opened for character output.
Any data written to this stream (accessible as the
EXTERNAL-PROCESS-INPUT-STREAM of the
EXTERNAL-PROCESS object) appears as
input to the external process.
- A
stream .
- Specifies that the lisp stream should provide
input tho the
EXTERNAL-PROCESS .
if-input-does-not-exist
- If the
input argument specifies the name
of an existing file, this argument is used as the
if-does-not-exist argument to OPEN
when that file is opened.
output
-
Specifies where standard output from the external
process should be sent. Analogous to
input
above.
if-output-exists
-
If
output is specified as a string
or pathname, this argument is used as the
if-exists argument to OPEN
when that file is opened.
error
- Specifies where error output from the external process
should be sent. In addition to the values allowed for
output , the keyword :OUTPUT
can be used to indicate that error output should be
sent where standard output goes.
if-error-exists
-
Analogous to
if-output-exists .
status-hook
-
A user-defined function of one argument (the
EXTERNAL-PROCESS structure.) This function
is called whenever OpenMCL detects a change in the
staus of the EXTERNAL-PROCESS .
|
signal-external-process [Function]
Syntax |
signal-external-process proc signal-number |
Description
|
Sends the specified "signal" to the specified external
process. (Typically, it would only be useful to
call this function f the EXTERNAL-PROCESS was
created with :WAIT NIL .
Returns T if successful; signals an error otherwise.
|
Arguments |
proc
- An
EXTERNAL-PROCESS , as returned by
RUN-PROGRAM .
signal
- A small integer.
|
external-process-id [Function]
Syntax |
external-process-id proc |
Description
|
Returns the process id assigned to the external
process by the operating system. This is typically a
positive, 16-bit number.
|
Arguments |
proc
- An
EXTERNAL-PROCESS , as returned by
RUN-PROGRAM .
|
external-process-input-stream [Function]
Syntax |
external-process-input-stream proc |
Description
|
Returns the stream created when the input
argument to run-program is specified as
:STREAM .
|
Arguments |
proc
- An
EXTERNAL-PROCESS , as returned by
RUN-PROGRAM .
|
external-process-output-stream [Function]
Syntax |
external-process-output-stream proc |
Description
|
Returns the stream created when the output
argument to run-program is specified as
:STREAM .
|
Arguments |
proc
- An
EXTERNAL-PROCESS , as returned by
RUN-PROGRAM .
|
external-process-error-stream [Function]
Syntax |
external-process-error-stream proc |
Description
|
Returns the stream created when the error
argument to run-program is specified as
:STREAM .
|
Arguments |
proc
- An
EXTERNAL-PROCESS , as returned by
RUN-PROGRAM .
|
external-process-status [Function]
Syntax |
external-process-status proc |
Description
|
Returns, as multiple values, a keyword denoting the
status of the external process (one of :running ,
:stopped ,signaled , or
:exited ), and the exit code or terminating
signal if the first value is other than running .
|
Arguments |
proc
- An
EXTERNAL-PROCESS , as returned by
RUN-PROGRAM .
|
Examples
;;; Capture the output of the "uname" program in a lisp string-stream
;;; and return the generated string (which will contain a trailing
;;; newline.)
(with-output-to-string (stream)
(run-program "uname" '("-r") :output stream))
;;; Write a string to *STANDARD-OUTPUT*, the hard way.
(run-program "cat" () :input (make-string-input-stream "hello")
:output t)
;;; Find out that "ls" doesn't expand wildcards.
(run-program "ls" '("*.lisp") :output t)
;;; Let the shell expand wildcards.
(run-program "sh" '("-c" "ls *.lisp") :output t)
Limitations and known bugs
-
OpenMCL and the external processs may get confused about
who owns which streams when
input
, output
,
or error
are specified as T
and
wait
is specified as NIL
.
-
External processes that need to talk to a terminal device
may not work properly; the environment (ILISP) under which
OpenMCL is run can affect this.
Last modified: Sun Sep 16 21:39:16 PDT 2001