Running external programs
|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.
Class precedence list:
ext:process, standard-object, ext:instance, t.
A structure encapsulating information about external programs executed via ext:run-program.
|ext:process-pid object||[Generic Function]|
The process ID, which is an integer.
Return the current status of process. The result is one of :running, :stopped, :exited, :signaled.
Returns t if the process is still alive, nil otherwise.
|ext:process-input object||[Generic Function]|
Return the input stream if any, otherwise nil. An input stream is created if the :input argument to ext:run-program is :stream. The stream must be closed to reclaim resources.
|ext:process-output object||[Generic Function]|
Return the output stream if any, otherwise nil. An output stream is created if the :output argument to ext:run-program is :stream. The stream must be closed to reclaim resources.
|ext:process-error object||[Generic Function]|
Return the error output stream if any, otherwise nil. An error stream is created if the :error argument to ext:run-program is :stream. The stream must be closed to reclaim resources.
|ext:process-wait process &optional check-for-stopped||[Function]|
Wait for the process to quit running for some reason. Returns process. If check-for-stopped is true then also return if the process stops.
Warning: for linuxthreads, only the parent thread may reap a child, and not other threads of the process. Other threads may also wait on the process but a status change will not be recognised until the parent thread checks the status. The linux new posix thread library (nptl) does not have this linux problem.
|ext:process-kill process signal &optional whom||[Function]|
Send the signal to process. The signal should be a valid signal number or a keyword of the standard UNIX signal name. If whom is :pid then send the signal to the process, or if whom is :process-group then send the signal to the process's group. Return true upon success otherwise nil and an error number.
|ext:process-exit-code object||[Generic Function]|
For a process that has exited return the exit code or the termination signal.
|ext:process-core-dumped object||[Generic Function]|
Return true if the process has dumped a core.