32.7. Shell, Pipes and Printing

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

32.7.1. Shell
32.7.2. Pipes
32.7.3. Printing

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

32.7.1. Shell

Platform Dependent: UNIX platform only.

(EXT:EXECUTE program
       arg₁
       arg₂ ...)

executes an external program. Its name is program (a full pathname). It is given the STRINGs arg₁, arg₂, ... as arguments.

Platform Dependent: UNIX, Win32 platforms only.

(EXT:SHELL [command]) calls the operating system's shell.

(EXT:SHELL) calls the shell for interactive use.

(EXT:SHELL command) calls the shell only for execution of the one given command, which can be a complex expression:

(EXT:SHELL "for x in 1 2 3; do echo $x; done")
1
2
3
⇒ NIL

Platform Dependent: UNIX platform only.: EXT:EXECUTE is called on the value of the environment variable SHELL if used interactively; /bin/sh -c command if used non-interactively.
Platform Dependent: Win32 platform only.: CreateProcess is called on (OR command (EXT:GETENV COMSPEC))

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.
program: the program. The directories listed in the environment variable PATH will be searched for it.
:ARGUMENTS: a list of arguments (STRINGs) 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 STREAMs are returned, as for the function EXT:MAKE-PIPE-IO-STREAM. Otherwise, the return value depends on the process termination status: if it exited on a signal or a core-dump, the signal number is returned as a negative INTEGER, else, if it ended normally with 0 exit status, NIL is returned; otherwise, the status is returned as a positive INTEGER.

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

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

Prev	Up	Next
32.6. Quickstarting delivery with CLISP	Home	32.8. Operating System Environment