---

2.13 Running Programs from Lisp ¶

It is possible to run programs from Lisp by using the following function.

Function: extensions:run-program program args &key :env :wait :pty :input :if-input-does-not-exist :output :if-output-exists :error :if-error-exists :status-hook :external-format :element-type ¶

run-program runs program in a child process. Program should be a pathname or string naming the program. Args should be a list of strings which this passes to program as normal Unix parameters. For no arguments, specify args as nil. The value returned is either a process structure or nil. The process interface follows the description of run-program. If run-program fails to fork the child process, it returns nil.

Except for sharing file descriptors as explained in keyword argument descriptions, run-program closes all file descriptors in the child process before running the program. When you are done using a process, call process-close to reclaim system resources. You only need to do this when you supply :stream for one of :input, :output, or :error, or you supply :pty non-nil. You can call process-close regardless of whether you must to reclaim resources without penalty if you feel safer.

run-program accepts the following keyword arguments:

:env

This is an a-list mapping keywords and simple-strings. The default is ext:*environment-list*. If :env is specified, run-program uses the value given and does not combine the environment passed to Lisp with the one specified.

:wait

If non-nil (the default), wait until the child process terminates. If nil, continue running Lisp while the child process runs.

:pty

This should be one of t, nil, or a stream. If specified non-nil, the subprocess executes under a Unix PTY. If specified as a stream, the system collects all output to this pty and writes it to this stream. If specified as t, the process-pty slot contains a stream from which you can read the program’s output and to which you can write input for the program. The default is nil.

:input

This specifies how the program gets its input. If specified as a string, it is the name of a file that contains input for the child process. run-program opens the file as standard input. If specified as nil (the default), then standard input is the file /dev/null. If specified as t, the program uses the current standard input. This may cause some confusion if :wait is nil since two processes may use the terminal at the same time. If specified as :stream, then the process-input slot contains an output stream. Anything written to this stream goes to the program as input. :input may also be an input stream that already contains all the input for the process. In this case run-program reads all the input from this stream before returning, so this cannot be used to interact with the process. If :input is a string stream, it is up to the caller to call string-encode or other function to convert the string to the appropriate encoding. In either case, the least significant 8 bits of the char-code of each character is sent to the program.

:if-input-does-not-exist

This specifies what to do if the input file does not exist. The following values are valid: nil (the default) causes run-program to return nil without doing anything; :create creates the named file; and :error signals an error.

:output

This specifies what happens with the program’s output. If specified as a pathname, it is the name of a file that contains output the program writes to its standard output. If specified as nil (the default), all output goes to /dev/null. If specified as t, the program writes to the Lisp process’s standard output. This may cause confusion if :wait is nil since two processes may write to the terminal at the same time. If specified as :stream, then the process-output slot contains an input stream from which you can read the program’s output. :output can also be a stream in which case all output from the process is written to this stream. If :output is a string-stream, each octet read from the program is converted to a character using code-char. It is up to the caller to convert this using the appropriate external format to create the desired encoded string.

:if-output-exists

This specifies what to do if the output file already exists. The following values are valid: nil causes run-program to return nil without doing anything; :error (the default) signals an error; :supersede overwrites the current file; and :append appends all output to the file.

:error

This is similar to :output, except the file becomes the program’s standard error. Additionally, :error can be :output in which case the program’s error output is routed to the same place specified for :output. If specified as :stream, the process-error contains a stream similar to the process-output slot when specifying the :output argument.

:if-error-exists

This specifies what to do if the error output file already exists. It accepts the same values as :if-output-exists.

:status-hook

This specifies a function to call whenever the process changes status. This is especially useful when specifying :wait as nil. The function takes the process as a required argument.

:external-format

This specifies the external format to use for streams created for run-program. This does not apply to string streams passed in as :input or :output parameters.

:element-type

If streams are created run-program, use this as the :element-type for the stream. Defaults to BASE-CHAR.

• Process Accessors