Table of Contents
OpenMCL provides primitives to run external Unix 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.
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
Runs the specified program in an external (Unix) process, returning an object of type EXTERNAL-PROCESS if successful.
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.
A list of simple-strings
Indicates whether or not run-program should wait for the EXTERNAL-PROCESS to complete or should return immediately.
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.
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 to the EXTERNAL-PROCESS.
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.
Specifies where standard output from the external process should be sent. Analogous to input above.
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.
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.
Analogous to if-output-exists.
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 proc signal-number
Sends the specified "signal" to the specified external process. (Typically, it would only be useful tocall this function if the EXTERNAL-PROCESS was created with :WAIT NIL. ) Returns T if successful; signals an error otherwise.
An EXTERNAL-PROCESS, as returned by RUN-PROGRAM.
A small integer.
external-process-id proc
Returns the process id assigned to the external process by the operating system. This is typically a positive, 16-bit number.
An EXTERNAL-PROCESS, as returned by RUN-PROGRAM.
external-process-output-stream proc
Returns the stream created when the output argument to run-program is specified as :STREAM.
An EXTERNAL-PROCESS, as returned by RUN-PROGRAM.
external-process-error-stream proc
Returns the stream created when the error argument to run-program is specified as :STREAM.
An EXTERNAL-PROCESS, as returned by RUN-PROGRAM.
external-process-status proc
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.
An EXTERNAL-PROCESS, as returned by RUN-PROGRAM.
;;; 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)
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.