Running external programs in OpenMCL


Table of Contents

Overview
Functional Reference
run-program [Function]
external-process-output-stream [Function]
external-process-error-stream [Function]
external-process-status [Function]
Examples
Limitations and known bugs

Overview

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.

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 (Unix) 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 to 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 tocall this function if 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.