The external-program Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The external-program Reference Manual

This is the external-program Reference Manual, version 0.0.6, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:52:20 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

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:

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:

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


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

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

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 external-program.asd

Location

/home/quickbuilder/quicklisp/dists/quicklisp/software/external-program-20160825-git/external-program.asd

Systems

external-program (system)

Packages

external-program-system


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 external-program/external-program.lisp

Parent

external-program (system)

Location

external-program.lisp

Packages

external-program

Exported Definitions
Internal Definitions

*signal-mapping* (special variable)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 external-program/utilities.lisp

Dependency

external-program.lisp (file)

Parent

external-program (system)

Location

utilities.lisp

Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 external-program/sbcl.lisp

Dependency

utilities.lisp (file)

Parent

external-program (system)

Location

sbcl.lisp

Exported Definitions
Internal Definitions

convert-environment (function)


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 external-program-system

Source

/home/quickbuilder/quicklisp/dists/quicklisp/software/external-program-20160825-git/external-program.asd

Use List

Previous: , Up: Packages   [Contents][Index]

4.2 external-program

Source

external-program.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

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

Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *signal-mapping*
Package

external-program

Source

external-program.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

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)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   E   F   L  
Index Entry  Section

E
external-program.asd: The external-program<dot>asd file
external-program/external-program.lisp: The external-program/external-program<dot>lisp file
external-program/sbcl.lisp: The external-program/sbcl<dot>lisp file
external-program/utilities.lisp: The external-program/utilities<dot>lisp file

F
File, Lisp, external-program.asd: The external-program<dot>asd file
File, Lisp, external-program/external-program.lisp: The external-program/external-program<dot>lisp file
File, Lisp, external-program/sbcl.lisp: The external-program/sbcl<dot>lisp file
File, Lisp, external-program/utilities.lisp: The external-program/utilities<dot>lisp file

L
Lisp File, external-program.asd: The external-program<dot>asd file
Lisp File, external-program/external-program.lisp: The external-program/external-program<dot>lisp file
Lisp File, external-program/sbcl.lisp: The external-program/sbcl<dot>lisp file
Lisp File, external-program/utilities.lisp: The external-program/utilities<dot>lisp file

Jump to:   E   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   C   E   F   G   M   P   R   S  
Index Entry  Section

C
convert-environment: Internal functions

E
embed-environment: Internal functions

F
Function, convert-environment: Internal functions
Function, embed-environment: Internal functions
Function, make-shell-string: Internal functions
Function, reformat-environment: Internal functions
Function, rename-parameter: Internal functions
Function, stringify-args: Internal functions

G
Generic Function, process-error-stream: Exported generic functions
Generic Function, process-id: Exported generic functions
Generic Function, process-input-stream: Exported generic functions
Generic Function, process-output-stream: Exported generic functions
Generic Function, process-p: Exported generic functions
Generic Function, process-status: Exported generic functions
Generic Function, run: Exported generic functions
Generic Function, signal-process: Exported generic functions
Generic Function, start: Exported generic functions

M
make-shell-string: Internal functions
Method, process-error-stream: Exported generic functions
Method, process-id: Exported generic functions
Method, process-input-stream: Exported generic functions
Method, process-output-stream: Exported generic functions
Method, process-p: Exported generic functions
Method, process-status: Exported generic functions
Method, run: Exported generic functions
Method, run: Exported generic functions
Method, signal-process: Exported generic functions
Method, signal-process: Exported generic functions
Method, signal-process: Exported generic functions
Method, start: Exported generic functions
Method, start: Exported generic functions

P
process-error-stream: Exported generic functions
process-error-stream: Exported generic functions
process-id: Exported generic functions
process-id: Exported generic functions
process-input-stream: Exported generic functions
process-input-stream: Exported generic functions
process-output-stream: Exported generic functions
process-output-stream: Exported generic functions
process-p: Exported generic functions
process-p: Exported generic functions
process-status: Exported generic functions
process-status: Exported generic functions

R
reformat-environment: Internal functions
rename-parameter: Internal functions
run: Exported generic functions
run: Exported generic functions
run: Exported generic functions

S
signal-process: Exported generic functions
signal-process: Exported generic functions
signal-process: Exported generic functions
signal-process: Exported generic functions
start: Exported generic functions
start: Exported generic functions
start: Exported generic functions
stringify-args: Internal functions

Jump to:   C   E   F   G   M   P   R   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*signal-mapping*: Internal special variables

S
Special Variable, *signal-mapping*: Internal special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   E   P   S  
Index Entry  Section

E
external-program: The external-program system
external-program: The external-program package
external-program-system: The external-program-system package

P
Package, external-program: The external-program package
Package, external-program-system: The external-program-system package

S
System, external-program: The external-program system

Jump to:   E   P   S