4.2 Running UNIX programs from Lisp

4.2.3 Reference Pages

Syntax:run-program name&key :input:output:error-output:wait:arguments:if-input-does-not-exist:if-output-exists:if-error-output-exists

The functionrun-program provides the ability to run other UNIX programs from the Lisp environment.

The name argument is a pathname or an object that can be coerced to a pathname. It represents the name of the program to be run. If the pathname is a relative pathname, each directory in the environment variablePATH is searched for the filename that corresponds to name. If the pathname is an absolute pathname, that is, if the name begins with a slash
( / ), that file is used. The namestring of name is the first argument to the program.

If Lisp is running under UNIX System V, you cannot userun-program to run Shell scripts directly. Under Berkeley UNIX, the name argument can represent the name of a Shell script. The first line of the script must state what type of Shell is required. For example, if name denotes a Bourne Shell script, the first line of the script must read as follows:

#!/bin/sh

Four values are returned byrun-program:

• The first value is a stream. If the value of either the:input or the:output keyword argument is:stream, that stream communicates with the running process and is the first value returned. If neither keyword is:stream,nil is returned.

• If the:error-output keyword argument is:stream, the second value returned is the resulting input stream from which Lisp can read the program's error output; otherwise,nil is returned.

• If the:wait keyword argument is t, the third value is the exit status of the program that was run. Otherwise, the exit status isnil.

• If the program is running, the fourth value returned is the UNIX process id; otherwise,nil is returned.

Note: The functionrun-program must be able to set the file position for input and output streams; thus, you cannot use a pipe withrun-program. For example, the following code will fail:

(defun test-run-prog ()
  (let ((pipe (run-program "echo"
                             :arguments '("one" "two" "three")
                             :output :stream    ; Write to a pipe.
                             :wait nil)))
    (read-char pipe)
    (run-program "cat" :input pipe)           ; Get input from 
    ))                                     ; pipe and copy it.

;;; This example shows how to run a program and have Lisp wait for 
;;; it to complete.  The example assumes you have a program called 
;;; "banner" on /usr/games.
> (run-program "csh")
% /usr/games/banner test
  #####  ######   ####    #####
    #    #       #        #
    #    #####    ####     #
    #    #            #   #
    #    #       #    #   #
    #    ######   ####     #

% exit

% NIL
NIL
0
NIL

See Also:shell (in The User's Guide)

Generated with Harlequin WebMaker