2.11 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 :before-execve

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

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

:before-execve

This specifies a function to run in the child process before it becomes the program to run. This is useful for actions such as authenticating the child process without modifying the parent Lisp process.

 
• 2.11.1 Process Accessors