4.2 Running UNIX programs from Lisp

4.2.1 Keyword options

• :input
  • nil

  If the value of:input isnil, the standard input stream for the program is the standard input stream for Lisp, which is normally the terminal. This option is analogous to typing a simple command to the Shell with no input redirection. The default value for:input isnil.

  • a filename

  If the value of:input is a filename, the standard input stream for the program is a stream opened to the specified file. This option is analogous to using the input redirection symbol < with a Shell command. If the file does not exist, the value of the argument:if-input-does-not-exist determines the outcome, as follows:

  • If the value is:error, an error is signaled.

  • If the value is:create, an empty file to read from is created and is given the specified filename.

  • If the value isnil,run-program returnsnil without taking any action.

  • :stream

  If the value of:input is:stream, the standard input stream for the program is a newly created Lisp output stream that is returned as the first value ofrun-program. Anything written to that stream by Lisp is read by the program. When the stream is closed, the program reads an end-of-file indicator. If for some reason the program terminates, writing to that stream causes Lisp to signal an error.

  • a stream

  If the value of:input is a stream, the standard input stream for the program is that stream, which must be an input stream open to a file or to another process. The stream must not be a string stream, synonym stream, or another higher-level Lisp stream.

  The stream must have been created by a call to the Common Lisp function open, the function make-lisp-stream, or the functionrun-program. (Note that the Common Lisp macro with-open-file does an implicitopen; that is, ifwith-open-file is called, a stream is created.)

  To feed the output from one program to another program, make an input stream by callingrun-program with the:output argument set to the value:stream. Then callrun-program again and use the newly created stream as the:input argument.

  When a Lisp stream is passed to a program, that stream can no longer be written to or read from by Lisp. It is effectively closed.

• :output
  • nil

  If the value of:output isnil, the standard output stream of the program is the standard output stream of Lisp, which is normally the terminal. This option is analogous to typing a simple command to the Shell and specifying no output redirection. The default value for :output isnil.

  • a filename

  If the value of:output is a filename, the standard output stream of the program is a stream opened to the specified file. This option is analogous to using the output redirection symbols> and>> with a Shell command. If the file already exists, the value of the:if-output-exists argument determines the outcome, as follows:

  • If the value is:error or is omitted, an error is signaled.

  • If the value is:append, the standard output stream from the program is appended to the end of the file.

  • If the value is:overwrite or:supersede, the file is overwritten by the standard output stream from the program.

  • If the value isnil,run-program returnsnil without taking any other action.

  • :stream

  If the value of:output is:stream, the standard output stream of the program is a newly created Lisp input stream that is returned as the first value ofrun-program. Lisp can read from this stream to get the program's standard output stream.

  • a stream

  If the value of:output is an output stream, the standard output stream of the program is that stream. The same restrictions that apply to a stream specified as:input apply to one specified as:output. Once a Lisp stream is passed to a program, the stream can no longer be written to or read from by Lisp. It is effectively closed.

• :error-output

This keyword argument specifies where error output from the program is sent. Its possible values and their meanings are the same as those of the:output keyword argument, with the following exceptions:

• There is an additional value for the keyword argument,:output. If the value of:error-output is:output, error output is merged with the program's standard output stream.

• The action taken when a specified error output file already exists is determined by the value of the:if-error-output-exists argument, rather than by the value of the:if-output-exists argument.

• :wait

This keyword argument determines whether Lisp waits for the program to complete.

• If the value of:wait ist, Lisp does not begin running until the program has completed; this value is the default.

• If the value of:wait isnil, Lisp continues to run in parallel with the program.

• If the value of:wait ist and the value of:input,:output, or:error-output is:stream, an error is signaled. Waiting and having a stream open to a process can lead to deadlock; thus, these combinations are not permitted.

• :arguments

This keyword argument must be a list of strings that are the normal Shell arguments to the program.

• :if-input-does-not-exist

This keyword argument can have one of the following values:

• The value:error signals an error; this value is the default.

• The value:create creates an empty file.

• The valuenil returnsnil without doing anything if the file mentioned does not exist.

• :if-output-exists,:if-error-output-exists

These keyword arguments can have one of the following values:

• The value:error signals an error; this value is the default.

• The value:append appends output to the file.

• The values:overwrite and:supersede overwrite the file with the new output.

• The valuenil returnsnil without doing anything if the file mentioned already exists.

The value:supersede is supported for the purposes of backward compatibility.

Generated with Harlequin WebMaker