|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:
- An a-list mapping environment variable names, as strings, to simple-string values.
- If true, the default, then wait until the created process finishes. If nil then continue running Lisp until the program finishes.
- 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.
- 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:
- Generate an error.
- Create an empty file.
- nil (the default)
- Return nil from run-program.
- 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.
- Output from the program supersedes the file.
- Output from the program is appended to the file.
- 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.
- Indicates the element type to use when opening a stream. Only the character and '(unsigned-byte 8) types are supported.
- 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.