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



Last modified: Sun Sep 16 21:39:16 PDT 2001