Although it's an open-source project, available free of charge under a liberal license, Clozure CL is also a fully-supported product of Clozure Associates. Clozure continues to extend, improve, and develop Clozure CL in response to customer and user needs, and offers full support and development services for Clozure CL.

Many extensions including: files mapped to Common Lisp vectors for fast file I/O; thread-local hash tables and streams to eliminate locking overhead; cons hashing support; and much more

Excellent debugging facilities. The names of all local variables are available in a backtrace.

Full native OS threads on all platforms. Threads are automatically distributed across multiple cores. The API includes support for shared memory, locking, and blocking for OS operations such as I/O.

Robust and stable. Customers report that their CPU-intensive, multi-threaded applications run for extended periods on Clozure CL without difficulty.

A fast, precise, compacting, generational garbage collector written in hand-optimized C. The sizes of the generations are fully configurable. Typically, a generation can be collected in a millisecond on modern systems.

On all supported platforms, Clozure CL can run as a command-line process, or as an inferior Emacs process using either SLIME or ILISP.

On Mac OS X, Clozure CL supports building GUI applications that use OS X's native Cocoa frameworks, and the OS X distributions include an IDE written with Cocoa, and distributed with complete sources.

Clozure CL compiles to native code and supports multithreading using native OS threads. It includes a foreign-function interface, and supports both Lisp code that calls external code, and external code that calls Lisp code. Clozure CL can create standalone executables on all supported platforms.

Some commands and source files may still refer to “OpenMCL” instead of Clozure CL.

Furthermore, the new name refers to Clozure CL's ancestry: in its early years, MCL was known as Coral Common Lisp, or “CCL”. For years the package that contains most of Clozure CL's implementation-specific symbols has been named “CCL”, an acronym that once stood for the name of the Lisp product. It seems fitting that “CCL” once again stands for the name of the product.

When it was forked from MCL in 1998, the new Lisp was named OpenMCL. Subsequently, Clozure renamed its Lisp to Clozure CL, partly because its ancestor MCL has been released as open source. Clozure thought it might be confusing for users if there were two independent open-source projects with such similar names. The new name also reflects Clozure CL's current status as the flagship product of Clozure Associates.

Clozure CL is a fast, mature, open source Common Lisp implementation that runs on Linux, Mac OS X, FreeBSD, and Windows. Clozure CL was forked from Macintosh Common Lisp (MCL) in 1998 and the development has been entirely separate since.

If you want to run Clozure CL as a double-clickable Macintosh application, you can do that. A version of Clozure CL is available from the Mac App Store if you would like to obtain it from there. Alternatively you can build the IDE yourself: please see Building the IDE . Currently, it's not possible to use the Mac App Store version of Clozure CL as a command-line program.

Finally, any arguments following the pseudo-argument -- are not processed, and are made available to Lisp as the value of *unprocessed-command-line-arguments* .

The --load and --eval options can each be provided multiple times. They're executed in the order specified on the command line, after the init file (if there is one) is loaded and before the toplevel read-eval-print loop is entered.

Specifies the image name for the kernel to load. Defaults to the kernel name with the suffix .image appended.

Execute in batch mode. End-of-file from *standard-input* causes Clozure CL to exit, as do attempts to enter a break loop.

Sets the size of the first thread's stack to n (see Thread Stack Sizes ).

Reserves n bytes for heap expansion. The default depends on the particular platform in use (see Heap space allocation ).

Suppresses printing of heralds and prompts when the --batch command line option is specified.

An expression is read (via read-from-string ) from the string form and evaluated. If form contains shell metacharacters, it may be necessary to escape or quote them to prevent the shell from interpreting them.

If this option is given, the init file is not loaded. This is useful if Clozure CL is being invoked by a shell script that should not be affected by whatever customizations a user might have in place.

Specifies the character encoding to use for *terminal-io* (see Character Encodings ). Specifically, the character-encoding-name string is uppercased and interned in the keyword package. If an encoding named by that keyword exists, *terminal-character-encoding-name* is set to the name of that encoding. The default is :utf-8 .

Prints the version of Clozure CL then exits. The version string is the same value that is returned by lisp-implementation-version .

Provides a definitive (if somewhat terse) summary of the command line options accepted by the Clozure CL implementation and then exits.

When using Clozure CL from the command line, the following options may be used to modify its behavior. The exact set of Clozure CL command-line arguments may vary per platform and may change over time. The definitive list of command line options may be retrieved by using the --help option.

To suppress the loading of this init-file, invoke Clozure CL with the --no-init (or -n ) option.

Because the init file is loaded the same way as normal Lisp code is, you can put anything you want in it. For example, you can change the working directory, and load code that you use frequently.

If you wish, you can compile your init file, and Clozure CL will load the compiled version if it is newer than the corresponding source file. In other words, Clozure CL loads your init file with (load "home:ccl-init") .

By default, Clozure CL will look for a file named ccl-init.lisp in your home directory, and load it upon startup. On Unix systems, it will also look for .ccl-init.lisp .

You may wish to install scripts/ccl64 with the name ccl if you use the 64-bit lisp more. If you want the 32-bit lisp to be available as well, you can install scripts/ccl as ccl32 . Note that there is nothing magical about these scripts. You should feel free to edit them as desired.

It can also be handy to run Clozure CL straight from a terminal prompt. In the scripts/ directory of the ccl directory, there are two files named ccl and ccl64 . Copy these files into /usr/local/bin or some other directory that is on your path, and then edit them so that the value of CCL_DEFAULT_DIRECTORY is your ccl directory. You can then start up the lisp by typing ccl or ccl64 .

If you always run Clozure CL from Emacs, it is sufficient to use the full pathname of the lisp kernel binary directly. That is, in your Emacs init file, you could write something like (setq inferior-lisp-program "/path/to/ccl/lx86cl64") or make the equivalent changes to slime-lisp-implementations .

If the lisp kernel binary does not work, you may need to recompile it on your local system. See Building the Kernel .

By default, the lisp kernel will look for a heap image with an appropriate name in the same directory that the lisp kernel itself is in. Thus, it is possible to start Clozure CL simply by running ./lx86cl64 (or whatever the appropriate binary is called) directly from the ccl directory.

The names used for the lisp kernel on the various platforms are listed in the table below. The heap images have the same basename as the corresponding lisp kernel, but a .image suffix. Thus, the image name for armcl would be armcl.image .

Clozure CL is made up of two parts: the lisp kernel , and a heap image . When the lisp kernel starts up, it locates the heap image, maps it into memory, and starts running the lisp code contained in the image. In the ccl directory, you will find pre-built lisp kernel executables and heap images for your platform.

After following the download instructions, you should have a directory on your system named ccl . This directory is called the ccl directory .

Clozure CL is distributed via the Internet. Please see http://ccl.clozure.com/download.html for instructions on how to download it.

If things go wrong in the early stages of the loading sequence, errors are often difficult to debug; until a fair amount of code (CLOS, the CL condition system, streams, the reader, the read-eval-print loop) is loaded, it's generally not possible for the lisp to report an error. Errors that occur during these early stages (“the cold load”) sometimes cause the lisp kernel debugger to be invoked; it's primitive, but can sometimes help one to get oriented.

The name new.image can be whatever you want. You may wish to use the default image name for your platform; see Platform-specific filename conventions .

This process will load a few dozen fasl files, printing a message as each file is loaded. If all of these files successfully load, the lisp will print a prompt. You should be able to do essentially everything in that environment that you can in the environment provided by a full heap image. If everything went well, you can save that image using save-application :

Other platoforms use analogous steps: use the appropriate platform-specific name for the lisp kernel, and use the name of boot image as reported by xload-level-0 .

To build a full image from a bootstrapping image, just invoke the kernel and tell it to load the bootstrapping image (as reported by xload-level-0 . For example, suppose you are using 64-bit Mac OS X:

xload-level-0 should be called whenever your existing boot image is out-of-date with respect to the source files in ccl:level-0; .

This function compiles the lisp sources in the ccl/level-0 directory as needed, and then loads the resulting fasl files into a simulated lisp heap contained in data structures inside the running lisp. It then writes this data to disk as a bootstrapping image and displays the pathname of the newly-written image on the terminal.

Given a source distribution, a lisp kernel, and a heap image, one can produce a bootstrapping image by first invoking Clozure CL from the shell:

The bootstrapping image is built by invoking a special utility inside a running Clozure CL heap image to load files contained in the ccl/level-0 directory. The bootstrapping image loads several dozen fasl files. After it's done so, it saves a heap image via save-application . This process is called cross-dumping.

The bootstrapping image isn't provided in Clozure CL distributions. It can be built from the source code provided in distributions (using a lisp image and kernel provided in those distributions) using the procedure described below.

Calling compile-ccl or xcompile-ccl in an environment where fasl files don't yet exist may produce warnings to that effect whenever files are require d during compilation; those warnings can be safely ignored. Depending on the maturity of the Clozure CL release, calling compile-ccl or xcompile-ccl may also produce several warnings about undefined functions, etc. They should be cleaned up at some point.

Unless there are bootstrapping considerations involved, it usually doesn't matter whether these files are reloaded after they're recompiled.

at the lisp prompt compiles any fasl files that are out-of-date with respect to the corresponding lisp sources; (ccl:compile-ccl t) forces recompilation. ccl:compile-ccl reloads newly-compiled versions of some files; ccl:xcompile-ccl is analogous, but skips this reloading step.

Start up the lisp kernel and tell it to load the bootstrapping image you just created

Typically, rebuild-ccl is used to rebuild all of Clozure CL. In special cases, you might want to exercise more control over how the heap image is built. These cases typically arise only when developing Clozure CL itself.

On Mac OS X, make sure that you have installed the command-line developer tools with xcode-select --install . If you get an error message saying that the file sys/signal.h cannot be found, this is a sign that you need to do this. You need to do this even if you have Xcode already installed.

The most common reason that the build fails is because m4 is not installed. If you see m4: command not found , then you should install m4.

Rebuilding the lisp kernel is straightfoward. Consult the table Platform-specific filename conventions to determine the name of the lisp kernel build directory you want. Then, change to that directory and say make . Suppose you wanted to build the lisp kernel for 64-bit FreeBSD/x86. We find that the name of the lisp kernel build directory is freebsdx8664 , so we do the following:

rebuild-ccl is essentially just a short cut for running all the individual steps involved in rebuilding the system. You can also execute these steps individually, as described below.

When all goes well, this all happen without user intervention and with some simple progress messages. If anything goes wrong during execution of either of the external processes, the process output is displayed as part of a lisp error message.

Runs another external process, which causes the newly compiled lisp kernel to load the new bootstrapping image. The bootstrapping image then loads the rest of the fasl files and a new copy of the platform's full heap image is then saved.

Runs an external process that runs make in the current platform's kernel build directory to create a new kernel. This step can only work if the C compiler and related tools are installed; see Kernel Build Prerequisites .

Does (xload-level-0 :force) in the running lisp. This compiles the lisp files in the ccl:level-0; directory and then creates a special bootstrapping image from the compiled fasl files.

Does (compile-ccl t) in the running lisp, to generate fasl files from the lisp sources.

With all the pre-requisites in place, building Clozure CL is very simple.

In order to build the lisp kernel, you must have installed a C compiler and its associated tools (such as as and ld ). Additionally, the lisp kernel build process uses m4 ; this program is often not installed by default, so make sure you have it. The lisp kernel makefiles generally assume that you are using GNU make.

You may also be interested in building the development version of Clozure CL, which is often called the trunk. The trunk may contain both interesting new features and interesting new bugs. See http://trac.clozure.com/ccl/wiki for information about how to check out a copy of the trunk.

The first of these is the current release branch. Fixes for serious bugs are sometimes checked into the release branch, and you might want to update from Subversion and rebuild in order to pick up these fixes.

At a given time, there are generally two versions of Clozure CL that you might want to use (and therefore might want to build from source).

Each supported platform (and possibly a few as-yet-unsupported ones) has a uniquely named subdirectory of ccl/lisp-kernel/ ; each such kernel build directory contains a Makefile and may contain some auxiliary files (linker scripts, etc.) that are used to build the lisp kernel on a particular platform. The platform-specific name of the kernel build directory is described in Platform-specific filename conventions .

A bootstrapping image (see Create a Bootstrapping Image ) is a minimal heap image used in the process of building Clozure CL itself. The bootstrapping image contains just enough code to load the rest of Clozure CL from fasl files. The function rebuild-ccl automatically creates a bootstrepping image as part of its work.

A heap image is a file that can be quickly mapped into a process's address space. Conceptually, it's not too different from an executable file or shared library in the OS's native format (ELF or Mach-O/dyld format); for historical reasons, Clozure CL's own heap images are in their own (fairly simple) format. A full heap image contains all of the code and data that comprise Clozure CL. The default image file name is the name of the lisp kernel with a .image suffix. See Platform-specific filename conventions .

The lisp kernel is a C program with a fair amount of platform-specific assembly language code. The lisp kernel provides runtime support for lisp code, such as garbage collection, memory allocation, exception handling, and so forth. When the lisp kernel starts, it maps the heap image into memory and transfers control to compiled lisp code that the image contains.

A fasl file is the file produced by compile-file . These files store the machine code associated with function definitions and the external representation of other lisp objects in a compact, machine-readable form. Short for “ FAS t L oading”. Clozure CL uses different pathname types (extensions) to name fasl files on different platforms; see Platform-specific filename conventions for the details.

The following terms are used in subsequent sections; it may be helpful to refer to these definitions.

In Clozure CL, the cleanup forms are always executed as if they were wrapped with without-interrupts . To allow interrupts, use with-interrupts-enabled .

One case in which this approach can be confusing is in the case of symbols. As noted in the Limitations section, coverage information is not recorded for variables; hence the coloring of a variable does not convey information about whether the variable was evaluated or not -- that information is not available, and the variable just inherits the color of the form that contains it.

first the whole outer form is painted with whatever color expresses the outer form coverage, and then the inner form color is replaced with whatever color expresses the inner form coverage. One consequence of this approach is that every part of the outer form that is not specifically inside some executable inner form will have the outer form's coverage color. If the syntax of outer form involves some non-executable forms, or forms that do not have coverage info of their own for whatever reason, then they will just inherit the color of the outer form, because they don't get repainted with a color of their own.

The source coloring is applied from outside in. So for example if you have

The output of ccl:report-coverage consists of formatted source code, with coverage indicated by coloring. Four colors are used: dark green for forms that compiled to code in which every single instruction was executed, light green for forms that have been entered but weren't totally covered, red for forms that were never entered, and the page background color for toplevel forms that weren't instrumented.

This macro arranges so that body doesn't record internal details of code coverage. It will be considered totally covered if it's entered at all. The Common Lisp macros ASSERT and CHECK-TYPE use this macro.

This variable controls whether functions are instrumented for code coverage. Files compiled while this variable is true will contain code coverage instrumentation.

collection can also be a sequence of deltas, in which case a subsequence of matching deltas is returned. In particular you can test whether any particular delta is affected by the changes by passing it in as a single-element list.

For example if the deltas represent tests, then the returned value is a list of all tests that might be affected by the changes.

Given a hash table collection whose values are incremental coverage deltas, return a list of all keys corresponding to those deltas that intersect any changed source in directory since revision revision in subversion.

The revision to compare to the working directory, an integer or another value whose printed representation is suitable for passing as the --revision argument to svn .

collection can also be a sequence of deltas, in which case a subsequence of matching deltas is returned. In particular you can test whether any particular delta intersects the sources by passing it in as a single-element list.

For example if the deltas represent tests, then the returned value is a list of all tests that cover some part of the source regions.

Given a hash table collection whose values are incremental coverage deltas, return a list of all keys corresponding to those deltas that intersect any region in sources .

Incremental coverage deltas are represented differently than the full coverage snapshots returned by functions such as ccl:get-coverage . Incremental coverage uses an abbreviated format and is missing some of the information in a full snapshot, and therefore cannot be passed to functions documented to accept a snapshot , only to functions specifically documented to accept incremental coverage deltas.

Returns the delta of coverage since the last reset of incremental coverage. If reset is true (the default), it also resets incremental coverage now, so that the next call to get-incremental-coverage will return the delta from this point.

Marks a starting point for recording incremental coverage. Note that calling this function does not affect regular coverage data (whereas calling ccl:reset-coverage resets incremental coverage as well).

the total number of code forms. A code form is an expression in the final stage of compilation, after all macroexpansion and compiler transforms and simplification

the number of conditionals with one branch taken and one not taken

the number of source expressions that have been entered (i.e. at least partially covered)

the name of the source file corresponding to this information

Returns a sequence of ccl:coverage-statistics objects, one for each source file, containing the same information as that written to the statistics file by report-coverage . The following accessors are defined for ccl:coverage-statistics objects:

Returns the snapshot saved in pathname. Doesn't affect the current coverage state. pathname can be the file previously created with ccl:write-coverage-to-file or ccl:save-coverage-in-file , or it can be the name of the fasl created from compiling such a file.

Saves the coverage snapshot in a file. The snapshot can be loaded back with ccl:read-coverage-from-file or loaded and restored with ccl:restore-coverage-from-file . Note that the file created is actually a lisp source file and can be compiled for faster loading.

Takes a list of coverage snapshots and returns a new coverage snapshot representing a union of all the coverage data.

Returns a snapshot of the current coverage data. A snapshot is a copy of the current coverage state. It can be saved in a file with ccl:write-coverage-to-file , reinstated back as the current state with ccl:restore-coverage , or combined with other snapshots with ccl:combine-coverage .

Restores the coverage data previously saved with ccl:save-coverage-in-file, for the set of instrumented fasls that were loaded both at save and restore time. I.e. coverage info is only restored for files that have been loaded in this session. For example if in a previous session you had loaded "foo.lx86fsl" and then saved the coverage info, in this session you must load the same "foo.lx86fsl" before calling restore-coverage-from-file in order to retrieve the stored coverage info for "foo". Equivalent to (ccl:restore-coverage (ccl:read-coverage-from-file pathname)) .

Saves all coverage info in a file, so you can restore the coverage state later. This allows you to combine multiple runs or continue in a later session. Equivalent to (ccl:write-coverage-to-file (ccl:get-coverage) pathname) .

Save all coverage into to a file so you can restore it later.

Gets rid of the information about which instrumented files have been loaded, so ccl:report-coverage will not report any files, and ccl:save-coverage-in-file will not save any info, until more instrumented files are loaded.

If you've loaded foo.lx64fsl and bar.lx64fsl , and have run some tests, you could do

If non-nil (the default), a comma-separated file is generated with the summary of statistics. You can specify a filename for the statistics argument, otherwise statistics.csv is created in the directory of output-file . See documentation of coverage-statistics below for a description of the values in the statistics file.

If non-nil, this should be a hash table mapping arbitrary keys (tags) to incremental coverage deltas. The HTML report will show a list of tags, and allow selection of an arbitrary subset of them to show the coloring and statistics for coverage by that subset.

If non-nil (the default), this will generate an HTML report, consisting of an index file in output-file and, in the same directory, one html file for each instrumented source file that has been loaded in the current session.

The following functions can be used to manage the coverage data:

creates a hash table mapping a test to a representation of all coverage recorded while running the test. This hash table can then be passed toor

While recording coverage, you can collect incremental coverage deltas between any two points in time. You might do this while running a test suite, to record the coverage for each test, for example:

When you execute functions loaded from instrumented fasl files, they will record coverage information every time they are executed. You can examine that information by calling ccl:report-coverage or ccl:coverage-statistics .

The compilation process will be many times slower than normal, and the fasl files will be many times bigger.

In order to gather code coverage information, you first have to recompile all your code to include code coverage instrumentation. Compiling files will generate code coverage instrumentation if ccl:*compile-code-coverage* is true:

Then you can see the coverage information in the definition of init-this-and-that .

Because the code coverage information is associated with compiled functions, code coverage information is not available for load-time toplevel expressions. You can work around this by creating a function and calling it. I.e. instead of

Sometimes the situation can be improved by modifying macros to try to preserve more of the input forms, rather than destructuring and rebuilding them.

While the information gathered for coverage of generated code is complete and precise, the mapping back to source forms is of necessity heuristic, and depends a great deal on the behavior of macros and the path of the source forms through compiler transforms. Source information is not recorded for variables, which further limits the source mapping. In practice, there is often enough information scattered about a partially covered function to figure out which logical path through the code was taken and which wasn't. If that doesn't work, you can try disassembling to see which parts of the compiled code were not executed: in the disassembled code there will be references to #<CODE-NOTE [xxx] ...> where xxx is NIL if the code that follows was never executed and non-NIL if it was.

Partly covered: This form was entered, and some parts were executed and some weren't.

In Clozure CL 1.4 and later, code coverage provides information about which paths through generated code have been executed and which haven't. For each source form, it can report one of three possible outcomes:

Sets the current thread's exception-enable and rounding-mode control flags to the indicated values for arguments that are supplied, and preserves the values assoicated with those that aren't supplied.

If supplied, must be one of :nearest, :zero, :positive, or :negative.

If t , the floating-point exception is signaled. If nil , it is masked.

If mode is supplied, it should be one of the keywords :rounding-mode , :overflow , :underflow , :division-by-zero , :invalid , or :inexact . The value of corresponding control flag is returned.

When called without the optional mode argument, this function returns a plist of keyword/value pairs which describe the floating point exception-enable and rounding-mode flags for the current thread.

Floating-point exceptions are generally enabled and detected. By default, threads start up with overflow, division-by-zero, and invalid enabled, and the rounding mode is set to nearest. The functions set-fpu-mode and get-fpu-mode provide user control over floating-point behavior.

In Clozure CL, the Common Lisp types short-float and single-float are implemented as IEEE single precision values; double-float and long-float are IEEE double precision values. On 64-bit platforms, single-floats are immediate values (like fixnums and characters).

The pathname-type of the output file and of each input file defaults to the current platform's fasl file type (see Platform-specific filename conventions ). If any of the input files has a different type an error will be signaled, but fasl-concatenate doesn't otherwise try too hard to verify that the input files are real fasl files for the current platform.

Loading the concatenated fasl file has the same effect as loading the invidual input fasl files in the specified order.

This function reads the fasl files specified by the list fasl-files and combines them into a single fasl file named output-file . The :if-exists keyword argument is interpreted as in the standard function open .

Multiple fasl files can be concatenated into a single file. The single file might be easier to distribute or install, and loading it may be slightly faster than loading the individual files (since it avoids the overhead of opening and closing each file in succession).

This variable contains a list of 0-argument functions that will be called after starting the lisp.

Note that save-application quits the lisp, so any functions on this list will be invoked before saving a heap image.

This variable contains a list of 0-argument functions that will be called before quitting the lisp.

This variable contains a list of 0-argument functions that will be called after restoring a saved heap image. Users may add functions to this list as needed.

This variable contains a list of 0-argument functions that will be called before saving a heap image. Users may add functions to this list as needed.

If true, saves the image as a native (ELF, Mach-O, PE) shared library. (On platforms where this isn't yet supported, a warning is issued and the option is ignored.)

This argument can be used to prepend any kind of file to the saved heap image. This can be useful in some special cases.

If the prepended file is execuatable, its execute mode bits will be copied to the output file.

Specifies the file to prepend to the saved heap image. A value of t means to prepend the lisp kernel binary that the lisp started with. Otherwise, the value of :prepend-kernel should be a pathname designator for the file to be prepended.

impurify moves objects in certain special memory areas into the regular dynamic heap, where they will be scanned by the GC.

If true, calls (in effect) impurify before saving the heap image. (If both :impurify and :purify are true, first impurify is done, and then purify .)

When true, calls (in effect) purify before saving the heap image. This moves certain objects that are unlikely to become garbage to a special memory area that is not scanned by the GC (since it is expected that the GC wouldn't find anything to collect).

If true, ensures that CLOS caches are emptied before saving the image. Normally you don't need to supply this parameter, but if for some reason you want to ensure the CLOS caches are clear when the image starts up, you can pass any true value.

The CLOS class that represents the saved Lisp application. Normally you don't need to supply this parameter; save-application uses the class ccl:lisp-development-system . In some cases you may choose to create a custom application class; in that case, pass the name of the class as the value for this parameter.

The error-handling mode for the saved image. The supplied value determines what happens when an error is not handled by the saved image. Valid values are :quit (Lisp exits with an error message); :quit-quietly (Lisp exits without an error message); or :listener (Lisp enters a break loop, enabling you to debug the problem by interacting in a listener). If you don't supply this parameter, the saved image uses the default error handler ( :listener ).

The pathname of a Lisp file to be loaded when the image starts up. You can place initialization expressions in this file, and use it to customize the behavior of the Lisp system when it starts up.

If this parameter is not supplied, Clozure CL uses its default toplevel. The default toplevel runs the read-eval-print loop .

The function to be executed after startup is complete. The toplevel is a function of no arguments that performs whatever actions the lisp system should perform when launched with this image.

The pathname of the file to be created when Clozure CL saves the application.

On all supported platforms, you can use save-application to create a command-line tool that runs very like any other command-line program does. Alternatively, if you choose not to prepend the kernel, you can save an image and then later run it by passing it as a command-line parameter to the ccl or ccl64 script.

Tthere is one exception to the conversion of macptr to dead-macptr objects: a macptr object that points to the address 0 is not converted, because address 0 can always be relied upon to refer to the same thing.

For that reason, save-application converts all macptr objects to dead-macptr objects when writing them to an image file. A dead-macptr is functionally identical to a macptr , except that code that operates on macptr objects distinguishes them from dead-macptr objects and can handle them appropriately-signaling errors, for example.

Because a macptr object is a pointer into a foreign heap that exists for the lifetime of the running Lisp process, and because a saved image is used by loading it into a brand new Lisp process, saved macptr objects cannot be relied on to point to the same things when reconstituted from a saved image. In fact, a restored macptr object might point to anything at all-for example an arbitrary location in the middle of a block of code, or a completely nonexistent virtual address.

Also on Mac OS X, Clozure CL supports an object type called macptr , which is the type of pointers into the foreign (Mac OS) heap. Examples of commonly-user macptr objects are Cocoa windows and other dynamically-allocated Mac OS system objects.

On Mac OS X, the application builder uses save-application to create the executable portion of the application bundle . Double-clicking the application bundle runs the executable image created by save-application .

In other words, you can develop any application you like by interactively modifying Clozure CL until it does what you want, then using save-application to preserve your changes in an executable image.

You can go a step further still. You can tell save-application to prepend the Lisp kernel to the image file. Doing this makes the resulting image into a self-contained executable binary. When you run the resulting file, the Lisp kernel immediately loads the attached image file and runs your saved system. The Lisp system that starts up can have any behavior you choose. It can be a Lisp development system, but with your customizations; or it can immediately perform some task of your design, making it a specialized tool rather than a general development system.

In fact, you can go further than that. You can replace Clozure CL's toplevel function with your own, and then, when the image is loaded, the Lisp system immediately performs your tasks rather than the default tasks that make it a Lisp development system. If you save an image in which you have done this, the resulting Lisp system is your tool rather than a Lisp development system.

If this scenario seems to you like a convenient way to create an application, that's just as intended. You can create an application by modifying the running Lisp until it does what you want, then use save-application to preserve your changes and later load them for use.

Using save-application , you can create a file that contains a modified image, one that includes any changes you've made to the running Lisp system. If you later pass your image file to the Clozure CL kernel as a command-line parameter, it then loads your image file instead of its default one, and Clozure CL starts up with your modifications.

Clozure CL consists of a small executable called the lisp kernel , which implements the very lowest level features of the Lisp system, and a heap image , which contains the in-memory representation of most of the Lisp system, including functions, data structures, variables, and so on. When you start Clozure CL, you are launching the kernel, which then locates and reads an image file, restoring the archived image in memory. Once the image is fully restored, the Lisp system is running.

Proclaims the variable special , assigns the variable the supplied value , and assigns the docstring to the variable's variable documentation. Marks the variable static, preventing any attempt to dynamically rebind it. Any attempt to dynamically rebind var signals an error.

In Clozure CL, access to a static variable is usually faster than access to a special variable that has not been declared static.

Static variables therefore provide a simple way to share mutable state across threads. They also provide a simple way to introduce race conditions and obscure bugs into your code, since every thread reads and writes the same instance of a given static variable. You must take care, therefore, in how you change the values of static variables, and use normal multithreaded programming techniques, such as locks or semaphores, to protect against race conditions.

Attempting to dynamically rebind a static variable (for instance, by using LET , or using the variable name as a parameter in a LAMBDA form) signals an error. Static variables are shared global resources; a dynamic binding is private to a single thread.

Clozure CL supports the definition of static variables , whose values are the same across threads, and which may not be dynamically bound. The value of a static variable is thus the same across all threads; changing the value in one thread changes it for all threads.

This function is a synonym for (map-file-to-ivector pathname '(unsigned-byte 8)) It is provided as a convenience for the common case of memory-mapping a file as a vector of bytes.

If the argument is a displaced-array returned by map-file-to-ivector , and if it has not yet been unmapped by this function, then unmap-ivector undoes the memory mapping, closes the mapped file, and changes the displaced-array so that its target is an empty vector (of length zero).

Currently, Clozure CL supports only read operations on memory-mapped files. If you try to change the contents of an array returned by map-file-to-ivector , Clozure CL signals a memory error.

Because of alignment issues, the mapped file's contents start a few bytes (4 bytes on 32-bit platforms, 8 bytes on 64-bit platforms) into the vector. The displaced array returned by map-file-to-ivector hides this overhead, but it's usually more efficient to operate on the underlying simple 1-dimensional array. Given a displaced array (like the value returned by map-file-to-ivector ), the function array-displacement returns the underlying array and the displacement index in elements.

The returned vector is a displaced-array whose element-type is (UPGRADED-ARRAY-ELEMENT-TYPE element-type) . The target of the displaced array is a vector of type (SIMPLE-ARRAY element-type (*)) whose elements are the contents of the memory-mapped file.

The element-type of the vector to be created. Specified as a type-specifier that names a subtype of either signed-byte or unsigned-byte .

The map-file-to-ivector function tries to open the file at pathname for reading. If successful, the function maps the file's contents to a range of virtual addresses. If successful, it returns a read-only vector whose element-type is given by element-type , and whose contents are the contents of the memory-mapped file.

Vectors created by map-file-to-ivector and map-file-to-octet-vector are required to respect Clozure CL's limit on the total size of an array. That means that you cannot use these functions to create a vector longer than array-total-size-limit , even if the filesystem supports file sizes that are larger. The value of array-total-size-limit is (expt 2 24) on 32-but platforms; and (expt 2 56) on 64-bit platforms.

The vectors returned by map-file-to-ivector and map-file-to-octet-vector are read-only; any attempt to change an element of a vector returned by these functions results in a memory-access error. Clozure CL does not currently support writing data to memory-mapped files.

Using a memory-mapped files has a result that is the same in that, like the above example, it returns a vector whose contents are the same as the contents of the file. It differs in that the above example creates a new vector in memory and copies the file's contents into it; using a memory-mapped file instead arranges for the vector's elements to point to the file's contents on disk directly, without copying them into memory first.

Without memory-mapped files, a common idiom for reading the contents of files might be something like this:

Clozure CL provides the functions map-file-to-ivector and map-file-to-octet-vector to support memory-mapping. These functions return vectors whose contents are the contents of memory-mapped files. Reading an element of such a vector returns data from the corresponding position in the file.

Using memory-mapped files may in some cases be more efficient than reading the contents of a file into a data structure in memory.

In release 1.2 and later, Clozure CL supports memory-mapped files . On operating systems that support memory-mapped files (including Mac OS X, Linux, and FreeBSD), the operating system can arrange for a range of virtual memory addresses to refer to the contents of an open file. As long as the file remains open, programs can read values from the file by reading addresses in the mapped range.

The Common Lisp standard allows considerable latitude in the details of an implementation, and each particular Common Lisp system has some idiosyncrasies. This chapter describes ordinary user-level features of Clozure CL, including features that may be part of the Common Lisp standard, but which may have quirks or details in the Clozure CL implementation that are not described by the standard. It also describes extensions to the standard; that is, features of Clozure CL that are not part of the Common Lisp standard at all.

Show information about the process proc , or all processes if proc is not specified.

Change to the directory specified by dir , which may be a namestring or a pathname object.

Note, though, that an internally-defined number of consecutive EOFs will exit lisp anyway.

When true, exit the top-level immediately upon receipt of an EOF. If *quit-on-eof* is nil (which is the default), ignore the EOF.

Read the source text from the original file if it is not already present in source-note .

Return the ending file position (not character position) for the thing described by source-note .

Return the starting file position (not character position) for the thing described by source-note .

When true, record PC to source mapping (but only if *save-source-locations* is also true).

Store source location information, but do not store a copy of the original source text. This is an optimization useful for compiling files that are not expected to change.

Do not record source location information. Filename information for definitions will still be saved if *record-source-file* is true.

Source notes are associated with definitons (via record-source-file ) and also stored in function objects (including anonymous and local functions). The former can be retrieved via find-definition-sources , and the latter via function-source-note .

The start and end positions are file positions and not character positions. The text will be nil unless source recording was on at read time. If the original source file is still available, ensure-source-note-text will force the missing source text to be read from the file.

When true, the output of disassemble may include platform-dependent additional information. For instance, on the x86 ports, the output will include the x86 opcode bytes.

The value returned by %address-of is only useful for debugging, since the GC may run at any time and may move objects around in memory, thereby changing their addresses.

Note that there are types other than fixnums that are represented as immediate values rather than heap-allocated objects. On various platforms, these might include characters and single-flosts, and possibly other values. The %address-of function will return fairly useless values for such objects.

This function returns the address of thing as an integer. If thing is a fixnum, thing is simply returned.

This function returns the size of thing in bytes, including any headers and alignment overhead. It does not descend into an object's components.

If threshold is non-nil, it should be a number between 0 and 1. All types whose share of the heap is less than threshold will be lumped together in an “All Others” line rather than being listed individually.

If :start is non-nil, it should be an object returned by ccl::get-allocation-sentinel ; only objects at higher address are scanned (roughly, only objects allocated after it).

By default, sizes are shown in bytes. The keyword argument :unit can be :kb , :mb , or :gb to show sizes in those units.

The keword argument :sort can be one of :count , :logical-size , or :physical-size to sort output by count or size.

The keyword argument :area can be used to restrict the walk to one memory area or a list of areas. Some possible values are :dynamic , :static , :managed-static , and :readonly . By default, all areas (including stacks) are examined.

If :classes is true, objects are classified by class rather than just basic type.

If :gc-first is true (the default), heap-utilization does a full gc before scanning the heap.

This function walks the lisp heap, collects information about the objects stored on the heap, and prints a report of the results to the stream speficied by the keyword argument :stream . It shows the number of objects of each type, the sum of their logical sizes (the size of the data part of the object) and the sum of their physical sizes (the total size as computed by object-direct-size ).

One problem with trying to monitor hash tables for writes is that the underlying hash-table-vector is replaced with an entirely new one when the hash table is rehashed. A previously-watched hash-table-vector will not be the used by the hash table after rehashing, and writes to the new vector will not be caught.

Hash tables are surprisingly complicated. The representation of a hash table includes an element called a hash-table-vector. The keys and values of the elements are stored pairwise in this vector.

In this case, uvector index in the report is the row-major index of the element that was written to.

Here are a couple more examples in addition to the above examples of watching a string and a standard-instance.

Having the object unwatched out from underneath a handler may at least confuse it, if not cause deeper trouble. Use caution with unwatch.

Now, as soon lisp code starts running again (for the callback), it's possible that some other thread could unwatch the very watched object that caused the exception, perhaps before we even have a chance to signal the condition, much less respond to it.

For example, suppose that a thread attempts to write to a watched object. This causes the operating system to generate an exception. The lisp kernel figures out what the exception is, and calls back into lisp to signal the write-to-watched-object condition and perhaps handle the error.

Although some care has been taken to minimize potential problems arising from watching and unwatching objects from multiple threads, there may well be subtle race conditions present that could cause bad behavior.

There is also an emulate restart. In some common cases, the faulting write instruction can be emulated, enabling the write to be performed without having to unwatch the object (and therefore let other threads potentially write to it). If the faulting instruction isn't recognized, the emulate restart will not be offered.

A few restarts are provided: one will skip over the faulting write instruction and proceed; another offers to unwatch the object and continue.

The byte offset from the tagged object pointer to the address of the write.

The actual object that was the destination of the write.

This condition is signaled when a watched object is written to. There are three slots of interest:

The UNWATCH function ensures that the specified object is in normal, non-monitored memory. If the object is not currently being watched, UNWATCH does nothing and returns NIL. Otherwise, the newly unwatched object is returned.

Note that even though the write was to slot-a, the uvector index was 1 (not 0). This is because the first element of a slot-vector is a pointer to the instance that owns the slots. We can retrieve that to look at the object that was modified:

Looking at a backtrace would presumably show what object and slot name were written.

As mentioned above, watch knows about arrays, hash-tables, and standard-instances, and will automatically watch the appropriate data-containing element.

In the case of more complicated objects (e.g., a hash-table, a standard-instance, a package, etc.), the elements of the uvector are like slots in a structure. It's necessary to know which one of those "slots" contains the data that will be changed when the object is written to.

Some CL objects, like strings and other simple vectors, map in a straightforward way onto the uvector representation. It is easy to understand what happens in such cases. The uvector index corresponds directly to the vector index:

So, a hash table is a uvector, as is a string, a standard instance, a double-float, a CL array or vector, and so forth.

If a memory-allocated object isn't a cons cell, then it is a vector-like object called a uvector. A uvector is a memory-allocated lisp object whose first word is a header that describes the object's type and the number of elements that it contains.

WATCH operates on cons cells, not lists. In order to watch a chain of cons cells, each cons cell must be watched individually. Because each watched cons cell takes up its own own virtual memory page (4 Kbytes), it's only feasible to watch relatively short lists.

WATCH operates at a fairly low level; it is not possible to avoid the details of the internal representation of objects. Nevertheless, as a convenience, WATCHing a standard-instance, a hash-table, or a multi-dimensional or non-simple CL array will watch the underlying slot-vector, hash-table-vector, or data-vector, respectively.

WATCH returns NIL if the object cannot be watched (typically because the object is in a static or pure memory area).

When called with no arguments, WATCH returns a freshly-consed list of the objects currently being watched.

When any write to the object is attempted, a WRITE-TO-WATCHED-OBJECT condition will be signaled.

The WATCH function arranges for the specified object to be monitored for writes. This is accomplished by copying the object to its own set of virtual memory pages, which are then write-protected. This protection is enforced by the computer's memory-management hardware; the write-protection does not slow down reads at all.

As of release 1.4, Clozure CL provides a way for lisp objects to be watched so that a condition will be signaled when a thread attempts to write to the watched object. For a certain class of bugs (someone is changing this value, but I don't know who), this can be extremely helpful.

The arguments have the same meaning as in advise .

The advisedp macro returns a list of existing pieces of advice that match spec , when , and name . When the value of spec is t and the values of when and name are nil, advisedp returns all existing pieces of advice.

Return a list of the pieces of advice matching spec , when , and name .

The arguments have the same meaning as in advise .

The unadvise macro removes the piece or pieces of advice matching spec , when , and name . When the value of spec is t and the values of when and name are nil, unadvise removes every piece of advice; when spec is t, the argument when is nil, and name is non-nil, unadvise removes all pieces of advice with the given name.

Remove the piece or pieces of advice matching spec , when , and name .

To do the same thing using a :before piece of advice:

The function foo , already defined, does something with a list of numbers. The following code uses a piece of advice to make foo return zero if any of its arguments is not a number. Using :around advice, you can do the following:

An argument that specifies when the piece of advice is run. There are three allowable values. The default is :before , which specifies that form is executed before the advised function is called. Other possible values are :after , which specifies that form is executed after the advised function is called, and :around , which specifies that form is executed around the call to the advised function. Use (:do-it) within form to indicate invocation of the original definition.

A form to execute before, after, or around the advised function. The form can refer to the variable arglist that is bound to the arguments with which the advised function was called. You can exit from form with (return).

A specification of the function on which to put the advice. This is either a symbol that is the name of a function or generic function, or an expression of the form (setf symbol ), or a specific method of a generic function in the form (:method symbol {qualifiers} (specializer {specializer})).

Add a piece of advice to the function or method specified by spec according to form .

The :name and :when keywords serve to identify the piece of advice. A later call to advise with the same values of :name and :when will replace the existing piece of advice; a call with different values will not.

The advise macro can be thought of as a more general version of trace . It allows code that you specify to run before, after, or around a given function, for the purpose of changing the behavior of the function. Each piece of added code is called a piece of advice. Each piece of advice has a unique name, so that you can have multiple pieces of advice on the same function, including multiple :before , :after , and :around pieces of advice.

By default, this is nil. If non-nil it should be a integer, and the default entry and exit messages will print a | instead of space every this many levels of indentation.

The default print actions bind *print-length* to this value while printing. Note that this rebinding is only in effect during the default entry and exit messages. It does not apply to printing of :print-before/:print-after forms or any explicit printing done by user code.

The default print actions bind *print-level* to this value while printing. Note that this rebinding is only in effect during the default entry and exit messages. It does not apply to printing of :print-before/:print-after forms or any explicit printing done by user code.

This is a functional version of the TRACE macro. spec and keyword s are as for TRACE, except that all arguments are evaluated.

The default before and after print actions will not indent by more than the value of *trace-max-indent* regardless of the current trace level.

Variable bound to the current nesting level during execution of before and after trace actions. The default printing actions use it to determine the amount of indentation.

Any other value is interpreted as a function to call on exit instead of printing the standard exit message. It is called with its first argument being the name of the function being traced, the remaining arguments being all the values returned by the function being traced, and ccl:*trace-level* bound to the current nesting level of trace actions.

specifies the action to be taken just after the traced function exits. action is one of:

Any other value is interpreted as a function to call on entry instead of printing the standard entry message. It is called with its first argument being the name of the function being traced, the remaining arguments being all the arguments to the function being traced, and *trace-level* bound to the current nesting level of trace actions.

specifies the action to be taken just before the traced function is entered. action is one of:

Evaluates form whenever the function being traced has just exited. The form may reference the lexical variable ccl::vals , which is a list of values returned by this call. The value returned by form is intepreted as follows:

Note that unlike with the other options, :backtrace is equivalent to :backtrace-before only, not both before and after, since it's usually not helpful to print the same backtrace both before and after the function call.

Evaluates form whenever the function being traced is about to be entered. The form may reference the lexical variable ccl::args , which is a list of the arguments in this call. The value returned by form is intepreted as follows:

Evaluates form whenever the function being traced has just exited, and if the result is non-nil, enters a debugger break loop. The form may reference the lexical variable ccl::vals , which is a list of values returned by this call.

Evaluates form whenever the function being traced is about to be entered, and if the result is non-nil, enters a debugger break loop. The form may reference the lexical variable ccl::args , which is a list of the arguments in this call.

Evaluates form whenever the function being has just exited. The form may reference the lexical variable ccl::vals , which is a list of values returned by this call.

Evaluates form whenever the function being traced is about to be entered. The form may reference the lexical variable ccl::args , which is a list of the arguments in this call.

Evaluates form whenever the function being traced has just exited, and prints the result after printing the standard exit message. The form may reference the lexical variable ccl::vals , which is a list of values returned by this call. To see multiple forms, use values : :print-after (values (one-thing) (another-thing)) .

Evaluates form whenever the function being traced is about to be entered, and prints the result before printing the standard entry message. The form may reference the lexical variable ccl::args , which is a list of the arguments in this call. To see multiple forms, use values : :print-before (values (one-thing) (another-thing)) .

Evaluates form whenever the function being traced has just exited, and inhibits the exit trace actions if form returns nil. The form may reference the lexical variable ccl::vals , which is a list of values returned by this call. If both :if and :after-if are specified, both must return non-nil in order for the after exit actions to happen.

Evaluates form whenever the function being traced is about to be entered, and inhibits the entry trace actions if form returns nil. The form may reference the lexical variable ccl::args , which is a list of the arguments in this call. If both :if and :before-if are specified, both must return non-nil in order for the before entry actions to happen.

Evaluates form whenever the function being traced is about to be entered, and inhibits all trace actions if form returns nil. The form may reference the lexical variable ccl::args , which is a list of the arguments in this call. :condition is just a synonym for :if , though if both are specified, both must return non-nil.

Inhibits all trace actions unless the current invocation of the function being traced is inside one of the outside-spec 's, i.e. unless a function named by one of the outside-spec 's is currently on the stack. outside-spec can name a function, a method, or a package, as above.

If true, and if applied to a spec naming a generic function, arranges to trace all the methods of the generic function in addition to the generic function itself.

By default, whenever a traced function is entered or exited, a short message is printed on *trace-output* showing the arguments on entry and values on exit. Options specified as key/value pairs can be used to modify this behavior. Options preceding the function spec s apply to all the functions being traced. Options specified along with a spec apply to that spec only and override any global options. The following options are supported:

A spec can also be a string naming a package, or equivalently a list (:package package-name ) , in order to request that all functions in the package to be traced.

A spec is either a symbol that is the name of a function, or an expression of the form (setf symbol ) , or a specific method of a generic function in the form (:method gf-name { qualifier }* ({ specializer }*)) , where a specializer can be the name of a class or an EQL specializer.

The trace macro encapsulates the functions named by spec s, causing trace actions to take place on entry and exit from each function. The default actions print a message on function entry and exit. Keyword / value options can be used to specify changes in the default behavior.

Clozure CL's tracing facility is invoked by an extended version of the Common Lisp trace macro. Extensions allow tracing of methods, as well as finer control over tracing actions.

When true (the default), lisp will enter a break loop when an error is signaled.

This variable was removed from ANSI CL. The rationale was that the same effect may be acheived with (setq *break-on-signals* 'warning) .

When use-byte-order-mark is true, the returned size will include the space needed for a byte-order marker.

Returns the number of octets required to encode string (or the substring delimited by :start and :end ) according to :external-format .

Characters in string that cannot be encoded into external-format will be replaced with an encoding-dependent replacement character (either #\Replacement_Character or #\Sub) before being encoded and written into the output vector.

If vector-offset is supplied, data will be written into the output vector starting at that offset.

If vector is supplied, output will be written to it. It must be of type (simple-array (unsigned-byte 8)) and be large enough to hold the encoded data. If it is not supplied, the function will allocate a new vector to hold the output.

When use-byte-order-mark is true, a byte-order mark will be included in the encoded data.

Encodes string (or the substring of it delimited by start and end ) into vector according to external-format . It returns, as multiple values, the vector of octets containing the encoded data and an integer that specifies the offset into the vector where the encoded data ends.

Sequences of octets in vector that cannot be decoded into characters according to external-format will be decoded as #\Replacement_Character .

Returns, as multiple values, the decoded string and the position in vector where the decoding ended.

If string is supplied, output will be written into it. It must be large enough to hold the decoded characters. If string is not supplied, a new string will be allocated to hold the decoded characters.

Decodes the octets in vector (or the subsequence of it delimited by start and end ) into a string according to external-format .

Returns the number of characters that would be produced by decoding vector (or the subsequence thereof delimited by start and end ) according to external-format .

Clozure CL provides functions to encode and decode strings to and from vectors of type (simple-array (unsigned-byte 8)).

A 16-bit, variable-length encoding in which characters with CHAR-CODEs less than #x10000 can be encoded in a single 16-bit word and characters with larger codes can be encoded in a pair of 16-bit words. The endianness of the encoded data is indicated by the endianness of a byte-order-mark character (#u+feff) prepended to the data; in the absence of such a character on input, the data is assumed to be in big-endian order. Output is written in native byte-order with a leading byte-order mark.

An 7-bit, fixed-width character encoding in which all character codes map to their Unicode equivalents.

ISO-8859-1 just covers the first 256 Unicode code points, where the first 128 code points are equivalent to US-ASCII. That should be pretty much equivalent to what earliers versions of Clozure CL did that only supported 8-bit characters, but it may not be optimal for users working in a particular locale.

An 8-bit, fixed-width character encoding in which all character codes map to their Unicode equivalents. Intended to support most characters used in most Western European languages.

Clozure CL uses this encoding for *terminal-io* and for all streams whose EXTERNAL-FORMAT isn't explicitly specified. The default for *terminal-io* can be set via the -K command-line argument (see Command Line Options ).

An 8-bit, variable-length character encoding in which characters with CHAR-CODEs in the range #x00-#x7f can be encoded in a single octet; characters with larger code values can be encoded in 2 to 4 bytes.

A few commonly-used encodings are described here. For the complete list, call describe-character-encodings . Most encodings have aliases, e.g. the encoding named :iso-8859-1 can also be referred to by the names :latin1 and :ibm819 , among others. Where possible, the keywordized name of an encoding is equivalent to the preferred MIME charset name (and the aliases are all registered IANA charset names.)

A byte order mark from a UTF-8 encoded input stream is not treated specially and just appears as a normal character from the input stream. It is probably a good idea to skip over this character.

Clozure CL writes a byte order mark as the first character of a file or socket stream when the endianness of the character encoding is not explicit. Clozure CL also expects a byte order mark on input from streams where the endianness is not explicit. If a byte order mark is missing from input data, that data is assumed to be in big-endian order.

The endianness of a character encoding is sometimes explicit, and sometimes not. For example, :utf-16be indicates big-endian, but :utf-16 does not specify endianness. A byte order mark is a special character that may appear at the beginning of a stream of encoded characters to specify the endianness of a multi-byte character encoding. (It may also be used with UTF-8 character encodings, where it is simply used to indicate that the encoding is UTF-8.)

The presence of a replacement character typically indicates that something got lost in translation: either data was not encoded properly or there was a bug in the decoding process.

When a character cannot be encoded or decoded according to a specified external format, the character in question will be replaced with an encoding-specific replacement character. This will be #\Replacement_Character if the destination external format includes such a character; otherwise the replacement character will be #\Sub .

Writes descriptions of all defined character encodings to *terminal-io* . These descriptions include the names of the encoding’s aliases and a doc string which briefly describes each encoding’s properties and intended use.

The set of character encodings supported by Clozure CL can be retrieved by calling describe-character-encodings .

Internally, character-encoding s are objects (structures) that are named by character encoding keywords ( :iso-8859-1 , :utf-8 , etc.). The structures contain attributes of the encoding and functions used to encode/decode external data, but unless you are trying to define or debug an encoding, there is little reason to know much about the character-encoding objects and it is usually preferable to refer to a character encoding by its name.

Internally, all characters and strings in Clozure CL are in UTF-32. Externally, files or socket streams may encode characters in a wide variety of ways. The International Organization for Standardization, widely known as ISO, defines many of these character encodings. Clozure CL implements some of these encodings as detailed below. These encodings are part of the specification of external formats (see External Formats ). When reading from a stream, characters are converted from the specified external character encoding to UTF-32. When writing to a stream, characters are converted from UTF-32 to the specified character encoding.

:inferred means that a stream's line-termination convention is determined by looking at the contents of a file. It is only useful for file-stream s that're open for :input or :io . The first buffer full of data is examined, and if a #\Return character occurs before any #\Linefeed character, then the line termination type is set to :windows if that #\Return character is immediately followed by a #\Linefeed character and to :macos otherwise. If a #\Return character isn't found in the buffer or if #\Return is preceded by #\Linefeed , the file's line terminationt type is set to :unix .

Line termination keywords indicate which characters are used to indicate the end of a line. On input, the external line termination characters are replaced by #\Newline and on output, #\Newline s are converted to the external line termination characters.

Despite the function's name, it doesn't necessarily create a new, unique external-format object: two calls to make-external-format with the same arguments made in the same dynamic environment return the same (eq) object.

A keyword that indicates a line termination keyword Line Termination Keywords . Defaults to :default which means use the value of the variable *default-line-termination* .

A keyword that specifies the character encoding for the external format. Character Encodings . Defaults to :default which means if domain is :file use the value of the variable *default-file-character-encoding* and if domain is :socket , use the value of the variable *default-socket-character-encoding* . The initial value of both of these variables is NIL , which means the :iso-8859-1 encoding.

This is used to indicate where the external format is to be used. Its value can be almost anything. It defaults to NIL . There are two domains that have a pre-defined meaning in Clozure CL: :file indicates encoding for a file in the file system and :socket indicates i/o to/from a socket. The value of domain affects the default values for character-encoding and line-termination .

Either creates a new external format object, or return an existing one with the same specified slot values.

The initial value of this variable in Clozure CL is :unix .

The value of this variable is used when an external-format doesn't specify a line-termination convention (or specifies it as :default .) It can meaningfully be given any value that can be used as a line termination keyword (see Line Termination Keywords ).

The initial value of this variable in Clozure CL is :unix , which is equivalent to (:line-termination :unix) , among other things.

The value of this variable is used when :external-format is unspecified or specified as :default . It can meaningfully be given any value that can be used as an external-format (except for the value :default .)

EXTERNAL-FORMATs are objects (structures) with two read-only fields that can be accessed via the functions: external-format-line-termination and external-format-character-encoding .

Note that the set of keywords used to denote character-encoding s and the set of keywords used to denote line-termination conventions is disjoint: a keyword denotes at most a character encoding or a line termination convention, but never both.

If :default is specified, then the value of *default-external-format* is used. If no line-termination is specified, then the value of *default-line-termination* is used, which defaults to :unix . If no character encoding is specified, then *default-file-character-encoding* is used for file streams and *default-socket-character-encoding* is used for socket streams. The default, default character encoding is nil which is a synonym for :iso-8859-1 .

The standard functions open , load , and compile-file all accept an :external-format keyword argument. The value of :external-format can be :default (the default value), a line termination keyword (see Line Termination Keywords ), a character encoding keyword (see Character Encodings ), an external-format object created using make-external-format , or a plist with the keys :domain , :character-encoding and :line-termination . If argument is a plist, the result of (apply #'make-external-format argument ) will be used.

Characters with codes in the range #xa0 - #x7ff also have symbolic names These are the names from the Unicode standard with spaces replaced by underscores. So #\Greek_Capital_Letter_Epsilon can be used to refer to the character whose char-code is #x395 . To see the complete list of supported character names, look just below the definition for ccl::register-character-name in ccl:level-1;l1-reader.lisp .

Clozure CL supports character names of the form u+xxxx -where x is a sequence of one or more hex digits. The value of the hex digits denotes the code of the character. The + character is optional, so #\u+0020 , #\U0020 , and #\U+20 all refer to the #\Space character.

There is one character type in Clozure CL. All character s are base-char s. char-code-limit is now #x110000 , which means that all Unicode characters can be directly represented. As of Unicode 5.0, only about 100,000 of 1,114,112 possible char-code s are actually defined. The function code-char knows that certain ranges of code values (notably #xd800 - #xddff ) will never be valid character codes and will return nil for arguments in that range, but may return a non- nil value (an undefined/non-standard character object) for other unassigned code values.

All characters and strings in Clozure CL fully support Unicode by using UTF-32. There is only one character type and one string type in Clozure CL. There has been a lot of discussion about this decision which can be found by searching the openmcl-devel archives at http://clozure.com/pipermail/openmcl-devel/ . Suffice it to say that we decided that the simplicity and speed advantages of only supporting UTF-32 outweigh the space disadvantage.

If true, include emacs-style lockfiles (symbolic links of the form .#something ) in the output. Defaults to nil .

A function of one argument (a pathname) which should return true if the pathname should be included in the output.

If true, includes the truenames of symbolic or hard links in the output; if false, includes the link filenames without attempting to resolve them. Defaults to t .

If true, includes files and directories whose names start with a dot character in the output. (But note that entries named “ . ” or “ .. ” are never included.) Defaults to t .

Returns the name of the encoding to be used in with-filename-cstrs . The default is nil , which means to use :iso-8859-1. It may be changed with setf .

On non-Darwin and non-Windows systems, with-filename-cstrs calls pathname-encoding-name to determine the encoding to use.

Various operating systems have different conventions for how they expect native pathname strings to be encoded. Darwin expects then to be decomposed UTF-8. The Unicode variants to Windows file-handling functions expect UTF-16. Other systems just treat them as opaque byte sequences. This macro ensures that the correct encoding is used, whatever the host operating system.

For example, one might use this macro in the following way:

Executes forms in an environemt in which each var is bound to a stack-allocated foreign pointer which refers to a C-style string suitable for passing to foreign code which expects a filename argument.

Lisp strings are not interchangable with C strings. Clozure CL provides a reasonably straightforward way to translate a lisp native namestring into a C-style string suitable for passing to a foreign function.

For example, suppose that p is a pathname made by (make-pathname :name "a.b" :type "c") . Then, (native-translated-namestring p) evaluates to "a.b.c". By contrast, (namestring p) evaluates to "a\\.b.c".

This function returns a namestring that represents a pathname using the native conventions of the operating system. Any quoting or escaping of special characters will be removed.

To get a native namestring suitable for passing to an operating system command, use the function native-translated-namestring .

When generating a namestring from a pathname object (as happens, for example, when printing a pathname), Clozure CL tries to avoid some potential ambiguity by escaping characters that might otherwise be used to separate pathname components. The character used to quote or escape the separators is a backlash on Unix systems, and a #\> character on Windows. So, for example, “ a\\.b.c ” has name “a.b” and type “c”, whereas “a.b\\.c” has name “a” and type “b.c”.

When translating a namestring into a pathname object, most implementations seem to follow the convention that a dot character in the namestring separates the pathname-name and the pathname-type . When there is more than one dot in involved, or when dots appear at the beginning or end of the namestrings, what to do is less clear: does “ .emacs ” describe a pathname whose name is nil and whose type is emacs or something else? Similarly, given “ a.b.c ”, the question is which parts are parsed as the pathname name, and which are parsed as the pathname type?

The syntax of namestrings is implementation-defined in Common Lisp. Portable programs cannot assume much of anything about them. (See section 19.1.1 of the Common Lisp standard for more information.)

The ccl logical host is meant to refer to the ccl directory. It is used for a variety of purposes by Clozure CL including: locating Clozure CL source code, require and provide , accessing foreign function information, and the Clozure CL build process. It is set to the value of the environment variable CCL_DEFAULT_DIRECTORY , if that variable exists. Otherwise, it is set to the directory containing the heap image file.

Leading tilde (~) characters in physical pathname namestrings are expanded in the way that most shells do: “ ~user/... ” can be used to refer to an absolute pathname rooted at the home directory of the user named “user”, and “ ~/... ” can be used to refer to an absolute pathname rooted at the home directory of the current user.

A list of strings that denotes the command-line arguments that remain after the lisp has processed and removed arguments that it interprets itself.

A list of strings decoded from the argument vector passed to the lisp process (as argv[] ) by the operating system. The foreign C strings are assumed to be UTF-8 encoded.

If the :error-handler keyword argument is supplied, it must be a function of one argument, the condition, that will be called if an error occurs when preparing to quit. The error-handler function should exit the lisp.

Alternatively, exit may be a function of no arguments. This function will be called instead of _exit() to exit the lisp.

Cleanly exit from lisp. If exit is a value of type (signed-byte 32) , that value will be passed to the C library function _exit() as the status code. A value of nil is treated as a zero.

If sig is outside the range of valid signals, or reserved by Clozure CL for its own use, an error is signaled. An error is always signaled on Windows systems.

Wait for the signal with signal number sig to be received, or until duration seconds have elapsed. If duration is nil , wait for an indeterminate very long time (many years).

This function sets the operating system environment variable denoted by the string name to the string value . If the environment variable is successfully set, 0 is returned. Otherwise, a platform-specific integer error code is returned.

This function looks up the value of the environment variable denoted by the string name and returns its value as a string. If there is no such envionment variable, then nil is returned.

Executes body with var bound to the result of applying make-socket to make-socket-args . The socket gets closed on exit.

Close socket , releasing the operating system resources associated with it. Normally, any pending buffered I/O will be finished up before closing, but if :abort is t , any pending I/O will be aborted. Note that for listener and udp sockets, there is never any buffered I/O to clean up, so the value of :abort is effectively ignored.

Returns a string describing the context where the error socket-error happened. On Linux, this is the name of the system call which returned the error.

Returns a symbol representing the socket error code contained in socket-error . It will be one of :address-in-use , :connection-aborted , :no-buffer-space , :connection-timed-out , :connection-refused , :host-unreachable , :host-down , :network-down , :address-not-available , :network-reset , :connection-reset , :shutdown , :access-denied , or :unknown .

This class is a representation of a socket endpoint address. Instances of this class are used to encapsulate the host and port of an IP socket endpoint or the filename of a file socket. They can be created by applications from a possibly symbolic address representation by the resolve-address function.

This function returns :stream if socket is a tcp-stream or listener-socket. If the socket is a udp-socket, socket-type will return :datagram.

Returns the format of socket as specified by the :format argument to make-socket.

This function examines socket and returns :active for a tcp-stream, :passive for listener-socket, and nil for a udp-socket.

This function returns the port number of the given socket-address . This function is available only for :internet and :internet6 socket addresses.

Returns the host portion of the given socket-address . For :internet addresses, this is a 32-bit integer. For :internet6 addresses, a vector of 16 bytes returned. For :file addresses, it is the file name string.

Returns :internet, :internet6 or :file, as appropriate for thing , which should be a socket or socket-address.

Returns the remote port number of socket , or NIL if socket is not connected.

Returns the 32-bit unsigned IPv4 address of the remote host, or nil if socket is not connected.

Returns the native OS's representation of socket , or nil if the socket is closed. On Unix, this will be a file descriptor. Note that it is rather dangerous to mess around with tcp-stream file descriptors, as there is all sorts of buffering and asynchronous I/O going on above the OS level. listener-socket and udp-socket file descriptors are safer to mess with directly as there is less magic going on.

Shuts down part of a bidirectional connection represented by socket . Typcially socket will be a tcp-stream. One situation where this can be useful is when you need to read responses after sending an end-of-file signal. The keyword argument :direction may be either :input (to disallow further input) or :output (to disallow further output).

The port to send the packet to, in any format acceptable to lookup-port. The default is the remote port specified in the call to make-socket.

The host to send the packet to, in any format acceptable to lookup-hostname. The default is the remote host specified in the call to make-socket.

The remote address to send the packet to, as a ccl::socket-address instance. The default is the remote address specified in the call to make-socket.

A vector containing the data to send. It must be an octet vector.

Indicates that the address of the sender of the data should be returned as a ccl::socket-address instance rather than as separate host and port values.

Specifies the start offset into the buffer at which data is to be stored. The default is 0.

If true, the subsequence of the buffer corresponding only to the data read in is extracted and returned as the first value. If false (the default) the original buffer is returned even if it is only partially filled.

If specified, must be an octet vector which will be used to read in the data. If not specified, a new buffer will be created (of type determined by socket-format).

Maximum number of bytes to read. If the packet is larger than this, any extra bytes are discarded.

The 32-bit unsigned IPv4 address or the 16 byte IPv6 addresss of the sender of the data

If :want-socket-address-p is nil , which is the default, four values are returned:

Reads a UDP packet from socket . If no packets are available, waits for a packet to arrive.

Finds the numeric port number for the specified port and protocol . port can be a string such as “http”, a symbol such as :http , or a port number. Note that strings are case-sensitive. Symbol names are converted to lower-case before lookup. Protocol must be one of “tcp” or “udp”.

Acceptable formats for host-spec include a host name string such as “www.clozure.com”, a dotted address string such as “192.168.0.1”, or a 32-bit unsigned IPv4 address such as 3232235521.

Converts ipaddr , a 32-bit unsigend integer, into a host name string. The keyword argument :ignore-cache is ignored (it is accepted for compatibility with Franz Allegro CL).

This function converts ipaddr , an integer representing an IPv4 host, into a dotted quad string. If :values is true, instead of a dotted quad string, it returns the four octets of the address as multiple values.

Converts dotted , which should be a dotted quad string such as “192.168.0.1”, into a integer representation. If :errorp is true, an error is signaled if dotted is invalid. Otherwise, nil is returned.

If this argument is set to a true value, which is the default, an error is signalled if the given host and/or port combination did not yield any matches. If it is passed as NIL, the function returns NIL if no addresses matched the supplied arguments.

If this argument is set to a true value, which is the default, only the first matching address is returned. If it is passed as NIL, all matching addresses are returned as a list.

If this argument is true, no service name lookups will be performed for the port address. A numeric port number must be passed in this case.

If this argument is true, no host name lookups will be performed for the host address. A numeric address literal must be passed in this case.

Specifies the address family that should be returned, can be specified as either :internet or :internet6. If it is specified, only addresses of that family are returned.

Specifies how the returned ccl::socket-address instances will be used. If :active is passed, which is the default, the host address will default to the address of the loopback interface of the local host if not specified. When :passive is used, the host address will default to the wildcard address for the given address family. This parameter has no effect if the :host parameter is used.

Service type for port lookups, can be either :stream for TCP services or :datagram for UDP. Defaults to :stream.

Specification of the port. This can be either a service name such as “http” or a port number.

Specification of the host, as a string. This can be either a host name such as “clozure.com” or any of the literal address forms accepted by getaddrinfo().

Converts a host and/or port specification to one or more ccl::socket-address instances. This function uses the getaddrinfo() system function underneath which knows how to translate all standard address and port formats and appropriately orders adresses for hosts with multiple addresses. It returns the best matching translation or, if the :singlep is false, all matching translations for the given parameter combination.

If :wait is t , and there are no connections waiting to be accepted, the function wait until one arrives. Otherwise, accept-connection will return nil immediately.

Extracts the first connection on the queue of pending connections for socket , accepts it (i.e. completes the connection startup protocol), and returns a new tcp-stream or file-socket-stream representing the newly established connection. The tcp stream inherits any properties of the listener socket that are relevant (e.g. :keepalive , :nodelay , and so forth.) The original listener socket continues to be open listening for more connections, so you can call accept-connection on it again.

Creates and returns a new socket. For :passive sockets, the :local-address, :local-port or :local-filename arguments are required, depending on the type of the socket. For :active sockets, either the :remote-address, the :remote-host and :remote-port, or the :remote-filename arguments must be present, depending on the socket type.

Specifies an absolute time in internal-time-units. If an I/O operation on the stream does not complete before the deadline then a COMMUNICATION-DEADLINE-EXPIRED error is signalled. A deadline takes precedence over any input/output timeouts that may be set. (see Stream Timeouts and Deadlines )

When non-nil, any resulting socket stream will be closed when the GC can prove that the stream is unreferenced. This is done via CCL's termination mechanism [TODO add xref].

The number of seconds before a connection attempt times out. [TODO: what are acceptable values?] If a connection attempt takes longer than the specified number of seconds, a socket-error is signalled. This can be useful if the specified interval is shorter than the interval that the OS's socket layer imposes, which is sometimes a minute or two.

The number of seconds before an output operation times out. Must be a real number between zero and one million. If an output operation takes longer than the specified number of seconds, an output-timeout error is signalled. (see Stream Timeouts and Deadlines )

The number of seconds before an input operation times out. Must be a real number between zero and one million. If an input operation takes longer than the specified number of seconds, an input-timeout error is signalled. (see Stream Timeouts and Deadlines )

For a listener socket, specifies the number of connections which can be pending but not accepted. The default is 5, which is also the maximum on some operating systems.

If specified and non-nil, should be the number of seconds the OS is allowed to wait for data to be pushed through when a close is done. Only relevant for TCP sockets.

If true, disables Nagle's algorithm, which tries to minimize TCP packet fragmentation by introducing transmission delays in the absence of replies. Try setting this if you are using a protocol which involves sending a steady stream of data with no replies and are seeing significant degradations in throughput.

If true, allows the reuse of local ports in listener sockets, overriding some TCP/IP protocol specifications. You will need this if you are debugging a server..

For file-listener-sockets, specifies the name of a file in the local filesystem which is used to name a UNIX-domain socket. The actual filesystem file should not previously exist when the file-listener-socket is created; its parent directory should exist and be writable by the caller. The file used to name the socket will be deleted when the file-listener-socket is closed.

Specify a local port for a socket. Most useful for listener sockets, where it is the port on which the socket will listen for connections.

Allows you to specify a local host address for a listener or UDP socket, for the case where you want to restrict connections to those coming to a specific local address for security reasons.

Allows you to specify a local address for a listener or UDP socket, for the case where you want to restrict connections to those coming to a specific local address for security reasons.

For file-socket streams, it specifies the name of a file in the local filesystem (e.g., NOT mounted via NFS, AFP, SMB, ...) which names and controls access to a UNIX-domain socket.

For TCP streams, it specifies the port to connect to (in any format acceptable to resolve-address). Ignored for listener sockets. For UDP sockets, it can be used to specify a default port for subsequent calls to for subsequent calls to send-to or receive-from.

For TCP streams, it specifies the host to connect to (in any format acceptable to resolve-address). Ignored for listener sockets. For UDP sockets, it can be used to specify a default host for subsequent calls to send-to or receive-from.

For TCP streams, it specifies the socket address to connect to, specified as socket-address instance. Ignored for listener sockets. For UDP sockets, it can be used to specify a default address for subsequent calls to send-to or receive-from.

One of :text (the default), :binary, or :bivalent. This argument is ignored for :stream sockets for now, as :stream sockets are currently always bivalent (i.e. they support both character and byte I/O). For :datagram sockets, this argument is ignored (the format of a datagram socket is always :binary).

This argument is currently ignored (it is accepted for compatibility with Franz Allegro).

This argument is only relevant to sockets of type :stream. One of :active (the default) to request a :passive to request a file or TCP listener socket.

One of :stream (the default) to request a connection-oriented socket, or :datagram to request a connectionless socket. The default is :stream.

The address/protocol family of this socket. Currently, :internet (the default), meaning IPv4, :internet6, meaning IPv6, and :file, referring to UNIX domain addresses, are supported.

A socket representing a packet-based UDP/IP connection. A udp-socket supports I/O but it is not a stream. Instead, you must use the special functions send-to and receive-from to read and write to it. Created by (make-socket :type :datagram ...)

A passive socket used to listen for incoming UNIX domain connections named by a file in the local filesystem. A listener-socket is not a stream. It doesn't support I/O. It can only be used to create new file-socket-streams by accept-connection. Created by (make-socket :address-family :file :type :stream :connect :passive ...)

A passive socket used to listen for incoming TCP/IP connections on a particular port. A listener-socket is not a stream. It doesn't support I/O. It can only be used to create new tcp-streams by accept-connection. Created by (make-socket :type :stream :connect :passive ...)

A buffered bi-directional stream over a "UNIX domain" connection. file-socket-stream is a subclass of stream, and you can read and write to it using all the usual stream functions. Created by (make-socket :address-family :file :type :stream :connect :active ...) or by (accept-connection ...),

A buffered bi-directional stream over a TCP/IP connection. tcp-stream is a subclass of stream, and you can read and write to it using all the usual stream functions. Created by (make-socket :address-family :internet :type :stream :connect :active ...) or by (accept-connection ...).

Clozure CL supports three types of sockets: TCP sockets, UDP sockets, and Unix-domain sockets. This should be enough for all but the most esoteric network situations. All sockets are created by make-socket . The type of socket depends on the arguments to it, as follows:

All symbols mentioned in this chapter are exported from the CCL package. As of version 0.13, these symbols are additionally exported from the OPENMCL-SOCKET package.

IPv6 is supported by the :internet6 address family. Applications should use the resolve-address function to translate host and port specifications to socket addresses. While host and port numbers can still be dealt with separately, it is preferable to use ccl::socket-address instances to specify socket endpoints for unified parsing of string representations and printing.

Clozure CL supports the socket abstraction for interprocess communication. A socket represents a connection to another process, typically (but not necessarily) a TCP/IP network connection to a client or server running on some other machine on the network.

A process can't successfully join itself, and only one process can successfully receive notification of another process's termination.

Waits for the specified process to terminate. If the process terminates "normally" (if its initial function returns), returns the values that that initial function returnes. If the process does not terminate normally (e.g., if it's terminated via process-kill and a default argument is provided, returns the value of that default argument. If the process doesn't terminate normally and no default argument is provided, signals an error.

The values returned by the specified process's initial function if that function returns, or the value of the default argument, otherwise.

A default value to be returned if the specified process doesn't exit normally.

Waits for a specified process to complete and returns the values that that process's initial function returned.

The command yields control of terminal input to the process p , which must have used with-terminal-input to request access to the terminal input stream.

:Y is a toplevel command, not a function. As such, it can only be used interactively, and only from the initial process.

a lisp process (thread), designated either by an integer which matches its process-serial-number , or by a string which is equal to its process-name .

Controls how attempts to obtain ownership of terminal input are made. When NIL, a message is printed on *TERMINAL-IO*; it's expected that the user will later yield control of the terminal via the :Y toplevel command. When T, a BREAK condition is signaled in the owning process; continuing from the break loop will yield the terminal to the requesting process (unless the :Y command was already used to do so in the break loop.)

Requests exclusive read access to the standard terminal stream, *terminal-io* . Executes body in an environment with that access.

Executes its body in an environment with exclusive read access to the terminal.

process-input-wait has a timeout parameter, and process-output-wait does not. This inconsistency should probably be corrected.

If process-output-wait is called on a network socket which has not yet established a connection, it will wait until the connection is established. This is an important use, often overlooked.

Wait until output is possible on fd or until timeout , if it is not NIL, has been exceeded. This uses the select() system call, and is generally a fairly efficient way of blocking while waiting to output.

either NIL or a time interval in milliseconds. Must be a non-negative integer. The default is NIL.

a file descriptor, which is a non-negative integer used by the OS to refer to an open file, socket, or similar I/O connection. See stream-device .

process-input-wait has a timeout parameter, and process-output-wait does not. This inconsistency should probably be corrected.

Note that it's possible to read without blocking if the file is at its end - although, of course, the read will return zero bytes.
