Forked from
cmucl / cmucl
5828 commits behind the upstream repository.
extensions.tex 72.89 KiB
\chapter{Design Choices and Extensions}
Several design choices in \clisp{} are left to the individual
implementation, and some essential parts of the programming environment
are left undefined. This chapter discusses the most important design
choices and extensions.
\section{Data Types}
\subsection{Integers}
The \tindexed{fixnum} type is equivalent to \code{(signed-byte 30)}.
Integers outside this range are represented as a \tindexed{bignum} or
a word integer (\pxlref{word-integers}.) Almost all integers that
appear in programs can be represented as a \code{fixnum}, so integer
number consing is rare.
\subsection{Floats}
\label{ieee-float}
\cmucl{} supports two floating point formats: \tindexed{single-float}
and \tindexed{double-float}. These are implemented with IEEE single
and double float arithmetic, respectively. \code{short-float} is a
synonym for \code{single-float}, and \code{long-float} is a synonym
for \code{double-float}. The initial value of
\vindexed{read-default-float-format} is \code{single-float}.
Both \code{single-float} and \code{double-float} are represented with
a pointer descriptor, so float operations can cause number consing.
Number consing is greatly reduced if programs are written to allow the
use of non-descriptor representations (\pxlref{numeric-types}.)
\subsubsection{IEEE Special Values}
\cmucl{} supports the IEEE infinity and NaN special values. These
non-numeric values will only be generated when trapping is disabled
for some floating point exception (\pxlref{float-traps}), so users of
the default configuration need not concern themselves with special
values.
\begin{defconst}{extensions:}{short-float-positive-infinity}
\defconstx[extensions:]{short-float-negative-infinity}
\defconstx[extensions:]{single-float-positive-infinity}
\defconstx[extensions:]{single-float-negative-infinity}
\defconstx[extensions:]{double-float-positive-infinity}
\defconstx[extensions:]{double-float-negative-infinity}
\defconstx[extensions:]{long-float-positive-infinity}
\defconstx[extensions:]{long-float-negative-infinity}
The values of these constants are the IEEE positive and negative
infinity objects for each float format.
\end{defconst}
\begin{defun}{extensions:}{float-infinity-p}{\args{\var{x}}}
This function returns true if \var{x} is an IEEE float infinity (of
either sign.) \var{x} must be a float.
\end{defun}
\begin{defun}{extensions:}{float-nan-p}{\args{\var{x}}}
\defunx[extensions:]{float-trapping-nan-p}{\args{\var{x}}}
\code{float-nan-p} returns true if \var{x} is an IEEE NaN (Not A
Number) object. \code{float-trapping-nan-p} returns true only if
\var{x} is a trapping NaN. With either function, \var{x} must be a
float.
\end{defun}
\subsubsection{Negative Zero}
The IEEE float format provides for distinct positive and negative
zeros. To test the sign on zero (or any other float), use the
\clisp{} \findexed{float-sign} function. Negative zero prints as
\code{-0.0f0} or \code{-0.0d0}.
\subsubsection{Denormalized Floats}
\cmucl{} supports IEEE denormalized floats. Denormalized floats
provide a mechanism for gradual underflow. The \clisp{}
\findexed{float-precision} function returns the actual precision of a
denormalized float, which will be less than \findexed{float-digits}.
Note that in order to generate (or even print) denormalized floats,
trapping must be disabled for the underflow exception
(\pxlref{float-traps}.) The \clisp{}
\w{\code{least-positive-}\var{format}-\code{float}} constants are
denormalized.
\begin{defun}{extensions:}{float-normalized-p}{\args{\var{x}}}
This function returns true if \var{x} is a denormalized float.
\var{x} must be a float.
\end{defun}
\subsubsection{Floating Point Exceptions}
\label{float-traps}
The IEEE floating point standard defines several exceptions that occur
when the result of a floating point operation is unclear or
undesirable. Exceptions can be ignored, in which case some default
action is taken, such as returning a special value. When trapping is
enabled for an exception, a error is signalled whenever that exception
occurs. These are the possible floating point exceptions:
\begin{Lentry}
\item[\kwd{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
\tindexed{floating-point-underflow} condition is signalled.
Otherwise, the operation results in a denormalized float or zero.
\item[\kwd{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 \tindexed{floating-point-overflow}
exception is signalled. Otherwise, the operation results in the
appropriate infinity.
\item[\kwd{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 \code{extensions:floating-point-inexact}
condition is signalled. Otherwise, the rounded result is returned.
\item[\kwd{invalid}] This exception occurs when the result of an
operation is ill-defined, such as \code{\w{(/ 0.0 0.0)}}. If
trapping is enabled, the \code{extensions:floating-point-invalid}
condition is signalled. Otherwise, a quiet NaN is returned.
\item[\kwd{divide-by-zero}] This exception occurs when a float is
divided by zero. If trapping is enabled, the
\tindexed{divide-by-zero} condition is signalled. Otherwise, the
appropriate infinity is returned.
\end{Lentry}
\subsubsection{Floating Point Rounding Mode}
\label{float-rounding-modes}
IEEE floating point specifies four possible rounding modes:
\begin{Lentry}
\item[\kwd{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 \clisp{} \findexed{round} function.
\item[\kwd{positive-infinity}] This mode rounds inexact results to the
possible value closer to positive infinity. This is analogous to
the \clisp{} \findexed{ceiling} function.
\item[\kwd{negative-infinity}] This mode rounds inexact results to the
possible value closer to negative infinity. This is analogous to
the \clisp{} \findexed{floor} function.
\item[\kwd{zero}] This mode rounds inexact results to the possible
value closer to zero. This is analogous to the \clisp{}
\findexed{truncate} function.
\end{Lentry}
\paragraph{Warning:}
Although the rounding mode can be changed with
\code{set-floating-point-modes}, use of any value other than the
default (\kwd{nearest}) can cause unusual behavior, since it will
affect rounding done by \llisp{} system code as well as rounding in
user code. In particular, the unary \code{round} function will stop
doing round-to-nearest on floats, and instead do the selected form of
rounding.
\subsubsection{Precision Control}
\label{precision-control}
The floating-point unit for the Intel IA-32 architecture supports a
precision control mechanism. The floating-point unit consists of an
IEEE extended double-float unit and all operations are always done
using his format, and this includes rounding. However, by setting the
precision control mode, the user can control how rounding is done for
each basic arithmetic operation like addition, subtraction,
multiplication, and division. The extra instructions for
trigonometric, exponential, and logarithmic operations are not
affected. We refer the reader to Intel documentation for more
information.
The possible modes are:
\begin{Lentry}
\item[\kwd{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.
\item[\kwd{53-bit}] In this mode, rounding is performed as if the
operands and results were IEEE double precision numbers.
\item[\kwd{64-bit}] In this mode, the default, rounding is performed
on the full IEEE extended double precision format.
\end{Lentry}
\paragraph{Warning:}
Although the precision mode can be changed with
\code{set-floating-point-modes}, use of anything other than
\kwd{64-bit} or \kwd{53-bit} can cause unexpected results, especially
if external functions or libraries are called. A setting of
\kwd{64-bit} also causes \code{(= 1d0 (+ 1d0 double-float-epsilon))}
to return \true instead of \false.
\subsubsection{Accessing the Floating Point Modes}
These functions can be used to modify or read the floating point modes:
\begin{defun}{extensions:}{set-floating-point-modes}{%
\keys{\kwd{traps} \kwd{rounding-mode}}
\morekeys{\kwd{fast-mode} \kwd{accrued-exceptions}}
\yetmorekeys{\kwd{current-exceptions} \kwd{precision-control}}}
\defunx[extensions:]{get-floating-point-modes}{}
The keyword arguments to \code{set-floating-point-modes} set various
modes controlling how floating point arithmetic is done:
\begin{Lentry}
\item[\kwd{traps}] A list of the exception conditions that should
cause traps. Possible exceptions are \kwd{underflow},
\kwd{overflow}, \kwd{inexact}, \kwd{invalid} and
\kwd{divide-by-zero}. Initially all traps except \kwd{inexact}
are enabled. \xlref{float-traps}.
\item[\kwd{rounding-mode}] The rounding mode to use when the result
is not exact. Possible values are \kwd{nearest},
\kwd{positive-infinity}, \kwd{negative-infinity} and \kwd{zero}.
Initially, the rounding mode is \kwd{nearest}. See the warning in
section \ref{float-rounding-modes} about use of other rounding
modes.
\item[\kwd{current-exceptions}, \kwd{accrued-exceptions}] Lists of
exception keywords used to set the exception flags. The
\var{current-exceptions} are the exceptions for the previous
operation, so setting it is not very useful. The
\var{accrued-exceptions} are a cumulative record of the exceptions
that occurred since the last time these flags were cleared.
Specifying \code{()} will clear any accrued exceptions.
\item[\kwd{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 \false. Sparc platforms support a fast mode where
denormal numbers are silently truncated to zero.
\item[\kwd{precision-control}] On the x86 architecture, you can set
the precision of the arithmetic to \kwd{24-bit}, \kwd{53-bit}, or
\kwd{64-bit} mode, corresponding to IEEE single precision, double
precision, and extended double precision.
\end{Lentry}
If a keyword argument is not supplied, then the associated state is
not changed.
\code{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 \code{set-floating-point-modes}, so
\code{apply} could be used with \code{set-floating-point-modes} to
restore the modes in effect at the time of the call to
\code{get-floating-point-modes}.
\end{defun}
To make handling control of floating-point exceptions, the following
macro is useful.
\begin{defmac}{ext:}{with-float-traps-masked}{traps \ampbody\ body}
\code{body} is executed with the selected floating-point exceptions
given by \code{traps} masked out (disabled). \code{traps} should be
a list of possible floating-point exceptions that should be ignored.
Possible values are \kwd{underflow}, \kwd{overflow}, \kwd{inexact},
\kwd{invalid} and \kwd{divide-by-zero}.
This is equivalent to saving the current traps from
\code{get-floating-point-modes}, setting the floating-point modes to
the desired exceptions, running the \code{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:
\begin{itemize}
\item Two approaches are available for detecting FP exceptions:
\begin{enumerate}
\item enabling the traps and handling the exceptions
\item disabling the traps and either handling the return values or
checking the accrued exceptions.
\end{enumerate}
Of these the latter is the most portable because on the alpha port
it is not possible to enable some traps at run-time.
\item 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.
\item 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.
\item 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.
\item 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.
\item On the x86, and, perhaps, the hppa, the FP exceptions may be
delivered at the next FP instruction which requires a FP
\code{wait} instruction (\code{x86::float-wait}) if using the lisp
conditions to catch trap within a \code{handler-bind}. The
\code{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.
\item The setting of the FP flags uses the
\code{(floating-point-modes)} and the \code{(set
(floating-point-modes)\ldots)} 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
\code{with-float-traps-masked} macro keeps the intervening code to
a minimum and uses only integer operations.
%% Safe byte-compiled?
%% Perhaps the VOPs (x86) should be smarter and only update some of
%% the flags, the trap masks and exceptions?
\end{itemize}
\end{defmac}
\subsection{Characters}
\cmucl{} implements characters according to \cltltwo{}. The
main difference from the first version is that character bits and font
have been eliminated, and the names of the types have been changed.
\tindexed{base-character} is the new equivalent of the old
\tindexed{string-char}. In this implementation, all characters are
base characters (there are no extended characters.) Character codes
range between \code{0} and \code{255}, using the ASCII encoding.
Table~\ref{tbl:chars}~\vpageref{tbl:chars} shows characters recognized
by \cmucl.
\begin{table}[tbhp]
\begin{center}
\begin{tabular}{|c|c|l|l|l|l|}
\hline
\multicolumn{2}{|c|}{ASCII} & \multicolumn{1}{|c}{Lisp} &
\multicolumn{3}{|c|}{} \\
\cline{1-2}
Name & Code & \multicolumn{1}{|c|}{Name} & \multicolumn{3}{|c|}{\raisebox{1.5ex}{Alternatives}}\\
\hline
\hline
\code{nul} & 0 & \code{\#\back{NULL}} & \code{\#\back{NUL}} & &\\
\code{bel} & 7 & \code{\#\back{BELL}} & & &\\
\code{bs} & 8 & \code{\#\back{BACKSPACE}} & \code{\#\back{BS}} & &\\
\code{tab} & 9 & \code{\#\back{TAB}} & & &\\
\code{lf} & 10 & \code{\#\back{NEWLINE}} & \code{\#\back{NL}} & \code{\#\back{LINEFEED}} & \code{\#\back{LF}}\\
\code{ff} & 11 & \code{\#\back{VT}} & \code{\#\back{PAGE}} & \code{\#\back{FORM}} &\\
\code{cr} & 13 & \code{\#\back{RETURN}} & \code{\#\back{CR}} & &\\
\code{esc} & 27 & \code{\#\back{ESCAPE}} & \code{\#\back{ESC}} & \code{\#\back{ALTMODE}} & \code{\#\back{ALT}}\\
\code{sp} & 32 & \code{\#\back{SPACE}} & \code{\#\back{SP}} & &\\
\code{del} & 127 & \code{\#\back{DELETE}} & \code{\#\back{RUBOUT}} & &\\
\hline
\end{tabular}
\caption{Characters recognized by \cmucl}
\label{tbl:chars}
\end{center}
\end{table}
\subsection{Array Initialization}
If no \kwd{initial-value} is specified, arrays are initialized to zero.
\subsection{Hash tables}
The \tindexed{hash-tables} defined by \clisp{} have limited utility because they
are limited to testing their keys using the equality predicates
provided by (pre-CLOS) \clisp{}. \cmucl{} overcomes this limitation
by allowing its users to specify new hash table tests and hashing
methods. The hashing method must also be specified, since the
compiler is unable to determine a good hashing function for an
arbitrary equality (equivalence) predicate.
\begin{defun}{extensions:}{define-hash-table-test}%
{\args{\var{hash-table-test-name} \var{test-function} \var{hash-function}}}
The \var{hash-table-test-name} must be a symbol.
% I just assumed the above. [2002/10/10:rpg]
The \var{test-function} takes two objects and returns true
iff they are the same. The \var{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
\code{(\index[funs]{make-hash-table}make-hash-table :test
\var{hash-table-test-name} \ldots)}.
Note that it is the \var{hash-table-test-name} that will be
returned by the function \findexed{hash-table-test}, when applied to
a hash-table created using this function.
This function updates \vindexed{hash-table-tests}, which is now
internal.
\end{defun}
% NOTE: This should be further updated with discussion of weak
% hash-tables. I've never used them, so haven't bothered to figure
% them out, and am not qualified to write even the most rudimentary
% docs. [2002/10/10:rpg]
\section{Default Interrupts for Lisp}
\cmucl{} has several interrupt handlers defined when it starts up,
as follows:
\begin{Lentry}
\item[\code{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.
\item[\code{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.
\item[\code{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.
\item[\code{SIGILL}, \code{SIGBUS}, \code{SIGSEGV}, and \code{SIGFPE}]
cause Lisp to signal an error.
\end{Lentry}
For keyboard interrupt signals, the standard interrupt character is in
parentheses. Your \file{.login} may set up different interrupt
characters. When a signal is generated, there may be some delay before
it is processed since Lisp cannot be interrupted safely in an arbitrary
place. The computation will continue until a safe point is reached and
then the interrupt will be processed. \xlref{signal-handlers} to define
your own signal handlers.
\section{Implementation-specific Packages}
When \cmucl{} is first started up, the default package is the
\code{common-lisp-user} package. The \code{common-lisp-user} package
uses the \code{common-lisp}, \code{extensions}, and \code{pcl}
packages. The symbols exported from these three packages can be
referenced without package qualifiers. This section describes packages
which have exported interfaces that may concern users. The numerous
internal packages which implement parts of the system are not
described here. Package nicknames are in parenthesis after the full
name.
\begin{Lentry}
\item[\code{alien}, \code{c-call}] Export the features of the Alien
foreign data structure facility (\pxlref{aliens}.)
\item[\code{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 \cltltwo.
\item[\code{debug}] The \code{debug} package contains the command-line
oriented debugger. It exports utility various functions and
switches.
\item[\code{debug-internals}] The \code{debug-internals} package
exports the primitives used to write debuggers.
\xlref{debug-internals}.
\item[\code{extensions (ext)}] The \code{extensions} packages exports
local extensions to \clisp{} that are documented in this manual.
Examples include the \code{save-lisp} function and time parsing.
\item[\code{hemlock (ed)}] The \code{hemlock} package contains all the
code to implement Hemlock commands. The \code{hemlock} package
currently exports no symbols.
\item[\code{hemlock-internals (hi)}] The \code{hemlock-internals}
package contains code that implements low level primitives and
exports those symbols used to write Hemlock commands.
\item[\code{keyword}] The \code{keyword} package contains keywords
(e.g., \kwd{start}). All symbols in the \code{keyword} package are
exported and evaluate to themselves (i.e., the value of the symbol
is the symbol itself).
\item[\code{profile}] The \code{profile} package exports a simple
run-time profiling facility (\pxlref{profiling}).
\item[\code{common-lisp (cl lisp)}] The \code{common-lisp} package
exports all the symbols defined by \cltl{} and only those symbols.
Strictly portable Lisp code will depend only on the symbols exported
from the \code{lisp} package.
\item[\code{unix}] This package exports system call
interfaces to Unix (\pxlref{unix-interface}).
\item[\code{system (sys)}] The \code{system} package contains
functions and information necessary for system interfacing. This
package is used by the \code{lisp} package and exports several
symbols that are necessary to interface to system code.
\item[\code{xlib}] The \code{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.
\item[\code{wire}] The \code{wire} package exports a remote procedure
call facility (\pxlref{remote}).
\end{Lentry}
\input{hierarchical-packages}
\section{The Editor}
The \code{ed} function invokes the Hemlock editor which is described
in {\it Hemlock User's Manual} and {\it Hemlock Command Implementor's
Manual}. Most users at CMU prefer to use Hemlock's slave \llisp{}
mechanism which provides an interactive buffer for the
\code{read-eval-print} loop and editor commands for evaluating and
compiling text from a buffer into the slave \llisp. Since the editor
runs in the \llisp, using slaves keeps users from trashing their
editor by developing in the same \llisp{} with \hemlock{}.
\section{Garbage Collection}
\cmucl{} uses a stop-and-copy garbage collector that compacts
the items in dynamic space every time it runs. Most users cause the
system to garbage collect (GC) frequently, long before space is
exhausted. With 16 or 24 megabytes of memory, causing GC's more
frequently on less garbage allows the system to GC without much (if
any) paging.
The following functions invoke the garbage collector or control whether
automatic garbage collection is in effect:
\begin{defun}{extensions:}{gc}{}
This function runs the garbage collector. If
\code{ext:*gc-verbose*} is non-\nil, then it invokes
\code{ext:*gc-notify-before*} before GC'ing and
\code{ext:*gc-notify-after*} afterwards.
\end{defun}
\begin{defun}{extensions:}{gc-off}{}
This function inhibits automatic garbage collection. After calling
it, the system will not GC unless you call \code{ext:gc} or
\code{ext:gc-on}.
\end{defun}
\begin{defun}{extensions:}{gc-on}{}
This function reinstates automatic garbage collection. If the
system would have GC'ed while automatic GC was inhibited, then this
will call \code{ext:gc}.
\end{defun}
\subsection{GC Parameters}
The following variables control the behavior of the garbage collector:
\begin{defvar}{extensions:}{bytes-consed-between-gcs}
\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 \code{ext:*bytes-consed-between-gcs*}. The default
value is 2000000.
\end{defvar}
\begin{defvar}{extensions:}{gc-verbose}
This variable controls whether \code{ext:gc} invokes the functions
in \code{ext:*gc-notify-before*} and
\code{ext:*gc-notify-after*}. If \code{*gc-verbose*} is \nil,
\code{ext:gc} foregoes printing any messages. The default value is
\code{T}.
\end{defvar}
\begin{defvar}{extensions:}{gc-notify-before}
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:
\begin{verbatim}
[GC threshold exceeded with 2,107,124 bytes in use. Commencing GC.]
\end{verbatim}
\end{defvar}
\begin{defvar}{extensions:}{gc-notify-after}
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:
\begin{verbatim}
[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.]
\end{verbatim}
\end{defvar}
Note that a garbage collection will not happen at exactly the new
threshold printed by the default \code{ext:*gc-notify-after*}
function. The system periodically checks whether this threshold has
been exceeded, and only then does a garbage collection.
\begin{defvar}{extensions:}{gc-inhibit-hook}
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 \code{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
\code{ext:gc-on}. The default value of this variable is \nil.
\end{defvar}
\begin{defvar}{extensions:}{before-gc-hooks}
\defvarx[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.
\end{defvar}
\subsection{Weak Pointers}
A weak pointer provides a way to maintain a reference to an object
without preventing an object from being garbage collected. If the
garbage collector discovers that the only pointers to an object are
weak pointers, then it breaks the weak pointers and deallocates the
object.
\begin{defun}{extensions:}{make-weak-pointer}{\args{\var{object}}}
\defunx[extensions:]{weak-pointer-value}{\args{\var{weak-pointer}}}
\code{make-weak-pointer} returns a weak pointer to an object.
\code{weak-pointer-value} follows a weak pointer, returning the two
values: the object pointed to (or \false{} if broken) and a boolean
value which is \false{} if the pointer has been broken, and true
otherwise.
\end{defun}
\subsection{Finalization}
Finalization provides a ``hook'' that is triggered when the garbage
collector reclaims an object. It is usually used to recover non-Lisp
resources that were allocated to implement the finalized Lisp object.
For example, when a unix file-descriptor stream is collected,
finalization is used to close the underlying file descriptor.
\begin{defun}{extensions:}{finalize}{\args{\var{object} \var{function}}}
This function registers \var{object} for finalization.
\var{function} is called with no arguments when \var{object} is
reclaimed. Normally \var{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 \var{function} must not
close over \var{object} itself, as this prevents the object from
ever becoming garbage.
\end{defun}
\begin{defun}{extensions:}{cancel-finalization}{\args{\var{object}}}
This function cancel any finalization request for \var{object}.
\end{defun}
\section{Describe}
\begin{defun}{}{describe}{ \args{\var{object} \&optional{} \var{stream}}}
The \code{describe} function prints useful information about
\var{object} on \var{stream}, which defaults to
\code{*standard-output*}. For any object, \code{describe} will
print out the type. Then it prints other information based on the
type of \var{object}. The types which are presently handled are:
\begin{Lentry}
\item[\tindexed{hash-table}] \code{describe} prints the number of
entries currently in the hash table and the number of buckets
currently allocated.
\item[\tindexed{function}] \code{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.
\item[\tindexed{fixnum}] \code{describe} prints whether the integer
is prime or not.
\item[\tindexed{symbol}] The symbol's value, properties, and
documentation are printed. If the symbol has a function
definition, then the function is described.
\end{Lentry}
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.
\end{defun}
A number of switches can be used to control \code{describe}'s behavior.
\begin{defvar}{extensions:}{describe-level}
The maximum level of recursive description allowed. Initially two.
\end{defvar}
\begin{defvar}{extensions:}{describe-indentation}
The number of spaces to indent for each level of recursive
description, initially three.
\end{defvar}
\begin{defvar}{extensions:}{describe-print-level}
\defvarx[extensions:]{describe-print-length}
The values of \code{*print-level*} and \code{*print-length*} during
description. Initially two and five.
\end{defvar}
\section{The Inspector}
\cmucl{} has both a graphical inspector that uses the X Window System,
and a simple terminal-based inspector.
\begin{defun}{}{inspect}{ \args{\ampoptional{} \var{object}}}
\code{inspect} calls the inspector on the optional argument
\var{object}. If \var{object} is unsupplied, \code{inspect}
immediately returns \false. Otherwise, the behavior of inspect
depends on whether Lisp is running under X. When \code{inspect} is
eventually exited, it returns some selected Lisp object.
\end{defun}
\subsection{The Graphical Interface}
\label{motif-interface}
\cmucl{} has an interface to Motif which is functionally similar to
CLM, but works better in \cmucl{}. This interface is documented in
separate manuals \textit{CMUCL Motif Toolkit} and \textit{Design Notes
on the Motif Toolkit}, which are distributed with \cmucl{}.
This motif interface has been used to write the inspector and graphical
debugger. There is also a Lisp control panel with a simple file management
facility, apropos and inspector dialogs, and controls for setting global
options. See the \code{interface} and \code{toolkit} packages.
\begin{defun}{interface:}{lisp-control-panel}{}
This function creates a control panel for the Lisp process.
\end{defun}
\begin{defvar}{interface:}{interface-style}
When the graphical interface is loaded, this variable controls
whether it is used by \code{inspect} and the error system. If the
value is \kwd{graphics} (the default) and the \code{DISPLAY}
environment variable is defined, the graphical inspector and
debugger will be invoked by \findexed{inspect} or when an error is
signalled. Possible values are \kwd{graphics} and {tty}. If the
value is \kwd{graphics}, but there is no X display, then we quietly
use the TTY interface.
\end{defvar}
\subsection{The TTY Inspector}
If X is unavailable, a terminal inspector is invoked. The TTY inspector
is a crude interface to \code{describe} which allows objects to be
traversed and maintains a history. This inspector prints information
about and object and a numbered list of the components of the object.
The command-line based interface is a normal
\code{read}--\code{eval}--\code{print} loop, but an integer \var{n}
descends into the \var{n}'th component of the current object, and
symbols with these special names are interpreted as commands:
\begin{Lentry}
\item[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.
\item[Q, E] Return the current object from \code{inspect}.
\item[R] Recompute object display, and print again. Useful if the
object may have changed.
\item[D] Display again without recomputing.
\item[H, ?] Show help message.
\end{Lentry}
\section{Load}
\begin{defun}{}{load}{%
\args{\var{filename}
\keys{\kwd{verbose} \kwd{print} \kwd{if-does-not-exist}}
\morekeys{\kwd{if-source-newer} \kwd{contents}}}}
As in standard \clisp{}, this function loads a file containing
source or object code into the running Lisp. Several CMU extensions
have been made to \code{load} to conveniently support a variety of
program file organizations. \var{filename} may be a wildcard
pathname such as \file{*.lisp}, in which case all matching files are
loaded.
If \var{filename} has a \code{pathname-type} (or extension), then
that exact file is loaded. If the file has no extension, then this
tells \code{load} to use a heuristic to load the ``right'' file.
The \code{*load-source-types*} and \code{*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
\var{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:
\begin{Lentry}
\item[\kwd{load-object}] The object file is loaded even though the
source file is newer.
\item[\kwd{load-source}] The source file is loaded instead of the
older object file.
\item[\kwd{compile}] The source file is compiled and then the new
object file is loaded.
\item[\kwd{query}] The user is asked a yes or no question to
determine whether the source or object file is loaded.
\end{Lentry}
This argument defaults to the value of
\code{ext:*load-if-source-newer*} (initially \kwd{load-object}.)
The \var{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 \kwd{source} or \kwd{binary}, which forces
loading in source and binary mode, respectively. You really
shouldn't ever need to use this argument.
\end{defun}
\begin{defvar}{extensions:}{load-source-types}
\defvarx[extensions:]{load-object-types}
These variables are lists of possible \code{pathname-type} values
for source and object files to be passed to \code{load}. These
variables are only used when the file passed to \code{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.
\end{defvar}
\begin{defvar}{extensions:}{load-if-source-newer}
This variable determines the default value of the
\var{if-source-newer} argument to \code{load}. Its initial value is
\kwd{load-object}.
\end{defvar}
\section{The Reader}
\subsection{Reader Extensions}
\cmucl{} supports an ANSI-compatible extension to enable reading of
specialized arrays. Thus
\begin{example}
* (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))
\end{example}
\subsection{Reader Parameters}
\begin{defvar}{extensions:}{ignore-extra-close-parentheses}
If this variable is \true{} (the default), then the reader merely
prints a warning when an extra close parenthesis is detected
(instead of signalling an error.)
\end{defvar}
\section{Stream Extensions}
\begin{defun}{extensions:}{read-n-bytes}{%
\args{\var{stream buffer start numbytes}
\ampoptional{} \var{eof-error-p}}}
On streams that support it, this function reads multiple bytes of
data into a buffer. The buffer must be a \code{simple-string} or
\code{(simple-array (unsigned-byte 8) (*))}. The argument
\var{nbytes} specifies the desired number of bytes, and the return
value is the number of bytes actually read.
\begin{itemize}
\item If \var{eof-error-p} is true, an \tindexed{end-of-file}
condition is signalled if end-of-file is encountered before
\var{count} bytes have been read.
\item If \var{eof-error-p} is false, \code{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 \var{count} and
eof has not been hit. See also \funref{make-fd-stream}.
\end{itemize}
\end{defun}
\section{Running Programs from Lisp}
It is possible to run programs from Lisp by using the following function.
\begin{defun}{extensions:}{run-program}{%
\args{\var{program} \var{args}
\keys{\kwd{env} \kwd{wait} \kwd{pty} \kwd{input}}
\morekeys{\kwd{if-input-does-not-exist}}
\yetmorekeys{\kwd{output} \kwd{if-output-exists}}
\yetmorekeys{\kwd{error} \kwd{if-error-exists}}
\yetmorekeys{\kwd{status-hook} \kwd{before-execve}}}}
\code{run-program} runs \var{program} in a child process.
\var{Program} should be a pathname or string naming the program.
\var{Args} should be a list of strings which this passes to
\var{program} as normal Unix parameters. For no arguments, specify
\var{args} as \nil. The value returned is either a process
structure or \nil. The process interface follows the description of
\code{run-program}. If \code{run-program} fails to fork the child
process, it returns \nil.
Except for sharing file descriptors as explained in keyword argument
descriptions, \code{run-program} closes all file descriptors in the
child process before running the program. When you are done using a
process, call \code{process-close} to reclaim system resources. You
only need to do this when you supply \kwd{stream} for one of
\kwd{input}, \kwd{output}, or \kwd{error}, or you supply \kwd{pty}
non-\nil. You can call \code{process-close} regardless of whether
you must to reclaim resources without penalty if you feel safer.
\code{run-program} accepts the following keyword arguments:
\begin{Lentry}
\item[\kwd{env}] This is an a-list mapping keywords and
simple-strings. The default is \code{ext:*environment-list*}. If
\kwd{env} is specified, \code{run-program} uses the value given
and does not combine the environment passed to Lisp with the one
specified.
\item[\kwd{wait}] If non-\nil{} (the default), wait until the child
process terminates. If \nil, continue running Lisp while the
child process runs.
\item[\kwd{pty}] This should be one of \true, \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 \true, the
\code{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.
\item[\kwd{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. \code{run-program} opens the file as
standard input. If specified as \nil{} (the default), then
standard input is the file \file{/dev/null}. If specified as
\true, the program uses the current standard input. This may
cause some confusion if \kwd{wait} is \nil{} since two processes
may use the terminal at the same time. If specified as
\kwd{stream}, then the \code{process-input} slot contains an
output stream. Anything written to this stream goes to the
program as input. \kwd{input} may also be an input stream that
already contains all the input for the process. In this case
\code{run-program} reads all the input from this stream before
returning, so this cannot be used to interact with the process.
\item[\kwd{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 \code{run-program} to return \nil{}
without doing anything; \kwd{create} creates the named file; and
\kwd{error} signals an error.
\item[\kwd{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
\file{/dev/null}. If specified as \true, the program writes to
the Lisp process's standard output. This may cause confusion if
\kwd{wait} is \nil{} since two processes may write to the terminal
at the same time. If specified as \kwd{stream}, then the
\code{process-output} slot contains an input stream from which you
can read the program's output.
\item[\kwd{if-output-exists}] This specifies what to do if the
output file already exists. The following values are valid:
\nil{} causes \code{run-program} to return \nil{} without doing
anything; \kwd{error} (the default) signals an error;
\kwd{supersede} overwrites the current file; and \kwd{append}
appends all output to the file.
\item[\kwd{error}] This is similar to \kwd{output}, except the file
becomes the program's standard error. Additionally, \kwd{error}
can be \kwd{output} in which case the program's error output is
routed to the same place specified for \kwd{output}. If specified
as \kwd{stream}, the \code{process-error} contains a stream
similar to the \code{process-output} slot when specifying the
\kwd{output} argument.
\item[\kwd{if-error-exists}] This specifies what to do if the error
output file already exists. It accepts the same values as
\kwd{if-output-exists}.
\item[\kwd{status-hook}] This specifies a function to call whenever
the process changes status. This is especially useful when
specifying \kwd{wait} as \nil. The function takes the process as
a required argument.
\item[\kwd{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.
\end{Lentry}
\end{defun}
\subsection{Process Accessors}
The following functions interface the process returned by \code{run-program}:
\begin{defun}{extensions:}{process-p}{\args{\var{thing}}}
This function returns \true{} if \var{thing} is a process.
Otherwise it returns \nil{}
\end{defun}
\begin{defun}{extensions:}{process-pid}{\args{\var{process}}}
This function returns the process ID, an integer, for the
\var{process}.
\end{defun}
\begin{defun}{extensions:}{process-status}{\args{\var{process}}}
This function returns the current status of \var{process}, which is
one of \kwd{running}, \kwd{stopped}, \kwd{exited}, or
\kwd{signaled}.
\end{defun}
\begin{defun}{extensions:}{process-exit-code}{\args{\var{process}}}
This function returns either the exit code for \var{process}, if it
is \kwd{exited}, or the termination signal \var{process} if it is
\kwd{signaled}. The result is undefined for processes that are
still alive.
\end{defun}
\begin{defun}{extensions:}{process-core-dumped}{\args{\var{process}}}
This function returns \true{} if someone used a Unix signal to
terminate the \var{process} and caused it to dump a Unix core image.
\end{defun}
\begin{defun}{extensions:}{process-pty}{\args{\var{process}}}
This function returns either the two-way stream connected to
\var{process}'s Unix PTY connection or \nil{} if there is none.
\end{defun}
\begin{defun}{extensions:}{process-input}{\args{\var{process}}}
\defunx[extensions:]{process-output}{\args{\var{process}}}
\defunx[extensions:]{process-error}{\args{\var{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.
\end{defun}
\begin{defun}{extensions:}{process-status-hook}{\args{\var{process}}}
This function returns the current function to call whenever
\var{process}'s status changes. This function takes the
\var{process} as a required argument. \code{process-status-hook} is
\code{setf}'able.
\end{defun}
\begin{defun}{extensions:}{process-plist}{\args{\var{process}}}
This function returns annotations supplied by users, and it is
\code{setf}'able. This is available solely for users to associate
information with \var{process} without having to build a-lists or
hash tables of process structures.
\end{defun}
\begin{defun}{extensions:}{process-wait}{
\args{\var{process} \ampoptional{} \var{check-for-stopped}}}
This function waits for \var{process} to finish. If
\var{check-for-stopped} is non-\nil, this also returns when
\var{process} stops.
\end{defun}
\begin{defun}{extensions:}{process-kill}{%
\args{\var{process} \var{signal} \ampoptional{} \var{whom}}}
This function sends the Unix \var{signal} to \var{process}.
\var{Signal} should be the number of the signal or a keyword with
the Unix name (for example, \kwd{sigsegv}). \var{Whom} should be
one of the following:
\begin{Lentry}
\item[\kwd{pid}] This is the default, and it indicates sending the
signal to \var{process} only.
\item[\kwd{process-group}] This indicates sending the signal to
\var{process}'s group.
\item[\kwd{pty-process-group}] This indicates sending the signal to
the process group currently in the foreground on the Unix PTY
connected to \var{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
\code{process-pty} of \var{process} is \nil, using this option is
an error.
\end{Lentry}
\end{defun}
\begin{defun}{extensions:}{process-alive-p}{\args{\var{process}}}
This function returns \true{} if \var{process}'s status is either
\kwd{running} or \kwd{stopped}.
\end{defun}
\begin{defun}{extensions:}{process-close}{\args{\var{process}}}
This function closes all the streams associated with \var{process}.
When you are done using a process, call this to reclaim system
resources.
\end{defun}
\section{Saving a Core Image}
A mechanism has been provided to save a running Lisp core image and to
later restore it. This is convenient if you don't want to load several files
into a Lisp when you first start it up. The main problem is the large
size of each saved Lisp image, typically at least 20 megabytes.
\begin{defun}{extensions:}{save-lisp}{%
\args{\var{file}
\keys{\kwd{purify} \kwd{root-structures} \kwd{init-function}}
\morekeys{\kwd{load-init-file} \kwd{print-herald} \kwd{site-init}}
\yetmorekeys{\kwd{process-command-line} \kwd{batch-mode}}}}
The \code{save-lisp} function saves the state of the currently
running Lisp core image in \var{file}. The keyword arguments have
the following meaning:
\begin{Lentry}
\item[\kwd{purify}] If non-\nil{} (the default), the core image is
purified before it is saved (see \funref{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.
\item[\kwd{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
\kwd{purify} is \nil. See \funref{purify}.
\item[\kwd{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.
\item[\kwd{load-init-file}] If non-NIL, then load an init file;
either the one specified on the command line or
``\w{\file{init.}\var{fasl-type}}'', or, if
``\w{\file{init.}\var{fasl-type}}'' does not exist,
\code{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.
\item[\kwd{site-init}] If non-NIL, the name of the site init file to
quietly load. The default is \file{library:site-init}. No error
is signalled if the file does not exist.
\item[\kwd{print-herald}] If non-NIL (the default), then print out
the standard Lisp herald when starting.
\item[\kwd{process-command-line}] If non-NIL (the default),
processes the command line switches and performs the appropriate
actions.
\item[\kwd{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.
\end{Lentry}
\end{defun}
To resume a saved file, type:
\begin{example}
lisp -core file
\end{example}
\begin{defun}{extensions:}{purify}{
\args{\var{file}
\keys{\kwd{root-structures} \kwd{environment-name}}}}
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.
\begin{Lentry}
\item[\kwd{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.
\var{defstruct} structures defined with the \code{(: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.
\item[\kwd{environment-name}] is gratuitous documentation for the
compacted version of the current global environment (as seen in
\code{c::*info-environment*}.) If \false{} is supplied, then
environment compaction is inhibited.
\end{Lentry}
\end{defun}
\section{Pathnames}
In \clisp{} quite a few aspects of \tindexed{pathname} semantics are left to
the implementation.
\subsection{Unix Pathnames}
\cpsubindex{unix}{pathnames}
Unix pathnames are always parsed with a \code{unix-host} object as the host and
\code{nil} as the device. The last two dots (\code{.}) in the namestring mark
the type and version, however if the first character is a dot, it is considered
part of the name. If the last character is a dot, then the pathname has the
empty-string as its type. The type defaults to \code{nil} and the version
defaults to \kwd{newest}.
\begin{example}
(defun parse (x)
(values (pathname-name x) (pathname-type x) (pathname-version x)))
(parse "foo") \result "foo", NIL, :NEWEST
(parse "foo.bar") \result "foo", "bar", :NEWEST
(parse ".foo") \result ".foo", NIL, :NEWEST
(parse ".foo.bar") \result ".foo", "bar", :NEWEST
(parse "..") \result ".", "", :NEWEST
(parse "foo.") \result "foo", "", :NEWEST
(parse "foo.bar.1") \result "foo", "bar", 1
(parse "foo.bar.baz") \result "foo.bar", "baz", :NEWEST
\end{example}
The directory of pathnames beginning with a slash (or a search-list,
\pxlref{search-lists}) is starts \kwd{absolute}, others start with
\kwd{relative}. The \code{..} directory is parsed as \kwd{up}; there is no
namestring for \kwd{back}:
\begin{example}
(pathname-directory "/usr/foo/bar.baz") \result (:ABSOLUTE "usr" "foo")
(pathname-directory "../foo/bar.baz") \result (:RELATIVE :UP "foo")
\end{example}
\subsection{Wildcard Pathnames}
Wildcards are supported in Unix pathnames. If `\code{*}' is specified for a
part of a pathname, that is parsed as \kwd{wild}. `\code{**}' can be used as a
directory name to indicate \kwd{wild-inferiors}. Filesystem operations
treat \kwd{wild-inferiors} the same as\ \kwd{wild}, but pathname pattern
matching (e.g. for logical pathname translation, \pxlref{logical-pathnames})
matches any number of directory parts with `\code{**}' (see
\pxlref{wildcard-matching}.)
`\code{*}' embedded in a pathname part matches any number of characters.
Similarly, `\code{?}' matches exactly one character, and `\code{[a,b]}'
matches the characters `\code{a}' or `\code{b}'. These pathname parts are
parsed as \code{pattern} objects.
Backslash can be used as an escape character in namestring
parsing to prevent the next character from being treated as a wildcard. Note
that if typed in a string constant, the backslash must be doubled, since the
string reader also uses backslash as a quote:
\begin{example}
(pathname-name "foo\(\backslash\backslash\)*bar") => "foo*bar"
\end{example}
\subsection{Logical Pathnames}
\cindex{logical pathnames}
\label{logical-pathnames}
If a namestring begins with the name of a defined logical pathname
host followed by a colon, then it will be parsed as a logical
pathname. Both `\code{*}' and `\code{**}' wildcards are implemented.
\findexed{load-logical-pathname-translations} on \var{name} looks for a
logical host definition file in
\w{\file{library:\var{name}.translations}}. Note that \file{library:}
designates the search list (\pxlref{search-lists}) initialized to the
\cmucl{} \file{lib/} directory, not a logical pathname. The format of
the file is a single list of two-lists of the from and to patterns:
\begin{example}
(("foo;*.text" "/usr/ram/foo/*.txt")
("foo;*.lisp" "/usr/ram/foo/*.l"))
\end{example}
\subsection{Search Lists}
\cindex{search lists}
\label{search-lists}
Search lists are an extension to \clisp{} pathnames. They serve a function
somewhat similar to \clisp{} logical pathnames, but work more like Unix PATH
variables. Search lists are used for two purposes:
\begin{itemize}
\item They provide a convenient shorthand for commonly used directory names,
and
\item They allow the abstract (directory structure independent) specification
of file locations in program pathname constants (similar to logical pathnames.)
\end{itemize}
Each search list has an associated list of directories (represented as
pathnames with no name or type component.) The namestring for any relative
pathname may be prefixed with ``\var{slist}\code{:}'', indicating that the
pathname is relative to the search list \var{slist} (instead of to the current
working directory.) Once qualified with a search list, the pathname is no
longer considered to be relative.
When a search list qualified pathname is passed to a file-system operation such
as \code{open}, \code{load} or \code{truename}, each directory in the search
list is successively used as the root of the pathname until the file is
located. When a file is written to a search list directory, the file is always
written to the first directory in the list.
\subsection{Predefined Search-Lists}
These search-lists are initialized from the Unix environment or when Lisp was
built:
\begin{Lentry}
\item[\code{default:}] The current directory at startup.
\item[\code{home:}] The user's home directory.
\item[\code{library:}] The \cmucl{} \file{lib/} directory (\code{CMUCLLIB} environment
variable.)
\item[\code{path:}] The Unix command path (\code{PATH} environment variable.)
\item[\code{target:}] The root of the tree where \cmucl{} was compiled.
\end{Lentry}
It can be useful to redefine these search-lists, for example, \file{library:}
can be augmented to allow logical pathname translations to be located, and
\file{target:} can be redefined to point to where \cmucl{} system sources are
locally installed.
\subsection{Search-List Operations}
These operations define and access search-list definitions. A search-list name
may be parsed into a pathname before the search-list is actually defined, but
the search-list must be defined before it can actually be used in a filesystem
operation.
\begin{defun}{extensions:}{search-list}{\var{name}}
This function returns the list of directories associated with the
search list \var{name}. If \var{name} is not a defined search list,
then an error is signaled. When set with \code{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.
\end{defun}
\begin{defun}{extensions:}{search-list-defined-p}{\var{name}}
\defunx[extensions:]{clear-search-list}{\var{name}}
\code{search-list-defined-p} returns \true{} if \var{name} is a
defined search list name, \false{} otherwise.
\code{clear-search-list} make the search list \var{name} undefined.
\end{defun}
\begin{defmac}{extensions:}{enumerate-search-list}{%
\args{(\var{var} \var{pathname} \mopt{result}) \mstar{form}}}
This macro provides an interface to search list resolution. The
body \var{forms} are executed with \var{var} bound to each
successive possible expansion for \var{name}. If \var{name} does
not contain a search-list, then the body is executed exactly once.
Everything is wrapped in a block named \nil, so \code{return} can be
used to terminate early. The \var{result} form (default \nil) is
evaluated to determine the result of the iteration.
\end{defmac}
\subsection{Search List Example}
The search list \code{code:} can be defined as follows:
\begin{example}
(setf (ext:search-list "code:") '("/usr/lisp/code/"))
\end{example}
It is now possible to use \code{code:} as an abbreviation for the directory
\file{/usr/lisp/code/} in all file operations. For example, you can now specify
\code{code:eval.lisp} to refer to the file \file{/usr/lisp/code/eval.lisp}.
To obtain the value of a search-list name, use the function search-list
as follows:
\begin{example}
(ext:search-list \var{name})
\end{example}
Where \var{name} is the name of a search list as described above. For example,
calling \code{ext:search-list} on \code{code:} as follows:
\begin{example}
(ext:search-list "code:")
\end{example}
returns the list \code{("/usr/lisp/code/")}.
\section{Filesystem Operations}
\cmucl{} provides a number of extensions and optional features beyond those
required by the \clisp{} specification.
\subsection{Wildcard Matching}
\label{wildcard-matching}
Unix filesystem operations such as \code{open} will accept wildcard pathnames
that match a single file (of course, \code{directory} allows any number of
matches.) Filesystem operations treat \kwd{wild-inferiors} the same as\
\kwd{wild}.
\begin{defun}{}{directory}{\var{wildname} \keys{\kwd{all} \kwd{check-for-subdirs}}
\kwd{truenamep} \morekeys{\kwd{follow-links}}}
The keyword arguments to this \clisp{} function are a \cmucl{} extension.
The arguments (all default to \code{t}) have the following
functions:
\begin{Lentry}
\item[\kwd{all}] Include files beginning with dot such as
\file{.login}, similar to ``\code{ls -a}''.
\item[\kwd{check-for-subdirs}] Test whether files are directories,
similar to ``\code{ls -F}''.
\item[\kwd{truenamep}] Call \code{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 \var{wildname} argument.
\item[\kwd{follow-links}] Follow symbolic links when searching for
matching directories.
\end{Lentry}
\end{defun}
\begin{defun}{extensions:}{print-directory}{%
\args{\var{wildname}
\ampoptional{} \var{stream}
\keys{\kwd{all} \kwd{verbose}}
\morekeys{\kwd{return-list}}}}
Print a directory of \var{wildname} listing to \var{stream} (default
\code{*standard-output*}.) \kwd{all} and \kwd{verbose} both default
to \false{} and correspond to the ``\code{-a}'' and ``\code{-l}''
options of \file{ls}. Normally this function returns \false{}, but
if \kwd{return-list} is true, a list of the matched pathnames are
returned.
\end{defun}
\subsection{File Name Completion}
\begin{defun}{extensions:}{complete-file}{%
\args{\var{pathname}
\keys{\kwd{defaults} \kwd{ignore-types}}}}
Attempt to complete a file name to the longest unambiguous prefix.
If supplied, directory from \kwd{defaults} is used as the ``working
directory'' when doing completion. \kwd{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.)
\end{defun}
\begin{defun}{extensions:}{ambiguous-files}{%
\args{\var{pathname}
\ampoptional{} \var{defaults}}}
Return a list of pathnames for all the possible completions of
\var{pathname} with respect to \var{defaults}.
\end{defun}
\subsection{Miscellaneous Filesystem Operations}
\begin{defun}{extensions:}{default-directory}{}
Return the current working directory as a pathname. If set with
\code{setf}, set the working directory.
\end{defun}
\begin{defun}{extensions:}{file-writable}{\var{name}}
This function accepts a pathname and returns \true{} if the current
process can write it, and \false{} otherwise.
\end{defun}
\begin{defun}{extensions:}{unix-namestring}{%
\args{\var{pathname}
\ampoptional{} \var{for-input}}}
This function converts \var{pathname} into a string that can be used
with UNIX system calls. Search-lists and wildcards are expanded.
\var{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.
\end{defun}
\section{Time Parsing and Formatting}
\cindex{time parsing} \cindex{time formatting}
Functions are provided to allow parsing strings containing time information
and printing time in various formats are available.
\begin{defun}{extensions:}{parse-time}{%
\args{\var{time-string}
\keys{\kwd{error-on-mismatch} \kwd{default-seconds}}
\morekeys{\kwd{default-minutes} \kwd{default-hours}}
\yetmorekeys{\kwd{default-day} \kwd{default-month}}
\yetmorekeys{\kwd{default-year} \kwd{default-zone}}
\yetmorekeys{\kwd{default-weekday}}}}
\code{parse-time} accepts a string containing a time (e.g.,
\w{"\code{Jan 12, 1952}"}) and returns the universal time if it is
successful. If it is unsuccessful and the keyword argument
\kwd{error-on-mismatch} is non-\nil{}, it signals an error.
Otherwise it returns \nil{}. The other keyword arguments have the
following meaning:
\begin{Lentry}
\item[\kwd{default-seconds}] specifies the default value for the
seconds value if one is not provided by \var{time-string}. The
default value is 0.
\item[\kwd{default-minutes}] specifies the default value for the
minutes value if one is not provided by \var{time-string}. The
default value is 0.
\item[\kwd{default-hours}] specifies the default value for the hours
value if one is not provided by \var{time-string}. The default
value is 0.
\item[\kwd{default-day}] specifies the default value for the day
value if one is not provided by \var{time-string}. The default
value is the current day.
\item[\kwd{default-month}] specifies the default value for the month
value if one is not provided by \var{time-string}. The default
value is the current month.
\item[\kwd{default-year}] specifies the default value for the year
value if one is not provided by \var{time-string}. The default
value is the current year.
\item[\kwd{default-zone}] specifies the default value for the time
zone value if one is not provided by \var{time-string}. The
default value is the current time zone.
\item[\kwd{default-weekday}] specifies the default value for the day
of the week if one is not provided by \var{time-string}. The
default value is the current day of the week.
\end{Lentry}
Any of the above keywords can be given the value \kwd{current} which
means to use the current value as determined by a call to the
operating system.
\end{defun}
\begin{defun}{extensions:}{format-universal-time}{
\args{\var{dest} \var{universal-time}
\\
\keys{\kwd{timezone}}
\morekeys{\kwd{style} \kwd{date-first}}
\yetmorekeys{\kwd{print-seconds} \kwd{print-meridian}}
\yetmorekeys{\kwd{print-timezone} \kwd{print-weekday}}}}
\defunx[extensions:]{format-decoded-time}{
\args{\var{dest} \var{seconds} \var{minutes} \var{hours} \var{day} \var{month} \var{year}
\\
\keys{\kwd{timezone}}
\morekeys{\kwd{style} \kwd{date-first}}
\yetmorekeys{\kwd{print-seconds} \kwd{print-meridian}}
\yetmorekeys{\kwd{print-timezone} \kwd{print-weekday}}}}
\code{format-universal-time} formats the time specified by
\var{universal-time}. \code{format-decoded-time} formats the time
specified by \var{seconds}, \var{minutes}, \var{hours}, \var{day},
\var{month}, and \var{year}. \var{Dest} is any destination
accepted by the \code{format} function. The keyword arguments have
the following meaning:
\begin{Lentry}
\item[\kwd{timezone}] is an integer specifying the hours west of
Greenwich. \kwd{timezone} defaults to the current time zone.
\item[\kwd{style}] specifies the style to use in formatting the
time. The legal values are:
\begin{Lentry}
\item[\kwd{short}] specifies to use a numeric date.
\item[\kwd{long}] specifies to format months and weekdays as
words instead of numbers.
\item[\kwd{abbreviated}] is similar to long except the words are
abbreviated.
\item[\kwd{government}] is similar to abbreviated, except the
date is of the form ``day month year'' instead of ``month day,
year''.
\end{Lentry}
\item[\kwd{date-first}] if non-\false{} (default) will place the
date first. Otherwise, the time is placed first.
\item[\kwd{print-seconds}] if non-\false{} (default) will format
the seconds as part of the time. Otherwise, the seconds will be
omitted.
\item[\kwd{print-meridian}] if non-\false{} (default) will format
``AM'' or ``PM'' as part of the time. Otherwise, the ``AM'' or
``PM'' will be omitted.
\item[\kwd{print-timezone}] if non-\false{} (default) will format
the time zone as part of the time. Otherwise, the time zone will
be omitted.
%%\item[\kwd{print-seconds}]
%%if non-\false{} (default) will format the seconds as part of
%%the time. Otherwise, the seconds will be omitted.
\item[\kwd{print-weekday}] if non-\false{} (default) will format
the weekday as part of date. Otherwise, the weekday will be
omitted.
\end{Lentry}
\end{defun}
\section{Random Number Generation}
\cindex{random number generation}
\clisp{} includes a random number generator as a standard part of the
language; however, the implementation of the generator is not
specified. Two random number generators are available in \cmucl{},
depending on the version.
\subsection{Original Generator}
\cpsubindex{random number generation}{original generator}
The default random number generator uses a lagged Fibonacci generator
given by
\begin{displaymath}
z[i] = z[i - 24] - z[i - 55] \bmod 536870908
\end{displaymath}
where $z[i]$ is the $i$'th random number. This generator produces
small integer-valued numbers. For larger integer, the small random
integers are concatenated to produce larger integers. For
floating-point numbers, the bits from this generator are used as the
bits of the floating-point significand.
\subsection{New Generator}
\cpsubindex{random number generation}{new generator}
In some versions of \cmucl{}, the original generator above has been
replaced with a subtract-with-borrow generator
combined with a Weyl generator.\footnote{The generator described here
is available if the feature \kwd{new-random} is available.} The
reason for the change was to use a documented generator which has
passed tests for randomness.
The subtract-with-borrow generator is described by the following
equation
\begin{displaymath}
z[i] = z[i + 20] - z[i + 5] - b
\end{displaymath}
where $z[i]$ is the $i$'th random number, which is a
\code{double-float}. All of the indices in this equation are
interpreted modulo 32. The quantity $b$ is carried over from the
previous iteration and is either 0 or \code{double-float-epsilon}. If
$z[i]$ is positive, $b$ is set to zero. Otherwise, $b$ is set to
\code{double-float-epsilon}.
To increase the randomness of this generator, this generator is
combined with a Weyl generator defined by
\begin{displaymath}
x[i] = x[i - 1] - y \bmod 1,
\end{displaymath}
where $y = 7097293079245107 \times 2^{-53}$. Thus, the resulting
random number $r[i]$ is
\begin{displaymath}
r[i] = (z[i] - x[i]) \bmod 1
\end{displaymath}
This generator has been tested by Peter VanEynde using Marsaglia's
diehard test suite for random number generators; this generator
passes the test suite.
This generator is designed for generating floating-point random
numbers. To obtain integers, the bits from the significand of the
floating-point number are used as the bits of the integer. As many
floating-point numbers as needed are generated to obtain the desired
number of bits in the random integer.
For floating-point numbers, this generator can by significantly faster
than the original generator.
\subsection{MT-19987 Generator}
\cpsubindex{random number generation}{MT-19987 generator}
On all platforms, this is the preferred generator as indicated by
\kwd{rand-mt19987} being in \code{*features*}. This is a Lisp
implementation of the MT-19987 generator of Makoto Matsumoto and
T. Nishimura. We refer the reader to their paper\footnote{``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} or to
their
\ifpdf
\href{http://www.math.keio.ac.jp/~matumoto/emt.html}{website}.
\else
website at
\href{http://www.math.keio.ac.jp/~matumoto/emt.html}{\texttt{http://www.math.keio.ac.jp/~matumoto/emt.html}}.
\fi
\section{Lisp Threads}
\cindex{lisp threads}
\cmucl{} supports Lisp threads for the x86 platform.
\section{Lisp Library}
\label{lisp-lib}
The \cmucl{} project maintains a collection of useful or interesting
programs written by users of our system. The library is in
\file{lib/contrib/}. Two files there that users should read are:
\begin{Lentry}
\item[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.
\item[READ-ME.TXT]
This file describes the library's organization and all the
possible pieces of information an entry's catalog description could contain.
\end{Lentry}
Hemlock has a command \F{Library Entry} that displays a list of the current
library entries in an editor buffer. There are mode specific commands that
display catalog descriptions and load entries. This is a simple and convenient
way to browse the library.