<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">\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} &amp; \multicolumn{1}{|c}{Lisp} &amp;
      \multicolumn{3}{|c|}{} \\
      \cline{1-2}
      Name &amp; Code &amp; \multicolumn{1}{|c|}{Name} &amp; \multicolumn{3}{|c|}{\raisebox{1.5ex}{Alternatives}}\\
      \hline
      \hline
      \code{nul} &amp; 0 &amp; \code{\#\back{NULL}} &amp; \code{\#\back{NUL}} &amp; &amp;\\
      \code{bel} &amp; 7 &amp; \code{\#\back{BELL}} &amp; &amp; &amp;\\
      \code{bs} &amp;  8 &amp; \code{\#\back{BACKSPACE}} &amp; \code{\#\back{BS}} &amp; &amp;\\
      \code{tab} &amp; 9 &amp; \code{\#\back{TAB}} &amp; &amp; &amp;\\
      \code{lf} &amp; 10 &amp; \code{\#\back{NEWLINE}} &amp; \code{\#\back{NL}} &amp; \code{\#\back{LINEFEED}} &amp; \code{\#\back{LF}}\\
      \code{ff} &amp; 11 &amp; \code{\#\back{VT}} &amp; \code{\#\back{PAGE}} &amp; \code{\#\back{FORM}} &amp;\\
      \code{cr} &amp; 13 &amp; \code{\#\back{RETURN}} &amp; \code{\#\back{CR}} &amp; &amp;\\
      \code{esc} &amp; 27 &amp; \code{\#\back{ESCAPE}} &amp; \code{\#\back{ESC}} &amp; \code{\#\back{ALTMODE}} &amp; \code{\#\back{ALT}}\\
      \code{sp} &amp; 32 &amp; \code{\#\back{SPACE}} &amp; \code{\#\back{SP}} &amp; &amp;\\
      \code{del} &amp; 127 &amp; \code{\#\back{DELETE}} &amp; \code{\#\back{RUBOUT}} &amp; &amp;\\
      \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} \&amp;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") =&gt; "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.
</pre></body></html>