• Data Types
  • Integers
  • Floats
    • IEEE Special Values
    • Negative Zero
    • Denormalized Floats
    • Floating Point Exceptions
    • Floating Point Rounding Mode
      • Warning:
    • Precision Control
      • Warning:
    • Accessing the Floating Point Modes
  • Characters
  • Array Initialization
  • Hash tables
• Default Interrupts for Lisp
• Implementation-specific Packages
• Hierarchical Packages
  • Introduction
  • Relative package names
  • Compatibility with ANSI Common Lisp
    • Changes to cl:find-package
    • Using hierarchical packages without modifying cl:find-package
• Package locks
  • Rationale
  • Disabling package locks
• The Editor
• Garbage Collection
  • GC Parameters
  • Generational GC
  • Weak Pointers
  • Finalization
• Describe
• The Inspector
  • The Graphical Interface
  • The TTY Inspector
• Load
• The Reader
  • Reader Extensions
  • Reader Parameters
• Stream Extensions
• Simple Streams
• Running Programs from Lisp
  • Process Accessors
• Saving a Core Image
• Pathnames
  • Unix Pathnames
  • Wildcard Pathnames
  • Logical Pathnames
  • Search Lists
  • Predefined Search-Lists
  • Search-List Operations
  • Search List Example
• Filesystem Operations
  • Wildcard Matching
  • File Name Completion
  • Miscellaneous Filesystem Operations
• Time Parsing and Formatting
• Random Number Generation
  • Original Generator
  • New Generator
  • MT-19987 Generator
• Lisp Threads
• Lisp Library
• Generalized Function Names
• CLOS
  • Primary Method Errors
  • Slot Type Checking
  • Slot Access Optimization
    • slot-boundp Declaration
    • inline Declaration
    • Automatic Method Recompilation
  • Inlining Methods in Effective Methods
  • Effective Method Precomputation
  • Sealing
  • Method Tracing and Profiling
  • Misc
• Differences from ANSI Common Lisp
  • Extensions
• Function Wrappers
• Dynamic-Extent Declarations
  • &rest argument lists
  • Closures
  • list, list*, and cons
• Modular Arithmetic

[Constant]
extensions:short-float-negative-infinity    

[Constant]
extensions:single-float-positive-infinity    

[Constant]
extensions:single-float-negative-infinity    

[Constant]
extensions:double-float-positive-infinity    

[Constant]
extensions:double-float-negative-infinity    

[Constant]
extensions:long-float-positive-infinity    

[Constant]
extensions:long-float-negative-infinity    

The values of these constants are the IEEE positive and negative infinity objects for each float format.

This function returns true if x is an IEEE float infinity (of either sign.) x must be a float.

[Function]
extensions:float-trapping-nan-p x    

float-nan-p returns true if x is an IEEE NaN (Not A Number) object. float-trapping-nan-p returns true only if x is a trapping NaN. With either function, x must be a float.

This function returns true if x is a denormalized float. x must be a float.

:underflow

This exception occurs when the result of an operation is too small to be represented as a normalized float in its format. If trapping is enabled, the floating-point-underflow condition is signalled. Otherwise, the operation results in a denormalized float or zero.

:overflow

This exception occurs when the result of an operation is too large to be represented as a float in its format. If trapping is enabled, the floating-point-overflow exception is signalled. Otherwise, the operation results in the appropriate infinity.

:inexact

This exception occurs when the result of a floating point operation is not exact, i.e. the result was rounded. If trapping is enabled, the extensions:floating-point-inexact condition is signalled. Otherwise, the rounded result is returned.

:invalid

This exception occurs when the result of an operation is ill-defined, such as (/ 0.0 0.0). If trapping is enabled, the extensions:floating-point-invalid condition is signalled. Otherwise, a quiet NaN is returned.

:divide-by-zero

This exception occurs when a float is divided by zero. If trapping is enabled, the divide-by-zero condition is signalled. Otherwise, the appropriate infinity is returned.

:nearest

In this mode, the inexact results are rounded to the nearer of the two possible result values. If the neither possibility is nearer, then the even alternative is chosen. This form of rounding is also called ``round to even'', and is the form of rounding specified for the Common Lisp round function.

:positive-infinity

This mode rounds inexact results to the possible value closer to positive infinity. This is analogous to the Common Lisp ceiling function.

:negative-infinity

This mode rounds inexact results to the possible value closer to negative infinity. This is analogous to the Common Lisp floor function.

:zero

This mode rounds inexact results to the possible value closer to zero. This is analogous to the Common Lisp truncate function.

Warning:

:24-bit

In this mode, all basic arithmetic operations like addition, subtraction, multiplication, and division, are rounded after each operation as if both the operands were IEEE single precision numbers.

:53-bit

In this mode, rounding is performed as if the operands and results were IEEE double precision numbers.

:64-bit

In this mode, the default, rounding is performed on the full IEEE extended double precision format.

Warning:

[Function]
extensions:get-floating-point-modes    

The keyword arguments to set-floating-point-modes set various modes controlling how floating point arithmetic is done:

:traps

A list of the exception conditions that should cause traps. Possible exceptions are :underflow, :overflow, :inexact, :invalid and :divide-by-zero. Initially all traps except :inexact are enabled. See section 2.1.2.4.

:rounding-mode

The rounding mode to use when the result is not exact. Possible values are :nearest, :positive-infinity, :negative-infinity and :zero. Initially, the rounding mode is :nearest. See the warning in section 2.1.2.5 about use of other rounding modes.

:current-exceptions, :accrued-exceptions

Lists of exception keywords used to set the exception flags. The current-exceptions are the exceptions for the previous operation, so setting it is not very useful. The accrued-exceptions are a cumulative record of the exceptions that occurred since the last time these flags were cleared. Specifying () will clear any accrued exceptions.

:fast-mode

Set the hardware's ``fast mode'' flag, if any. When set, IEEE conformance or debuggability may be impaired. Some machines may not have this feature, in which case the value is always nil. Sparc platforms support a fast mode where denormal numbers are silently truncated to zero.

:precision-control

On the x86 architecture, you can set the precision of the arithmetic to :24-bit, :53-bit, or :64-bit mode, corresponding to IEEE single precision, double precision, and extended double precision.

If a keyword argument is not supplied, then the associated state is not changed.

get-floating-point-modes returns a list representing the state of the floating point modes. The list is in the same format as the keyword arguments to set-floating-point-modes, so apply could be used with set-floating-point-modes to restore the modes in effect at the time of the call to get-floating-point-modes.

body is executed with the selected floating-point exceptions given by traps masked out (disabled). traps should be a list of possible floating-point exceptions that should be ignored. Possible values are :underflow, :overflow, :inexact, :invalid and :divide-by-zero.

This is equivalent to saving the current traps from get-floating-point-modes, setting the floating-point modes to the desired exceptions, running the body, and restoring the saved floating-point modes. The advantage of this macro is that it causes less consing to occur.

Some points about the with-float-traps-masked:

• Two approaches are available for detecting FP exceptions:
  1. enabling the traps and handling the exceptions
  2. disabling the traps and either handling the return values or checking the accrued exceptions.
  Of these the latter is the most portable because on the alpha port it is not possible to enable some traps at run-time.
  
  
• To assist the checking of the exceptions within the body any accrued exceptions matching the given traps are cleared at the start of the body when the traps are masked.
  
  
• To allow the macros to be nested these accrued exceptions are restored at the end of the body to their values at the start of the body. Thus any exceptions that occurred within the body will not affect the accrued exceptions outside the macro.
  
  
• Note that only the given exceptions are restored at the end of the body so other exception will be visible in the accrued exceptions outside the body.
  
  
• On the x86, setting the accrued exceptions of an unmasked exception would cause a FP trap. The macro behaviour of restoring the accrued exceptions ensures than if an accrued exception is initially not flagged and occurs within the body it will be restored/cleared at the exit of the body and thus not cause a trap.
  
  
• On the x86, and, perhaps, the hppa, the FP exceptions may be delivered at the next FP instruction which requires a FP wait instruction (x86::float-wait) if using the lisp conditions to catch trap within a handler-bind. The handler-bind macro does the right thing and inserts a float-wait (at the end of its body on the x86). The masking and noting of exceptions is also safe here.
  
  
• The setting of the FP flags uses the (floating-point-modes) and the (set (floating-point-modes)...) VOPs. These VOPs blindly update the flags which may include other state. We assume this state hasn't changed in between getting and setting the state. For example, if you used the FP unit between the above calls, the state may be incorrectly restored! The with-float-traps-masked macro keeps the intervening code to a minimum and uses only integer operations.

---

ASCII		Lisp
Name	Code	Name	1.5exAlternatives
nul	0	#\NULL	#\NUL
bel	7	#\BELL
bs	8	#\BACKSPACE	#\BS
tab	9	#\TAB
lf	10	#\NEWLINE	#\NL	#\LINEFEED	#\LF
ff	11	#\VT	#\PAGE	#\FORM
cr	13	#\RETURN	#\CR
esc	27	#\ESCAPE	#\ESC	#\ALTMODE	#\ALT
sp	32	#\SPACE	#\SP
del	127	#\DELETE	#\RUBOUT

Table 2.1: Characters recognized by CMUCL

---

The hash-table-test-name must be a symbol. The test-function takes two objects and returns true iff they are the same. The hash-function takes one object and returns two values: the (positive fixnum) hash value and true if the hashing depends on pointer values and will have to be redone if the object moves.

To create a hash-table using this new ``test'' (really, a test/hash-function pair), use (make-hash-table :test hash-table-test-name ...).

Note that it is the hash-table-test-name that will be returned by the function hash-table-test, when applied to a hash-table created using this function.

This function updates *hash-table-tests*, which is now internal.

SIGINT (Ctrl-c)

causes Lisp to enter a break loop. This puts you into the debugger which allows you to look at the current state of the computation. If you proceed from the break loop, the computation will proceed from where it was interrupted.

SIGQUIT (Ctrl-L)

causes Lisp to do a throw to the top-level. This causes the current computation to be aborted, and control returned to the top-level read-eval-print loop.

SIGTSTP (Ctrl-z)

causes Lisp to suspend execution and return to the Unix shell. If control is returned to Lisp, the computation will proceed from where it was interrupted.

SIGILL, SIGBUS, SIGSEGV, and SIGFPE

cause Lisp to signal an error.

alien, c-call

Export the features of the Alien foreign data structure facility (see section 8.)

pcl

This package contains PCL (Portable CommonLoops), which is a portable implementation of CLOS (the Common Lisp Object System.) This implements most (but not all) of the features in the CLOS chapter of Common Lisp: The Language II.

clos-mop (mop)

This package contains an implementation of the CLOS Metaobject Protocol, as per the book The Art of the Metaobject Protocol.

debug

The debug package contains the command-line oriented debugger. It exports utility various functions and switches.

debug-internals

The debug-internals package exports the primitives used to write debuggers. See section 11.

extensions (ext)

The extensions packages exports local extensions to Common Lisp that are documented in this manual. Examples include the save-lisp function and time parsing.

hemlock (ed)

The hemlock package contains all the code to implement Hemlock commands. The hemlock package currently exports no symbols.

hemlock-internals (hi)

The hemlock-internals package contains code that implements low level primitives and exports those symbols used to write Hemlock commands.

keyword

The keyword package contains keywords (e.g., :start). All symbols in the keyword package are exported and evaluate to themselves (i.e., the value of the symbol is the symbol itself).

profile

The profile package exports a simple run-time profiling facility (see section 5.14).

common-lisp (cl)

The common-lisp package exports all the symbols defined by Common Lisp: The Language and only those symbols. Strictly portable Lisp code will depend only on the symbols exported from the common-lisp package.

unix

This package exports system call interfaces to Unix (see section 6).

system (sys)

The system package contains functions and information necessary for system interfacing. This package is used by the lisp package and exports several symbols that are necessary to interface to system code.

xlib

The xlib package contains the Common Lisp X interface (CLX) to the X11 protocol. This is mostly Lisp code with a couple of functions that are defined in C to connect to the server.

wire

The wire package exports a remote procedure call facility (see section 9).

stream

The stream package exports the public interface to the simple-streams implementation (see section 2.13).

• Reduce collisions with user-defined packages: it is a well-known problem that package names used by the Lisp implementation and those defined by users can easily conflict. The intent of hierarchical packages is to reduce such conflicts to a minimum.
  
  
• Improve modularity: the current organization of packages in various implementations has grown over the years and appears somewhat random. Organizing future packages into a hierarchy will help make the intention of the implementation more clear.
  
  
• Foster growth in Common Lisp programs, or modules, available to the CL community: the Perl and Java communities are able to contribute code to repositories, with minimal fear of collision, because of the hierarchical nature of the name spaces used by the contributed code. We want the Lisp community to benefit from shared modules in the same way.

---

relative name	current package	absolute name of referenced package
foo	any	foo
foo.bar	any	foo.bar
.foo	mypack	mypack.foo
.foo.bar	mypack	mypack.foo.bar
..foo	mypack.bar	mypack.foo
..foo.baz	mypack.bar	mypack.foo.baz
...foo	mypack.bar.baz	mypack.foo
.	mypack.bar.baz	mypack.bar.baz
..	mypack.bar.baz	mypack.bar
...	mypack.bar.baz	mypack

Table 2.2: Examples of hierarchical packages

---

1. All packages in the hierarchy must exist.
   
   
2. Warning about nicknames: Unless you provide nicknames for your hierarchical packages (and we recommend against doing so because the number gets quite large), you can only use the names supplied. You cannot mix in nicknames or alternate names. cl-user (and user) are nicknames of the common-lisp-user package. Consider the following:

      (defpackage :cl-user.foo)
   

   When the current package (the value of the variable *package*) is common-lisp-user, you might expect .foo to refer to cl-user.foo, but it does not. It refers to the non-existent package common-lisp-user.foo. Note that the purpose of nicknames is to provide shorter names in place of the longer names that are designed to be fully descriptive. The hope is that hierarchical packages makes longer names unnecessary and thus makes nicknames unnecessary.
   
   
3. Multiple dots can only appear at the beginning of a package name. For example, foo.bar..baz does not mean foo.baz -- it is invalid. (Of course, it is perfectly legal to name a package foo.bar..baz, but cl:find-package will not process such a name to find foo.baz in the package hierarchy.)

   (defpackage :my.foo.bar
     #-relative-package-names (:nicknames #:..bar)
     ...)

   (defpackage :my.foo.baz
     #-relative-package-names (:nicknames #:..baz)
     ...)

CL-USER> (defmacro 1+ (x) (* x 2))
Attempt to modify the locked package COMMON-LISP, by defining macro 1+
   [Condition of type LISP::PACKAGE-LOCKED-ERROR]

Restarts:
  0: [continue      ] Ignore the lock and continue
  1: [unlock-package] Disable the package's definition-lock then continue
  2: [unlock-all    ] Unlock all packages, then continue
  3: [abort         ] Return to Top-Level.

CL-USER> (defun ext:gc () t)
Attempt to modify the locked package EXTENSIONS, by redefining function GC
   [Condition of type LISP::PACKAGE-LOCKED-ERROR]

Restarts:
  0: [continue      ] Ignore the lock and continue
  1: [unlock-package] Disable package's definition-lock, then continue
  2: [unlock-all    ] Disable all package locks, then continue
  3: [abort         ] Return to Top-Level.

CL-USER> (unexport 'load-foreign :ext)
Attempt to modify the locked package EXTENSIONS, by unexporting symbols LOAD-FOREIGN
   [Condition of type lisp::package-locked-error]

Restarts:
  0: [continue      ] Ignore the lock and continue
  1: [unlock-package] Disable package's lock then continue
  2: [unlock-all    ] Unlock all packages, then continue
  3: [abort         ] Return to Top-Level.

   (setf (ext:package-lock (find-package "UNIX")) nil)
   (setf (ext:package-definition-lock (find-package "UNIX")) nil)

This function is an accessor for a package's structural lock, which protects it against modifications to its list of exported symbols.

This function is an accessor for a package's definition-lock, which protects symbols in that package from redefinition. As well as protecting the symbol's fdefinition from change, attempts to change the symbol's definition using defstruct, defclass or deftype will be trapped.

This macro can be used to execute forms with all package locks (both structure and definition locks) disabled.

This function disables both structure and definition locks on all currently defined packages. Note that package locks are reset when CMUCL is restarted, so the effect of this function is limited to the current session.

heney]extensions:gc&optional verbose-p

This function runs the garbage collector. If ext:*gc-verbose* is non-nil, then it invokes ext:*gc-notify-before* before GC'ing and ext:*gc-notify-after* afterwards.

verbose-p indicates whether GC statistics are printed or not.

This function inhibits automatic garbage collection. After calling it, the system will not GC unless you call ext:gc or ext:gc-on.

This function reinstates automatic garbage collection. If the system would have GC'ed while automatic GC was inhibited, then this will call ext:gc.

CMUCL automatically GC's whenever the amount of memory allocated to dynamic objects exceeds the value of an internal variable. After each GC, the system sets this internal variable to the amount of dynamic space in use at that point plus the value of the variable ext:*bytes-consed-between-gcs*. The default value is 2000000.

This variable controls whether ext:gc invokes the functions in ext:*gc-notify-before* and ext:*gc-notify-after*. If *gc-verbose* is nil, ext:gc foregoes printing any messages. The default value is T.

This variable's value is a function that should notify the user that the system is about to GC. It takes one argument, the amount of dynamic space in use before the GC measured in bytes. The default value of this variable is a function that prints a message similar to the following:

   [GC threshold exceeded with 2,107,124 bytes in use.  Commencing GC.]

This variable's value is a function that should notify the user when a GC finishes. The function must take three arguments, the amount of dynamic spaced retained by the GC, the amount of dynamic space freed, and the new threshold which is the minimum amount of space in use before the next GC will occur. All values are byte quantities. The default value of this variable is a function that prints a message similar to the following:

    [GC completed with 25,680 bytes retained and 2,096,808 bytes freed.]
    [GC will next occur when at least 2,025,680 bytes are in use.]
  

This variable's value is either a function of one argument or nil. When the system has triggered an automatic GC, if this variable is a function, then the system calls the function with the amount of dynamic space currently in use (measured in bytes). If the function returns nil, then the GC occurs; otherwise, the system inhibits automatic GC as if you had called ext:gc-off. The writer of this hook is responsible for knowing when automatic GC has been turned off and for calling or providing a way to call ext:gc-on. The default value of this variable is nil.

[Variable]
extensions:*after-gc-hooks*

These variables' values are lists of functions to call before or after any GC occurs. The system provides these purely for side-effect, and the functions take no arguments.

encgc]extensions:gc&key :verbose :gen :full

This function runs the garbage collector. If ext:*gc-verbose* is non-nil, then it invokes ext:*gc-notify-before* before GC'ing and ext:*gc-notify-after* afterwards.

verbose

Print GC statistics if non-NIL.

gen

The number of generations to be collected.

full

If non-NIL, a full collection of all generations is performed.

Returns statistics about the generation, as multiple values:

1. Bytes allocated in this generation
2. The GC trigger for this generation. When this many bytes have been allocated, a GC is started automatically.
3. The number of bytes consed between GCs.
4. The number of GCs that have been done on this generation. This is reset to zero when the generation is raised.
5. The trigger age, which is the maximum number of GCs to perform before this generation is raised.
6. The total number of bytes allocated to this generation.
7. Average age of the objects in this generations. The average age is the cumulative bytes allocated divided by current number of bytes allocated.

Sets the GC trigger value for the specified generation.

Sets the GC trigger age for the specified generation.

Sets the minimum average memory age for the specified generation. If the computed memory age is below this, GC is not performed, which helps prevent a GC when a large number of new live objects have been added in which case a GC would usually be a waste of time.

[Function]
extensions:weak-pointer-value weak-pointer

make-weak-pointer returns a weak pointer to an object. weak-pointer-value follows a weak pointer, returning the two values: the object pointed to (or nil if broken) and a boolean value which is nil if the pointer has been broken, and true otherwise.

This function registers object for finalization. function is called with no arguments when object is reclaimed. Normally function will be a closure over the underlying state that needs to be freed, e.g. the unix file descriptor in the fd-stream case. Note that function must not close over object itself, as this prevents the object from ever becoming garbage.

This function cancel any finalization request for object.

The describe function prints useful information about object on stream, which defaults to *standard-output*. For any object, describe will print out the type. Then it prints other information based on the type of object. The types which are presently handled are:

hash-table

describe prints the number of entries currently in the hash table and the number of buckets currently allocated.

function

describe prints a list of the function's name (if any) and its formal parameters. If the name has function documentation, then it will be printed. If the function is compiled, then the file where it is defined will be printed as well.

fixnum

describe prints whether the integer is prime or not.

symbol

The symbol's value, properties, and documentation are printed. If the symbol has a function definition, then the function is described.

If there is anything interesting to be said about some component of the object, describe will invoke itself recursively to describe that object. The level of recursion is indicated by indenting output.

The maximum level of recursive description allowed. Initially two.

The number of spaces to indent for each level of recursive description, initially three.

[Variable]
extensions:*describe-print-length*

The values of *print-level* and *print-length* during description. Initially two and five.

inspect calls the inspector on the optional argument object. If object is unsupplied, inspect immediately returns nil. Otherwise, the behavior of inspect depends on whether Lisp is running under X. When inspect is eventually exited, it returns some selected Lisp object.

This function creates a control panel for the Lisp process.

When the graphical interface is loaded, this variable controls whether it is used by inspect and the error system. If the value is :graphics (the default) and the DISPLAY environment variable is defined, the graphical inspector and debugger will be invoked by inspect or when an error is signalled. Possible values are :graphics and tty. If the value is :graphics, but there is no X display, then we quietly use the TTY interface.

U

Move back to the enclosing object. As you descend into the components of an object, a stack of all the objects previously seen is kept. This command pops you up one level of this stack.

Q, E

Return the current object from inspect.

R

Recompute object display, and print again. Useful if the object may have changed.

D

Display again without recomputing.

H, ?

Show help message.

As in standard Common Lisp, this function loads a file containing source or object code into the running Lisp. Several CMU extensions have been made to load to conveniently support a variety of program file organizations. filename may be a wildcard pathname such as *.lisp, in which case all matching files are loaded.

If filename has a pathname-type (or extension), then that exact file is loaded. If the file has no extension, then this tells load to use a heuristic to load the ``right'' file. The *load-source-types* and *load-object-types* variables below are used to determine the default source and object file types. If only the source or the object file exists (but not both), then that file is quietly loaded. Similarly, if both the source and object file exist, and the object file is newer than the source file, then the object file is loaded. The value of the if-source-newer argument is used to determine what action to take when both the source and object files exist, but the object file is out of date:

:load-object

The object file is loaded even though the source file is newer.

:load-source

The source file is loaded instead of the older object file.

:compile

The source file is compiled and then the new object file is loaded.

:query

The user is asked a yes or no question to determine whether the source or object file is loaded.

This argument defaults to the value of ext:*load-if-source-newer* (initially :load-object.)

The contents argument can be used to override the heuristic (based on the file extension) that normally determines whether to load the file as a source file or an object file. If non-null, this argument must be either :source or :binary, which forces loading in source and binary mode, respectively. You really shouldn't ever need to use this argument.

[Variable]
extensions:*load-object-types*

These variables are lists of possible pathname-type values for source and object files to be passed to load. These variables are only used when the file passed to load has no type; in this case, the possible source and object types are used to default the type in order to determine the names of the source and object files.

This variable determines the default value of the if-source-newer argument to load. Its initial value is :load-object.

  * (setf *print-readably* nil)
  NIL
  * (make-array '(2 2) :element-type '(signed-byte 8))
  #2A((0 0) (0 0))
  * (setf *print-readably* t)
  T
  * (make-array '(2 2) :element-type '(signed-byte 8))
  #A((SIGNED-BYTE 8) (2 2) ((0 0) (0 0)))
  * (type-of (read-from-string "#A((SIGNED-BYTE 8) (2 2) ((0 0) (0 0)))"))
  (SIMPLE-ARRAY (SIGNED-BYTE 8) (2 2))
  * (setf *print-readably* nil)
  NIL
  * (type-of (read-from-string "#A((SIGNED-BYTE 8) (2 2) ((0 0) (0 0)))"))
  (SIMPLE-ARRAY (SIGNED-BYTE 8) (2 2))

If this variable is t (the default), then the reader merely prints a warning when an extra close parenthesis is detected (instead of signalling an error.)

On streams that support it, this function reads multiple bytes of data into a buffer. The buffer must be a simple-string or (simple-array (unsigned-byte 8) (*)). The argument nbytes specifies the desired number of bytes, and the return value is the number of bytes actually read.

• If eof-error-p is true, an end-of-file condition is signalled if end-of-file is encountered before count bytes have been read.
  
  
• If eof-error-p is false, read-n-bytes reads as much data is currently available (up to count bytes.) On pipes or similar devices, this function returns as soon as any data is available, even if the amount read is less than count and eof has not been hit. See also make-fd-stream.

run-program runs program in a child process. Program should be a pathname or string naming the program. Args should be a list of strings which this passes to program as normal Unix parameters. For no arguments, specify args as nil. The value returned is either a process structure or nil. The process interface follows the description of run-program. If run-program fails to fork the child process, it returns nil.

Except for sharing file descriptors as explained in keyword argument descriptions, run-program closes all file descriptors in the child process before running the program. When you are done using a process, call process-close to reclaim system resources. You only need to do this when you supply :stream for one of :input, :output, or :error, or you supply :pty non-nil. You can call process-close regardless of whether you must to reclaim resources without penalty if you feel safer.

run-program accepts the following keyword arguments:

:env

This is an a-list mapping keywords and simple-strings. The default is ext:*environment-list*. If :env is specified, run-program uses the value given and does not combine the environment passed to Lisp with the one specified.

:wait

If non-nil (the default), wait until the child process terminates. If nil, continue running Lisp while the child process runs.

:pty

This should be one of t, nil, or a stream. If specified non-nil, the subprocess executes under a Unix PTY. If specified as a stream, the system collects all output to this pty and writes it to this stream. If specified as t, the process-pty slot contains a stream from which you can read the program's output and to which you can write input for the program. The default is nil.

:input

This specifies how the program gets its input. If specified as a string, it is the name of a file that contains input for the child process. run-program opens the file as standard input. If specified as nil (the default), then standard input is the file /dev/null. If specified as t, the program uses the current standard input. This may cause some confusion if :wait is nil since two processes may use the terminal at the same time. If specified as :stream, then the process-input slot contains an output stream. Anything written to this stream goes to the program as input. :input may also be an input stream that already contains all the input for the process. In this case run-program reads all the input from this stream before returning, so this cannot be used to interact with the process.

:if-input-does-not-exist

This specifies what to do if the input file does not exist. The following values are valid: nil (the default) causes run-program to return nil without doing anything; :create creates the named file; and :error signals an error.

:output

This specifies what happens with the program's output. If specified as a pathname, it is the name of a file that contains output the program writes to its standard output. If specified as nil (the default), all output goes to /dev/null. If specified as t, the program writes to the Lisp process's standard output. This may cause confusion if :wait is nil since two processes may write to the terminal at the same time. If specified as :stream, then the process-output slot contains an input stream from which you can read the program's output.

:if-output-exists

This specifies what to do if the output file already exists. The following values are valid: nil causes run-program to return nil without doing anything; :error (the default) signals an error; :supersede overwrites the current file; and :append appends all output to the file.

:error

This is similar to :output, except the file becomes the program's standard error. Additionally, :error can be :output in which case the program's error output is routed to the same place specified for :output. If specified as :stream, the process-error contains a stream similar to the process-output slot when specifying the :output argument.

:if-error-exists

This specifies what to do if the error output file already exists. It accepts the same values as :if-output-exists.

:status-hook

This specifies a function to call whenever the process changes status. This is especially useful when specifying :wait as nil. The function takes the process as a required argument.

:before-execve

This specifies a function to run in the child process before it becomes the program to run. This is useful for actions such as authenticating the child process without modifying the parent Lisp process.

This function returns t if thing is a process. Otherwise it returns nil

This function returns the process ID, an integer, for the process.

This function returns the current status of process, which is one of :running, :stopped, :exited, or :signaled.

This function returns either the exit code for process, if it is :exited, or the termination signal process if it is :signaled. The result is undefined for processes that are still alive.

This function returns t if someone used a Unix signal to terminate the process and caused it to dump a Unix core image.

This function returns either the two-way stream connected to process's Unix PTY connection or nil if there is none.

[Function]
extensions:process-output process

[Function]
extensions:process-error process

If the corresponding stream was created, these functions return the input, output or error fd-stream. nil is returned if there is no stream.

This function returns the current function to call whenever process's status changes. This function takes the process as a required argument. process-status-hook is setf'able.

This function returns annotations supplied by users, and it is setf'able. This is available solely for users to associate information with process without having to build a-lists or hash tables of process structures.

This function waits for process to finish. If check-for-stopped is non-nil, this also returns when process stops.

This function sends the Unix signal to process. Signal should be the number of the signal or a keyword with the Unix name (for example, :sigsegv). Whom should be one of the following:

:pid

This is the default, and it indicates sending the signal to process only.

:process-group

This indicates sending the signal to process's group.

:pty-process-group

This indicates sending the signal to the process group currently in the foreground on the Unix PTY connected to process. This last option is useful if the running program is a shell, and you wish to signal the program running under the shell, not the shell itself. If process-pty of process is nil, using this option is an error.

This function returns t if process's status is either :running or :stopped.

This function closes all the streams associated with process. When you are done using a process, call this to reclaim system resources.

The save-lisp function saves the state of the currently running Lisp core image in file. The keyword arguments have the following meaning:

:purify

If non-nil (the default), the core image is purified before it is saved (see purify.) This reduces the amount of work the garbage collector must do when the resulting core image is being run. Also, if more than one Lisp is running on the same machine, this maximizes the amount of memory that can be shared between the two processes.

:root-structures

This should be a list of the main entry points in any newly loaded systems. This need not be supplied, but locality and/or GC performance will be better if they are. Meaningless if :purify is nil. See purify.

:init-function

This is the function that starts running when the created core file is resumed. The default function simply invokes the top level read-eval-print loop. If the function returns the lisp will exit.

:load-init-file

If non-NIL, then load an init file; either the one specified on the command line or ``init.fasl-type'', or, if ``init.fasl-type'' does not exist, init.lisp from the user's home directory. If the init file is found, it is loaded into the resumed core file before the read-eval-print loop is entered.

:site-init

If non-NIL, the name of the site init file to quietly load. The default is library:site-init. No error is signalled if the file does not exist.

:print-herald

If non-NIL (the default), then print out the standard Lisp herald when starting.

:process-command-line

If non-NIL (the default), processes the command line switches and performs the appropriate actions.

:batch-mode

If NIL (the default), then the presence of the -batch command-line switch will invoke batch-mode processing upon resuming the saved core. If non-NIL, the produced core will always be in batch-mode, regardless of any command-line switches.

lisp -core file

This function optimizes garbage collection by moving all currently live objects into non-collected storage. Once statically allocated, the objects can never be reclaimed, even if all pointers to them are dropped. This function should generally be called after a large system has been loaded and initialized.

:root-structures

is an optional list of objects which should be copied first to maximize locality. This should be a list of the main entry points for the resulting core image. The purification process tries to localize symbols, functions, etc., in the core image so that paging performance is improved. The default value is NIL which means that Lisp objects will still be localized but probably not as optimally as they could be.

defstruct structures defined with the (:pure t) option are moved into read-only storage, further reducing GC cost. List and vector slots of pure structures are also moved into read-only storage.

:environment-name

is gratuitous documentation for the compacted version of the current global environment (as seen in c::*info-environment*.) If nil is supplied, then environment compaction is inhibited.

(defun parse (x)
  (values (pathname-name x) (pathname-type x) (pathname-version x)))

(parse "foo") ==> "foo", NIL, :NEWEST
(parse "foo.bar") ==> "foo", "bar", :NEWEST
(parse ".foo") ==> ".foo", NIL, :NEWEST
(parse ".foo.bar") ==> ".foo", "bar", :NEWEST
(parse "..") ==> ".", "", :NEWEST
(parse "foo.") ==> "foo", "", :NEWEST
(parse "foo.bar.1") ==> "foo", "bar", 1
(parse "foo.bar.baz") ==> "foo.bar", "baz", :NEWEST

(pathname-directory "/usr/foo/bar.baz") ==> (:ABSOLUTE "usr" "foo")
(pathname-directory "../foo/bar.baz") ==> (:RELATIVE :UP "foo")

(pathname-name "foo\\*bar") => "foo*bar"

(("foo;*.text" "/usr/ram/foo/*.txt")
 ("foo;*.lisp" "/usr/ram/foo/*.l"))

• They provide a convenient shorthand for commonly used directory names, and
  
  
• They allow the abstract (directory structure independent) specification of file locations in program pathname constants (similar to logical pathnames.)

default:

The current directory at startup.

home:

The user's home directory.

library:

The CMUCL lib/ directory (CMUCLLIB environment variable.)

path:

The Unix command path (PATH environment variable.)

target:

The root of the tree where CMUCL was compiled.

This function returns the list of directories associated with the search list name. If name is not a defined search list, then an error is signaled. When set with setf, the list of directories is changed to the new value. If the new value is just a namestring or pathname, then it is interpreted as a one-element list. Note that (unlike Unix pathnames), search list names are case-insensitive.

[Function]
extensions:clear-search-list name

search-list-defined-p returns t if name is a defined search list name, nil otherwise. clear-search-list make the search list name undefined.

This macro provides an interface to search list resolution. The body forms are executed with var bound to each successive possible expansion for name. If name does not contain a search-list, then the body is executed exactly once. Everything is wrapped in a block named nil, so return can be used to terminate early. The result form (default nil) is evaluated to determine the result of the iteration.

(setf (ext:search-list "code:") '("/usr/lisp/code/"))

(ext:search-list name)

(ext:search-list "code:")

The keyword arguments to this Common Lisp function are a CMUCL extension. The arguments (all default to t) have the following functions:

:all

Include files beginning with dot such as .login, similar to ``ls -a''.

:check-for-subdirs

Test whether files are directories, similar to ``ls -F''.

:truenamep

Call truename on each file, which expands out all symbolic links. Note that this option can easily result in pathnames being returned which have a different directory from the one in the wildname argument.

:follow-links

Follow symbolic links when searching for matching directories.

Print a directory of wildname listing to stream (default *standard-output*.) :all and :verbose both default to nil and correspond to the ``-a'' and ``-l'' options of ls. Normally this function returns nil, but if :return-list is true, a list of the matched pathnames are returned.

Attempt to complete a file name to the longest unambiguous prefix. If supplied, directory from :defaults is used as the ``working directory'' when doing completion. :ignore-types is a list of strings of the pathname types (a.k.a. extensions) that should be disregarded as possible matches (binary file names, etc.)

Return a list of pathnames for all the possible completions of pathname with respect to defaults.

Return the current working directory as a pathname. If set with setf, set the working directory.

This function accepts a pathname and returns t if the current process can write it, and nil otherwise.

This function converts pathname into a string that can be used with UNIX system calls. Search-lists and wildcards are expanded. for-input controls the treatment of search-lists: when true (the default) and the file exists anywhere on the search-list, then that absolute pathname is returned; otherwise the first element of the search-list is used as the directory.

parse-time accepts a string containing a time (e.g., "Jan 12, 1952") and returns the universal time if it is successful. If it is unsuccessful and the keyword argument :error-on-mismatch is non-nil, it signals an error. Otherwise it returns nil. The other keyword arguments have the following meaning:

:default-seconds

specifies the default value for the seconds value if one is not provided by time-string. The default value is 0.

:default-minutes

specifies the default value for the minutes value if one is not provided by time-string. The default value is 0.

:default-hours

specifies the default value for the hours value if one is not provided by time-string. The default value is 0.

:default-day

specifies the default value for the day value if one is not provided by time-string. The default value is the current day.

:default-month

specifies the default value for the month value if one is not provided by time-string. The default value is the current month.

:default-year

specifies the default value for the year value if one is not provided by time-string. The default value is the current year.

:default-zone

specifies the default value for the time zone value if one is not provided by time-string. The default value is the current time zone.

:default-weekday

specifies the default value for the day of the week if one is not provided by time-string. The default value is the current day of the week.

Any of the above keywords can be given the value :current which means to use the current value as determined by a call to the operating system.

[Function]
extensions:format-decoded-time dest seconds minutes hours day month year
&key :timezone
:style :date-first
:print-seconds :print-meridian
:print-timezone :print-weekday

format-universal-time formats the time specified by universal-time. format-decoded-time formats the time specified by seconds, minutes, hours, day, month, and year. Dest is any destination accepted by the format function. The keyword arguments have the following meaning:

:timezone

is an integer specifying the hours west of Greenwich. :timezone defaults to the current time zone.

:style

specifies the style to use in formatting the time. The legal values are:

:short

specifies to use a numeric date.

:long

specifies to format months and weekdays as words instead of numbers.

:abbreviated

is similar to long except the words are abbreviated.

:government

is similar to abbreviated, except the date is of the form ``day month year'' instead of ``month day, year''.

:date-first

if non-nil (default) will place the date first. Otherwise, the time is placed first.

:print-seconds

if non-nil (default) will format the seconds as part of the time. Otherwise, the seconds will be omitted.

:print-meridian

if non-nil (default) will format ``AM'' or ``PM'' as part of the time. Otherwise, the ``AM'' or ``PM'' will be omitted.

:print-timezone

if non-nil (default) will format the time zone as part of the time. Otherwise, the time zone will be omitted.

:print-weekday

if non-nil (default) will format the weekday as part of date. Otherwise, the weekday will be omitted.

CATALOG.TXT

This file contains a page for each entry in the library. It contains information such as the author, portability or dependency issues, how to load the entry, etc.

READ-ME.TXT

This file describes the library's organization and all the possible pieces of information an entry's catalog description could contain.

Define lists starting with the symbol name as a new extended function name syntax.

body is executed with var bound to an actual function name of that form, and should return two values:

• A generalized boolean that is true if var is a valid function name.
• A symbol that can be used as a block name in functions whose name is var. (For some sorts of function names it might make sense to return nil for the block name, or just return one value.)

Users should not define function names starting with a symbol that CMUCL might be using internally. It is therefore advisable to only define new function names starting with a symbol from a user-defined package.

Returns two values:

• True if name is a valid function name.
• A symbol that can be used as a block name in functions whose name is name. This can be nil for some function names.

• no primary method is applicable to the generic function's actual arguments, and
• the generic function's method combination is either the standard method combination or a method combination defined with the short form of define-method-combination. The latter includes the standardized method combinations like progn, and, etc.

• reading slot values with slot-value in methods, or
  
  
• setting slots with (setf slot-value) in methods, or
  
  
• creating instances with make-instance, when slots are initialized from initforms. This currently depends on PCL being able to use its internal make-instance optimization, which it usually can.

(defclass foo ()
  ((a :type fixnum)))

(defmethod bar ((object foo) value)
  (with-slots (a) object
    (setf a value)))

(defmethod baz ((object foo))
  (< (slot-value object 'a) 10))

Slot type checking can be turned off by setting this variable to nil, which can be useful for compiling code containing incorrect slot type declarations.

declare (ext:slots specifier*)

specifier   ::= (quality class-entry*)
quality     ::= SLOT-BOUNDP | INLINE
class-entry ::= class | (class slot-name*)
class       ::= the name of a class
slot-name   ::= the name of a slot

(defclass foo ()
  (a b))

(defmethod bar ((x foo))
  (declare (ext:slots (slot-boundp foo)))
  (list (slot-value x 'a) (slot-value x 'b)))

(defclass foo ()
  (a b))

(defmethod bar ((x foo))
  (declare (ext:slots (inline (foo a))))
  (list (slot-value x 'a) (slot-value x 'b)))

(declaim (ext:slots (inline (foo slot-a))))
(defclass foo () ...)
(defclass bar (foo) ...)

• class foo has a subclass in which slot a is at a different location, or
  
  
• there exists a slot-value-using-class method for foo or a subclass of foo.

• there exist, at compile time, applicable methods on the reader/writer generic function that are not standard accessor methods (for instance, there exist around-methods), or
  
  
• applicable reader/writer methods access different slots in a class accessed inline, and one of its subclasses.

This variable controls if inline slot access optimizations are performed. It is true by default.

declaim (ext:auto-compile specifier*)
declaim (ext:not-auto-compile specifier*)

specifier   ::= gf-name | (gf-name qualifier* (specializer*))
gf-name     ::= the name of a generic function
qualifier   ::= a method qualifier
specializer ::= a method specializer

(declaim (ext:auto-compile foo))
(defmethod foo :around ((x bar)) ...)

(declaim (ext:auto-compile (foo (bar))))
(defmethod foo :around ((x bar)) ...)
(defmethod foo ((x bar)) ...)

(declaim (ext:auto-compile foo))
(declaim (ext:not-auto-compile (foo :around (bar)))  
(defmethod foo :around ((x bar)) ...)
(defmethod foo ((x bar)) ...)

(declaim (inline (method foo (foo))
                 (method foo :before (foo))))
(defmethod foo ((x foo)) ...)
(defmethod foo :before ((x foo)) ...)

Flush cached effective method functions. If gf is supplied, it should be a generic function metaobject or the name of a generic function, and this function flushes all cached effective methods for the given generic function. If gf is not supplied, all cached effective methods are flushed.

If true, the default, perform method inlining as described above. If false, don't.

If nonzero, the default value is 100, precompute effective methods when methods are loaded, and the method's generic function has less than the specified number of methods.

If zero, compute effective methods only when the generic function is called.

Seal name with respect to the given specifiers; name can be the name of a class or generic-function.

Supported specifiers are :subclasses for classes, which prevents changing subclasses of a class, and :methods which prevents changing the methods of a generic function.

Sealing violations signal an error of type pcl:sealed-error.

Remove seals from name-or-object.

(defmethod foo ((x integer)) x)
(defmethod foo :before ((x integer)) x)

(trace (method foo (integer)))
(trace (method foo :before (integer)))
(untrace (method foo :before (integer)))

(trace :methods 'foo)
(untrace :methods 'foo)

(defmethod foo ((x integer)) x)
(defmethod foo :before ((x integer)) x)

(profile:profile (method foo (integer)))
(profile:profile (method foo :before (integer)))
(profile:unprofile (method foo :before (integer)))

(profile:profile :methods 'foo)
(profile:unprofile :methods 'foo)

(profile:profile-all :methods t)

This variable controls compilation of interpreted method functions, e.g. for methods defined interactively at the REPL. Default is true, that is, method functions are compiled.

As an extension, CMUCL allows constantly to accept more than one value which are returned as multiple values.

(use-package :fwrappers)

(define-fwrapper foo (x y)
  (format t "x = ~s, y = ~s, user-data = ~s~%"
          x y (fwrapper-user-data fwrapper))
  (let ((value (call-next-function)))
    (format t "value = ~s~%" value)
    value))

(defun bar (x y)
  (+ x y))

(fwrap 'bar #'foo :type 'foo :user-data 42)

(bar 1 2)
 =>
 x = 1, y = 2, user-data = 42
 value = 3
 3   

This macro is like defun, but defines a function named name that can be used as an fwrapper definition.

In body, the symbol fwrapper is bound to the current fwrapper object.

The macro call-next-function can be used to invoke the next fwrapper, or the primary function being fwrapped. When called with no arguments, call-next-function invokes the next function with the original arguments passed to the fwrapper, unless you modify one of the parameters. When called with arguments, call-next-function invokes the next function with the given arguments.

This function wraps function function-name in an fwrapper fwrapper which was defined with define-fwrapper.

The value of type, if supplied, is used as an identifying tag that can be used in various other operations.

The value of user-data is stored as user-supplied data in the fwrapper object that is created for the function encapsulation. User-data is accessible in the body of fwrappers defined with define-fwrapper as (fwrapper-user-data fwrapper).

Value is the fwrapper object created.

Remove fwrappers from the function named function-name. If type is supplied, remove fwrappers whose type is equal to type. If test is supplied, remove fwrappers satisfying test.

Find an fwrapper of function-name. If type is supplied, find an fwrapper whose type is equal to type. If test is supplied, find an fwrapper satisfying test.

Update the funcallable instance function of the fwrapper object fwrapper from the definition of its function that was defined with define-fwrapper. This can be used to update fwrappers after changing a define-fwrapper.

Update fwrappers of function-name; see update-fwrapper. If type is supplied, update fwrappers whose type is equal to type. If test is supplied, update fwrappers satisfying test.

Set function-names's fwrappers to elements of the list fwrappers, which is assumed to be ordered from outermost to innermost. fwrappers null means remove all fwrappers.

Return a list of all fwrappers of function-name, ordered from outermost to innermost.

Prepend fwrapper fwrapper to the definition of function-name. Signal an error if function-name is an undefined function.

Remove fwrapper fwrapper from the definition of function-name. Signal an error if function-name is an undefined function.

Evaluate body with var bound to consecutive fwrappers of fdefn. Return result at the end. Note that fdefn must be an fdefn object. You can use kernel:fdefn-or-lose, for instance, to get the fdefn object from a function name.

If the value of *trust-dynamic-extent-declarations* is NIL, dynamic-extent declarations are effectively ignored.

If the value of this variable is a function, the function is called with four arguments to determine if a dynamic-extent declaration should be trusted. The arguments are the safety, space, speed, and debug settings at the point where the dynamic-extent declaration is used. If the function returns true, the declaration is trusted, otherwise it is not trusted.

In all other cases, dynamic-extent declarations are trusted.

(defun foo (x &rest rest)
  (declare (dynamic-extent rest))
  ...)

(defun bar ()
  (lambda (&rest rest)
    (declare (dynamic-extent rest))
    ...))

(defun foo (x)
  (flet ((bar () x))
    (declare (dynamic-extent #'bar))
    (baz #'bar)))

(defun foo (x)
  (flet ((bar () x))
    (baz #'bar)
    (locally (declare (dynamic-extent #'bar))
      (baz #'bar))))

(let ((x (list 1 2))
      (y (list* 1 2 x))
      (z (cons 1 (cons 2 nil))))
  (declare (dynamic-extent x y z))
  ...
  (setq x (list 2 3))
  ...)

(defun i (x y)
  (declare (type (unsigned-byte 32) x y))
  (ldb (byte 32 0) (logxor x (lognot y))))

1

The generator described here is available if the feature :new-random is available.

2

``Mersenne Twister: A 623-Dimensionally Equidistributed Uniform Pseudorandom Number Generator,'' ACM Trans. on Modeling and Computer Simulation, Vol. 8, No. 1, January 1998, pp.3--30