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:

: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.

ext:process

[Class]

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.

ext:process-status process

[Function]

Return the current status of process. The result is one of :running, :stopped, :exited, :signaled.

ext:process-alive-p process

[Function]

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.