32.6. Shell, Pipes and Printing
Prev | Chapter 32. Platform Specific Extensions | Next

## 32.6. Shell, Pipes and Printing

This section describes how CLISP can invoke external executables and communicate with the resulting processes.

### 32.6.1. Shell

Platform Dependent: UNIX platform only.
  `(`EXT:EXECUTE` `program` `arg1` `arg2` ...)` executes an external program. Its name is `program` (a full pathname). It is given the `STRING`s `arg1`, `arg2`, ... as arguments.
Platform Dependent: UNIX, Win32 platforms only.
  `(`EXT:SHELL` [`command`])` calls the operating system's shell, the value of the environment variable `SHELL` on UNIX and `COMSPEC` on Win32. `(`EXT:SHELL`)` calls the shell for interactive use. `(`EXT:SHELL` `command`)` calls the shell only for execution of the one given `command`.
Platform Dependent: UNIX, Win32 platforms only.

  The functions `EXT:RUN-SHELL-COMMAND` and `EXT:RUN-PROGRAM` are the general interface to `EXT:SHELL` and the above:

  `(`EXT:RUN-SHELL-COMMAND` `command` `&KEY` `:MAY-EXEC` `:INDIRECTP` `:INPUT` `:OUTPUT` `:IF-OUTPUT-EXISTS` `:WAIT`)` runs a shell command (including shell built-in commands, like DIR on Win32 and for/do/done on UNIX).

  `(`EXT:RUN-PROGRAM` `program` `&KEY` `:MAY-EXEC` `:INDIRECTP` `:ARGUMENTS` `:INPUT` `:OUTPUT` `:IF-OUTPUT-EXISTS` `:WAIT`)` runs an external program.

  `command`

    the shell command.

    Platform Dependent: UNIX platform only.
      The shell the command is passed to is the value of the environment variable `SHELL`, which normally is /bin/sh. The command should be a “simple command”; a “command list” should be enclosed in "{ ... ; }" (for /bin/sh) or "( ... )" (for `/bin/csh`).
  `program`
    the program. The directories listed in the environment variable `PATH` will be searched for it.
  `:ARGUMENTS`
    a list of arguments (`STRING`s) that are given to the program.
  `:INPUT`
    where the program's input is to come from: either `:TERMINAL` (`stdin`, the default) or `:STREAM` (a Lisp `STREAM` to be created) or a pathname designator (an input file) or `NIL` (no input at all).
  `:OUTPUT`
    where the program's output is to be sent to: either `:TERMINAL` (`stdout`, the default) or `:STREAM` (a Lisp `STREAM` to be created) or a pathname designator (an output file) or `NIL` (ignore the output).
  `:IF-OUTPUT-EXISTS`
    what to do if the `:OUTPUT` file already exists. The possible values are `:OVERWRITE`, `:APPEND`, `:ERROR`, with the same meaning as for `OPEN`. The default is `:OVERWRITE`.
  `:WAIT`
    whether to wait for program termination or not (this is useful when no i/o to the process is needed); the default is `T`, i.e., synchronous execution.
  `:MAY-EXEC`
    pass exec to the underlying shell (UNIX only).
  `:INDIRECTP`
    use a shell to run the command, e.g., `(`EXT:RUN-PROGRAM` "dir" :indirectp `T`)` will run the shell built-in command DIR. This argument defaults to `T` for `EXT:RUN-SHELL-COMMAND` and to `NIL` for `EXT:RUN-PROGRAM`. (Win32 only).

  If `:STREAM` was specified for `:INPUT` or `:OUTPUT`, a Lisp `STREAM` is returned. If `:STREAM` was specified for both `:INPUT` and `:OUTPUT`, three Lisp `STREAM`s are returned, as for the function `EXT:MAKE-PIPE-IO-STREAM`. Otherwise, the return value depends on the process termination status: if it ended normally (without signal, core-dump etc), its exit status is returned as an `INTEGER`, otherwise `NIL` is returned.

  This use of `EXT:RUN-PROGRAM` can cause deadlocks, see `EXT:MAKE-PIPE-IO-STREAM`.

### 32.6.2. Pipes

Platform Dependent: UNIX, Win32 platforms only.
  `(`EXT:MAKE-PIPE-INPUT-STREAM` `command` `&KEY` `:ELEMENT-TYPE` `:EXTERNAL-FORMAT` `:BUFFERED`)`
    returns an input `STREAM` that will supply the output from the execution of the given operating system command.
  `(`EXT:MAKE-PIPE-OUTPUT-STREAM` `command` `&KEY` `:ELEMENT-TYPE` `:EXTERNAL-FORMAT` `:BUFFERED`)`
    returns an output `STREAM` that will pass its output as input to the execution of the given operating system command.
  `(`EXT:MAKE-PIPE-IO-STREAM` `command` `&KEY` `:ELEMENT-TYPE` `:EXTERNAL-FORMAT` `:BUFFERED`)`

    returns three values. The primary value is a bidirectional `STREAM` that will simultaneously pass its output as input to the execution of the given operating system command and supply the output from this command as input. The second and third value are the input `STREAM` and the output `STREAM` that make up the bidirectional `STREAM`, respectively.

    ### Warning

    These three streams must be closed individually, see CLOSE-CONSTRUCTED-STREAM:ARGUMENT-STREAM-ONLY.

    ### Warning

    Improper use of this function can lead to deadlocks. Use it at your own risk!

    A deadlock occurs if the command and your Lisp program either both try to read from each other at the same time or both try to write to each other at the same time.

    To avoid deadlocks, it is recommended that you fix a protocol between the command and your program and avoid any hidden buffering: use `READ-CHAR`, `READ-CHAR-NO-HANG`, `LISTEN`, `SOCKET:SOCKET-STATUS` instead of `READ-LINE` and `READ` on the input side, and complete every output operation by a `FINISH-OUTPUT`. The same precautions must apply to the called command as well.

### 32.6.3. Printing

The macro `EXT:WITH-OUTPUT-TO-PRINTER`:

    (EXT:WITH-OUTPUT-TO-PRINTER (variable [:EXTERNAL-FORMAT])
      {declaration}*
      {form}*)

binds the variable `variable` to an output `STREAM` that sends its output to the printer.

| These notes document CLISP version 2.45 | Last modified: 2008-05-14

Enter your search termsSubmit search form
Webclisp.cons.orgclisp.podval.orgwww.lisp.org

Prev | Up | Next
32.5. Quickstarting delivery with CLISP | Home | 32.7. Operating System Environment