The external-program Reference Manual

Table of Contents

The external-program Reference Manual

This is the external-program Reference Manual, version 0.0.6, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Mar 25 18:02:40 2020 GMT+0.

1 Introduction

EXTERNAL-PROGRAM enables running programs outside the Lisp process. It is an attempt to make the RUN-PROGRAM functionality in implementations like SBCL and CCL as portable as possible without sacrificing much in the way of power.

Note: This library is available via Quicklisp.

Here are some of the differences:

• splits START (async) and RUN (sync) into two separate functions, rather than using a single function with a WAIT parameter that changes the function's specification;
• offers a REPLACE-ENVIRONMENT-P parameter that indicates whether provided env vars should build on or replace the current environment.

Read the API documention for details. It’s a bit spartan, but should explain a lot.

Not all functionality is available on all platforms. EXTERNAL-PROGRAM provides warnings and errors when these limitations are encountered. But I'll try my best to work around them.

There is currently at least some support for:

• Allegro (blocking only)
• Armed Bear (blocking only)
• CLisp
• Clozure CL (née OpenMCL)
• CMUCL
• ECL
• LispWorks
• SBCL

In addition to some implementations only providing blocking calls, some don’t use $PATH – the ones that don’t won’t find bareword commands, you’ll need to use

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 external-program

Author

Greg Pfeil <greg@technomadic.org>

License

LLGPL

Version

0.0.6

Dependency

trivial-features

Source

external-program.asd (file)

Components

• external-program.lisp (file)
• utilities.lisp (file)
• sbcl.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 external-program.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/external-program-20190307-git/external-program.asd

Systems

external-program (system)

Packages

external-program-system

3.1.2 external-program/external-program.lisp

Parent

external-program (system)

Location

external-program.lisp

Packages

external-program

Exported Definitions

• process-error-stream (generic function)
• process-id (generic function)
• process-input-stream (generic function)
• process-output-stream (generic function)
• process-p (generic function)
• process-status (generic function)
• run (generic function)
• run (method)
• signal-process (generic function)
• signal-process (method)
• start (generic function)
• start (method)

Internal Definitions

*signal-mapping* (special variable)

3.1.3 external-program/utilities.lisp

Dependency

external-program.lisp (file)

Parent

external-program (system)

Location

utilities.lisp

Internal Definitions

• embed-environment (function)
• make-shell-string (function)
• reformat-environment (function)
• rename-parameter (function)
• stringify-args (function)

3.1.4 external-program/sbcl.lisp

Dependency

utilities.lisp (file)

Parent

external-program (system)

Location

sbcl.lisp

Exported Definitions

• process-error-stream (method)
• process-id (method)
• process-input-stream (method)
• process-output-stream (method)
• process-p (method)
• process-status (method)
• run (method)
• signal-process (method)
• signal-process (method)
• start (method)

Internal Definitions

convert-environment (function)

4 Packages

Packages are listed by definition order.

4.1 external-program-system

Source

/home/quickref/quicklisp/dists/quicklisp/software/external-program-20190307-git/external-program.asd

Use List

• asdf/interface
• common-lisp

4.2 external-program

Source

external-program.lisp (file)

Use List

common-lisp

Exported Definitions

• process-error-stream (generic function)
• process-error-stream (method)
• process-id (generic function)
• process-id (method)
• process-input-stream (generic function)
• process-input-stream (method)
• process-output-stream (generic function)
• process-output-stream (method)
• process-p (generic function)
• process-p (method)
• process-status (generic function)
• process-status (method)
• run (generic function)
• run (method)
• run (method)
• signal-process (generic function)
• signal-process (method)
• signal-process (method)
• signal-process (method)
• start (generic function)
• start (method)
• start (method)

Internal Definitions

• *signal-mapping* (special variable)
• convert-environment (function)
• embed-environment (function)
• make-shell-string (function)
• reformat-environment (function)
• rename-parameter (function)
• stringify-args (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Generic functions

Generic Function: process-error-stream PROCESS

Returns the stream created when the error argument to ‘START‘ is specified as ‘:STREAM‘.

Package

external-program

Source

external-program.lisp (file)

Methods

Method: process-error-stream PROCESS

Source

sbcl.lisp (file)

Generic Function: process-id PROCESS

Returns the process id assigned to the external
process by the operating system. This is typically a positive, 16-bit number.

Package

external-program

Source

external-program.lisp (file)

Methods

Method: process-id PROCESS

Source

sbcl.lisp (file)

Generic Function: process-input-stream PROCESS

Returns the stream created when the input argument to ‘START‘ is specified as ‘:STREAM‘.

Package

external-program

Source

external-program.lisp (file)

Methods

Method: process-input-stream PROCESS

Source

sbcl.lisp (file)

Generic Function: process-output-stream PROCESS

Returns the stream created when the output argument to ‘START‘ is specified as ‘:STREAM‘.

Package

external-program

Source

external-program.lisp (file)

Methods

Method: process-output-stream PROCESS

Source

sbcl.lisp (file)

Generic Function: process-p PROCESS

‘T‘ if object is a process, ‘NIL‘ otherwise.

Package

external-program

Source

external-program.lisp (file)

Methods

Method: process-p PROCESS

Source

sbcl.lisp (file)

Generic Function: process-status PROCESS

Returns, as multiple values, a keyword denoting the
status of the external process (one of ‘:RUNNING‘, ‘:STOPPED‘, ‘:SIGNALED‘, or ‘:EXITED‘), and the exit code or terminating signal if the first value is other than ‘:RUNNING‘.

Package

external-program

Source

external-program.lisp (file)

Methods

Method: process-status PROCESS

Source

sbcl.lisp (file)

Generic Function: run PROGRAM ARGS &key INPUT IF-INPUT-DOES-NOT-EXIST OUTPUT IF-OUTPUT-EXISTS ERROR IF-ERROR-EXISTS ENVIRONMENT REPLACE-ENVIRONMENT-P &allow-other-keys

Runs the specified program similarly to ‘START‘,
however it blocks and returns the external process status once the
program exits.

‘:STREAM‘ is not a valid argument to ‘INPUT‘, ‘OUTPUT‘, or ‘ERROR‘ for this function.

Package

external-program

Source

external-program.lisp (file)

Methods

Method: run PROGRAM ARGS &rest REST &key ENVIRONMENT REPLACE-ENVIRONMENT-P &allow-other-keys

Source

sbcl.lisp (file)

Method: run (PROGRAM pathname) ARGS &rest REST

Generic Function: signal-process PROCESS SIGNAL

Sends the specified unix signal to the specified
external process. Signals an error if unsuccessful. The signal may be either an integer, or one of the keywords in ‘EXTERNAL-PROGRAM::*SIGNAL-MAPPING*‘.

Package

external-program

Source

external-program.lisp (file)

Methods

Method: signal-process PROCESS (SIGNAL integer)

Source

sbcl.lisp (file)

Method: signal-process PROCESS (SIGNAL symbol)

Source

sbcl.lisp (file)

Method: signal-process PROCESS SIGNAL

Generic Function: start PROGRAM ARGS &key INPUT IF-INPUT-DOES-NOT-EXIST OUTPUT IF-OUTPUT-EXISTS ERROR IF-ERROR-EXISTS ENVIRONMENT REPLACE-ENVIRONMENT-P STATUS-HOOK &allow-other-keys

Runs the specified program in an external (Unix) process,
returning a process object if successful.

‘INPUT‘, ‘OUTPUT‘, and ‘ERROR‘ all behave similarly, accepting one of
the following values:

* ‘NIL‘, specifying that a null stream (e.g., ‘/dev/null‘) should be used;
* ‘T‘, specifying that the ‘EXTERNAL-PROCESS‘ should use the source or destination with which the Lisp was invoked;
* a stream;
* a pathname designator, to redirect to/from a file;
* ‘:STREAM‘, which creates a new stream opened for character input or output (accessible via the ‘EXTERNAL-PROCESS-*-STREAM‘ functions);
or
* ‘:OUTPUT‘, (only available for ‘ERROR‘) which directs the error
output to the same destination as the standard output.

‘ENVIRONMENT‘ contains an alist mapping vars to values.

‘REPLACE-ENVIRONMENT-P‘ indicates whether the argument passed as ‘ENVIRONMENT‘ should replace or extend the current environment. The default is ‘NIL‘ (to extend the environment).

‘STATUS-HOOK‘ is a function the system calls whenever the status of
the process changes. The function takes the process as an argument.

Package

external-program

Source

external-program.lisp (file)

Methods

Method: start PROGRAM ARGS &rest REST &key ENVIRONMENT REPLACE-ENVIRONMENT-P &allow-other-keys

Source

sbcl.lisp (file)

Method: start (PROGRAM pathname) ARGS &rest REST

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *signal-mapping*

Package

external-program

Source

external-program.lisp (file)

5.2.2 Functions

Function: convert-environment REST ENVIRONMENT REPLACE-ENVIRONMENT-P

Package

external-program

Source

sbcl.lisp (file)

Function: embed-environment PROGRAM ARGS ENVIRONMENT REPLACE-ENVIRONMENT-P

Package

external-program

Source

utilities.lisp (file)

Function: make-shell-string PROGRAM ARGS ENVIRONMENT REPLACE-ENVIRONMENT-P

Package

external-program

Source

utilities.lisp (file)

Function: reformat-environment ENVIRONMENT

SBCL accepts vars as either ("FOO=meh" ...) or ((:foo . "meh") ...), but not (("FOO" . "meh") ...), so we build up the first kind (since the second kind is potentially lossy).

Package

external-program

Source

utilities.lisp (file)

Function: rename-parameter FROM-NAME TO-NAME REST

Package

external-program

Source

utilities.lisp (file)

Function: stringify-args ARGS

Package

external-program

Source

utilities.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types