The eazy-process Reference Manual

This is the eazy-process Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 16:20:31 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 eazy-process

Yet Another Portable Library for Process Handling / Subshell Invokation

Author

Masataro Asai

Contact

License

MIT

Long Description

In ‘run-program‘ interface in the popular
implementations, piping between subprocesses are hard. It requires either reading the entire output stream and packing the contents as a new string-input-stream, or using some other implementation-specific functions. Also, compatibility libraries e.g. trivial-shell or inferior-shell, often depend on these functions, implying the same problem. Iolib also has ‘run-program‘ that allows easy piping, but it is restricted to 3 fds: ‘input,output,error‘.

Eazy-process provides a clean, declarative and thin layer to the processes. It depends on the concept of ’everything is a file’ and do not provide interfaces to streams.

Version

0.1

Dependencies
  • iterate (system).
  • alexandria (system).
  • cffi (system).
  • trivia (system).
  • trivia.ppcre (system).
  • iolib/syscalls (system).
  • trivial-garbage (system).
  • cl-ppcre (system).
  • cl-rlimit (system).
Source

eazy-process.asd.

Child Components

3 Modules

Modules are listed depth-first from the system components tree.


3.1 eazy-process/src

Source

eazy-process.asd.

Parent Component

eazy-process (system).

Child Components

3.2 eazy-process/compat

Dependency

src (module).

Source

eazy-process.asd.

Parent Component

eazy-process (system).

Child Component

trivial-shell.lisp (file).


4 Files

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


4.1 Lisp


4.1.1 eazy-process/eazy-process.asd

Source

eazy-process.asd.

Parent Component

eazy-process (system).

ASDF Systems

eazy-process.

Packages

eazy-process-asd.


4.1.2 eazy-process/src/package.lisp

Source

eazy-process.asd.

Parent Component

src (module).

Packages

eazy-process.


4.1.3 eazy-process/src/mktempfifo.lisp

Dependency

package.lisp (file).

Source

eazy-process.asd.

Parent Component

src (module).

Internals

mktempfifo (function).


4.1.4 eazy-process/src/pipe.lisp

Dependency

mktempfifo.lisp (file).

Source

eazy-process.asd.

Parent Component

src (module).

Public Interface
Internals

4.1.5 eazy-process/src/environ.lisp

Dependency

pipe.lisp (file).

Source

eazy-process.asd.

Parent Component

src (module).

Public Interface

environment (function).


4.1.6 eazy-process/src/specials.lisp

Dependency

environ.lisp (file).

Source

eazy-process.asd.

Parent Component

src (module).

Public Interface
Internals

+max-rlimit-constant+ (special variable).


4.1.7 eazy-process/src/fdspec.lisp

Dependency

specials.lisp (file).

Source

eazy-process.asd.

Parent Component

src (module).

Internals

4.1.8 eazy-process/src/shell.lisp

Dependency

fdspec.lisp (file).

Source

eazy-process.asd.

Parent Component

src (module).

Public Interface

shell (function).

Internals

4.1.9 eazy-process/src/process.lisp

Dependency

shell.lisp (file).

Source

eazy-process.asd.

Parent Component

src (module).

Public Interface
Internals

4.1.10 eazy-process/src/macros.lisp

Dependency

process.lisp (file).

Source

eazy-process.asd.

Parent Component

src (module).

Public Interface

with-process (macro).


4.1.11 eazy-process/src/resources.lisp

Dependency

macros.lisp (file).

Source

eazy-process.asd.

Parent Component

src (module).

Public Interface

with-rlimit (macro).


4.1.12 eazy-process/compat/trivial-shell.lisp

Source

eazy-process.asd.

Parent Component

compat (module).

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 eazy-process-asd

Source

eazy-process.asd.

Use List
  • asdf/interface.
  • common-lisp.

5.2 eazy-process

Source

package.lisp.

Use List
  • alexandria.
  • cffi.
  • cl-rlimit.
  • common-lisp.
  • iterate.
  • trivia.level2.
  • trivia.ppcre.
Public Interface
Internals

6 Definitions

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


6.1 Public Interface


6.1.1 Special variables

Special Variable: *interpreter*

Command line string which is invoked in order to run the subshell. Default value is "sh -c". The value is then followed by the command specified in shell-command, e.g. ,
when command = ’ls -la’, the running command is "sh -c ’ls -la’".
It provides the ability to call the interpreters like perl/AWK easily.

The name/path of the interpreter must be separated by spaces from the options like ’-c’.
Do not use complex things like — LANG=C sh . The first word is always considered the pathname. If you want to do complicated stuff, then do it inside the interpreter.

The process is forked, then the child process calls execvp with the name of
the interpreter. (This is defined in function ‘eazy-process:shell’.) The
actual pathname of the intepreter can be resolved using PATH environment
variable.

Package

eazy-process.

Source

trivial-shell.lisp.

Special Variable: *rlimit-resources*

A vector of rlimit resource value, where the index suggests +rlimit-XXX+, which is an integer (usually below 16) This value does not affect the lisp process itself; The effect is applied to the child process only.
Rather than modifying this variable directly, use ‘with-rlimit’ instead.

Package

eazy-process.

Source

specials.lisp.

Special Variable: +fdspecs-default+
Package

eazy-process.

Source

specials.lisp.


6.1.2 Symbol macros

Symbol Macro: *bourne-compatible-shell*
Package

eazy-process.

Source

trivial-shell.lisp.


6.1.3 Macros

Macro: with-process ((process argv &optional fdspecs environment search) &body body)

Spawn a process, bind the process to PROCESS,
execute the body and finalize (= kill and wait w/ nohang) the process.
BODY works as an implicit progn, and the return value is that of the progn.

It does not synchronously wait the process. Therefore, it is the user’s
responsibility to inhibit the early termination of the process.
The aim of finalization is to release the resources of the process e.g. file descriptor and pipes.

Example:

(with-open-process (p ("sleep" "10"))
(print :waiting)
(wait p))

Package

eazy-process.

Source

macros.lisp.

Macro: with-rlimit (pairs &body body)

Append/overwrite the current rlimit resouce limitation. This does not affect the lisp process itself.
Only the spawned child process will be affected.

Package

eazy-process.

Source

resources.lisp.


6.1.4 Ordinary functions

Function: close-pipe (pipe)
Package

eazy-process.

Source

pipe.lisp.

Function: environment ()
Package

eazy-process.

Source

environ.lisp.

Function: fd (process n)

Returns the file descriptor of the lisp process.
The returned fd is connected to the n-th fd of the child process through a pipe. Example:

(fd P 1) ; –> 5

This means that the 5’th fd of the lisp process is connected to the 1st fd of the process P.

Package

eazy-process.

Source

process.lisp.

Function: fd-as-pathname (process fd)

Return the pathname for each file descriptor.
Lisp can read/write to each fd by opening this file.

Since the buffer size of file-stream is implementation-dependent, and the call to cl:read might cache a considerable amount of characters from the file, we are not able to ensure that the same file can be opened more than once.

Even if you just cl:open the file and just cl:read-char the stream,
it might read the entire characters of the file into the buffer as a side-effect. We just advise you not to open the file more than once.

Package

eazy-process.

Source

process.lisp.

Function: fds (process)

Returns an fresh array of fds available from lisp process.

Package

eazy-process.

Source

process.lisp.

Function: finalize-process (process &optional sig)

Waitpid the process. If the process is alive, kill it with SIG first, then with SIGKILL.

Package

eazy-process.

Source

process.lisp.

Function: pipe ()
Package

eazy-process.

Source

pipe.lisp.

Function: shell (argv &optional fdspecs environments search)

Asynchronously execute ‘argv’ using fork(2) and ‘execve’
family of system calls, returns a process structure object.

ARGV is a sequence of strings. Each string is converted to null-terminated
C strings char* ARGV and passed to execvp. The first element is also
passed to execvp as the pathname of the executable.

FDSPECS is a sequence specifying how the child process should handle its output.
For the documentation of fd-specifier see ‘+fdspecs-default+’.
Example: (:in :out :out) , (5 :out 8)

Each element in FDSPECS corresponds to each file descriptor of the child process.

When an i-th element of FDSPECS is a symbol, then a new pipe(2) is created for each i. The i-th fd of the child process p1 is associated with the correct end of the new pipe, the other end of the pipe is readable/writable from lisp from the process interface.
(see the documentation of class PROCESS.)

When an i-th element of FDSPECS is an integer j,
then it should be the lisp end of a pipe connected to some other child process p2.
(not the normal fd of the lisp process, like 0,1,2)
The i-th fd of p1 is connected to this pipe,
then p1 and p2 can exchange the data each other.
When this happens, lisp process should not read from this pipe
(or the data will not be sent to the destination of the pipe).
For that purpose, add a layer like ‘tee’.

When ENVIRONMENT is specified, it is passed to execve/execvpe.
It should be a list of strings ("NAME1=VALUE1" "NAME2=VALUE2")
or an alist (("NAME1" . "VALUE1") ...).
When SEARCH is t, it uses execvp/execvpe. (==executable is searched through PATH)

On error during system call in the parent process, iolib.syscalls:syscall-error is signalled. In the child process, the system call failure result in error status 203.
FIXME: this might not be good.

Package

eazy-process.

Source

shell.lisp.

Function: shell-command (command &key input result-type external-format verbose)

simple interface compatible to trivial-shell @ https://github.com/gwkkwg/trivial-shell.git.

returns (values output error-output exit-status).
The input is read from the :input key argument.

Additional functionality:

:external-format — specifies the decoding of the output.

Package

eazy-process.

Source

trivial-shell.lisp.

Function: wait (process &optional option)

option is one of :nohang, :untraced, :continued.
Returns a value of the following signature:

(list (boolean ifexited)
(integer exitstatus)
(boolean ifsignalled)
(integer termsig)
(boolean coredump)
(boolean ifstopped)
(integer stopsig)
(boolean ifcontinued)
(integer status)).

When the value is inappropriate as defined in man wait(2), some integer values may return NIL.
When :nohang is specified but no child has changed its state, then it returns NIL instead.
‘wait(0)’, i.e. wait for any children, is not available.

Package

eazy-process.

Source

process.lisp.


6.1.5 Generic functions

Generic Reader: pid (object)
Package

eazy-process.

Methods
Reader Method: pid ((process process))

automatically generated reader method

Source

process.lisp.

Target Slot

pid.


6.1.6 Standalone methods

Method: print-object ((p process) s)
Source

process.lisp.


6.1.7 Structures

Structure: pipe
Package

eazy-process.

Source

pipe.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: read
Package

common-lisp.

Type

fixnum

Initform

0

Readers

pipe-read.

Writers

(setf pipe-read).

Slot: write
Package

common-lisp.

Type

fixnum

Initform

1

Readers

pipe-write.

Writers

(setf pipe-write).


6.1.8 Classes

Class: process

A class representing a process.

Package

eazy-process.

Source

process.lisp.

Direct methods
Direct slots
Slot: pid
Package

none (uninterned).

Initargs

:pid

Readers

pid.

Writers

This slot is read-only.

Slot: fds
Package

none (uninterned).

Initargs

:fds

Readers

%fds.

Writers

This slot is read-only.


6.2 Internals


6.2.1 Special variables

Special Variable: +max-rlimit-constant+
Package

eazy-process.

Source

specials.lisp.


6.2.2 Macros

Macro: with-retry-open-file ((tag &key max) args &body body)
Package

eazy-process.

Source

trivial-shell.lisp.


6.2.3 Ordinary functions

Function: %close-fd-safely (fd)
Package

eazy-process.

Source

process.lisp.

Function: %exec (argv env search)
Package

eazy-process.

Source

shell.lisp.

Function: %execv (argv)
Package

eazy-process.

Source

shell.lisp.

Function: %execvp (argv)
Package

eazy-process.

Source

shell.lisp.

Function: %finalize-process (pid sig fds)

True finalizer of a process object. However,
This function should not contain reference to the process itself because it prevents process object from GC-ing.

Package

eazy-process.

Source

process.lisp.

Function: %in-child (fdspecs argv environments search)

if the child process died of errno, the exit value is that value

Package

eazy-process.

Source

shell.lisp.

Function: %in-parent (fdspecs pid)
Package

eazy-process.

Source

shell.lisp.

Function: %make-process (pid fds)
Package

eazy-process.

Source

process.lisp.

Function: %open (path &key direction if-exists if-does-not-exist)

ANSI CL standard:

if-does-not-exist—one of :error, :create, or nil.
The default is
:error if direction is :input or if-exists is :overwrite or :append
:create if direction is :output or :io, and if-exists is neither :overwrite nor :append; or nil when direction is :probe.

Package

eazy-process.

Source

fdspec.lisp.

Function: %pipe (pipe &key direction)
Package

eazy-process.

Source

fdspec.lisp.

Function: %setenv (pair)
Package

eazy-process.

Source

shell.lisp.

Function: canonicalize-fdspec (fdspec &optional fd)

Take an fd-specifier and return a cons of (parent-fn . child-fn) where both parent-fn and child-fn are closures of 1 arg, the fd on the child end. Each function runs a job that should be done in the context of parent/child process.

if FD is specified and the direction is not specified, use the default direction of that fd by default. For FD > 2, there is no default direction and it signals an error.

Parent-fn should return the fd of the parent-end.

Package

eazy-process.

Source

fdspec.lisp.

Function: check-alive (process)
Package

eazy-process.

Source

trivial-shell.lisp.

Function: close-fd (fd)
Package

eazy-process.

Source

trivial-shell.lisp.

Function: copy-pipe (instance)
Package

eazy-process.

Source

pipe.lisp.

Function: dclose (old new)

Duplicate the old fd, set it to the new fd, then close the old fd

Package

eazy-process.

Source

fdspec.lisp.

Function: io-loop-string (p in s0 s1 s2)
Package

eazy-process.

Source

trivial-shell.lisp.

Function: make-c-char* (list-of-string)
Package

eazy-process.

Source

shell.lisp.

Function: make-pipe (&key read write)
Package

eazy-process.

Source

pipe.lisp.

Function: mktempfifo ()
Package

eazy-process.

Source

mktempfifo.lisp.

Function: pipe-p (object)
Package

eazy-process.

Source

pipe.lisp.

Reader: pipe-read (instance)
Writer: (setf pipe-read) (instance)
Package

eazy-process.

Source

pipe.lisp.

Target Slot

read.

Reader: pipe-write (instance)
Writer: (setf pipe-write) (instance)
Package

eazy-process.

Source

pipe.lisp.

Target Slot

write.

Function: try-read-write-char (sin sout fd)
Package

eazy-process.

Source

trivial-shell.lisp.


6.2.4 Generic functions

Generic Reader: %fds (object)
Package

eazy-process.

Methods
Reader Method: %fds ((process process))

automatically generated reader method

Source

process.lisp.

Target Slot

fds.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %   (  
C   D   E   F   G   I   M   P   S   T   W  
Index Entry  Section

%
%close-fd-safely: Private ordinary functions
%exec: Private ordinary functions
%execv: Private ordinary functions
%execvp: Private ordinary functions
%fds: Private generic functions
%fds: Private generic functions
%finalize-process: Private ordinary functions
%in-child: Private ordinary functions
%in-parent: Private ordinary functions
%make-process: Private ordinary functions
%open: Private ordinary functions
%pipe: Private ordinary functions
%setenv: Private ordinary functions

(
(setf pipe-read): Private ordinary functions
(setf pipe-write): Private ordinary functions

C
canonicalize-fdspec: Private ordinary functions
check-alive: Private ordinary functions
close-fd: Private ordinary functions
close-pipe: Public ordinary functions
copy-pipe: Private ordinary functions

D
dclose: Private ordinary functions

E
environment: Public ordinary functions

F
fd: Public ordinary functions
fd-as-pathname: Public ordinary functions
fds: Public ordinary functions
finalize-process: Public ordinary functions
Function, %close-fd-safely: Private ordinary functions
Function, %exec: Private ordinary functions
Function, %execv: Private ordinary functions
Function, %execvp: Private ordinary functions
Function, %finalize-process: Private ordinary functions
Function, %in-child: Private ordinary functions
Function, %in-parent: Private ordinary functions
Function, %make-process: Private ordinary functions
Function, %open: Private ordinary functions
Function, %pipe: Private ordinary functions
Function, %setenv: Private ordinary functions
Function, (setf pipe-read): Private ordinary functions
Function, (setf pipe-write): Private ordinary functions
Function, canonicalize-fdspec: Private ordinary functions
Function, check-alive: Private ordinary functions
Function, close-fd: Private ordinary functions
Function, close-pipe: Public ordinary functions
Function, copy-pipe: Private ordinary functions
Function, dclose: Private ordinary functions
Function, environment: Public ordinary functions
Function, fd: Public ordinary functions
Function, fd-as-pathname: Public ordinary functions
Function, fds: Public ordinary functions
Function, finalize-process: Public ordinary functions
Function, io-loop-string: Private ordinary functions
Function, make-c-char*: Private ordinary functions
Function, make-pipe: Private ordinary functions
Function, mktempfifo: Private ordinary functions
Function, pipe: Public ordinary functions
Function, pipe-p: Private ordinary functions
Function, pipe-read: Private ordinary functions
Function, pipe-write: Private ordinary functions
Function, shell: Public ordinary functions
Function, shell-command: Public ordinary functions
Function, try-read-write-char: Private ordinary functions
Function, wait: Public ordinary functions

G
Generic Function, %fds: Private generic functions
Generic Function, pid: Public generic functions

I
io-loop-string: Private ordinary functions

M
Macro, with-process: Public macros
Macro, with-retry-open-file: Private macros
Macro, with-rlimit: Public macros
make-c-char*: Private ordinary functions
make-pipe: Private ordinary functions
Method, %fds: Private generic functions
Method, pid: Public generic functions
Method, print-object: Public standalone methods
mktempfifo: Private ordinary functions

P
pid: Public generic functions
pid: Public generic functions
pipe: Public ordinary functions
pipe-p: Private ordinary functions
pipe-read: Private ordinary functions
pipe-write: Private ordinary functions
print-object: Public standalone methods

S
shell: Public ordinary functions
shell-command: Public ordinary functions

T
try-read-write-char: Private ordinary functions

W
wait: Public ordinary functions
with-process: Public macros
with-retry-open-file: Private macros
with-rlimit: Public macros


A.4 Data types

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

C
Class, process: Public classes
compat: The eazy-process/compat module

E
eazy-process: The eazy-process system
eazy-process: The eazy-process package
eazy-process-asd: The eazy-process-asd package
eazy-process.asd: The eazy-process/eazy-process․asd file
environ.lisp: The eazy-process/src/environ․lisp file

F
fdspec.lisp: The eazy-process/src/fdspec․lisp file
File, eazy-process.asd: The eazy-process/eazy-process․asd file
File, environ.lisp: The eazy-process/src/environ․lisp file
File, fdspec.lisp: The eazy-process/src/fdspec․lisp file
File, macros.lisp: The eazy-process/src/macros․lisp file
File, mktempfifo.lisp: The eazy-process/src/mktempfifo․lisp file
File, package.lisp: The eazy-process/src/package․lisp file
File, pipe.lisp: The eazy-process/src/pipe․lisp file
File, process.lisp: The eazy-process/src/process․lisp file
File, resources.lisp: The eazy-process/src/resources․lisp file
File, shell.lisp: The eazy-process/src/shell․lisp file
File, specials.lisp: The eazy-process/src/specials․lisp file
File, trivial-shell.lisp: The eazy-process/compat/trivial-shell․lisp file

M
macros.lisp: The eazy-process/src/macros․lisp file
mktempfifo.lisp: The eazy-process/src/mktempfifo․lisp file
Module, compat: The eazy-process/compat module
Module, src: The eazy-process/src module

P
Package, eazy-process: The eazy-process package
Package, eazy-process-asd: The eazy-process-asd package
package.lisp: The eazy-process/src/package․lisp file
pipe: Public structures
pipe.lisp: The eazy-process/src/pipe․lisp file
process: Public classes
process.lisp: The eazy-process/src/process․lisp file

R
resources.lisp: The eazy-process/src/resources․lisp file

S
shell.lisp: The eazy-process/src/shell․lisp file
specials.lisp: The eazy-process/src/specials․lisp file
src: The eazy-process/src module
Structure, pipe: Public structures
System, eazy-process: The eazy-process system

T
trivial-shell.lisp: The eazy-process/compat/trivial-shell․lisp file