The ECL manual

Juan Jose Garcia-Ripoll

Daniel Kochmański

1. About this book
2. What is ECL?
3. History
4. Copyright of ECL
5. Copyright of this manual
6. Installation
6.1. Supported platforms
6.2. Autoconf based configuration
6.3. Platform specific instructions
6.3.1. Microsoft compilers
6.3.2. OpenBSD and NetBSD
I. Standards
1. Overview
1.1. Reading this manual
1.1.1. Common Lisp users
1.1.2. C/C++ programmers
1.2. C Reference
1.2.1. One type for everything: cl_object
1.2.2. Naming conventions
1.2.3. Only in Common Lisp
2. Evaluation and compilation
2.1. Declarations
2.2. C Reference
ecl_process_env — Per-thread environment
ANSI Dictionary — Common Lisp and C equivalence
3. Syntax
4. Types and classes
4.1. Built-in-class
4.2. C Reference
ANSI Dictionary — Common Lisp and C equivalence
5. Data and control flow
5.1. LET, FLET, LABELS and function lambda list ANSI addendum
5.2. Minimal compilation
5.3. Function types
5.4. C Calling conventions
5.5. C Reference
ecl_bds_bind — Bind a special variable
ecl_bds_unwind — Undo one variable binding
ecl_setq — C equivalent of setq
ecl_symbol_value — C equivalent of symbol-value
ecl_va_arg — Accepting a variable number of arguments
ecl_nth_value, ecl_nvalues — Accessing output values
ecl_return0, ecl_return1, ... — Returning multiple values
ECL_BLOCK_BEGIN — C macro for block
ECL_CATCH_BEGIN — C macro for catch
ECL_UNWIND_PROTECT_BEGIN — C macro for unwind-protect
ANSI Dictionary — Common Lisp and C equivalence
6. Iteration
7. Objects
7.1. C Reference
ANSI Dictionary — Common Lisp and C equivalence
8. Structures
8.1. C Reference
ANSI Dictionary — Common Lisp and C equivalence
9. Conditions
9.1. C Reference
ECL_HANDLER_CASE — C macro for handler-case
ECL_RESTART_CASE — C macro for restart-case
Conditions C dictionary — Common Lisp and C equivalence
10. Symbols
10.1. C Reference
ecl_make_keyword — Find a lisp keyword
ecl_make_symbol — Find a lisp symbol
ANSI Dictionary — Common Lisp and C equivalence
11. Packages
11.1. C Reference
ANSI Dictionary — Common Lisp and C equivalence
12. Numbers
12.1. Numeric types
12.2. Random-States
12.3. C Reference
Number C types — Numeric C types understood by ECL
Number constructors — Creating Lisp types from C numbers
Number accessors — Unchecked conversion from Lisp types to C numbers
Number coercion — Checked conversion from Lisp types to C numbers
Numbers C dictionary — Common Lisp and C equivalence
13. Characters
13.1. Unicode vs. POSIX locale
13.1.1. Character types
13.1.2. Character names
13.2. #\Newline characters
13.3. C Reference
C types — C character types
Constructors — Creating and extracting characters from Lisp objects
Predicates — C predicates for Lisp characters
Character case — C functions related to the character case
ANSI Dictionary — Common Lisp and C equivalence
14. Conses
14.1. C Reference
ANSI Dictionary — Common Lisp and C equivalence
15. Arrays
15.1. Array limits
15.2. Specializations
15.3. C Reference
Types and constants — C types, limits and enumerations
ecl_aet_to_symbol, ecl_symbol_to_aet — To and from element types
Constructors — Creating arrays and vectors
Accessors — Reading and writing array elements
Array properties — Array size, fill pointer, etc
ANSI Dictionary — Common Lisp and C equivalence
16. Strings
16.1. String types & Unicode
16.2. C Reference
Base string constructors — Building strings for C data
String accessors — Reading and writing characters into a string
Strings C dictionary — Common Lisp and C equivalence
17. Sequences
17.1. C Reference
Sequences C dictionary — Common Lisp and C equivalence
18. Hash tables
18.1. C Reference
Hash tables C dictionary — Common Lisp and C equivalence
19. Filenames
19.1. Syntax
19.2. Wild pathnames and matching
19.3. C Reference
Filenames C dictionary — Common Lisp and C equivalence
20. Files
20.1. Dictionary
20.2. C Reference
Files C dictionary — Common Lisp and C equivalence
21. Streams
21.1. ANSI Streams
21.1.1. Supported types
21.1.2. Element types
21.1.3. External formats
21.2. C Reference
Streams C dictionary — Common Lisp and C equivalence
22. Printer
22.1. C Reference
ANSI Dictionary — Common Lisp and C equivalence
23. Reader
23.1. C Reference
ANSI Dictionary — Common Lisp and C equivalence
24. System Construction
24.1. C Reference
ANSI Dictionary — Common Lisp and C equivalence
25. Environment
25.1. Dictionary
disassemble — Display the assembly code of a function
trace — Follow execution of functions
25.2. C Reference
ANSI Dictionary — Common Lisp and C equivalence
II. Extensions and Libraries
1. System building
1.1. Introduction
1.2. System definition files
1.3. Practical examples
1.4. ASDF Reference
asdf:make-build — Block-build an ASDF system definition
asdf:load-bundle-op — Compile and load one ore more libraries using unified FASL
2. Operating System Interface
2.1. Processes
2.2. Command line arguments
2.3. OS Reference
3. Foreign Function Interface
3.1. What is a FFI?
3.2. Two kinds of FFI
3.3. Foreign objects
3.4. Higher level interfaces
3.4.1. UFFI example
3.4.2. CFFI example
3.4.3. Low level example
3.5. FFI Reference
ffi:clines — Insert C declarations and definitions
ffi:c-inline — Inline C code in a lisp form.
4. Multithreading
4.1. Tasks, threads or processes
4.2. Multithreading Reference
mp:all-processes — Return the list of active processes.
mp:exit-process — Exit the task from which it is invoked.
mp:holding-lock-p — Determine whether current process holds the lock.
mp:interrupt-process — Interrupt a task.
mp:get-lock — Try to obtain a lock.
mp:giveup-lock — Release a lock we have obtained before.
mp:make-lock — Create a new lock.
mp:make-process — Create a new thread.
mp:process-active-p — Determine whether a task is running.
mp:process-enable — Start up a task which was not running.
mp:process-kill — Try to stop a running task.
mp:process-name — Return the name of a task.
mp:process-preset — Associate a function to a process.
mp:process-run-function — Create a task and execute a function in it.
mp:recursive-lock-p — Determine whether lock is recursive or not.
mp:with-lock — Synchronize a piece of code between different tasks.
5. Memory Management
5.1. Introduction
5.2. Boehm-Weiser garbage collector
5.3. Memory limits
5.4. Memory Conditions
5.5. Finalization
5.6. Memory Management Reference
ext:stack-overflow — Stack overflow condition.
ext:storage-exhausted — Memory overflow condition.
ext:get-finalizer — Return finalizer associated to an object.
ext:get-limit — Query a memory or stack limit.
ext:set-finalizer — Associate a finalizer to an object.
ext:set-limit — Set a memory or stack limit.
6. Meta-Object Protocol (MOP)
6.1. Introduction
6.2. Classes
6.3. Slots
6.4. Generic functions and methods
6.5. Sealed slots and classes
7. Signals and interrupts
7.1. Problems associated to signals
7.2. Kinds of signals
7.2.1. Synchronous signals
7.2.2. Asynchronous signals
7.3. Signals and interrupts in ECL
7.3.1. Handling of asynchronous signals
7.3.2. Handling of synchronous signals
7.4. Considerations when embedding ECL
7.5. Signals Reference
ext:with-interrupts — Execute code with interrupts optionally enabled.
ext:without-interrupts — Execute code without being interrupted.
8. Embedding ECL
8.1. Introduction
8.2. Embedding Reference
CL_CATCH_ALL — Create a protected region.
CL_UNWIND_PROTECT — Create a protected region.
cl_boot — Setup the lisp environment.
cl_shutdown — Close the lisp environment.
ecl_set_option — Set a boot option.
ecl_get_option — Read the value of a boot option.
ecl_clear_interrupts — Clear all pending signals and exceptions.
ecl_disable_interrupts — Postpone handling of signals and exceptions.
ecl_enable_interrupts — Activate handling of signals and exceptions.
III. Internals
1. Building programs
1.1. What can ECL do?
1.2. Compiling files
1.3. Building standalone executables
1.4. Building libraries
1.5. File names
1.6. Compiler examples
1.6.1. The hello.lisp file
1.6.2. Example of loadable object file
1.6.3. Example of standalone program
1.6.4. Combining files into a larger FASL
2. Manipulating Lisp objects
2.1. Objects representation
2.2. Constructing objects
2.3. Integers
2.4. Characters
2.5. Arrays
2.6. Strings
2.7. Bitvectors
2.8. Streams
2.9. Structures
2.10. Instances
2.11. Bytecodes
3. The interpreter
3.1. ECL stacks
3.2. Procedure Call Conventions
3.3. The lexical environment
3.4. The interpreter stack
4. The compiler
4.1. The compiler translates to C
4.2. The compiler mimics human C programmer
4.3. Implementation of Compiled Closures
4.4. Use of Declarations to Improve Efficiency
4.5. Inspecting generated C code
5. Porting ECL
IV. UFFI Reference
I. Primitive Types
def-constant — Binds a symbol to a constant.
def-foreign-type — Defines a new foreign type.
null-char-p — Tests a character for NULL value.
II. Aggregate Types
def-enum — Defines a C enumeration.
def-struct — Defines a C structure.
get-slot-value — Retrieves a value from a slot of a structure.
get-slot-pointer — Retrieves a pointer from a slot of a structure.
def-array-pointer — Defines a pointer to a array of type.
deref-array — Deference an array.
def-union — Defines a foreign union type.
III. Objects
allocate-foreign-object — Allocates an instance of a foreign object.
free-foreign-object — Frees memory that was allocated for a foreign boject.
with-foreign-object — Wraps the allocation of a foreign object around a body of code.
size-of-foreign-type — Returns the number of data bytes used by a foreign object type.
pointer-address — Returns the address of a pointer.
deref-pointer — Deferences a pointer.
ensure-char-character — Ensures that a dereferenced :char pointer is a character.
ensure-char-integer — Ensures that a dereferenced :char pointer is an integer.
make-null-pointer — Create a NULL pointer.
null-pointer-p — Tests a pointer for NULL value.
+null-cstring-pointer+ — A constant NULL cstring pointer.
with-cast-pointer — Wraps a body of code with a pointer cast to a new type.
def-foreign-var — Defines a symbol macro to access a variable in foreign code
IV. Strings
convert-from-cstring — Converts a cstring to a Lisp string.
convert-to-cstring — Converts a Lisp string to a cstring.
free-cstring — Free memory used by cstring.
with-cstring — Binds a newly created cstring.
convert-from-foreign-string — Converts a foreign string into a Lisp string.
convert-to-foreign-string — Converts a Lisp string to a foreign string.
allocate-foreign-string — Allocates space for a foreign string.
V. Functions & Libraries
def-function — Declares a function.
load-foreign-library — Loads a foreign library.
find-foreign-library — Finds a foreign library file.
Common Lisp symbols
C/C++ index
List of Figures
List of Tables