Scieneer Common Lisp 1.3.9 online documentation

ext:run-program program args &key env wait pty input if-input-does-not-exist output if-output-exists error if-error-exists element-type external-format[Function]

Create a new process and run the unix program in the file specified by the the pathname program. If the program is a relative pathname then it is firstly resolved against file://path/ which is initialized from the UNIX environment PATH list, and this path list is searched. Otherwise, if the program path is absolute it is resolved against file://localhost/.

The args are the standard arguments that can be passed to a Unix program. For no arguments use nil which means just the name of the program is passed as arg 0. Either return nil or a process structure.

The keyword arguments have the following meanings:

:env
An a-list mapping environment variable names, as strings, to simple-string values.
:wait
If true, the default, then wait until the created process finishes. If nil then continue running Lisp until the program finishes.
:pty
Either t, nil, or a stream. Unless nil, the subprocess is established under a PTY. If :pty is a stream, all output to this pty is sent to this stream, otherwise the ext:process-pty slot is filled in with a stream connected to pty that can read output and write input.
:input
Either t, nil, a pathname, a stream, or :stream. If t then the standard input for the current process is inherited. If nil then /dev/null is used. If a pathname then the file specified is used. If a stream then all the input is read from that stream and sent to the subprocess. If :stream then the ext:process-input slot is filled in with a stream that sends its output to the process, and it is the responsibility of the caller to ensure that this stream is closed appropriately. Defaults to nil.
:if-input-does-not-exist (when :input is the name of a file)
Can be one of:
:error
Generate an error.
:create
Create an empty file.
nil (the default)
Return nil from run-program.
:output
Either t, nil, a pathname, a stream, or :stream. If t then the standard output for the current process is inherited. If nil then /dev/null is used. If a pathname then the file specified is used. If a stream then all the output from the process is written to this stream. If :stream then the ext:process-output slot is filled in with a stream that can be read to get the output, and it is the responsibility of the caller to ensure that this stream is closed appropriately. Defaults to nil.
:if-output-exists (when :output is the name of a file) -
Can be one of:
:error (the default)
Generates an error if the file already exists.
:supersede
Output from the program supersedes the file.
:append
Output from the program is appended to the file.
nil
run-program returns nil without doing anything.
:error and :if-error-exists
Same as :output and :if-output-exists, except that :error can also be specified as :output in which case all error output is routed to the same place as normal output.
:element-type
Indicates the element type to use when opening a stream. Only the character and '(unsigned-byte 8) types are supported.
:external-format
When a character stream is opened this is the external character format to use. The default value is :default for which the value of ext:*default-external-format* is used.

When the :pty, :input, :output, or :error argument is a stream, a new thread is created for each stream to read or write between the process and the stream. Operations on the stream will occur in the context of these threads.