\documentstyle{report}
\pagestyle{plain}
\pagenumbering{roman}
\begin{document}

\title{ Kyoto Common Lisp Report}

\author{Taiichi Yuasa and Masami Hagiya\\ Research Institute for
Mathematical Sciences\\ Kyoto University} 

\date{} 

\maketitle

\newpage

\centerline{\LARGE Preface}

\vspace{.3in}

\noindent Kyoto Common Lisp (KCL for short) is a full implementation of the
Common Lisp language described in the Common Lisp Reference Manual:

\vspace{.2in}

\centerline{\it Common Lisp: The Language}
\centerline{ by Guy L. Steele et al.}
\centerline{ Digital Press, 1984}

\vspace{.2in} 

\noindent All Common Lisp functions, macros, and special
forms are defined in KCL, though a few of them have slightly different
meanings from those described in the Common Lisp Reference Manual .
All such differences are described in this report: If a Common Lisp
function (or macro or special form) does not work as described in the
Common Lisp Reference Manual and if this report does not describe the
d
ifference explicitly, then there must be a bug in KCL.  All Common
Lisp variables and constants are defined in KCL exactly as described
in the Common Lisp Reference Manual .

\vspace{.2in}

\noindent Currently, there are four major versions of KCL:

\begin{enumerate}

\item KCL/AOS, under the AOS/VS operating system for Data
General's ECLIPSE MV series machines.

\item  KCL/VAX, under the Unix 4.2 bsd operating system for
Digital Equipment Corporation's VAX 11 series machines.

\item  KCL/SUN, under the Unix 4.2 bsd operating system for Sun
Microsystems' Sun Workstation.

\item KCL/UST, under the Unix V (Uniplus' version) operating
system for Sumitomo Electric Industries and Digital Computer
Laboratory's Ustation E15.

\end{enumerate}

\vspace{.2in}

\noindent KCL/ AOS is the original version of KCL, which was developed at the
Research Institute for Mathematical Sciences (RIMS), Kyoto University,
with the cooperation of Nippon Data General Corporation.  The other
three versions, which are collectively called {\it KCL on Unix}, are
transplanted versions of KCL/AOS.

\vspace{.2in}

\noindent This report is intended to complement the {\it Common Lisp Reference
Manual}.  This report describes deviations of KCL from Common Lisp,
those features specific to KCL, and the implementation-dependent
functions of Common Lisp.

\newpage

\centerline{\LARGE Acknowledgements}

\vspace{.3in}

\noindent The project of KCL was supported by many people affiliated with many
institutions.  We are very grateful especially to the following people
for their contributions to the KCL project.

\vspace{.2in}

First of all, we are grateful to the contributors to the design
of Common Lisp.

Prof. Reiji Nakajima at RIMS, Kyoto University, provided us with
considerable encouragement and moral support.
Nippon Data General Corporation (NDG) helped us implement KCL/AOS.
Mr. Teruo Yabe and Mr. Toshiyasu Harada joined us during the first
stage of the KCL project and did a lot of coding.  Mr. Takashi Suzuki
and Mr. Kibo Kurokawa arranged the joint project.  NDG is now
supporting the distribution of KCL/AOS.

Data General Corporation in the United States sent us materials
necessary to implement a Common Lisp system, such as the preliminary
drafts of the Common Lisp reference manual and benchmark tests for
Common Lisp.  For the benchmark tests we are indebted to Dr. Richard
Gabriel at Stanford University.

Dr. Daniel Weinreb at Symbolics answered most of our questions about
the language specification.  He also sent us the definition of
rationalize written by Dr. Skef Wholey at CMU.
We use this definition in KCL without any change.

Dr. Carl Hoffman at Symbolics checked the top-level of KCL and gave us
advice for improving KCL.  He also found some bugs in KCL and fixed
them for us.

Mr. Naruhiko Kawamura at RIMS developed a Prolog system using the
earliest version of KCL/AOS.  That was one of the first big projects
with KCL and he found many bugs.

Mr. Takashi Sakuragawa at RIMS hacked with KCL/AOS and gave us much
advice concerning those features specific to KCL.

Mr. Tatsuya Hagino at Edinburgh University developed Micro EMACS on
which FeCl2, the full-screen editor embedded in KCL/AOS, is based.

Mr. Kunihiko Nakamura at Kagawa University converted the assembly
language version of Micro EMACS into the C language, which happened to
become the prototype of FeCl2.

Prof. Akinori Yonezawa at Tokyo Institute of Technology encouraged us
to port KCL/AOS to the VAX 11.

Mr. Etsuya Shibayama at Tokyo Institute of Technology helped us
while we were working with the VAX 11 at the Institute.

Hagiwara Laboratory at Kyoto University offered (and is offering)
their VAX 11 for finishing transplantation and maintaining KCL/VAX.
We got also technical advice from people at Hagiwara Laboratory.

Prof. Shuji Doshita at Kyoto University offered the SUN Workstation at
his Laboratory and gave us a lot of advice for transplantation to the
SUN Workstation.

Mr. Takashi Hattori at RIMS gave us useful information about the
Motorola 68000, the CPU chip of SUN Workstation.

\newpage

\tableofcontents

\chapter{How to Start and End a KCL Session}
\pagenumbering{arabic}
 
KCL on Unix is invoked by the Shell command {\tt kcl}.\hfill\break

\begin{verbatim}
          % kcl
          KCL (Kyoto Common Lisp)  July 1, 1985
\end{verbatim}

\centerline{------------Note to KCL/AOS users------------}
\vspace{.1in}

KCL/AOS is invoked by the CLI command {\tt KCL.\hfill\break

\vspace{.1in}

\hspace*{1in}{}) KCL\hfill\break
\hspace*{1in}{}KCL (Kyoto Common Lisp)  July 1, 1985}\hfill\break

\vspace{.1in}

\centerline{---------------End of Note---------------}

\vspace{.2in}

\noindent When invoked, KCL will print the banner and initialize the system.
The date in the KCL banner identifies the revision of KCL.
{\tt ``July 1, 1985''}  is the value of the
function {\tt lisp-implementation-version}.

\medskip

\noindent If there exists a file named {\tt init.lsp} in the current working
directory, KCL successively evaluates the forms in the file,
immediately after the system initialization.  The user may set up his
or her own KCL environment (e.g., the memory configuration) with
{\tt init.lsp}.

\medskip

\noindent After the initialization, KCL enters the  {\it top-level loop}  and
prints the prompt `$>$'.

\begin{verbatim}
          >
\end{verbatim}

\noindent The prompt indicates that KCL is now ready to receive a form
from the terminal and to evaluate it.

\noindent Usually, the current package (i.e., the value of {\tt
*package*}) is the user package, and the prompt appears as above.  If,
however, the current package is other than the user package, then the
prompt will be prefixed by the package name.\hfill\break

\vspace*{.1in}

\hspace*{.8in}{}{\it package-name$>$}\hfill\break

\vspace*{.1in}

\noindent To exit from KCL, call the function {\tt bye} (or {\tt by}).\hfill\break

\begin{verbatim}
          >(bye)
          Bye.
          %
\end{verbatim}

\centerline{------------Note to KCL/AOS users------------}

\vspace{.1in}

\noindent In this report, we sometimes assume that KCL is invoked from
the Unix Shell.  In particular, we use the standard prompt of the Unix
Shell {\tt `\%'} in most examples.

\vspace{.1in}

\centerline{---------------End of Note---------------}

\vspace{.1in}

\noindent Alternatively, you may type {\tt \^{}D} (control-D), i.e.,
press the key D while pressing down the control key.\hfill\break

\begin{verbatim}
          >^Dbye.
          %
\end{verbatim}

\noindent The top-level loop of KCL is almost the same as that defined
in Section 20.2 of the {\it Common Lisp Reference Manual}.  Since the
input from the terminal is in line mode, each top-level form should be
followed by a newline.  If more than one value is returned by the
evaluation of the top-level form, the values will be printed
successively.  If no value is returned, then nothing will be
printed.\hfill\break 

\vspace{.1in}

\begin{verbatim}
        >(values 1 2)
        1
        2

        >(values)

        >
 \end{verbatim}

\vspace{.1in}

\noindent When an error is signalled, control will enter the break loop.
\begin{verbatim}

        >(defun foo (x) (bar x))
        foo

        >(defun bar (y) (bee y y))
        bar
 
        >(foo 'lish)
        Error: The function BEE is undefined.
        Error signalled by BAR.

        Broken at BAR.
        >>
\end{verbatim}

\vspace{.1in}

\noindent {\tt `$>>$'} in the last line is the prompt of the break loop.
Like in the top-level loop, the prompt will be prefixed by the current
package name, if the current package is other than the {\tt user}
package.

\medskip

\noindent To go back to the top-level loop, type {\tt :q}

\vspace{.1in}

\begin{verbatim}
        >>:q

        Top level.
        > 
\end{verbatim}

\vspace{.1in}

\noindent See Section 5.4 for the details of the break loop.\hfill\break

\medskip

\noindent In KCL on Unix, the terminal interrupt (usually caused by typing
{\tt \^{}C} (control-C) or by typing {\tt DELETE}) is a kind of error.
It breaks the running program and calls the break level loop.

\vspace{.1in}

	Example:\hfill\break
\begin{verbatim}
        >(defun foo () (do () (nil)))
        foo

        >(foo)
        ^C
        Correctable error: Console interrupt.
        Signalled by DO.

        Broken at FOO.
        >>
\end{verbatim}

\vspace{.1in}

\centerline{------------Note to KCL/AOS users------------}
\vspace{.1in}

\noindent In KCL/AOS, the console interrupt caused by typing {\tt \^{}C}
(control-C) followed by {\tt \^{}A} (control-A) is a kind of error.
Typing {\tt ctrlC} and {\tt \^{}A} breaks the running program and calls
the break loop.  On the other hand, the console interrupt caused by
{\tt \^{}C} and {\tt \^{}B} (control-B) will immediately terminate KCL.

\vspace{.1in}

     Example:

\vspace{.1in}

\begin{verbatim}
        >(defun foo () (do () (nil)))
        foo

        >(foo)
        ^C^A
        Correctable error: Console interrupt.
        Signalled by DO.

        Broken at FOO.
        >>(foo)
        ^C^B
	*ABORT*
	CONSOLE INTERRUPT
	ERROR: FROM PROGRAM
        LEVEL 1
	x,kcl
	) 
\end{verbatim}

\vspace{.1in}

\centerline{---------------End of Note---------------}


\chapter{Data Types}


KCL supports all Common Lisp data types exactly as defined
in the {\it Common Lisp Reference Manual}.  This chapter simply
complements Chapter 2 of the {\it Common Lisp Reference Manual}, by
describing implementation dependent features of Common Lisp data
types.  Each section in this chapter corresponds to the section in
Chapter 2 of the {\it Common Lisp Reference Manual}, with the same
section title.


\section{Numbers}

\subsection{Integers}

\noindent {\tt Fixnums} in KCL are those integers in the range -(2 to the power of 31)
to (2 to the power of 31)-1, inclusive.  Other integers are {\tt bignums}.
Thus 25 factorial (25!)
\begin{verbatim}

    15511210043330985984000000

\end{verbatim}

\noindent is certainly a bignum in KCL.\hfill\break

\medskip

\noindent Common Lisp constants related to integers have the following values
in KCL.
\begin{verbatim}

  most-positive-fixnum = 2147483647 = (2 to the power of 31)-1
  most-negative-fixnum = -2147483648 = - (2 to the power of 31)

  boole-1 = 3
  boole-2 = 5
  boole-and = 1
  boole-andc1 = 4
  boole-andc2 = 2
  boole-c1 = 12
  boole-c2 = 10
  boole-clr = 0
  boole-eqv = 9
  boole-ior = 7
  boole-nand = 14
  boole-nor = 8
  boole-orc1 = 13
  boole-orc2 = 11
  boole-set = 15
  boole-xor = 6
 
\end{verbatim}

\noindent See Chapter 12 of the  {\it Common Lisp Reference Manual}  for their
meanings.


\subsection{Ratios}
 
\noindent There are no implementation-dependent features for ratios.


\subsection{Floating-Point Numbers}

\noindent KCL provides two distinct internal floating-point formats.  One format
is {\it short}; the other is {\it single} and serves also as {\it
double} and {\it long}.  The data types {\tt single-float} , {\tt
double-float }, and {\tt long-float} are considered to be identical,
but {\tt short-float } is distinct.  An expression such as {\tt (eql
1.0s0 1.0d0)} is false, but {\tt (eql 1.0f0 1.0d0)} is true.  Similarly,
{\tt (typep 1.0L0 'short-float)} is false, but {\tt (typep 1.0L0
'single-float}) is true.  For output purposes all floating-point
numbers are assumed to be of {\it short} or {\it single} format.

\vspace{.1in}

\noindent The floating-point precisions are:

\begin{verbatim}

Format     KCL/AOS     KCL/VAX     KCL/SUN     KCL/UST
------------------------------------------------------ 
Short      24 bits     23 bits     24 bits     24 bits
Single     56 bits     55 bits     53 bits     53 bits
Double     56 bits     55 bits     53bits      53 bits
Long       56 bits     55 bits     53 bits     53 bits

\end{verbatim}

\noindent The floating-point exponent sizes are:\hfill\break
\begin{verbatim}

Format     KCL/AOS     KCL/VAX     KCL/SUN     KCL/UST
------------------------------------------------------
Short      7 bits      8 bits       8 bits      8 bits
Single     7 bits      8 bits      11 bits     11 bits
Double     7 bits      8 bits      11 bits     11 bits
Long       7 bits      8 bits      11 bits     11 bits

\end{verbatim}

\noindent There is no ``minus zero.''  {\tt (eql 0.0 -0.0)}  is true.\hfill\break

\medskip

\noindent Common Lisp constants related to floating-point numbers have the
following values in KCL.
\begin{verbatim}

    most-positive-short-float
      = - most-negative-short-float
      = 7.237005s75  (KCL/AOS)
        1.701412s38  (KCL/VAX)
        3.402823s38  (KCL/SUN and KCL/UST)

    least-positive-short-float
      = - least-negative-short-float
      = 5.397605s-79  (KCL/AOS)
        2.938736s-39  (KCL/VAX)
        1.401298s-45  (KCL/SUN and KCL/UST)

    most-positive-long-float
      = most-positive-double-float
      = most-positive-single-float
      = - most-negative-long-float
      = - most-negative-double-float
      = - most-negative-single-float
      = 7.237005577332264f75  (KCL/AOS)
        1.701411834604692f38  (KCL/VAX)
        1.797693134862315f308  (KCL/SUN and KCL/UST)

    least-positive-long-float
      = least-positive-double-float
      = least-positive-single-float
      = - least-negative-long-float
      = - least-negative-double-float
      = - least-negative-single-float
      = 5.397605346934027f-79  (KCL/AOS)
        2.938735877055719f-39  (KCL/VAX)
        4.940656458412469f-324  (KCL/SUN and KCL/UST)

    short-float-epsilon
      = 4.468372s-7  (KCL/AOS)
        6.938894s-18  (KCL/VAX)
        2.980232s-8  (KCL/SUN and KCL/UST)

    short-float-negative-epsilon
      = 2.980232s-8  (KCL/AOS)
        6.938894s-18  (KCL/VAX)
        2.980232s-8  (KCL/SUN and KCL/UST)

    long-float-epsilon
      = double-float-epsilon
      = single-float-epsilon
      = 1.110223024625157f-16  (KCL/AOS)
        6.938893903907228f-18  (KCL/VAX)
        5.5511151231257827f-17  (KCL/SUN and KCL/UST)

    long-float-negative-epsilon
      = double-float-negative-epsilon
      = single-float-negative-epsilon
      = 6.938893903907228f-18  (KCL/AOS)
        6.938893903907228f-18  (KCL/VAX)
        5.5511151231257827f-17  (KCL/SUN and KCL/UST)

    pi = 3.141592653589793

\end{verbatim}

\noindent See Chapter 12 of the  {\it Common Lisp Reference Manual}  for their
meanings.


\subsection{Complex Numbers}
 
\noindent There are no implementation-dependent features for complex numbers.


\section{Characters}

\subsection{Standard Characters}

\noindent KCL supports all standard and semi-standard characters listed in
Section 2.2.1 of the {\it Common Lisp Reference Manual} .
Non-printing characters have the following character codes.
\begin{verbatim}

       Character        Code  (in octal)
       --------------------------------
       #\Space                 040
       #\Newline               012
       #\Backspace             010
       #\Tab                   011
       #\Linefeed              012
       #\Page                  014
       #\Return                015
       #\Rubout                177

\end{verbatim}

\noindent Note that {\tt \#$\backslash$Linefeed} is synonymous with
{\tt \#$\backslash$Newline} and thus is a member of
{\tt standard-char}.  Other semi-standard characters are not members
of {\tt standard-char}.

\vspace{.1in}

\centerline{------------ Note to KCL/AOS users------------}\hfill\break

KCL/AOS uses 025 (in octal) as the character code of
{\tt \#$\backslash$Backspace}.

\vspace{.1in}

\centerline{--------------- End of Note ---------------}\hfill\break

\subsection{Line Divisions}
 
\noindent Since KCL represents the {\tt \#$\backslash$Newline}  character by a single
code 12 , problems with line divisions discussed in Section 2.2.2
of the  {\it Common Lisp Reference Manual}  cause no problem in KCL.


\subsection{Non-standard Characters}
 
\noindent KCL supports no additional non-standard characters.


\subsection{Character Attributes}
 
\noindent The bit and font fields of KCL characters are always 0 .\hfill\break

\vspace{.1in}

\noindent Common Lisp constants related to characters have the following values
in KCL.

\begin{verbatim}
    char-bits-limit = 1
    char-code-limit = 256
    char-control-bit = 0 
    char-font-limit = 1 
    char-hyper-bit = 0 
    char-meta-bit = 0 
    char-super-bit = 0
\end{verbatim}

\noindent See Chapter 13 of the  {\it Common Lisp Reference Manual}  for their
meanings.


\subsection{String Characters}
 
\noindent Since the bit and font fields of KCL characters are always 0 ,
{\tt string-char}  is considered to be identical to {\tt character}.


\section{Symbols}
 
\noindent The print name of a symbol may consist of up to 16777216 (i.e., the value
of {\tt array-total-size-limit}) characters.  However, when a symbol is
read, the number of characters (not counting escape characters)
in the print name is limited to 2048.


\section{Lists and Conses}
 
\noindent There are no implementation-dependent features for lists and conses.

\section{Arrays}
 
\noindent KCL arrays can have up to 64 ranks.\hfill\break

\medskip

\noindent When the value of the Common Lisp variable {\tt
$\ast$print-array$\ast$} (see Section 22.1.6 of the {\it Common Lisp
Reference Manual} ) is {\tt nil}, then bit-vectors are printed as
{\tt \#<a bit-vector>}, other vectors are printed as {\tt \#<a vector>},
and other arrays are printed as {\tt \#<an array>}.

\medskip

\noindent Common Lisp constants related to arrays have the following values in
KCL.

\begin{verbatim}
    array-dimension-limit = 16777216
    array-rank-limit = 64
    array-total-size-limit = 16777216
\end{verbatim}

\noindent See Section 17.1 of the  {\it Common Lisp Reference Manual}  for
their meanings.


\subsection{Vectors}
 
\noindent In KCL, array elements are represented in one of six ways depending
on the type of the {\tt array}.

\begin{verbatim}

Array Type                               Element Representation
---------------------------------------------------------------
(array t) and (vector t)                      a cell pointer
(array fixnum) and (vector fixnum)            32 bit signed integer
(array string-char) and string                8 bit code
(array short-float) and (vector short-float)  32 bit floating point
(array long-float) and (vector long-float)    64 bit floating point
(array bit) and bit-vector                    1 bit bit
\end{verbatim}

\subsection{Strings}

\noindent A string may consists of up to 16777216 (i.e., the value of
{\tt array-total-size-limit}) characters.  However, when a string is
read, the number of characters (not counting escape characters) in the
string is limited to 2048.


\subsection{Bit-Vectors}
 
\noindent There are no implementation-dependent features for bit-vectors.


\section{Hash Tables}
 
\noindent All hash tables are printed as {\tt \#<a hash-table>}.


\section{Readtables}
 
\noindent All readtables are printed as {\tt \#<a readtable>}.


\section{Packages}
 
\noindent The following packages are built into KCL.

\begin{verbatim}
     lisp     user     keyword     system     compiler
\end{verbatim}


\noindent The {\tt compiler} package contains symbols used by the KCL compiler.
Other packages are described in Section 11.6 of the {\it Common Lisp
Reference Manual}.  The {\tt system} package has two nicknames {\tt sys}
and {\tt si} ; {\tt system: symbol} may be written as {\tt sys: symbol}
or {\tt si: symbol}.  Other packages have no nicknames.

\medskip

\noindent Packages are printed as {\tt \#<{\it package-name} package>}.


\section{Pathnames}
 
\noindent KCL provides a {\tt \#}  macro {\tt \#"}  that reads a
pathname:  {\tt \#"{\it string}"}  is equivalent
to ( a{\tt pathname "{\it string}"}) .  For example,

\begin{verbatim}
          #"foo.lsp"
\end{verbatim}

\noindent is equivalent to

\begin{verbatim}
          (pathname "foo.lsp").
\end{verbatim}

\noindent The same format is used when a pathname is printed.

\medskip

\noindent The initial value of the Common Lisp variable  {\tt
\*default-pathname-defaults\*} is {\tt \#""}  (or, equivalently,  {\tt (pathname "")} ).

\medskip

\noindent A pathname in the file system of Common Lisp consists of the following
six elements:

\begin{verbatim}
          host  device  directory  name  type  version
\end{verbatim}

\noindent Among these elements, KCL does not use {\tt host, device}, and {\tt version}.
That is, when converting a namestring into a pathname, KCL turns these
three elements into {\tt nil}.  Conversely, when converting a pathname into
a namestring, KCL ignores these three elements.

\medskip

\noindent In the sequel, we explain how KCL converts a namestring into
a pathname.

\medskip

\noindent If a namestring contains one or more periods `.', the last period
separates the namestring into the file name and the filetype.

\begin{verbatim}
     "foo.lsp"
         name:          "foo" 
         type:          "lsp"

     "a.b.c" 
         name:          "a.b" 
         type:          "c" 
\end{verbatim}

\noindent If a namestring ends with a period, the filetype becomes the null
string.
\begin{verbatim}
     "foo." 
          name:          "foo" 
          type:          ""  (null string)
\end{verbatim}

\noindent If a namestring begins with a period, the file name becomes  {\tt nil} .

\begin{verbatim}
     ".lsp" 
          name:          nil 
          type:          "lsp" 
\end{verbatim}

\noindent If a namestring contains no period, the filetype is  {\tt nil} .

\begin{verbatim}
    "foo" 
          name:          "foo" 
          type:          nil 
\end{verbatim}

\noindent In a pathname, the file directory is represented as a list.

\begin{verbatim}
     "common/demo/foo.lsp" 
          directory:     ("common"   "demo") 
          name:          "foo" 
          type:          "lsp" 
\end{verbatim}

\noindent If a namestring does not contain a directory, the directory component
of the pathname is {\tt nil} . 

\begin{verbatim}
     "foo.lsp" 
          directory:     nil 
          name:          "foo" 
          type:          "lsp" 
\end{verbatim}

\noindent In a pathname, the root directory is represented by the keyword
{\tt :root}.

\begin{verbatim}
     "/usr/common/foo.lsp"
          directory:     (:root "usr" "common") 
          name:          "foo" 
          type:          "lsp" 
\end{verbatim}

\noindent The abbreviation symbols ` . ' and ` .. ' may be used in a namestring.

\begin{verbatim}
     "./demo/queen.lsp" 
          directory:     (:current\(ri ':current) "demo") 
          name:          "queen" 
          type:          "lsp" 

     "../../demo/queen.lsp" 
          directory:     (:parent\(ri ':parent) :parent "demo") 
          name:          "queen" 
          type:          "lsp" 
\end{verbatim}

\noindent {\tt :current} and {\tt :parent} represent the current directory and
the parent directory, respectively.

\medskip

\noindent The part of a namestring after the last slash `{\tt /}' is always regarded
as representing the file name and the filetype.  In order to represent
a pathname with both the name and the filetype {\tt nil}, end the pathname
with a slash.

\begin{verbatim}
     "/usr/common/" 
          directory:     (:root "usr" "common") 
          name:          nil 
          type:          nil 

     "/usr/common/.lsp" 
          directory:     (:root "usr" "common") 
          name:          nil 
          type:          "lsp" 
\end{verbatim}

\noindent ` $\ast$ ' in the place of file name or filetype becomes  {\tt :wild}

\begin{verbatim}
     "*.lsp" 
          name:          :wild 
          type:          "lsp" 

     "foo.*" 
          name:          "foo" 
          type:          :wild 
\end{verbatim}

\centerline{---------- Note to KCL/AOS users ------------}\hfill\break

\noindent In KCL/AOS, all the lower-case letters are turned into
upper-case letters by pathname conversions.  Thus, for example,

\begin{verbatim}
     "foo.lsp" 
          name:          "FOO" 
          type:          "LSP"
\end{verbatim}

\noindent KCL/AOS follows the convention of the AOS/VS file system: The symbols
`{\tt /} ', ` . ', ` .. ', and ` $\ast$ ' in the examples above should be
replaced by ` : ', ` {\tt =} ', ` \^{}', and ` - ', respectively, in
KCL/AOS.

\vspace{.1in}

\centerline{--------------- End of Note ---------------}

\vspace{.1in}

\section{Streams}
 
\noindent Streams are printed in the following formats.

\vspace{.1in}

\noindent  {\tt \#<input stream  {\it file-name} > }\hfill\break
\indent     An input stream from the file  {\it file-name} .\hfill\break

\noindent  {\tt \#<output stream  {\it file-name} >} \hfill\break
\indent     An output stream to the file  {\it file-name} .\hfill\break

\noindent  {\tt \#<string-input stream from  {\it string} >} \hfill\break
\indent     An input stream generated by  {\tt
(make-string-input-stream  {\it string} )}.\hfill\break

\noindent {\tt \#<a string-output stream>} \hfill\break
\indent     An output stream generated by the function  {\tt
make-string-output-\hfill\break
\indent stream}.\hfill\break

\noindent {\tt \#<a two-way stream>} \hfill\break
\indent     A stream generated by the function  {\tt make-two-way-stream}.\hfill\break

\noindent {\tt \#<an echo stream>} \hfill\break
\indent     A bidirectional stream generated by the function  {\tt make-echo-stream}.\hfill\break

\noindent  {\tt \#<synonym stream to  {\it symbol} >}\hfill\break 
\indent     The stream generated by  {\tt (make-synonym-stream {\it symbol} )}.\hfill\break

\noindent  {\tt \#<a concatenated stream>} \hfill\break
\indent     An input stream generated by the function  {\tt make-concatenated-stream}.\hfill\break

\noindent  {\tt \#<a broadcast stream>} \hfill\break
\indent     An output stream generated by the function  {\tt make-broadcast-stream}.\hfill\break

\section{Random-States}

\noindent KCL provides a {\tt \#} macro {\tt ` \#\$ '} that reads a random state.
{\tt \#\$}{\it integer} is equivalent to {\tt (make-random-state {\it
integer})} .  The same format is used when a random state is printed.


\section{Structures}
 
\noindent There are no implementation-dependent features for structures.


\section{Functions}
 
\noindent An interpreted function (including macro expansion functions) is
represented in one of the following formats.



\noindent {\tt (lambda  {\it lambda-list}  .  body )}

\begin{description}

\item[] A lambda-expression with null lexical environment and with no implicit
block around it.  This type of function typically appears when
{\tt `(lambda  {\it lambda-list}  .  body )}  is evaluated.

\end{description}

\noindent {\tt (lambda-block  {\it block-name   lambda-list}  .  body )}

\begin{description}

\item[] A lambda-expression with null lexical environment but with an
implicit block around it.  This type of function typically appears
when {\tt (defun  {\it function-name   lambda-list}  .  body )}  is
evaluated.  In this case,  {\it block-name}  is identical to  {\it function-name} .

\end{description}

\noindent {\tt (lambda-closure  {\it env1   env2   env3   lambda-list}
.  body )}

\begin{description}

\item[] A lambda-expression with lexical environments but with no
implicit block around it.  This type of function typically appears
when {\tt \#`(lambda  {\it lambda-list}  .  body )}  (or, equivalently,
{\tt (function (lambda  {\it lambda-list}  .  body )) } ) is
evaluated.   {\it env1 ,  env2} , {\it and  env3}  represent
the variable bindings, the local function/macro definitions, and
the tag/block-name establishments, respectively, at the time the closure
was created.

\end{description}

\noindent {\tt (lambda-block-closure  {\it env1   env2   env3
block-name   lambda-list}  .  body )}

\begin{description}

\item[] A lambda-expression with lexical environments and with an
implicit block around it.  Local functions and local macros are
represented in this format.  {\it env1 , env2} , and {\it env3}
represent the variable bindings, the local function/macro bindings,
and the tag/block-name establishments, respectively, at the time the
local function/macro was created by {\tt flet, labels}, or {\tt
macrolet}.  The {\it block-name} is identical to the local
function/macro name.
\end{description}

\noindent Compiled functions (including compiled macro-expansion functions) are
printed in the following formats.

\vspace{.1in}

\indent {\tt \#<compiled-function  {\it name} >} \hfill\break
\noindent  or\hfill\break
\indent {\tt \#<compiled-closure nil>}

\vspace{.1in}

\noindent Incidentally, the value of {\tt (symbol-function {\it
special-form-name} )} is a list,

\vspace{.1in}

     {\tt (special .  {\it address} )}\hfill\break

\vspace{.1in}

\noindent if  {\it special-form-name}  names a special form.

\vspace{.1in}

\noindent Common Lisp constants related to functions have the following values
in KCL.

\begin{verbatim}
    call-arguments-limit = 64
    lambda-list-keywords = (&optional &rest &key &allow-
                            other-keys &aux &whole 
                            &environment &body)
    lambda-parameters-limit = 64
    multiple-values-limit = 32
\end{verbatim}

\noindent Refer to the  {\it {\it Common Lisp Reference Manual}}  for their meanings.


\section{Unreadable Data Objects}
 
\noindent There are no implementation-dependent features for unreadable data objects.


\section{Overlap, Inclusion, and Disjointness of Types}

 
\noindent In KCL, the types {\tt number} and {\tt array} are certainly
subtypes of common, since KCL does not extend the set of objects
of these types.


\chapter{Input and Output}

\section{Read Macros}
 
\noindent The following {\tt \#} macros are introduced in KCL.\hfill\break
 

\begin{description}

\item[{\tt \#"} \hspace*{.3in}{}] {\tt \#" {\it string} "}  reads a pathname.\hfill\break
{\tt \#" {\it string}  "}  is equivalent to  {(\tt (pathname " {\it string} ")}.
 
\item[{\tt \#\$} \hspace*{.3in}{}] {\tt \#\${\it integer}}  reads a random state.\hfill\break
{\tt \#\$}{\it integer}  is equivalent to  {\tt (make-random-state {\it integer} )} .

\end{description}

\noindent The {\tt \#} macro {\tt `\#,'} works as described
in the  {\it Common Lisp Reference Manual} ,
only if it is included in a constant object.  The forms immediately
after {\tt `\#,'} below will be evaluated when the compiled code is loaded.

\begin{verbatim}
     '#,x
     '(a b c (d #,e f) g)
     #(1 2 3 #,(+ a b c) 5 6)
     #C(0.0 #,(exp 1))
\end{verbatim}

\noindent Otherwise, the effect of using {\tt `\#,'} is unpredictable.  Note
that, when interpreted code is loaded, {\tt `\#,'} has the same effect
as the {\tt \#} macro {\tt `\#.'}.


\section{Input and Output Functions}

\noindent The input and output functions of KCL almost follow the definitions in
Chapter 22 of the {\it Common Lisp Reference Manual} .  Most of the
differences come from the fact that, in KCL, input from the terminal
is always in line mode and binary I/O is not supported.

\medskip

\noindent In KCL, {\tt $\ast$terminal-io$\ast$} is a two-way stream from the
standard input and to the standard output.  The echoing to the
terminal is performed by the underlying operating system.  In
particular, when a disk file is assigned to the standard output,
nothing will be echoed at the terminal.

\medskip

\noindent Those functions that deviate from the definitions in the {\it 
Common Lisp Reference Manual} are listed below.

\vspace{.1in}

\noindent{\tt load {\it pathname} \&key :print :verbose
:if-does-not-exist}\hfill[{\it Function}]\\ 
\begin{description}
\item[] If pathname does not specify the filetype of the input file,
then load first tries to load a file with the filetype .o , i.e., the
fasl file (see Chapter 6).  If it fails, then {\tt load} tries to load a
file with the filetype {\tt .lsp}.  KCL assumes that {\tt .lsp} is the standard
filetype for source files.  If it fails again, then {\tt load} will load the
specified file with no filetype.

\item[] {\tt load} recognizes a file as a fasl file if and only if the
filetype of the file is .o .  Other files are assumed to be source
files.
\end{description}

\vspace{.1in}

\centerline{------------ Note to KCL/AOS users -------------}

\vspace{.1in}

In KCL/AOS, the filetype of fasl files is  {\tt .fasl}  (see Chapter 6).
Therefore, if the  pathname  argument does not explicitly specify the
filetype,  {\tt load}  first tries to load a file with the filetype
{\tt .fasl} .  In addition,
{\tt load}  recognizes a file as a fasl file if and
only if the filetype of the file is  {\tt .fasl} .

\vspace{.1in}

\centerline{---------------- End of Note -----------------}

\vspace{.1in}

\noindent{\tt open}\hfill[{\it Function }]\\
\begin{description}
\item[] The argument to the keyword variable  {\tt :element-type}
and  {\tt :element-type}  is always bound to the value
{\tt string-char} .
\end{description}

\noindent{\tt  close}\hfill[{\it Function}]\\
\begin{description}
\item[] The keyword variable  {\tt :abort} is always ignored.
\end{description}

\noindent{\tt listen}\hfill[{\it Function}]\\
\begin{description}
\item[] {\tt listen}  always returns  {\tt t} .
\end{description}

\noindent{\tt read-char-no-hang}\hfill[{\it Function}]\\
\begin{description}
\item[] {\tt read-char-no-hang}  is equivalent to  {\tt read-char}
\end{description}

\noindent{\tt clear-input}\hfill[{\it Function}]\\
\noindent{\tt clear-output}\hfill[{\it Function}]\\
\begin{description}
\item[] {\tt clear-input}  and  {\tt clear-output}  simply
return  {\tt nil}  without doing anything.
\end{description}

\noindent{\tt read-byte}\hfill[{\it Function}]\\
\noindent{\tt write-byte}\hfill[{\it Function}]\\
\begin{description}
\item[] These functions may operate on any stream.  They read or write a byte
(8 bits) at a time.
\end{description}

\noindent{\tt princ}\hfill[{\it Function}]\\
\noindent{\tt write-char}\hfill[{\it Function}]\\
\noindent{\tt write-byte}\hfill[{\it Function}]\\
\begin{description}
\item[] These functions do not always flush the stream.  The stream is flushed when
\begin{description}

\item[1.] a newline character is written, or

\item[2.] the input from the terminal is requested in the case that these
functions operate on {\tt $\ast$terminal-io$\ast$}
\end{description}
\end{description}
\newpage

\chapter{Memory Management}
 
\section{Implementation Types}

\noindent Each KCL object belongs to one of the 22 {\it implementation types}.  The
implementation types are shown in Table 4-1 with the corresponding
Common Lisp data types.  In the table, the compiled functions are
divided into two implementation types; {\tt cfun}  is the type of
compiled functions without environment, and  {\tt cclosure}  is the
type of compiled functions with environment (i.e., the type of
compiled closures).  {\tt spice } is the type of internal data used by KCL,
and does not correspond to any Common Lisp data type.

\newpage

\centerline{Table 4-1  Implementation Types}

\vspace{.1in}

\begin{tabular}{ll}

{\it Implementation Type}&{\it Common Lisp Data Type} \\[.1in]

{\tt cons}&{\tt cons}\\
{\tt fixnum}&{\tt fixnum}\\
{\tt bignum}&{\tt bignum}\\
{\tt ratio}&{\tt ratio}\\
{\tt short-float}&{\tt short-float}\\
{\tt long-float}&{\tt long-float (= double-float = single-float)}\\
{\tt complex}&{\tt complex}\\
{\tt character}&{\tt character}\\
{\tt symbol}&{\tt symbol}\\
{\tt package}&{\tt package}\\
{\tt hash-table}&{\tt hash-table}\\
{\tt array}&{\tt (and array (not vector))}\\
{\tt vector}&	{\tt (and vector (not string) (not bit-vector))}\\
{\tt string}&{\tt string}\\
{\tt bit-vector}&{\tt bit-vector}\\
{\tt structure}&{\tt structure}\\
{\tt stream}&{\tt stream}\\
{\tt random-state}&{\tt random-state}\\
{\tt readtable}&{\tt readtable}\\
{\tt cfun}&{\tt compiled-function  without environment} \\
{\tt cclosure}&{\tt compiled-function  with environment} \\
{\tt spice}&{\tt none} \\
\end{tabular}

\noindent Each object is represented by a cell allocated in the heap area of the
interpreter.  The size of the cell is determined by the implementation
type of the object.

\medskip

\noindent The implementation types are classified according to the size of the
cells for the objects of the type, as shown in Table 4-2.  The size of
the cells in the same type class is the same.

\medskip

\centerline{Table 4-2  Classification of Implementation Types}

\vspace{.1in}

\begin{tabular}{ll}

{\it Class}&{\it Implementation Types}\\[.1in]

1&{\tt 	 cons bignum ratio long-float complex }\\
2&{\tt 	 fixnum short-float character random-state readtable spice }\\
3&{\tt 	 symbol package }\\
4&{\tt 	 array hash-table vector bit-vector stream pathname cclosure }\\
5&{\tt 	 string cfun }\\
6&{\tt 	 structure }\\
\end{tabular}

\vspace{.1in}

\noindent For objects of the (implementation) types {\tt readtable, symbol,
package, array, hash-table, vector, bit-vector, stream, cclosure, string, cfun}, and {\tt structure}, the cell is simply a header
of the object.  The body of the object is allocated separately from
the cell and is managed in a different manner.  The memory space
occupied by the body of such an object is called a {\it block} .  A
block is either {\it contiguous} or {\it relocatable} depending on the
area in which it is allocated.  The difference between the two areas
will be explained below.  Table 4-3 lists these types, along with the
contents of the body and the kind of the block. 

\vspace{.1in}
		
\centerline{Table 4-3  Types with Bodies}

\vspace{.1in}

\begin{tabular}{lll}


{\it Type}&{\it Body}&{\it Block }\\[.1in]

{\tt readtable}&{\tt read table}&{\tt contiguous}\\
{\tt symbol}&{\tt symbol name}&{\tt relocatable}\\
{\tt package}&{\tt hash table}&{\tt contiguous}\\
{\tt array }&{\tt array body}&{\tt relocatable or contiguous}\\
{\tt hash-table }&{\tt hash table}&{\tt relocatable}\\
{\tt vector}&{\tt vector body}&{\tt relocatable or contiguous}\\
{\tt bit-vector}&{\tt bit-vector body}&{\tt relocatable or contiguous}\\
{\tt stream }&{\tt I/O buffer}&{\tt contiguous}\\
{\tt cclosure}&{\tt code}&{\tt 	contiguous}\\
{\tt string}&{\tt string body}&{\tt relocatable or contiguous}\\
{\tt cfun }&{\tt code}&{\tt contiguous}\\
{\tt structure}&{\tt structure body}&{\tt relocatable}\\
\end{tabular}

\vspace{.1in}

\noindent Usually, the body of an array, a vector, a bit-vector, or a string is
allocated as a relocatable block.  In KCL, the function {\tt
make-array} takes an extra keyword argument {\tt :static}.
If the {\tt :static} argument is supplied with a non- {\tt nil} value, then the
body of the array is allocated as a contiguous block.  

\section{Heap and Relocatable Areas}

\noindent The memory space of KCL is divided into two parts: the heap area and
the relocatable area.  Both areas occupy a contiguous space in the
memory.

\medskip

\noindent Cells of KCL objects are allocated in the heap.  KCL divides the heap
into pages (1 page = 2048 bytes), and each page consists of cells in
the same type class (see Table 4-2).  Cells in different type classes
are allocated in different pages.  Some blocks are also allocated in
the heap: They are called contiguous blocks.  The pages for contiguous
blocks contain only contiguous blocks.  Thus each page in the heap is
either a page for cells in a particular type class, or a page for
contiguous blocks.  Blocks not in the heap are called relocatable
blocks and are allocated in the relocatable area.

\medskip

\noindent The user may specify the maximum number of pages that can be allocated
for each type class by calling the KCL specific function {\tt
allocate}.  There is also a limit on the number of pages for
contiguous blocks; the limit can be altered by calling the KCL
specific function {\tt allocate-contiguous-pages}
size of the relocatable area is specified
by the KCL specific function  {\tt allocate-relocatable-pages}.  See
Section 4.4 for these functions.

\medskip

\noindent In some installations of KCL, the total amount of memory that KCL can
use is limited.  In such cases, the entire memory may become exhausted
before the maximum number of pages for each type class, for contiguous
blocks, or for the relocatable area have been allocated.

\medskip

\noindent The heap lies in a part of memory with lower address than the
relocatable area and there is a ``hole'' between the two areas (see
Figure 4-1).  On request for a new page of heap, the page with the
lowest address in the hole is used.  When the hole is exhausted, the
relocatable area is shifted toward the higher address space and a new
hole of an appropriate size is created between the two areas.

\vspace{.1in}

\centerline{Figure 4-1  Heap and Relocatable Area}

\vspace{.1in}

\centerline{\tt lower address \hspace*{3in}{}higher address}

\centerline{\fbox{\hspace*{.5in}{}\tt heap \hspace*{.5in}{}}\hspace*{.2in}{}{\tt hole} \hspace*{.2in}{}\fbox{\tt relocatable area}}

\section{The Garbage Collector}

\noindent The garbage collector of KCL has three levels according to what it
collects:
\begin{enumerate}
	\item cells
	\item cells and relocatable blocks
	\item cells, relocatable blocks and contiguous blocks.
\end{enumerate}

\noindent In levels 2 and 3,
the relocatable area is shifted to the higher address space to reserve
an appropriate number of pages in the hole.

\medskip

\noindent For each type class,
KCL keeps a free list of unused cells,
and when the free list is exhausted,
a new page is allocated, or the garbage collector is invoked,
depending on whether the maximum number of pages for that class
have been allocated or not.

\medskip

\noindent The garbage collector does not compactify the heap.  That is,
cells and contiguous blocks are never moved
to another place.  Moreover,
once a page is allocated for a particular type class
or for contiguous blocks,
that page will never be freed for other classes,
even if the entire page becomes garbage.

\medskip

\noindent On the other hand, the relocatable area is compactified
during level 2 and level 3 of garbage collection.  A relocatable
block is really relocatable.

\medskip

\noindent The garbage collector is automatically invoked in one of the following
situations.  The number in the parentheses indicates the level of garbage
collection that is performed.

\begin{description}

\item[*]  The free list of a certain type class is exhausted
after the maximum number of pages have been allocated for that
type class (1). 

\item[*] The hole is exhausted (2).

\item[*]  The relocatable area is exhausted
after the maximum number of pages have
been allocated for the relocatable area (2). 

\item[*]  The contiguous blocks are exhausted
after the maximum number of pages have been allocated for contiguous blocks (3). 
\end{description}

\noindent The garbage collector is also invoked by the following KCL
specific function.

\vspace{.2in}

\noindent{\tt gbc x}\hfill[{\it Function}]\\

\begin{description}
\item[]The garbage collector is invoked with the level specified
by {\tt x}.  If {\tt x} is  {\tt nil},
the garbage collector is invoked for
level 1 garbage collection.  If  {\tt x} is  {\tt t},
it is invoked for level 3 garbage collection.  Otherwise,
it is invoked for level 2 garbage collection.
\end{description}

\section{Allocation Functions}
 
\noindent The following functions are used to set or inspect
the (maximum) number of pages for each type class, for contiguous blocks,
or for relocatable blocks.

\vspace{.2in}

\noindent{\tt allocate} {\it type number}\hfill[{\it Function}]\\
\begin{description}
\item[] Sets the maximum number of pages for the type class of the
implementation type {\it type} to {\it number}.  If more than {\it
number} pages have already been allocated, an error is signalled.
\end{description}

\noindent{\tt allocated-pages} {\it type}\hfill[{\it Function}]\\
\begin{description}
\item[] Returns the number of pages currently allocated
for the type class of the implementation type  {\it type}.
\end{description}

\noindent{\tt maximum-allocatable-pages} {\it type}\hfill[{\it Function}]\\
\begin{description}
\item[] Returns the current maximum number of pages
for type class of the implementation type  {\it type}.
\end{description}

\noindent{\tt allocate-contiguous-pages} {\it number}\hfill[{\it 
Function}]\\
\begin{description}
\item[] Sets the maximum number of pages for contiguous blocks to {\it number}.
\end{description}

\noindent{\tt allocated-contiguous-pages}\hfill[{\it Function}]\\
\begin{description}
\item[] Returns the number of pages allocated for contiguous blocks.
\end{description}

\noindent{\tt maximum-contiguous-pages}\hfill[{\it Function}]\\
\begin{description}
\item[] Returns the current maximum number of pages for contiguous blocks.
\end{description}

\noindent{\tt allocate-relocatable-pages} {\it number}\hfill[{\it 
Function}]\\
\begin{description}
\item[] Sets the maximum number of pages for relocatable blocks
to  {\it number}.  The relocatable area is expanded to {\it number }
pages immediately.  Therefore,``the current maximum number'' and ``the
number of pages allocated'' have the same meanings for relocatable blocks.
\end{description}

\noindent{\tt allocated-relocatable-pages}\hfill[{\it Function}]\\
\begin{description}
\item[] Returns the number of pages allocated for relocatable blocks.
\end{description}

\noindent If the pages for a particular type class are exhausted
after the maximum number of pages for that class have been allocated,
and if there remain no free cells (actually, if there remain very few cells),
KCL behaves as directed by the value of the KCL specific
variable {\tt *ignore-maximum-pages*}.  If
the value is  {\tt nil},
then KCL signals a correctable error and enters the break loop.  The
user can reset the maximum number by calling  {\tt allocate} 
and then continue the execution of the program by typing  {\tt :r}.

\vspace{.1in}

     Example:

\begin{verbatim}

        >(make-list 100000)

        Correctable error: The storage for CONS is exhausted.
                           Currently, 531 pages are allocated.
                           Use ALLOCATE to expand the space.
        Signalled by MAKE-LIST.

        Broken at FUNCALL.
        >>(ALLOCATE 'CONS 1000)
        t

        >>:r

        (nil nil nil nil nil nil nil nil nil nil ............
\end{verbatim}
 
\noindent The user can also reset the maximum number of pages
for relocatable blocks and for contiguous blocks in a similar manner.
On the other hand, if
the value of  {\tt *ignore-maximum-pages*}
is non- {\tt nil},
then KCL automatically increments the maximum number of pages for the
class by 50 percent.  The initial value of  {\tt *ignore-maximum-pages*} is
{\tt t}.


\section{Storage Information}
 
\noindent{\tt room \& optional} {\it x}\hfill[{\it Function}]\\
\begin{description}
\item[] The function  {\tt room} prints the storage information.  The argument
{\it x}  is simply ignored and
the output of  {\tt room}  is always in the same
format.   {\tt room}  prints the following information:
\end{description}

\begin{verbatim}

     * for each type class
          * the number of pages so-far allocated for the type class 
          * the maximum number of pages for the type class
          * the percentage of used cells to cells so-far allocated 
          * the number of times the garbage collector has been 
            called to collect cells of the type class 
          * the implementation types that belong to the type class
     * the number of pages actually allocated for contiguous blocks
     * the maximum number of pages for contiguous blocks
     * the number of times the garbage collector has been called to 
       collect contiguous blocks 
     * the number of pages in the hole
     * the maximum number of pages for relocatable blocks
     * the number of times the garbage collector has been called to
       collect relocatable blocks 
     * the total number of pages allocated for cells
     * the total number of pages allocated
     * the number of available pages
     * the number of pages KCL can use.
\end{verbatim}

\noindent The number of times the garbage collector has been called
is not shown, if the number is zero.

\medskip

\noindent In the following example,
the maximum of  {\tt 531}  pages have already been allocated
for the type class to which  cons  belongs, but only 16.9 percent
of the cells are actually used.  The garbage collector was
once invoked to collect cells in this type class.

\begin{verbatim}


>(room)
 531/531    16.9%  1  cons bignum ratio long-float complex
    3/52    10.4%     fixnum short-float character random-state
                      readtable spice
   47/65    73.6%     symbol package
    3/71    32.4%     array hash-table vector bit-vector stream
                      pathname cclosure
   46/96    98.8%     string cfun
    1/32     2.3%     structure

  17/512              contiguous (3 blocks)
      14              hole
      50    47.4%  2  relocatable

   631 pages for cells
   712 total pages
 14840 pages available
 16384 maximum pages
 
 >
\end{verbatim}

\chapter{Debugging Facilities}

\section{The Tracer}
 
\noindent The Tracer causes selected {\tt functions} to be traced.  When such a traced  
{\tt function} is invoked, it prints

\begin{description}
\item[]	 {\it level} $>$ ({\it name   arg1   ...   argn}) 
\end{description}

\noindent On return from a traced {\tt function}, it prints
\begin{description}
\item[]	 $<$  {\it level}  ({\it name   value1   ...   valuen}) 
\end{description}

\noindent {\it name}  is the name of the traced {\tt function},
{\it args} are the arguments,
and  {\it values} are the return values.   {\it level}  is a number which is incremented each time
a traced {\tt function} is invoked and is decremented at the completion of the
invocation.  Trace print-outs are indented according to the  {\it level}.

\medskip

\noindent In the current version of KCL, macros and special forms cannot be traced.

\vspace{.1in}

\noindent{\tt trace} \{{\it function-name}\}*\hfill[{\it Macro}]\\
\begin{description}
\item[] Causes one or more functions to be traced.  {\it function-names} must be
symbols and they are not evaluated.  If a function is called from
a compiled function, the call may not produce trace
print-outs.  If this is the case, the simplest way to get
trace print-outs is to recompile the caller with
a  {\tt notinline} declaration for the called function (see
Chapter 7).   {\tt trace}  returns a name list of those functions that were
traced by the call to  trace .  If no  {\it function-name}  is
given,  {\tt trace}  simply returns
a name list of all the currently traced functions.
\end{description}

\noindent{\tt untrace \{{\it function-name}\}}*\hfill[{\it Macro}]\\
\begin{description}
\item[] Causes the specified functions to be not traced any more.           
{\it function-names} must be symbols and they are not evaluated.            
{\tt untrace}  returns a name list of those functions that were untraced by
the call to  {\tt untrace}.  If no {\it function-name}  is given, {\tt 
untrace} will untrace
all the currently traced functions and will return a list of their names.
\end{description}

\section{The Stepper}

\noindent{\tt step} {\it form}\hfill[{\it Macro}]\\
\begin{description}
\item[] Starts evaluating the  {it form}  in the single-step mode.  In this mode, before any form is evaluated,
the Stepper will print the form and prompt the user
for a Stepper command.  The Stepper binds
the two variables  *{\tt print-level}* and *{\tt print-length}* both to 
{\tt 2}, so that the current form may not occupy too much
space on the screen.  A Stepper command will be executed when the user types
the single character for the command followed by the required
arguments, if any, and presses the newline key.  If the user presses the    
newline key without having typed any character,
then the Stepper will assume that the Stepper command
{\tt n} was abbreviated.
\end{description}

\noindent The Stepper commands are:

\begin{description}
\item[{\tt n}]  Next.  Evaluates the current form in the single-step mode. 

\item[{\tt s}]  Skip.  Evaluates the current form in the ordinary mode.  The single-step mode will be resumed at completion
of the evaluation. 

\item[{\tt p}]  Print.  Pretty-prints the current form and then prompts again. 

\item[{\tt f}{\it fn}]	 Function.  Evaluates the current form in the ordinary mode until the specified
function  {\it fn} is invoked.  If the specified function is not invoked at all, then this command has the same effects as the  q  command below. 

\item[{\tt q}] Quit.  Evaluates the current form and any other forms in the ordinary mode. 

\item[{\tt e}{\it form}] Eval.  Evaluates the specified form in the ordinary mode and prints the resulting values.  Then prompts again with the same current form. 

\item[{\tt ?}] Help.  Lists the Stepper commands. 
\end{description}

\section{Errors}

\noindent*{\tt break-enable}*\hfill[{\it Variable}]\\
\begin{description}
\item[] This variable is used to determine whether to enter the
break loop (see Section 5.4) when an error occurs.  Even the function
{\tt break} checks this variable.  Initially, this variable is set to {\tt 
t}, and thus
an error will invoke the break loop.  If the value is {\tt nil},
functions that cause fatal errors, such as {\tt error},
will just print an error message and control will return to the top-level loop
(or to the current break loop, if already in the break loop).  Functions
that cause correctable errors, such as {\tt cerror},
will print an error message and a ``continue message'', and
control will return to the next form.  In KCL, backtrace is not part of an error message, but
a break loop command will print backtrace.  Therefore, if *{\tt 
break-enable}* is {\tt nil},
no backtrace appears on the screen.

\item[] When the break loop is entered,  *{\tt break-enable}* 
will be bound to {\tt nil}.
\end{description}

\section{The Break Loop}
 
\noindent The break loop is a read-eval-print loop similar to the top-level loop.  In addition to ordinary Lisp forms, the break loop accepts
various commands with which the user can inspect and modify the
state of the program execution.  Each break loop command is identified
with a keyword (i.e., a symbol in the {\tt keyword} package).  A break loop command is executed when the user inputs a list
whose first element is the keyword that identifies the command.  The rest of the list is the arguments to the command.  They are evaluated before being passed to the command.  If the command
needs no arguments, then the user may input only the keyword.  It is an error if the given keyword does not identify any command.  Any other input to the break loop is regarded as an
ordinary Lisp form; the form will be evaluated and the resulting values
will be printed on the terminal.

\medskip

\noindent There can be several instances of the break loop at the same time, and
each such instance is identified by a {\it level number}.  When the break loop is entered during execution in the
top-level loop, the break loop instance is given the level number  1 .      
The break loop instance that is entered from the level {\it n} 
break loop is given the level number  $n+1$ .  The prompt of the level {\it 
n} break loop is $n+1$ 
consecutive $>$'s, occasionally prefixed with the name of
the current package.

\medskip

\noindent The break loop keeps track of the invocation sequence of functions
(including special forms and macro expansion functions),
which led up to the break loop
from the previous break loop (or from the top-level loop,
if the current break loop is level  1 ).  The invocation sequence is        
maintained in a pushdown stack of  {\it events}.  An event consists of an   
{\it event function} and an {\it event environment}.  An event function is:
\begin{enumerate}
	\item an interpreted (i.e., not compiled) function (global function, local function, lambda-expression, or closure), 
	\item a special form within an interpreted function, 
	\item a macro expansion function called from an interpreted function, 
	\item a compiled function called from an interpreted function, or 
	\item a compiled function called from another compiled
function which was compiled while the {\tt safety} optimize
level is  3  or with a  {\tt notinline} 
declaration for the called function (see Chapter 7). 
\end{enumerate}

\noindent An event is pushed on the event stack when execution of its event
function begins, and is poped away at the completion of the
execution.  An event environment is the `environment' of the
event function at the time the next event is pushed.  Actually, an event
environment is a pointer to
the main stack of KCL.  For each interpreted event function (i.e., event
function in classes 1, 2, and 3),
the pointer points to the first entry of the three contiguous
main stack entries that hold the lexical environment of the event
function.  For each compiled event function (i.e., event function in classes
4 and 5),
the pointer is set to the first entry of the
main stack area that is used locally by the compiled code.  In most cases,
the first argument to the compiled function is saved in the
first entry, the second argument in the second entry, and so on.  The local
variables of the function are allocated in the entries following the
arguments.  However, this is not always the case.  Refer to Section 7.3 for
variable allocations in compiled functions.

\medskip

\noindent By break level commands,
the user can choose one of the events as  the {\it current event}.  If the
current event function is an interpreted event function, then
the break loop evaluates Lisp forms
in the lexical environment retrieved from the event
environment.  In particular, local variables may be referenced
by the variable names,
local functions and local macros may be invoked as usual, established
blocks may be exited from, and
tags may be used as the destination of {\tt go}.  If the current function is a compiled function,
Lisp forms are evaluated in the null environment.

\medskip

\noindent Within the break loop, each event is represented by the {\it event
symbol}.  The  {\tt :backtrace} 
command, for example, lists events in terms of their event symbols.  If the event function is a named function (global or local)
or a macro expansion function, then the function or macro name
is used as the event symbol.  If the event function is a special form,
then the name of the special form is used.  If the event function is
a lambda-expression (or a closure), then the symbol  lambda  (or
 lambda-closure ) is used.

\medskip

\noindent To suppress unnecessary information,
the user can hide (or make invisible) some of the events.  Invisible events do 
not appear in the backtrace, for example.  Initially, only those events are  
invisible whose event symbols belong to the
system internal package  system.  When the break loop is entered,
the last visible event becomes the current event.

\medskip

\noindent The break loop commands are described below.  Some of the commands
allow abbreviation in the keywords that identify them.  For example, the user  
may abbreviate  {\tt :current}  as {\tt :c}.  The break loop commands return no values at all.

\vspace{.1in}

\noindent{\tt :current}\hfill[{\it Break Loop Command}]\\
\noindent{\tt :c}\hfill[{\it Abbreviated Break Loop Command}]\\
\begin{description}
\item[] Prints the event symbol of the current event.
\end{description}

\noindent{\tt :previous \&optional} {\it n}\hfill[{\it Break Loop Command}]\\
\noindent{\tt :p \&optional} {\it n}\hfill[{\it Abbreviated Break Loop Command}]\\
\begin{description}
\item[] Makes the {\it n}-th previous visible event the
new current event.  Invisible events are not counted.  If there are less than 
{\it n}  previous
events, then the first visible event in the invocation sequence
becomes the new current event. {\it n}  must be a positive integer and the  
default is {\tt 1}.
\end{description}

\noindent{\tt :next \&optional} {\it n}\hfill[{\it Break Loop Command}]\\
\noindent{\tt :n \&optional} {\it n}\hfill[{\it Abbreviated Break Loop Command}]\\
\begin{description}
\item[] Makes the  {\it n}-th next visible event the
new current event.  If there are less than {\it n} next events,
then the last visible event in the invocation sequence
becomes the new current event.  {\it n}  must be a positive integer and the  
default is {\tt 1}.
\end{description}

\noindent{\tt :backtrace}\hfill[{\it Break Loop Command}]\\
\noindent{\tt :b}\hfill[{\it Abbreviated Break Loop Command}]\\
\begin{description}
\item[] Prints the event symbols of all visible events in order.  The symbol of
the current event is printed
in upper-case letters and the event symbols of other events are in lower-case.
\end{description}

\noindent{\tt :help}\hfill[{\it Break Loop Command}]\\
\noindent{\tt :h}\hfill[{\it Abbreviated Break Loop Command}]\\
\begin{description}
\item[] Lists the break loop commands.
\end{description}

\noindent{\tt :quit \&optional} {\it n}\hfill[{\it Break Loop Command}]\\
\noindent{\tt :q \&optional} {\it n}\hfill[{\it Abbreviated Break Loop Command}]
\\
\begin{description}
\item[] Returns control to the level {\it n}  break loop.  If {\it n}  is  0   
or if {\it n}  is omitted, then
control will return to the top-level loop.  {\it n}  must be a non-negative  
integer smaller than the current break level.
\end{description}

\noindent{\tt :resume}\hfill[{\it Break Loop Command}]\\
\noindent{\tt :r}\hfill[{\it Abbreviated Break Loop Command}]\\
\begin{description}
\item[] Returns control to the caller of the break loop.  If the break loop has been
entered from {\tt cerror},
{\tt cerror}  returns {\tt nil}  as its value and
control will resume at that point.  Otherwise, this command returns control to the previous break loop (or to
the top-level loop, if the current break level is 1).
\end{description}

\noindent{\tt :variables}\hfill[{\it Break Loop Command}]\\
\noindent{\tt :v}\hfill[{\it Abbreviated Break Loop Command}]\\
\begin{description}
\item[] Prints the names of the bound variables in the current
environment.  To see the value of a bound variable, just type the
variable name.
\end{description}

\noindent{\tt :functions}\hfill[{\it Break Loop Command}]\\
\begin{description}
\item[] Prints the names of the local functions and local macros
in the current environment.  To see the definition of a local function
or macro, use the  function  special form in the
usual way.  That is,  ({\tt function} {\it name})  will return the
definition of the local function or macro
whose name is {\it name}.  Local functions and local macros
may be invoked as usual.
\end{description}

\noindent{\tt :blocks}\hfill[{\it Break Loop Command}]\\
\begin{description}
\item[] Prints the names of the blocks established in the current
environment.  If a block {\it block} is established,
then the {\tt return-from} form
{\tt (return-from} {\it block value} ) 
works as usual.  That is, the block form that established {\it block} 
will return {\it value}  as its value and control will resume at
that point.
\end{description}

\noindent{\tt :tags}\hfill[{\it Break Loop Command}]\\
\begin{description}
\item[] Prints the tags established in the current environment.  If a tag 
{\it tag}  is established,
then the {\tt go} form ({\tt go} {\it tag})  works as usual.  That is, control  
will resume at the position of {\it tag}  in the
surrounding {\tt tagbody}.
\end{description}

\noindent{\tt :local \&optional} {\it n}\hfill[{\it Break Loop Command}]\\
\noindent{\tt :l \&optional} {\it n}\hfill[{\it Abbreviated Break Loop Command}]\\
\begin{description}
\item[] If {\it n}  is {\tt 0}  or if it is omitted,
then this command prints the value stored in the main stack entry
that is pointed to by the current event environment.  {\it n}  is an offset  
from that entry.  If {\it n}  is positive, then the value of
the {\it n}-th next (i.e., toward the top of the main stack) entry
is printed.  If {\it n}  is negative, then the value of
the | {\it n} |-th previous (i.e., toward the bottom of the main stack) entry
is printed.  {\it n} must be an integer.  It is an error if the specified entry does not lie between the bottom and
the top of the stack.
\end{description}

\noindent{\tt :hide} {\it symbol}\hfill[{\it Break Loop Command}]\\
\begin{description}
\item[] Hides all events whose event symbol is {\it symbol}.  In particular,  
by  ({\tt :hide 'lambda})  and
 ({\tt :hide 'lambda-closure}) , all events become invisible
whose event functions are lambda-expressions and closures, respectively.  If  
the event symbol of the current event happens to be {\it symbol},
then the last previous visible event will become the new current event.  
{\it symbol}  must be a symbol.

\item[] Events of {\tt eval} and {\tt evalhook} may never become
invisible and attempts to hide them are simply ignored.  It is always
the case that the first event function is either {\tt eval} 
or {\tt evalhook}.  Keeping both of them visible is the simplest way
to avoid the silly attempts of the user to hide all events.
\end{description}

\noindent{\tt :hide-package} {\it package}\hfill[{\it Break Loop 
Command}]\\
\begin{description}
\item[] Hides all events whose event symbol belongs to the package
{\it package}.  {\it package}  may be any object that represents a package, i.e., a package object, a symbol, or a string.  If the event symbol
of the current event happens to belong to the
package {\it package},
then the last previous visible event will
become the new current event.  Even if {\tt lisp}  package was
specified as {\it package},
events of {\tt eval} and {\tt evalhook} 
do not become invisible.  See the description of {\tt :hide}  above.
\end{description}

\noindent{\tt :unhide} {\it symbol}\hfill[{\it Break Loop Command}]\\
\begin{description}
\item[] {\tt :unhide}  is the inverse command of {\tt :hide}.  If, however, {\it 
symbol}  belongs to one of the {\tt :hide-packaged}
packages, events of {\it symbol}  become visible only after the
package is  {\tt :unhide-package 'd}.  {\it symbol}  must be a symbol.
\end{description}

\noindent{\tt :unhide-package} {\it package}\hfill[{\it Break Loop 
Command}]\\
\begin{description}
\item[] {\tt :unhide-package}  is the inverse
command of  {\tt :hide-package}.  However, an event whose event symbol belongs  
to {\it package}  becomes
visible only after the symbol is {\tt :unhide 'd}, if the symbol
was  {\tt :hide 'd} before.  {\it package}  may be any object that represents a package, i.e., a package object, a symbol, or a string.
\end{description}

\vspace{.1in}

Example:

\begin{verbatim}
>(defun fact (x) (if (= x 0) one (* x (fact (1- x)))))
fact                   ;;;  Wrong definition for  fact , the factorial. 
	
>(fact 6)              ;;;  Tries to calculate factorial 6. 

Error: The variable ONE is unbound.
Error signalled by IF.

Broken at IF:          ;;;  Enters the break-loop. 
>>:h                   ;;;  Help. 
:c(urrent)             Shows the current function.
:p(revious)            To the previous function.
:n(ext)                To the next function.
:b(acktrace)           Prints backtrace.
:h(elp)                Help.
:q(uit)                Returns to top-level.
:r(esume)              Returns to the caller of break-level.
:l(ocal)               Shows the n-th local value on the stack.
:v(ariables)           Shows local variables.
:functions             Shows local functions.
:blocks                Shows block names.
:tags                  Shows tags.
:(un)hide(-package)    (Un)hide a function (or a package).

>>:b                   ;;;  Backtrace. 
Backtrace: eval > fact > if > fact > if > fact > if > fact >
if > fact > if > fact > if > fact > IF

>>:p                   ;;;  Moves to the previous event. 
Broken at FACT.

>>:b                   ;;;  Now inside of  fact  but outside of  if . 
Backtrace: eval > fact > if > fact > if > fact > if > fact > 
if > fact > if > fact > if > FACT > if

>>:v                   ;;;  Shows local variables. 
Local variables: x.

>>x                    ;;;  The value of  x  is  0 . 
0

>>:blocks              ;;;  Shows blocks. 
Block names: fact.

>>(return-from fact 1) ;;;  Returns from the  fact  block with value  1 . 
720                    ;;;  Now the correct answer. 

>                      ;;;  Top-level.
\end{verbatim}

\section{Describe and Inspect}

\noindent{\tt describe} {\it object}\hfill[{\it Function}]\\
\begin{description}
\item[] Prints the information about {\it object}  to the stream that is
the value of  *{\tt standard-output}*.  The description of an object consists of several fields,
each of which is described in a recursive manner.  For example,
a symbol may have fields such as
home package, variable documentation, value, function documentation,
function binding, type documentation, {\tt deftype} definition,
properties.
\end{description}

\noindent{\tt inspect} {\it object}\hfill[{\it Function}]\\
\begin{description}
\item[] Prints the information about {\it object} 
in an interactive manner.  The output of  inspect  is similar to that
of {\tt describe},
but after printing the label and the value of a field
(the value itself is not {\tt describe 'd}),
it prompts the user to input a one-character command.  The input to {\tt inspect} is taken from the stream
that is the value of  *{\tt query-io}* .  Normally, the
inspection of {\it object}  terminates
after all of its fields have been inspected.  The following commands are
supported:
\end{description}

\begin{description}
\item[{\tt n}] Next.  Goes to the next level; the field is inspected 
recursively.

\item[{\tt s}] Skip.  Skips the inspection of the field. {\tt inspect}  proceeds to  
the next field. 

\item[{\tt p}] Print.  Pretty-prints the field and prompts again.

\item[{\tt u} {\it form}] Update.  The {\it form}  is evaluated and the field is  
replaced by the resulting value.  If the field cannot be updated, the message 
{\tt Not updated.}  will be printed. 

\item[{\tt a}] Abort.  Aborts the inspection of the current object.  The field and  
the rest of the fields are not inspected.

\item[{\tt e} {\it form}] Eval.  Evaluates the specified form in the null environment 
and prints the resulting values.  Then prompts again with the same 
field.

\item[{\tt q}] Quit.  Aborts the entire inspection.

\item[{\tt ?}] Help.  Lists the {\tt inspect}  commands.
\end{description}


\chapter{The Compiler}
 
The KCL compiler translates a Lisp program stored
in a source file
into a C-language program, invokes the C-language compiler to compile
the C-language program, and then generates an object file, called
{\it fasl file}  (or {\it o-file}  because of the actual filetype).  The compiled program in a fasl file is loaded by
the function {\tt load}.

\medskip

\noindent Ordinarily, the object program generated by the KCL compiler scarcely
does runtime
error-checking for runtime efficiency.  In addition, Lisp functions in the
same source file are linked together and some system functions are
open-coded in-line.  To control runtime error checking, supply
appropriate {\tt optimize}  declarations (see Section 7.1).

\medskip

\noindent The KCL compiler processes
the  {\tt eval-when}  special form
exactly as specified in the  {\it Common Lisp Reference
Manual}.  However, all top-level forms in the source file are normally
processed in {\it compile-time-too}  mode, not
in {\it not-compile-time}  mode (see Section 5.3.3 of the
{\it Common Lisp Reference Manual}).  That is, each top-level form
{\it top-level-form}  is processed as if it were surrounded by the
{\tt eval-when}  special form with the situations {\tt compile,
load}, and {\tt eval}.

\vspace{.1in}

    {\tt (eval-when (compile load eval)} {\it top-level-form})

\vspace{.1in}

\noindent There is no exception for this rule.  Thus, for instance, in the example of
{\tt set-macro-character}  form in Section 5.3.3 of the {\it Common Lisp
Reference Manual}, the surrounding {\tt eval-when}  form is
unnecessary in KCL.  If it is desired that each top-level form be
processed in {\it not-compile-time}  mode, change the
value of the KCL specific variable
 *{\tt eval-when-compile}* as described below.

\medskip

\noindent The KCL compiler is invoked by the functions {\tt
compile-file, compile}, and {\tt disassemble} described below.  In
addition, the KCL compiler may be invoked directly by the Shell
commands {\tt lc} or {\tt lc1}.  These commands require the file name
of the source file as their argument.  Both {\tt lc} and {\tt lc1}
simply add ``.{\tt lsp}'' to the file name argument to obtain the full
name of the source file.

\vspace{.1in}

	{\tt \% lc} {\it filename}

\vspace{.1in}

\noindent has the same effect as the compiler invocation ({\tt
compile-file} ``{\it filename}'') from within KCL, and

\vspace{.1in}

	{\tt \% lc1} {\it filename}

\vspace{.1in}

\noindent has the same effects as ({\tt compile-file} ``{\it
filename}'' {\tt :o-file t :c-file t :h-file t :data-file t}).

\vspace{.1in}

\noindent{\tt compile-file} {\it input-pathname}\hfill[{\it Function}]\\
\begin{description}
\item[] {\tt \&key :output-file :output-file :o-file :c-file :h-file        
:data-file}
\end{description}

\noindent{\tt compile-file}  compiles the Lisp program stored in the file
specified by {\it input-pathname}, and generates a fasl file.  Also  {\tt   
compile-file}  generates the following temporary files.

\vspace{.1in}
\begin{tabular}{l@{\hspace{1in}}l}
{\it Temporary File}&{\it Contents} \\ \hline

{\it c-file}&	C version of the Lisp program \\
{\it h-file} & The include file referenced in the c-file \\
{\it data-file} & The Lisp data to be used at load time\\
\end{tabular}

\vspace{.1in}

\noindent If files of these names already exist, the old files will be
deleted first.  Usually, these intermediate files are automatically
deleted after execution of {\tt compile-file}.

\medskip

\noindent The input-file is determined in the usual
manner (see Section 2.9), except
that, if the filetype is not specified, then the default filetype
{\tt .lsp}  will be used.  The keyword parameter {\tt :output-file} 
defines the default directory and the default name to be applied to
the output files (i.e., the fasl file and
the temporary files).  {\tt :output-file}  itself defaults
to {\it input-pathname}.  That is, if {\tt :output-file}  is not
supplied, then the
directory and the name of the input file will be used as the default
directory and the default name for the output files.  The filetypes
of the output files are fixed as follows.

\vspace{.1in}

\begin{tabular}{l@{\hspace{1in}}l}
{\it Output File}&{\it Filetype}\\ \hline 
 
	fasl file&	{\tt .o} \\ 
	c-file&		{\tt .c} \\
	h-file&		{\tt .h} \\ 
	data-file&	{\tt .data}
\end{tabular}

\vspace{.1in}

\noindent Each output file can be specified by the corresponding keyword
parameter.  If the value of the keyword parameter is {\tt nil}, then
the output file will
be deleted after execution of {\tt compile-file}.  If the value of
the keyword
parameter is {\tt t}, then the output file will be left in the
default directory under the default name.  Otherwise,
the output file will be left in the directory under the name specified by
the keyword parameter.  The default value
of {\tt :o-file} 
is  t , and the default values of
{\tt :c-file,  :h-file},
and {\tt :data-file}  are all {\tt nil}.

\vspace{.1in}

     Example:


\noindent (compile-file 'foo) 
\begin{description}
\item[]	The source file is  ``FOO.lsp'' and the fasl file is ``FOO.o'' both in the current directory.
\end{description}

\noindent (compile-file 'foo.lish) 
\begin{description}
\item[] The source file is ``FOO.LISH'' and the fasl file is ``FOO.o''.
\end{description}

\noindent (compile-file ``/usr/mas/foo'' :output-file ``/usr/tai/baa'') 
\begin{description}
\item[] The source file is ``foo.lsp'' in the directory ``/usr/mas'', and the fasl file is ``baa.o'' in the directory ``/usr/tai''.
\end{description}

\vspace{.1in}

\centerline{------------  Note to KCL/AOS users ------------}

\vspace{.1in}
The compiler of KCL/AOS generates the following output files.

\vspace{.1in}

\begin{tabular}{l@{\hspace{.5in}}ll}
{\it Output File}&	{\it Filetype}&		{\it Contents} \\ \hline 
 
	fasl file&	{\tt .fasl}& 	The fasl file\\
	c-file&		{\tt .c}&	C version of the Lisp program\\
	h-file&		{\tt .h}&	The include file referenced in the c-file\\
	ob-file&	{\tt .ob}& 	The object file generated by the C 
compiler\\
	data-file&	{\tt .data}& 	The Lisp data to be used at load time
\end{tabular}

\medskip

\noindent Note that the filetype of the fasl file is {\tt .fasl}  in KCL/AOS.  Also
note that the compiler of KCL/AOS generates
an additional file {\it ob-file}.  Accordingly, the function
{\tt compile-file}  has a slightly different definition:

\vspace{.1in}

\noindent {\tt compile-file} {\it input-pathname}\hfill[{\it Function}]\\
\begin{description}
\item[]	{\tt \&key :output-file :fasl-file   
:c-file :h-file :ob-file :data-file}
\end{description} 

\noindent The keyword parameter  {\tt :fasl-file}  corresponds to the keyword
parameter {\tt :o-file}  in KCL on Unix.  In particular, the default
value of {\tt :fasl-file}  is  t  and the default values of
{\tt :c-file,  :h-file,  :ob-file,} and
{\tt :data-file}  are all {\tt nil}.  In KCL/AOS,

\begin{verbatim}
          ) lc1  filename 
\end{verbatim}

\noindent has the same effects as ({\tt compile-file} ``{\it filename}'' {\tt
:fasl-file t :c-file t :h-file t :ob-file t :data-file t}).

\medskip

\noindent Because KCL/AOS follows the convention of the AOS/VS file system, the
last example above should be replaced as:

\medskip

{\tt ( compile-file ``:udd:mas:foo'' :output-file ``:udd:tai:baa'') }
\begin{description} \item[] The source file is ``FOO.LSP'' in the
directory ``:UDD:MAS'',	and the fasl file is ``BAA.FASL'' in the
directory ``:UDD:TAI''.
\end{description}

\centerline{------------  End of Note  ------------}

\vspace{.1in}

\noindent{\tt compile} {\it name} {\tt \&optional} {\it definition}\hfill[{\it  
Function}]\\
\begin{description}
\item[] If {\it definition}  is not supplied, {\it name}  should be the name
of a not-yet-compiled function.  In this case,  compile  compiles the
function, replaces the previous definition of {\it name}
with the compiled function,{\it and} returns
{\it name}.  If {\it definition}  is supplied, it should be a
lambda-expression to be compiled and {\it name}  should
be a symbol.  If {\it name}  is a non-{\tt nil}  symbol,
then  compile  installs the compiled function as the function
definition
of {\it name}  and returns {\it name}.  If {\it name} 
is {\tt nil}, then  compile  simply returns the
compiled function.

\item[] The KCL compiler is essentially a file compiler, and forms to be compiled
are supposed to be stored in a file.  Thus  compile  actually
creates a source file which
contains the form designated by the arguments.  Then  compile 
calls {\tt compile-file}  to get a fasl file, which
is then loaded into KCL.  The source file and the fasl file are given the
names {\tt gazonk.lsp}  and {\tt gazonk.fasl}, respectively.  These files are not
deleted automatically after the execution of {\tt compile:}.
\end{description}

\noindent{\tt disassemble \&optional} {\it thing} {\tt \&key :h-file :data-file} 
\hfill[{\it Function}]\\
\begin{description}
\item[] This function does not actually disassemble.  It always
calls the KCL compiler and
prints the contents of the c-file, i.e., the C-language code, generated by
the KCL compiler.  If {\it thing}  is not supplied, or if it is {\tt nil}, then
the previously compiled form by  disassemble  will be
compiled again.  If {\it thing}  is a symbol other than {\tt nil},
then it must be the
name of a not-yet-compiled
function, whose definition is to be compiled.  In this case, it is an error if
the name is associated with a special form or a macro.  If {\it thing} 
is a lambda-expression
 ({\tt lambda}  {\it lambda-list  .  body}), then
{\tt disassemble}  first creates a function definition  ({\tt defun gazonk} 
{\it lambda-list  .  body})  and this definition
is compiled.  (The function name {\tt gazonk}  has
no special meanings.  Indeed,
the displayed code is essentially independent
of the function name.)  Otherwise, {\it thing}  itself
will be compiled as a top-level form.  In any case, {\tt disassemble} 
does not install the compiled
function.  {\tt disassemble}  returns no value.

\item[] No intermediate h-file is created if the keyword parameter
{\tt :h-file}  is {\tt nil}  or if {\tt :h-file}  is not
supplied.  Otherwise, an intermediate h-file is created under the name
specified by {\tt :h-file}.  Similarly, the intermediate data-file
is specified by the keyword parameter {\tt :data-file}.
\end{description}

\noindent*{\tt eval-when-compile}*\hfill[{\it Variable}]\\
\begin{description}
\item[] The compiler processes each top-level form
in {\it not-compile-time}  mode if the value of this
variable is{\tt nil}, and in {\it compile-time-too}  mode,
otherwise.  See Section 5.3.3 of {\it Common Lisp Reference Manual} 
for these two modes.  The initial value of this variable is  t .
\end{description}


\chapter{Declarations}
 
KCL supports all kinds of declarations described in the
{\it Common Lisp Reference Manual}.  Any valid declaration
will affect the KCL environment in some way or another, although information
obtained by declarations, other than  special  declarations,
is mainly used by the KCL compiler.

\medskip

\noindent As described in the {\it Common Lisp Reference Manual},
Common Lisp declarations are divided into two classes: {\it proclamations} 
and others.  A proclamation is a global declaration given by the function
{\tt proclaim}, the top-level
{\it macro} {\tt defvar}, or the top-level
macro {\tt defparameter}.  Once given,
a proclamation remains effective
during the KCL session unless it is shadowed by a local declaration or is
canceled by another proclamation.  Any other declaration is a {\it local
declaration} and is given only by the special
form {\tt declare}.  A local declaration remains in
effect only within the body of the construct that surrounds the
declaration.  In the following nonsensical example borrowed from
Chapter 9 of the  {\it Common Lisp Reference Manual},

\begin{verbatim}
     (defun nonsense (k x z)
        (foo z x)
        (let ((j (foo k x))
              (x (* k k)))
             (declare (inline foo) (special x z))
          (foo x j z)))
\end{verbatim}

\noindent the {\tt inline}  and the  special  declarations both remain
in effect within the surrounding {\tt let}  form.  In this case,
we say that the {\tt let}  form is the {\it surrounding
construct}  of these declarations.

\noindent{\tt proclamation} {\it decl-spec}\hfill[{\it Function}]\\
\begin{description}
\item[] This function is introduced to KCL so that the user can see currently
effective proclamations.  The argument {\it decl-spec}  specifies the
proclamation to be checked.  It may be any declaration specification that
can be a valid argument to the function {\tt proclaim}.  The
function {\tt proclamation}  returns  t  if the specified
proclamation is still in effect.  Otherwise, it returns {\tt nil}.
For example,
\end{description}

\begin{verbatim}
>(proclaim '(special *x*))  ;;;  The variable  *x*  is 
nil                         ;;;  proclaimed to be globally special. 
 
>(proclamation '(special *x*))
t
 
>(defvar *y*)                ;;;  Another way to proclaim a variable 
nil                          ;;;  to be globally special. 
 
>(proclamation '(special *y*))
t
\end{verbatim}

\noindent{\tt the} {\it value-type form}\hfill[{\it Special Form}]\\
\begin{description}
\item[] The KCL interpreter does actually check whether the value of the
{\it form}  conforms to the data type specified by {\it value-type}  and
signals an error if the value does not.  The type checking is performed by
the function {\tt typep}.  For example,
\end{description}

\begin{verbatim}
        (the fixnum (foo))

      is equivalent to

      (let ((values (multiple-value-list (foo))))
         (cond ((endp values) (error ``Too few return values.''))
               ((not (endp (cdr values)))
                (error ``Too many return values.''))
               ((typep (car values) 'fixnum) (car values))
               (t (error ``~s is not of type fixnum.'' (car values)))))
\end{verbatim}

\begin{description} 
\item[] On the other hand, the KCL compiler uses the  the  special form to
obtain type information for compiled code optimization.  No code for runtime
type-checking is embedded in the compiled code.
\end{description}

\section{Declaration Specifiers}
 
\noindent KCL recognizes all declaration specifiers defined in the
{\it Common Lisp Reference Manual}.  The syntax of each such declaration
specifier is exactly the same as defined
in the {\it Common Lisp Reference Manual}.  In addition, KCL recognizes the
{\tt object} declaration specifier which is specific to KCL.

\vspace{.1in}

\noindent{\tt special} \{ {\it variable-name} \}*\hfill[{\it Declaration    
Specifier}]\\
\begin{description}
\item[] The interpreter and the compiler of KCL both treat  special 
declarations exactly as described in the {\it Common Lisp Reference Manual}.
\end{description}

\noindent{\tt type} {\it type \{  variable-name \}}*\hfill[{\it Declaration  
Specifier}]\\
\begin{description}
\item[] A {\tt type}  proclamation  ({\tt type} {\it type var1
var2}  ... )  specifies that the dynamic values of the
named variables are of the type {\it type}.  A local {\tt type} 
declaration specifies that the variables mentioned are bound by the
surrounding construct and have values of the type {\it type}  during
execution of the surrounding construct.  The compiler issues a warning if
one of the named variables is not bound by
the surrounding construct.  The information given by
{\tt type}  declarations is used by the compiler to optimize
the compiled code.  The behavior of the compiled code
is unpredictable if a wrong {\tt type}  declaration is supplied.  The
compiler detects certain wrong {\tt type}  declarations at compile
time.  For example,
\end{description}

\begin{verbatim}
             >(defun foo (x y)
                (declare (fixnum x) (character y))
                (setq x y)
               ...))
             foo

             >(compile 'foo)

             ; (defun foo ...) is being compiled.
             ;; Warning: Type mismatches between x and y.}
\end{verbatim}

\begin{description}
\item[] See Section 7.3 for further information on {\tt type} declarations.
\end{description}

\noindent{\it type} \{{\it  variable-name} \}*\hfill[{\it Declaration       
Specifier}]\\
\begin{description}
\item[] ({\it type var1 var2}  ...) is equivalent to
 ({\tt type} {\it type var1 var2}  ... ), provided
that {\it type}  is one of the symbols in Table 4-1
of the {\it Common Lisp Reference Manual}, other
than {\tt function}.  Declaration specifications that begin
with {\tt function}  are
regarded as {\tt function}  declarations (see below).
\end{description}

\noindent{\tt function} {\it function-name argument-types.  
return-types}\hfill[{\it Declaration Specifier}]\\
\begin{description}
\item[] A  {\tt function}  declaration is used to obtain type
information for function call forms.
That is, a  {\tt function}  declaration specifies
the argument and the return
types of each form that calls the named function.
\end{description}

\begin{verbatim}
         (defun foo ()
           (declare (function bar (character) fixnum))
           (+ (bar (atcholi1)) (bar (atcholi2))))
\end{verbatim}

\begin{description} 
\item[] In this example, the {\tt function}  declaration
specifies that
the two functions {\tt atcholi1}  and {\tt atcholi2}  both return
character objects when called
within the body of {\tt foo}, and that the function  bar 
returns fixnum objects when called within the body of {\tt foo}.
The type information given by
 function  declarations is used by the compiler to optimize
the compiled code.  The behavior of the compiled code
is unpredictable if a wrong {\tt function}  declaration is supplied.
The compiler detects certain wrong {\tt function}  declarations at compile
time.  For example,
\end{description}

\begin{verbatim} 
      >(defun foo (x)
         (declare (fixnum x)
                  (function bar (character) fixnum))
         (bar x))
      foo

      >(compile 'foo)

      ; (defun foo ...) is being compiled.
      ;; Warning: The type of the form x is not character.
\end{verbatim}

\begin{description}
\item[] However, the compiler does not check the number of arguments, and thus,
the following function definition will be compiled successfully without
any warnings.
\end{description}

\begin{verbatim} 
      (defun foo ()
        (declare (function bar (character character) fixnum))
        (+ (bar (atcholi1)) (bar (atcholi2) (atcholi3) (atcholi4))))
\end{verbatim}

\begin{description} 
\item[] For this definition, the compiler assumes that the three functions
{\tt atcholi1,  atcholi2,} and {\tt atcholi3}  will
return fixnum objects.  The return type of {\tt atcholi4}  is
unknown at compile time.

\item[] The complete syntax of a  function  declaration is:
\end{description}

\begin{verbatim} 
  (function  function-name 
    ( { type }* [ { &optional | &rest | &key } { thing }* ] )
    { (values { type }* ) | { type }* } 
  )
\end{verbatim}

\begin{description}
\item[] Although {\tt \&optional,  \&rest,} and {\tt \&key}  markers
may appear in the list of argument types, only those {\it types} are
recognized that appear before any such markers and the rest of the
list is simply ignored.  Note that
functions with {\tt \&optional,  \&rest,} or {\tt \&key} 
parameters may still be declared by {\tt function}  declarations because
of the use of {\tt function}  declarations mentioned above.

\item[] The {\tt values}  construct in the specification of return types is almost
useless:   ({\tt function} {\it function-name argument-types} 
({\tt values} {\it type1 type2}  ... ))  is equivalent
to  ({\tt function} {\it function-name
argment-types  type1 type2}  ... ) .  We, the implementors of
KCL wonder why the  value  construct was introduced in Common Lisp.

\item[] See Section 7.3 for further information on {\tt function}  declarations.
\end{description}

\noindent{\tt ftype} {\it function-type \{function-name}\}*\hfill[{\it      
Declaration Specifier}]\\
\begin{description}
\item[] {\it function-type}  must be a list whose first element
is the symbol {\tt function}.
{\tt (ftype (function}. {\it rest)  function-name-1  ...  
function-name-n})  is
equivalent to {\it n}  consecutive  {\tt function}  declarations
 ({\tt function}  {\it function-name-1  .  rest})  ...
 ({\tt function} {\it function-name-n  .  rest}).
\end{description}

\noindent{\tt notinline} \{{\it  function-name}\}*\hfill[{\it Declaration   
Specifier}]\\
\begin{description}
\item[] ({\tt notinline} {\it function1 function2}  ... )  specifies
that the compiler should not compile the named functions in-line.  Calls
to the named functions can be traced and an event (see Section 5.4) is pushed
on the event stack when any one of the named functions is invoked.
\end{description}

\noindent{\tt inline} \{{\it  function-name}\}*\hfill[{\it Declaration      
Specifier}]\\
\begin{description}
\item[] An  {\tt inline}  proclamation cancels currently
effective {\tt notinline}  proclamations, and a local
{\tt inline}  declaration locally shadows currently effective
{\tt notinline}  declarations.
\end{description}

\begin{verbatim}
    >(defun foo (x)
       (cons (car x)
             (locally (declare (inline car)) (car x))))
    foo

    >(defun bar (x)
       (cons (car x)
             (locally (declare (inline car)) (car x))))
    foo
 
    >(proclaim '(notinline car))
    nil
 
    >(compile 'foo)
    ...
 
    >(proclaim '(inline car))
    nil
 
    >(compile 'bar)
    ...
\end{verbatim}

\begin{description}
\item[] Usually, primitive functions such as  car  are
compiled in-line.  Therefore, in this example, only the first
call to {\tt car}  within {\tt foo}  is compiled not in-line.

\item[] In general, the KCL compiler compiles functions in-line
whenever possible.  Thus an {\tt inline} 
declaration  ({\tt inline}  {\it function1
function2}  ... )  is worthless if none of the named functions
have previously been declared to be {\tt notinline} .
\end{description}

\noindent{\tt ignore} \{{\it variable-name}\}*\hfill[{\it Declaration       
Specifier}]\\
\begin{description}
\item[] Usually, the compiler issues a warning if a lexical variable is
never referred to.   ({\tt ignore} {\it var1  ...  varn} ) 
causes the compiler not to issue a warning even if the named variables are
never referred to.  The compiler issues a warning if
one of the named variables is not bound by
the surrounding construct, or if a named variable is
actually referred to.  {\tt ignore}  proclamations are simply ignored.
\end{description}

\noindent{\tt optimize} \{ \{  ({\it quality value} )  $|$ {\it 
quality}\}\}*\hfill[{\it Declaration Specifier}]\\
\begin{description}
\item[] KCL supports the four {\tt optimize}  qualities listed in the
{\it Common Lisp Reference Manual}.  {\tt speed} 
and {\tt compilation-speed}  are used to set up the optimization switch
of the C language compiler which is invoked to compile the C-language
code generated by the KCL compiler (see Chapter 6).   ({\tt optimize 
(speed} {\it n} ))  and
 ({\tt optimize (compilation-speed} {it m} ))  are equivalent,
where {\it n}  and {\it m}  are integers between  0 
and  3 , and {\it m}  is equal to  3-{\it n}.  When
a KCL session is started, the {\tt speed}  quality is set
to 3.  That is, by default, the compiler generates the fastest
code in the longest compilation time.  The  {\tt space} quality
specifies whether the code size is important or not:  The compiled code
is a little bit larger and faster when compiled with the  space 
quality  0, than when compiled with the  space  quality
 1,  2, or 3.  When a KCL session is started,
the {\tt space}  quality is set to  0.  The {\tt safety} 
quality determines how much runtime error checking code should be embedded in
the compiled code.  If the {\tt safety}  quality is  0, the
compiled code
scarcely does runtime error checking.  If
the {\tt safety}  quality is  1 , then the compiled code for a
function will check the number of arguments to the function
at runtime.  If the  {\tt safety}  quality is  2  or  3, then the
compiled code does full runtime error checking.  In addition, the
highest quality value  3  causes the compiler to treat all
functions as if they were declared to be {\tt notinline}.  When a KCL
session is started, the {\tt safety}  quality is set to 0.
\end{description}

\noindent{\tt declaration} \{{\it name}\}*\hfill[{\it Declaration 
Specifier}]\\
\begin{description}
\item[] A {\tt declaration}  declaration is used exactly as specified in the
{\it Common Lisp Reference Manual}.
\end{description}

\noindent{\tt object} \{{\it variable-name}\}*\hfill[{\it Declaration       
Specifier}]\\
\begin{description}
\item[] This is the only declaration specifier that is specific to KCL.     
({\tt object} {\it var1  ...  varn} )  affects only variable bindings and
specifies that the named variables can be allocated in the
C stack (see Section 7.3).  The compiler issues a warning if
one of the named variables is not bound by the surrounding
construct. {\tt object}  proclamations are simply ignored.
\end{description}

\section{Significant Type Specifiers}

\noindent Whenever a declaration is encountered, each type specifier
(if any) in the declaration is converted to one of the following type
specifiers, which are collectively called the {\it significant type
specifiers}.

\begin{verbatim}
          |------------   fixnum 
          |------------   character 
          |------------   short-float 
          |------------   long-float 
      t --|----   (array t)  --------------  (vector t) 
          |----   (array fixnum)  ---------  (vector fixnum) 
          |----   (array string-char)   ---  string 
          |----   (array short-float)   ---  (vector short-float) 
          |----   (array long-float)    ---  (vector long-float) 
          |----   (array bit)   -----------   bit-vector 
\end{verbatim}

\noindent Here, the lines indicate subtype relations; the right type
is a subtype of the left type.  For instance,  ({\tt vector t}) 
is a subtype of  ({\tt array t})  and {\tt t}, and
 ({\tt array t})  itself is a subtype of {\tt t}.  However,
 ({\tt array t}) and  ({\tt array string-char})  are disjoint types.

\medskip

\noindent The function  {\tt subtypep} is used for the conversion to
significant type specifiers:  If the
first value of  ({\tt subtypep} {\it raw-type type})  is
{\tt t}  for one of the significant type specifiers  {\it type},
then the type specifier {\it raw-type}  in
the declaration is converted to {\it type}.  If there are more than one
such significant type specifiers, then the type specifier that is a
subtype of other specifiers is selected.  For
example, type specifiers {\tt fixnum,  (mod 3)}, and
 ({\tt member 0 1})  are all converted to {\tt fixnum}, though they are
also subtypes of {\tt t}.

\medskip

\noindent Because of this type specifier conversion, KCL may sometimes regard
two seemingly distinct declarations as the same.  For example,
the following {\tt type} declarations are
completely equivalent, internally in KCL.

\begin{verbatim}
    (declare (type fixnum x))

    (declare (type (mod 3) x))

    (declare (type (member 0 1) x))
\end{verbatim}
 
\noindent Type specifiers in declaration specifications passed to the
KCL specific function
{\tt proclamation}  are also converted to significant type specifiers.  Thus, for example,

\begin{verbatim}
    >(proclaim '(function foo (fixnum) fixnum))
    nil
 
    >(proclamation '(function foo ((mod 3)) (member 0 1)))
    t
 
    >(proclamation '(function foo (number) character))
    nil
\end{verbatim}

\noindent The first call to {\tt proclamation}  returns {\tt t}  because
both  ({\tt mod 3})  and  ({\tt member 0 1})  are converted to
{\tt fixnum}  before the function type of {\tt foo}  is checked.

\section{Treatment of Type Declarations}
 
\noindent KCL has several runtime stacks.  One of them is called the {\it value
stack}  which is the ``main stack'' of KCL:  Arguments to functions and
resulting values of functions are usually passed via the value stack,
lexical variables in compiled code are usually allocated on the value stack,
and temporary values during evaluation of nested expressions are usually
saved on the value stack.  However, if appropriate declarations are
supplied to the compiler, the compiled code will use another
stack called the {\it C stack}, which can be accessed more efficiently
than the value stack.  In addition, arguments and resulting values passed
via the C stack, values of lexical variables allocated on the C stack,
and temporary values saved on the C stack may sometimes be represented
as {\it raw data}  instead of pointers to heap-allocated
cells.  In KCL, even a fixnum object is usually represented as a pointer
to a fixnum cell in which the raw datum (i.e., the 32-bit signed integer)
for the fixnum is stored.  Accessing such raw data on the C stack results
in faster compiled code,
partly because no pointer deferencing operation is necessary, and
partly because no cell is newly allocated on the heap when a new object is
created.  In contrast, any object on the value stack is represented
as a pointer to a heap-allocated cell.

\medskip

\noindent One of the deficiencies of the use of the C stack is that
raw data on the C stack may sometimes need to be reallocated on the
heap.  Suppose, in the following example, that
the lexical variable {\tt x}  is
allocated on the C stack and has always a fixnum raw datum as its
value.  (The situations in which this occurs will be explained later.)

\begin{verbatim}
    (defun foo ()
      (let ((x 0))
        ....
        (bar x)
        ....
        ))
\end{verbatim}

\noindent Also suppose that the function  bar  expects its argument to be
passed via the value stack rather than via the C stack.  (This situation
typically occurs when {\tt foo}  and {\tt bar}  are defined in separate
source files.  See below.)  On call to {\tt bar}, the compiled code
of {\tt foo}  will allocate a fixnum cell on the heap and push the pointer
to this cell on the value stack as the argument to {\tt bar}.

\medskip

\noindent Another deficiency is that it is sometimes dangerous to allocate
a cell pointer onto the C stack.  (This occurs when
{\tt object} declarations
are supplied.  See below.)  The garbage
collector of KCL never takes care of cell pointers on the C stack and thus
a heap-allocated cell pointed
to only from the C stack may be recycled for
further use, while the data in the cell is still in use.  This is why
KCL usually uses the less efficient value
stack.  In contrast, objects on the value stack are automatically
protected against
garbage collection.  Note that raw data on the C stack need not be protected
against garbage collection because they remain alive until the C stack is
popped.

\section{Variable Allocations}
 
\noindent If a lexical variable is declared to be of {\tt fixnum ,
 character ,  short-float ,  long-float}, or
their subtypes, then it is allocated on the C stack rather than on the
value stack.  In addition, the variable always has a raw datum as its
value: 32 bit signed integer for fixnums, 8 bit character code
with 24 bit padding for
characters (remember that the font and bit fields of KCL characters are
always  0 ), 32 bit floating point representation for short-floats,
and 64 bit floating point representation for
long-floats.  Similarly, if a lexical variable is named in an {\tt object} declaration (see Section 7.1),
then it is allocated on the C stack but, in this case, the variable
always has a cell pointer as its value.  The user is strongly recommended to
make sure that objects stored in such an {\tt object}  variable may
never be garbage collected unexpectedly.  For example,

\begin{verbatim}
    (do ((x (foo) (cdr x)))
        ((endp x))
        (let ((y (car x)))
             (declare (object y))
          (bar y)))
\end{verbatim}

\noindent this {\tt object} declaration is completely safe because the value of
the variable {\tt y}  is always a substructure of the value
of {\tt x}, which in turn is protected against garbage
collection.  Incidentally, loop variables of {\tt dolist}  may always be
declared as  object  variables, since the {\tt dolist}  form has
essentially the same control structure as the {\tt do}  form above.  On
the other hand, the result of evaluation of the following form is
unpredictable, because the cons cell pointed to from the {\tt object} 
variable {\tt z}  may be garbage collected before {\tt bar}  is called.

\begin{verbatim}
    (let ((z (cons x y)))
         (declare (object z))
      (foo (cons x y))
      (bar z))
\end{verbatim}

\noindent Lexical variables that are not declared to be of  {\tt fixnum,
 character,  short-float,  long-float}, or
their subtypes, and that are not named in {\tt object}  declarations are
usually allocated on the value stack, but may possibly
be allocated on the C stack automatically by the compiler.

\section{Built-in Functions that Operate on Raw Data Directly}
 
\noindent Some built-in Common Lisp functions can directly operate on raw data, if
appropriate declarations are supplied.  The addition function  $+$  is
among such functions.

\begin{verbatim}
    (let ((x 1))
         (declare (fixnum x))
      ....
      (setq x (+ x 2))
      ....
      )
\end{verbatim}

\noindent In the compiled code for this {\tt let}  form, the raw fixnum datum (i.e.,
the 32 bit signed integer) stored
in {\tt x}  is simply incremented by 2 and the resulting 32 bit signed
integer is stored back into {\tt x}.  The compiler is sure that
the addition for 32 bit signed integers
will be performed on the call to  $+$, because
the arguments are both fixnums
and the return value must be also a fixnum since the value
is to be assigned to the {\tt fixnum}  variable.  The knowledge
of both the argument types and the return type is necessary
for this decision:  Addition of two fixnums
may possibly produce a bignum and addition of two bignums may happen to
produce a fixnum value.  If either the argument type or the return type
were not known to the
compiler, the general addition function would be called to
handle the general case.  In the following form, for example, 
the compiler cannot be sure that the return value of the multiplication is
a fixnum or that the arguments of the addition are fixnums.

\begin{verbatim}
    (setq x (+ (* x 3) 2))
\end{verbatim}

\noindent In order to obtain the optimal code,
a {\tt the} special form should surround the multiplication.

\begin{verbatim}
    (setq x (+ (the fixnum (* x 3)) 2))
\end{verbatim}

\noindent Built-in Common Lisp functions that can directly operate on raw data are:

\begin{enumerate}
\item arithmetic functions such as {\tt +,  -,
1+,  1-,  *, floor,  mod}, /, and {\tt expt}.

\item predicates such as {\tt eq, eql, equal, zerop, plusp, minusp, =, /=,  
$<$, $<$=, $>$, $>$=, char=, char/=, char$<$, char$<$=, char$>$}, and {\tt char$>$=}.

\item sequence processing functions that receive or return one or more
fixnum values, such as {\tt nth, nthcdr, length}, and {\tt elt}.

\item array access functions such as {\tt svref, char, schar}, and {\tt 
aref}  (see below).

\item system-internal functions for array update (see below).
 
\item type-specific functions such as {\tt char-code, code-char}, and {\tt  
float}.
\end{enumerate}

\noindent As mentioned in Section 2.5.1, array elements are represented in one of  six ways depending
on the type of the array.  By supplying appropriate array type declarations, array access and update
operations can handle raw data stored in arrays.  For example,

\begin{verbatim}
    (let ((a (make-array n :element-type 'fixnum))
          (sum 0))
         (declare (type (array fixnum) a)
                  (fixnum sum))
      (dotimes (i n)             ;;; Array initialization.
               (declare (fixnum i))
         (setf (aref a i) i))
      ....
      (dotimes (i n)             ;;; Summing up the elements.
               (declare (fixnum i))
         (setq sum (+ (aref a i) sum)))
      ....
      )
\end{verbatim}

\noindent The {\tt setf}  form replaces the {\tt i-th} element of the
array  a  by the raw fixnum value of {\tt i}.  The
{\tt aref} form retrieves the raw fixnum datum stored
in {\tt a}.  This raw datum is then added to the raw fixnum
value of the fixnum variable {\tt sum}, producing the raw fixnum datum to be stored
in {\tt sum}.  Similar raw data handling is possible for
arrays of types
{\tt (array fixnum) ,  (vector fixnum) ,
 (array string-char) ,  string ,
 (array short-float) ,  (vector short-float) ,
 (array long-float)}, and {\tt (vector long-float)} .

\section{Arguments/Values Passing}
 
\noindent Function proclamations  ({\tt function} {\it function-name  ( arg-type1     
arg-type2  ...)  return-type}) 
or its equivalents give the compiler the
chance to generate compiled code so that arguments to the named functions
and resulting values of the named functions will be passed via the C stack, thus
increasing the efficiency of calls to these functions.  Such arguments/values
passing via the C stack is possible only if the called function is
also defined in the same source file.  This is because the code for the
called function must have two entries:  One entry for arguments/values passing
via the C stack and another for ordinary arguments/values passing via the
value stack.  (An ordinary function has only the latter entry.)  When the
latter entry is used, the arguments on the value stack are pushed onto the
C stack and then the former entry is used to execute the body of the
function.  On return from the function, the resulting value on the C stack
is pushed onto the value stack.  This means that ordinary calls to these
functions are slower than calls to ordinary functions.

\medskip

\noindent One of the merits of arguments/values passing via the C stack is that
raw data stored in C-stack-allocated variables can be passed directly to
other functions and raw data returned from functions
may directly be saved in C-stack-allocated variables or may directly be
used as arguments to another function.  A good example of this follows.

\begin{verbatim}
    (eval-when (compile)
      (proclaim '(function tak (fixnum fixnum fixnum) fixnum)))

    (defun tak (x y z)
      (declare (fixnum x y z))
      (if (not (< y x))
          z
          (tak (tak (1- x) y z)
               (tak (1- y) z x)
               (tak (1- z) x y))))

    ;;; Call (tak 18 12 6).
\end{verbatim}

\noindent When {\tt tak}  is called with the arguments {\tt 18, 12},
and {\tt 6}, the raw fixnum data of the arguments are set to the
parameters {\tt x, y, z}  which are allocated on the
C stack.  After that, only
raw data on the C stack are used to perform the execution:  No cell pointers
are newly allocated nor even referenced.  Arguments and resulting values for
recursive calls to {\tt tak} are passed via the C stack, and the
built-in functions  $<$  and {\tt 1-}  directly operate on the
raw data.  Only at the return from the top-level call of {\tt tak},
the resulting raw data value (which happens to be {\tt 7} ) is reallocated
on the heap.  Note that both the {\tt function}
proclamation and the
local {\tt fixnum} declaration are necessary to obtain the optimal
code.  The {\tt function}  proclamation is necessary for arguments/values
passing via the C stack and the {\tt fixnum}  declaration is necessary to
allocate the parameters onto the C stack.


\chapter{Operating System Interface}

KCL provides the following facilities that are not
defined in the {\it Common Lisp Reference Manual}.

\vspace{.1in}

\noindent{\tt save} {\it filename}\hfill[{\it Function}]\\
\begin{description}
\item[] {\tt save}  saves the current memory
image into a program file {\it filename}.  After saving the memory image,
the KCL process terminates immediately.  To execute the saved program file,
specify the full pathname of the file, as indicated in the example below.
\end{description}

\vspace{.1in}

\centerline{------------  Note to KCL/AOS users  ------------}

\vspace{.1in}

In KCL/AOS, if the filename does not contain the filetype {\tt .pr},
then the program file
is given the name {\it filename} {\tt.pr}.  Also {\tt save}  saves a
symbol table file with
the filetype {\tt .st}.  When the program file is executed,
execution begins
at the top-level of KCL.  Even if there were streams that were open at
the call of {\tt save},
these streams are not effective when the program file
is executed.  The function  {\tt save}  of KCL/AOS does not terminate
the KCL process.

\vspace{.1in}

\centerline{------------  End of Note  -----------}

\vspace{.1in}

     Example:
\begin{verbatim}
        >(defun plus (x y) (+ x y))
        plus

        >(save ``savefile'')
        %

        % pwd
        /usr/hagiya
        % /usr/hagiya/savefile

        >(plus 2 3)
        5

        >(bye)
        Bye.
        %
\end{verbatim}

\centerline{------------  Note to KCL/AOS users  ------------}

\vspace{.1in}

Here is the example of save in KCL/AOS.

\begin{verbatim}
        >(defun plus (x y) (+ x y))
        plus

        >(save ``savefile'')
        t

        >(bye)
        Bye.
        )

        ) X SAVEFILE

        >(plus 2 3)
        5

        >(bye)
        Bye.
        ) 
\end{verbatim}

\centerline{------------  End of Note  ------------}

\vspace{.1in}

\noindent{\tt system} {\it string}\hfill[{\it Function}]\\
\begin{description}
\item[] Executes a Shell command as if {\it string} is an input to the Shell.  
On return from the Shell command, {\tt system}  returns the exit code
of the command as an integer.
\end{description}

\vspace{.1in}

\centerline{------------  Note to KCL/AOS users  ------------}

\vspace{.1in}

\noindent This function is not supported in KCL/AOS.  Use instead those functions
specific to KCL/AOS described below.

\vspace{.1in}

\centerline{------------  End of Note  ------------}

\vspace{.1in}

\noindent{\tt bye \&optional} {\it exit-code}\hfill[{\it Function}]\\
\noindent{\tt by \&optional} {\it exit-code}\hfill[{\it Function}]\\
\begin{description}
\item[] Terminates KCL and returns the {\it exit-code}  to the parent process.  
{\it exit-code}  must be an integer and its default value is  0 .
\end{description}

\vspace{.1in}
\centerline{------------  Note to KCL/AOS users  ------------}
\vspace{.1in}

\noindent The functions {\tt bye} and {\tt by}  of KCL/AOS accept a string
instead of an {\it exit-code}.  If {\it string}  is supplied, these functions  
return the {\it string}  to the father as the termination message.

\vspace{.1in}
\centerline{------------  End of Note  ------------}
\vspace{.1in}

The following functions {\tt process,
 termination-message}, and
{\tt last-termination-message} 
are specific to KCL/AOS and are not supported in KCL on Unix.

\vspace{.1in}

\noindent{\tt process} {\it progname} {\tt \&optional} {\it 
ipc-message}\hfill[{\it Function}]\\
\begin{verbatim}
        \&key    :block :console :debug :dir
                 :input :output :username
                 :list :data :ioc
\end{verbatim}
\begin{description}
\item[] This function is defined only in KCL/AOS.  {\tt process} creates a  
process in the way specified by its arguments.\\
\end{description}

\begin{description}
\item[progname]	 The name of the process to create.  Must be a 
string.\\
\item[ipc-message] The IPC message passed to the process.  Must be a string.   
Arguments in the message must be separated with commas ' , '.\\
 
\item[:block] If {\tt non- nil}, KCL blocks its execution while the son     
executes.  Defaults to {\tt t}.\\

\item[:console] The name of the file to be associated to @{\tt console}.    
Must be a string.  No file is associated if {\tt :console} is not specified  
and if the {\tt :ioc} argument (see below) is specified with a non-{\tt 
nil} value.  {\tt :console}  supercedes {\tt :ioc}.\\

\item[:debug] If non-{\tt nil}, the son runs in the debug mode.\\

\item[:input] The name of the file to be associated to @{\tt input}.  Must be  
a string.  No file is associated if {\tt :input}  is not specified and if the 
{\tt :ioc} argument (see below) is specified with a non-{\tt nil} value.  
{\tt :input} superceds {\tt :ioc}.\\

\item[:output] The name of the file to be associated to @{\tt output}.  Must  
be a string.  No file is associated if {\tt :output} is not specified and if  
the {\tt :ioc} argument (see below) is specified with a non-{\tt nil}  value.  
{\tt :output}  supercedes {\tt :ioc}.\\ 

\item[:username] The user-name of sub-process.  Must be a string.  If not   
specified, the current user-name is used.\\ 

\item[:list] If a string, the name of the file to be associated to @{\tt 
list}.  If {\tt t}, the file currently associated to  @{\tt list} is used.   
If {\tt nil}, or if not specified, no list file is passed to the 
son.\\

\item[:data] If a string, the name of the file to be associated to @{\tt 
data}.  If {\tt t}, the file currently associated to @{\tt data} is used. If   
{\tt nil}, or if not specified, no data file is passed to the son.\\

\item[:ioc] If non-{\tt nil, current} @{\tt input}, @{\tt output}, and 
@{\tt console} files are passed to the son.  If not specified, these
files are not passed unless specified by the {\tt :console,  :input}, or {\tt 
:output} arguments. 
\end{description}

     Example:
\begin{verbatim}
        >(process ``:cli.pr'')

        AOS/VS CLI  REV 03f.03.00.00   19-APRIL-84   12:00:00
        )by
        AOS/VS CLI  TERMINATING        19-APRIL-84   12:00:00
        t

        >
\end{verbatim}

\noindent{\tt termination-message}\hfill[{\it Function}]\\
\begin{description}
\item[] This function is defined only in KCL/AOS. {\tt termination-message}  
returns a string consisting of the termination message of a son.  Used in   
connection with the function {\tt process}.
\end{description}

\noindent{\tt last-termination-message}\hfill[{\it Function}]\\
\begin{description}
\item[] This function is defined only in KCL/AOS.                           
{\tt last-termination-message} flushes all the messages currently spooled and
returns the last termination message.
\end{description}

\chapter{Macros}
 
\section{System Macros}
 
\noindent The KCL interpreter implements the following system macros as if
they were special forms.  That is, macro forms of the following macros are
directly evaluated without being macro-expanded.

\begin{verbatim}
    and       case      cond      decf      defmacro  defun
    do        do*       dolist    dotimes   incf      locally
    loop      multiple-value-bind           multiple-value-list
    multiple-value-setq           or        pop       prog
    prog*     prog1     prog2     psetq     push      return
    setf      unless    when
\end{verbatim}

\noindent For these macro forms, the functions {\tt macro-function}  and
{\tt special-form-p}  both return non-{\tt nil}  values:
{\tt macro-function}  returns the macro expansion function
and {\tt special-form-p}  returns {\tt t}.  Of course,
functions such as {\tt macroexpand} and
{\tt macroexpand-1} will successfully
expand macro forms for these system macros.

\section{Defmacro Lambda-Lists}
 
\noindent A {\it defmacro lambda-list}  is a lambda-list-like construct that is used
as the third element in the {\tt defmacro}  form,
\begin{description}
\item[] ({\tt defmacro} {\it name defmacro-lambda-list  \{declaration  $|$   
doc-string\}*   \{ form \}* )} 
\end{description}

\noindent The description of defmacro lambda-lists in the {\it Common Lisp Reference  
Manual} is quite ambiguous.  KCL employs the
following syntax.

\noindent The complete syntax of a defmacro lambda-list is:

\begin{verbatim} 
( [ &whole var ] 
  [ &environment var ] 
  { pseudo-var }* 
  [ &optional { var | ( pseudo-var [ initform [ pseudo-var ] ] ) }* ] 
  { [ { &rest | &body } pseudo-var ]
    [ &key { var | ( { var | ( keyword pseudo-var ) } 
                     [ initform [ pseudo-var ] ] ) }* 
	     [ &allow-other-keys ] ] 
      [ &aux { var | ( pseudo-var [ initform ] ) }* ] 
 | . var } 
)
\end{verbatim}

\noindent where  {\it pseudo-var}  is either a symbol or a list of the following form:

\begin{verbatim}
( { pseudo-var }* 
  [ &optional { var | ( pseudo-var [ initform [ pseudo-var ] ] ) }* ] 
  { [ { &rest | &body } pseudo-var ] 
    [ &key { var | ( { var | ( keyword pseudo-var ) } 
                     [ initform [ pseudo-var ] ] ) }* 
	     [ &allow-other-keys ] ] 
      [ &aux { var | ( pseudo-var [ initform ] ) }* ] 
  | . var } 
)
\end{verbatim}

\noindent The defmacro lambda-list keyword {\tt \&whole} may
appear only at the top-level,
first in the defmacro lambda-list.  It is not allowed within
{\it pseudo-var}.  Use of the {\tt \&whole}  keyword does not affect
the processing of the rest of the defmacro lambda-list:

\begin{verbatim}
    (defmacro foo (&whole w x y) ... )
\end{verbatim}
\noindent and
\begin{verbatim} 
    (defmacro foo (x y) ... )
\end{verbatim}

\noindent both bind the variables {\tt x}  and {\tt y}  to the second and the
third elements, respectively, of macro forms of {\tt foo}.

\noindent The defmacro lambda-list keyword {\tt \&environment} may
appear only at the top-level, first in the defmacro lambda-list if
{\tt \&whole} is not supplied, or immediately after the variable that
follows {\tt \&whole}, if {\tt \&whole} is supplied.  {\tt
\&environment} is not allowed within {\it pseudo-var}.  Like {\tt
\&whole}, use of {\tt \&environment} does not affect the processing of
the rest of the defmacro lambda-list.  If an {\tt \&environment}
parameter is supplied andif this parameter is not used at all, then
the KCL compiler will issue a warning.  To suppress the warning, just
remove the parameter from the defmacro lambda-list, or add an {\tt
ignore} declaration.
 
\medskip

\noindent The defmacro lambda-list keyword {\tt \&body}  is completely equivalent to the {\tt \&rest} keyword.  KCL takes no special action for {\tt
\&body} parameters.

\medskip

\noindent Although useless, KCL allows supplied-p parameters
to be destructured.  This is useless because supplied-p parameters can
never be bound to a non-empty list.  Our intention is to stick to the
specification in the {\it Common Lisp Reference Manual} as far as
possible, even if it is silly to do so.

\medskip

\noindent Like for ordinary lambda-lists, the interpreter detects invalid arguments to macro expansion functions.  When a parameter is destructured, the
structure of the corresponding argument is also checked.  Such runtime
argument checking may or may not be embedded in compiled code, depending on the environment when the code was generated.  If the code
was generated while the {\tt safety} optimize level is zero (that is,
while the value of ({\tt proclamation '(optimize (safety 0))) is t}),
then the generated code does not perform argument checking at all.
Otherwise, the compiled code does check the validity of arguments.

\chapter{The C Language Interface}
 
This chapter describes the facility of KCL to interface the C language and KCL.  With this facility, the user can arrange his or her
C-language programs so that they can be invoked from KCL.  In
addition, the user can write Lisp function definitions in the C
language to increase runtime efficiency.

\medskip

\noindent The basic idea of interfacing the C language is this:  As mentioned
in Chapter 6, the KCL compiler, given a Lisp source file, creates an
intermediate C-language program file, called {\it c-file}, which is
then compiled by the C-language compiler to obtain the final
fasl-file.  Usually, the c-file consists of C-language function
definitions.  The first C-language function in the c-file is the
``initializer'', which is executed when the fasl file is loaded, and
the other C-language functions are the C versions of the Lisp
functions (including macro expansion functions) defined in the source
file.  By using the top-level macros {\tt Clines} and {\tt defCfun}
described below, the user can direct the compiler to insert his or her
own C-language function definitions and/or C-language preprocessor
macros such as {\tt \#define} and {\tt \#include} into the c-file.  In
order that such C-language functions be invoked from KCL, another
top-level macro {\tt defentry} is used.  This macro defines a Lisp
function whose body consists of the calling sequence to the specified
C-language function.

\medskip

\noindent The C-language function definitions are placed in the c-file in the
order of the corresponding Lisp functions defined
in the source file.  That is, the C code for the first Lisp function comes
first, the C code for the second Lisp function comes second, and so on.  If
a {\tt Clines}  or {\tt defCfun}  macro form appears between two
Lisp function definitions in the source file, then the C code specified by
the macro is placed in between the C code for the Lisp functions.

\medskip

\noindent We define some terminology here which is used throughout
this Chapter.  A {\it C-id}  is either a Lisp string consisting of a
valid C-language identifier, or a Lisp symbol
whose print-name, with all its alphabetic characters turned into lower case,
is a valid C identifier.  Thus the
symbol {\tt foo}  is equivalent to the string  {\tt ``foo''} 
when used as a C-id.  Similarly, a {\it C-expr}  is a
string or a symbol that may be regarded as a C-language expression.  A {\it  
C-type}  is one of
the Lisp symbols {\tt int, char, float, double,} and {\tt object}.  Each    
corresponds to a data
type in the C language; {\tt object}  is the type of Lisp object and
other C-types are primitive
data types in the C language.

\vspace{.1in}

\noindent{\tt Clines} \{{\it string}\}*\hfill[{\it Macro}]\\
\begin{description}
\item[] When the KCL compiler encounters a macro form  ({\tt Clines}        
{\it string1  ...  stringn}), it
simply outputs the {\it strings} into the c-file.  The arguments are not evaluated and
each argument must be a string.  Each {\it string}  may consist of any number of lines,
and separate lines in the {\it string}  are placed in separate lines in the c-file.  In addition,
each {\it string}  opens a fresh line in the c-file, i.e., the first character  
in the {\it string}  is
placed at the first column of a line.  Therefore, C-language preprocessor commands
such as  {\tt \#define}  and  {\tt \#include}  will be recognized as such by  
the C compiler, if the ' \# ' sign
appears as the first character of the {\it string}  or as the first
character of a line within the {\it string}.

\item[] In order to clearly distinguish C code from other parts of Lisp programs,
we, the implementors of KCL, make it our rule to start each C code line
with a percent sign ' \% '.  We define  \%  as a read macro
which returns the rest of the line as a string.  For   example,
\end{description}

\begin{verbatim}
        ;;; C version of TAK.
        (Clines

        %       int tak(x, y, z)
        %       int x, y, z;
        %       {       if (y >= x) return(z);
        %               else return(tak(tak(x-1, y, z),
        %                               tak(y-1, z, x),
        %                               tak(z-1, x, y)));
        %       }
        )
\end{verbatim}

\begin{description} 
\item[] Of course, the user may instead enclose each C code line or the
whole C code with double quotes, but we recommend the use of
the percent sign read macro.  Since
the percent sign read macro is not a standard read macro, the users must
define this read macro by themselves.  We use the following definition.
\end{description}

\begin{verbatim} 
      (set-macro-character
          #\\%
          #'(lambda (stream char) (values (read-line stream)))))
\end{verbatim}

\begin{description}
\item[] Here, the lambda-expression returns the first value of {\tt read-line} by   
using {\tt values} as a filter.

\item[] When interpreted, a {\tt Clines}  macro form expands to {\tt nil}.
\end{description}

\noindent{\tt defentry} {\it function parameter-list C-function}\hfill[{\it  
Macro}]\\
\begin{description}
\item[] {\tt defentry}  defines a Lisp function whose body consists of
the calling sequence to a
C-language function. {\it function}  is the name of the Lisp function
to be defined, and {\it C-function}  specifies the C function
to be invoked. {\it C-function}  must be either a list
 ({\it type  C-id})  or {\it C-id},
where {\it type}  and {\it C-id}  are the type and
the name of the C function. {\it type}  must be a C-type or
the symbol {\tt void}  which means that the C function returns
no value.   ({\tt object} {\it C-id} )  may be abbreviated
as {\it C-id}.  {\it parameter-list}  is a list of C-types
for the parameters of the C function.  For example,
the following {\tt defentry}
 form defines a Lisp function {\tt tak}  from
which the C function {\tt tak}  above is called.
\end{description}

\begin{verbatim}
	(defentry tak (int int int) (int tak))
\end{verbatim}

\begin{description}
\item[] The Lisp function {\tt tak}  defined by this {\tt defentry}  form
requires three arguments.  The arguments are converted to
{\tt int}  values before they are passed to the C function.  On return
from the C
function, the returned {\tt int}  value is converted
to a Lisp integer (actually a fixnum)
and this fixnum will be returned as the value
of the Lisp function.  See below for
type conversion between Lisp and the C language.

\item[] A {\tt defentry}  form is treated in the above way only when it appears 
 as a top-level form of a Lisp source file.  Otherwise, a {\tt defentry} form  
expands to {\tt nil}.
\end{description}

\noindent{\tt defla} {\it name lambda-list \{declaration $|$ doc-string\}*  
\{form\}}*\hfill[{\it Macro}]\\
\begin{description}
\item[] When interpreted, {\tt defla}  is exactly the same as {\tt defun}.   
That is,  ({\tt defla} {\it name
lambda-list  .  body}) 
expands to  ({\tt defun} {\it name lambda-list  .  body}) .  However,       
{\tt defla} forms are completely ignored by the compiler; no C-language code will be
generated for {\tt defla} forms.  The primary use of {\tt defla} is to define  
a Lisp function in two ways within a single Lisp source file; one in the C language and the other in
Lisp.  {\tt defla}  is short for {\it DEF}ine {\it L}isp {\it A}lternative.

\item[] Suppose you have a Lisp source file whose contents are:
\end{description}

\begin{verbatim} 
      ;;; C version of TAK.
      (Clines

      %      int tak(x, y, z)
      %      int x, y, z;
      %      {       if (y >= x) return(z);
      %              else return(tak(tak(x-1, y, z),
      %                              tak(y-1, z, x),
      %                              tak(z-1, x, y)));
      %      }
      
      )
 
      ;;;  TAK calls the C function tak defined above.
      (defentry tak (int int int) (int tak))
      ;;;  The alternative Lisp definition of TAK.
      (defla tak (x y z)
         (if (>= y x)
             z
             (tak (tak (1- x) y z)
                  (tak (1- y) z x)
                  (tak (1- z) x y))))
\end{verbatim}

\begin{description} 
\item[] When this file is loaded into KCL, the interpreter uses the Lisp    
version of the {\tt tak} definition.  Once this file has been compiled, and  
when the generated fasl file is
loaded into KCL, a function call to tak is actually the call to the C version  
of {\tt tak}.
\end{description}

\noindent{\tt defCfun} {\it header n \{element\}}*\hfill[{\it Macro}]\\
\begin{description}
\item[] {\tt defCfun}  defines a C-language function which calls
Lisp functions and/or which
handles Lisp objects.  {\it header}  is a string consisting of the C
code for

\begin{description}
\item[]	the optional {\it type-specifier}  of the C function,
\item[]	the {\it function-declarator}  of the C function, and
\item[]	the {\it type-decl-list}  of the parameters to the C function.
\end{description}

\item[] (For the C-language terminology, refer to {\it The C Programming    
Language}  by Brian W.  Kernighan and Dennis M. Ritchie.)  The rest of the C  
function definition, i.e., the
{\it function-statement}, is given by {\it elements}.  Each {\it element}   
may be a string, in which case
the string is treated in the same way as the arguments to the {\tt Clines}   
macro.  Or else, the {\it element}  is a list
 (({\it name arg1  ...  argn )  place1  ...  placem} ) .  The compiler
translates this list into a calling sequence to the Lisp function
whose name is {\it name}.  As will be
mentioned later, {\it name}  may be {\tt quote},
but {\it name}  may not be the name of any other special
form or a macro.  The {\it args} specify the arguments to the function
and the {\it places}
specify where the values should go.  Thus the list-formed {\it element} could  
be regarded as something like the Lisp form:
\end{description}

\begin{verbatim} 
            (multiple-value-setq
                ( place1  ...  placem )
                ( name   arg1  ...  argn )).
\end{verbatim}

\begin{description}
\item[] Each {\it arg}  is a list  ({\it C-type   C-expr}), where {\it 
C-expr} is any C-language expression of the
type {\it C-type}.  If {\it type}  is {\tt object}, then {\it arg}  may be  
written simply as {\it C-expr}.  Similarly,
each {\it place}  is a list  ({\it C-type   C-expr}), or it may be abbreviated  
as {\it C-expr}  if {\it C-type}  is
{\tt object}.  The {\it C-expr}  in this case is any {\it lvalue}  (in the  
terminology of the C language), i.e., it may be any valid C-language code that can be written at the left
side of an assignment.

\item[] The function call is performed as follows.  The {\it args} are      
evaluated, and the
values are sent to the specified Lisp function after type conversion from C to Lisp.  On return from the called Lisp function, each returned value is assigned to the
corresponding {\it place}, i.e., the first returned value goes to {\it 
place1}, the second to {\it place2},
and so on.  If there are more {\it places} than the values returned, extra  
values of {\tt nil}
 are assigned to the remaining {\it places}.  If there are more values than 
{\it places}, the
excess values are simply discarded.  If necessary, Lisp-to-C type conversion may
take place before each returned value is assigned.

\item[] If the Lisp function is called just for side-effects, then the      
list-formed {\it element}
 may be abbreviated as a one-level list  ({\it name   arg1  ...  argn}).

\item[] As a special case, if a list-formed {\it element}  is of the form   
(({\tt quote} {\it value)  place}),
the Lisp object {\it value}  is assigned to {\it place}.  Here {\it value}  
 may be any Lisp object.

\item[] The following {\tt defCfun}  form defines the C function  silly  which  
adds 100 to the value of the parameter {\tt x}  and prints the result in three different ways.  The
second argument to {\tt defCfun}  will be described later, and the user may ignore it.
\end{description}

\begin{verbatim}
        (defCfun ``silly(x) int x;'' 0
        %       int y;
                ((+ (int x) (int ``100'')) (int y))
        %       printf(``\\n%d'', y);
        %       y = x+100;
                (print (int y))
                (print (int ``x+100''))
         )
\end{verbatim}

\begin{description}
\item[] When a C function handles Lisp objects (i.e., data of type {\tt 
object}), the user
should be careful enough so that the objects may not be garbage-collected.  This is
because the garbage collector of KCL does not take care of Lisp objects used in the
C function.  See the following C function which is assumed to return a two-element
list consisting of its two arguments.
\end{description}

\begin{verbatim} 
        (defCfun ``object list2(x,y) object x,y;'' 0
        %      object z;
               ('nil z)
               ((cons y z) z)
               ((cons x z) z)
         %     return(z);
         )
\end{verbatim}

\begin{description}
\item[] When invoked, {\tt list2}  first sets {\tt nil}  to the variable 
{\tt z}, conses {\tt y}  to {\tt z}, and then conses
{\tt x}.  Each time {\tt cons}  is called, a new cons cell is allocated and the pointer to this cell
is stored in {\tt z}.  However, there is no way to inform
the garbage collector that the cells are referenced from the C variable 
{\tt z}.  Suppose
that the cons cell allocated by the first {\tt cons}  is the last cons cell available at that
time.  Then, during execution of the second call to {\tt cons}, the garbage collector
begins to run and, unfortunately, the cons cell in {\tt z}  will be destroyed so that the
cell can be recycled for further use.

\item[] To prevent a Lisp object from being unexpectedly garbage collected, the user
must save the object in some place that is recognized by the garbage collector.  The
second parameter {\it n}  to {\tt defCfun}  is used to reserve {\it n}  such  
places for each call to the
C function.  In the body of the C function, these reserved places are referenced as
{\tt vs[0], ...,  vs}[{\it n-1}].  The function {\tt list2} above, therefore,  
should be revised as follows.
\end{description}

\begin{verbatim}
        (defCfun ``object list2(x,y) object x,y;'' 1
               ('nil ``vs[0]'')
               ((cons y ``vs[0]'') ``vs[0]'')
               ((cons x ``vs[0]'') ``vs[0]'')
        %      Creturn(vs[0]);
        )
\end{verbatim}

\begin{description}
\item[] Notice that {\tt return}  is replaced by {\tt Creturn}.  {\tt 
Creturn}  is similar to {\tt return}  except
that {\tt Creturn}  releases the reserved places on
return from the function.  In the C
code within a {\tt defCfun} form,
write ``{\tt Creturn}({\it value});'' instead of
``{\tt return}({\it value});'', and
write ``{\tt Cexit};'' instead of ``{\tt return};''.

\item[] Again, a {\tt defCfun} form has the above meaning only when it appears  
as a top-level form in a Lisp source file.  Otherwise, the form expands to 
{\tt nil}.
\end{description}

\noindent KCL converts a Lisp object into a C-language data by using the Common Lisp function {\tt coerce}: For the C-type {\tt int} (or {\tt char}), the object is first coerced to a Lisp integer and the least significant 32-bit (or
8-bit) field is used as the C {\tt int} (or {\tt char}).  For the
C-type {\tt float} (or {\tt double}), the object is coerced to a
short-float (or a long-float) and this value is used as the {\tt C
float} (or {\tt double}).  Conversion from a C data into a Lisp object
is obvious: {\tt C char, int, float,} and {\tt double} become the
equivalent Lisp character, fixnum, short-float, and long-float,
respectively.

\noindent  Here we list the complete syntax of {\tt Clines, defentry,} and 
{\tt defCfun} macro forms.

\begin{verbatim}
Clines-form:
        (Clines { string }* )

defentry-form:
        (defentry function-symbol
                ( { C-type }* )
                { C-function-name | ( { C-type | void } C-function-name ) } )

defCfun-form:
        (defCfun string non-negative-integer
                { string
                  | ( function-symbol { value }* )
                  | (( function-symbol  { value }* ) { place }* ) }  )

value:
place:
         { C-expr | ( C-type C-expr ) }

C-function-name:
C-expr:
         { string | symbol }
 
C-type:
         { object | int | char | float | double }
\end{verbatim}



\chapter{The Editor}

KCL/AOS is equipped with a screen editor
FeCl2 ({\it F}ull-screen {\it E}ditor
as a {\it C}ommon {\it L}isp {\it TOO}l).  FeCl2 is an EMACS-like editor with  
facilities for Lisp coding.  FeCl2 is invoked from KCL by the function {\tt 
ed} and the result of editing can be passed to KCL directly.  For the details  
of FeCl2 refer to {\it The FeCl2 Editor Reference Manual}.

\vspace{.1in}

\noindent{\tt ed \&optional} {\it filename}\hfill[{\it Function}]\\
\begin{description}
\item[] {\tt ed}  invokes FeCl2
and sets the edit file of FeCl2 to {\it filename}.  If the filetype of the  
file is not explicitly specified, then the {\it filename} is
first merged into  \#{\tt ``.lsp''}.
\end{description}

\noindent The FeCl2 editor is not supported by other versions of KCL.  The function {\tt ed} of KCL/VAX, KCL/SUN, and KCL/UST calls the vi editor.  If you
hate vi, define your own {\tt ed} function using the function {\tt
system} described in Chapter 8.

\newpage

\centerline{\large\bf Appendix A. KCL Summary}

\vspace{.4in}
 
\noindent The following table lists all symbols defined in KCL.  Each line has the
following form.

\vspace{.1in}

       {\it symbol    [kind]    remark}\\

\vspace{.1in}

\noindent where {\it kind}  is Function, Macro, Special (i.e., Special form name),
Variable, Constant, Symbol, or Keyword.  In the table, some symbols are
labeled both as a macro and a special form name.  This means
that, although these symbols are defined to be a macro name
in the   {\it Common Lisp Reference Manual} , KCL treats them as
if they were special forms (see Section 9.1).  The pages in the remark
refer to pages in this report.

\begin{verbatim}
*                               [Function]
*                               [Variable]
**                              [Variable]
***                             [Variable]
+                               [Function]
+                               [Variable]
++                              [Variable]
+++                             [Variable]
-                               [Function]
-                               [Variable]
/                               [Function]
/                               [Variable]
//                              [Variable]
///                             [Variable]
/=                              [Function]
1+                              [Function]
1-                              [Function]
<                               [Function]
<=                              [Function]
=                               [Function]
>                               [Function]
>=                              [Function]
:abort                          [Keyword]
abs                             [Function]
acons                           [Function]
acos                            [Function]
acosh                           [Function]
adjoin                          [Function]
adjust-array                    [Function]
\end{verbatim}

\newpage

\begin{verbatim}
:adjustable                     [Keyword]
adjustable-array-p              [Function]
allocate                        [Function] Added.
allocate-contiguous-pages       [Function] Added.
allocated-contiguous-pages      [Function] Added.
allocated-pages                 [Function] Added.
allocated-relocatable-pages     [Function] Added.
allocate-relocatable-pages      [Function] Added.
alpha-char-p                    [Function]
alphanumericp                   [Function]
and                             [Special, Macro]
append                          [Function]
:append                         [Keyword]
apply                           [Function]
applyhook                       [Function]
*applyhook*                     [Variable]
apropos                         [Function]
apropos-list                    [Function]
aref                            [Function]
:array                          [Keyword]
array-dimension                 [Function]
array-dimension-limit           [Constant]
array-dimensions                [Function]
array-element-type              [Function]
array-has-fill-pointer-p        [Function]
array-in-bounds-p               [Function]
array-rank                      [Function]
array-rank-limit                [Constant]
array-row-major-index           [Function]
array-total-size                [Function]
array-total-size-limit          [Constant]
arrayp                          [Function]
ash                             [Function]
asin                            [Function]
asinh                           [Function]
assert                          [Macro]
assoc                           [Function]
assoc-if                        [Function]
assoc-if-not                    [Function]
atan                            [Function]
\end{verbatim}

\newpage

\begin{verbatim}
atanh                           [Function]
atom                            [Function]
:b                              [Keyword] Abbreviate Break Loop Command.
:backtrace                      [Keyword] Break Loop Command.
:base                           [Keyword]
bit                             [Function]
bit-and                         [Function]
bit-andc1                       [Function]
bit-andc2                       [Function]
bit-eqv                         [Function]
bit-ior                         [Function]
bit-nand                        [Function]
bit-nor                         [Function]
bit-not                         [Function]
bit-orc1                        [Function]
bit-orc2                        [Function]
bit-vector-p                    [Function]
bit-xor                         [Function]
block                           [Special]
:block                          [Keyword] Added.
:blocks                         [Keyword] Break Loop Command.
boole                           [Function]
boole-1                         [Constant]
boole-2                         [Constant]
boole-and                       [Constant]
boole-andc1                     [Constant]
boole-andc2                     [Constant]
boole-c1                        [Constant]
boole-c2                        [Constant]
boole-clr                       [Constant]
boole-eqv                       [Constant]
boole-ior                       [Constant]
boole-nand                      [Constant]
boole-nor                       [Constant]
boole-orc1                      [Constant]
boole-orc2                      [Constant]
boole-set                       [Constant]
boole-xor                       [Constant]
both-case-p                     [Function]
boundp                          [Function]
\end{verbatim}

\newpage

\begin{verbatim}
break                           [Function]
*break-on-warnings*             [Variable]
*break-enable*                  [Variable] Added.
butlast                         [Function]
by                              [Function] Added.
bye                             [Function] Added.
byte                            [Function]
byte-position                   [Function]
byte-size                       [Function]
:c                              [Keyword] Abbreviated Break Loop Command.
caaaar                          [Function]
caaadr                          [Function]
caaar                           [Function]
caadar                          [Function]
caaddr                          [Function]
caadr                           [Function]
caar                            [Function]
cadaar                          [Function]
cadadr                          [Function]
cadar                           [Function]
caddar                          [Function]
cadddr                          [Function]
caddr                           [Function]
cadr                            [Function]
call-arguments-limit            [Constant]
car                             [Function]
:case                           [Keyword]
case                            [Special, Macro]
catch                           [Special]
ccase                           [Macro]
cdaaar                          [Function]
cdaadr                          [Function]
cdaar                           [Function]
cdadar                          [Function]
cdaddr                          [Function]
cdadr                           [Function]
cdar                            [Function]
cddaar                          [Function]
cddadr                          [Function]
cddar                           [Function]
\end{verbatim}

\newpage

\begin{verbatim}
cdddar                          [Function]
cddddr                          [Function]
cdddr                           [Function]
cddr                            [Function]
cdr                             [Function]
ceiling                         [Function]
cerror                          [Function]
:c-file                         [Keyword] Added.
char                            [Function]
char-bit                        [Function]
char-bits                       [Function]
char-bits-limit                 [Constant]
char-code                       [Function]
char-code-limit                 [Constant]
char-control-bit                [Constant]
char-downcase                   [Function]
char-equal                      [Function]
char-font                       [Function]
char-font-limit                 [Constant]
char-greaterp                   [Function]
char-hyper-bit                  [Constant]
char-int                        [Function]
char-lessp                      [Function]
char-meta-bit                   [Constant]
char-name                       [Function]
char-not-equal                  [Function]
char-not-greaterp               [Function]
char-not-lessp                  [Function]
char-super-bit                  [Constant]
char-upcase                     [Function]
char/=                          [Function]
char<                           [Function]
char<=                          [Function]
char=                           [Function]
char>                           [Function]
char>=                          [Function]
character                       [Function]
characterp                      [Function]
check-type                      [Macro]
:circle                         [Keyword]
\end{verbatim}

\newpage

\begin{verbatim}
cis                             [Function]
clear-input                     [Function] Different.
clear-output                    [Function] Different.
clines                          [Macro] Added.
close                           [Function] Different.
clrhash                         [Function]
code-char                       [Function]
coerce                          [Function]
commonp                         [Function]
compilation-speed               [Symbol] Optimize Quality.
compile                         [Function]
compile-file                    [Function]
compiled-function-p             [Function]
compiler-let                    [Special]
complex                         [Function]
complexp                        [Function]
:conc-name                      [Keyword]
concatenate                     [Function]
cond                            [Special, Macro]
conjugate                       [Function]
cons                            [Function]
:console                        [Keyword] Added.
consp                           [Function]
constantp                       [Function]
:constructor                    [Keyword]
:copier                         [Keyword]
copy-alist                      [Function]
copy-list                       [Function]
copy-readtable                  [Function]
copy-seq                        [Function]
copy-symbol                     [Function]
copy-tree                       [Function]
cos                             [Function]
cosh                            [Function]
count                           [Function]
:count                          [Keyword]
count-if                        [Function]
count-if-not                    [Function]
:create                         [Keyword]
ctypecase                       [Macro]
\end{verbatim}

\newpage

\begin{verbatim}
:current                        [Keyword] Break Loop Command.
:data                           [Keyword] Added.
:data-file                      [Keyword] Added.
:debug                          [Keyword] Added.
*debug-io*                      [Variable]
decf                            [Special, Macro]
declaration                     [Symbol] Declaration Specifier.
declare                         [Special]
decode-float                    [Function]
decode-universal-time           [Function]
:default                        [Keyword]
*default-pathname-defaults*     [Variable]
:defaults                       [Keyword]
defautoload                     [Macro] Added.
defcfun                         [Macro] Added.
defconstant                     [Macro]
defentry                        [Macro] Added.
define-modify-macro             [Macro]
define-setf-method              [Macro]
defla                           [Macro] Added.
defmacro                        [Special, Macro]
defparameter                    [Macro]
defsetf                         [Macro]
defstruct                       [Macro]
deftype                         [Macro]
defun                           [Special, Macro]
defvar                          [Macro]
delete                          [Function]
delete-duplicates               [Function]
delete-file                     [Function]
delete-if                       [Function]
delete-if-not                   [Function]
denominator                     [Function]
deposit-field                   [Function]
describe                        [Function]
:device                         [Keyword]
digit-char                      [Function]
digit-char-p                    [Function]
:dir                            [Keyword] Added.
:direction                      [Keyword]
\end{verbatim}

\newpage

\begin{verbatim}
directory                       [Function]
:directory                      [Keyword]
directory-namestring            [Function]
disassemble                     [Function] Different.
:displaced-index-offset         [Keyword]
:displaced-to                   [Keyword]
do                              [Special, Macro]
do*                             [Special, Macro]
do-all-symbols                  [Macro]
do-external-symbols             [Macro]
do-symbols                      [Macro]
documentation                   [Function]
dolist                          [Special, Macro]
dotimes                         [Special, Macro]
double-float-epsilon            [Constant]
double-float-negative-epsilon   [Constant]
dpb                             [Function]
dribble                         [Function]
ecase                           [Macro]
ed                              [Function] Different.
eighth                          [Function]
:element-type                   [Keyword]
elt                             [Function]
encode-universal-time           [Function]
:end                            [Keyword]
:end1                           [Keyword]
:end2                           [Keyword]
endp                            [Function]
enough-namestring               [Function]
&environment                    [Symbol] Defmacro-lambda Keyword.
eq                              [Function]
eql                             [Function]
equal                           [Function]
equalp                          [Function]
error                           [Function]
:error                          [Keyword]
*error-output*                  [Variable]
:escape                         [Keyword]
etypecase                       [Macro]
eval                            [Function]
\end{verbatim}

\newpage

\begin{verbatim}
evalhook                        [Function]
*evalhook*                      [Variable]
eval-when                       [Macro]
*eval-when-compile*             [Variable] Added.
evenp                           [Function]
every                           [Function]
exp                             [Function]
export                          [Function]
expt                            [Function]
:external                       [Keyword]
:fasl-file                      [Keyword] Added.
fboundp                         [Function]
fceiling                        [Function]
*features*                      [Variable]
ffloor                          [Function]
fifth                           [Function]
file-author                     [Function]
file-length                     [Function]
file-namestring                 [Function]
file-position                   [Function]
file-write-date                 [Function]
fill                            [Function]
fill-pointer                    [Function]
:fill-pointer                   [Keyword]
find                            [Function]
find-all-symbols                [Function]
find-if                         [Function]
find-if-not                     [Function]
find-package                    [Function]
find-symbol                     [Function]
finish-output                   [Function]
first                           [Function]
flet                            [Special]
float                           [Function]
float-digits                    [Function]
float-precision                 [Function]
float-radix                     [Function]
float-sign                      [Function]
floatp                          [Function]
floor                           [Function]
\end{verbatim}

\newpage

\begin{verbatim}
fmakunbound                     [Function]
force-output                    [Function]
format                          [Function]
fourth                          [Function]
fresh-line                      [Function]
:from-end                       [Keyword]
fround                          [Function]
ftruncate                       [Function]
ftype                           [Symbol] Declaration Specifier.
funcall                         [Function]
function                        [Special] Also Declaration Specifier.
functionp                       [Function]
:functions                      [Keyword] Break Loop Command.
gbc                             [Function] Added.
gcd                             [Function]
gensym                          [Function]
:gensym                         [Keyword]
gentemp                         [Function]
get                             [Function]
get-decoded-time                [Function]
get-dispatch-macro-character    [Function]
get-internal-real-time          [Function]
get-internal-run-time           [Function]
get-macro-character             [Function]
get-output-stream-string        [Function]
get-properties                  [Function]
get-setf-method                 [Function]
get-setf-method-multiple-value  [Function]
get-universal-time              [Function]
getf                            [Function]
gethash                         [Function]
go                              [Special]
graphic-char-p                  [Function]
hash-table-count                [Function]
hash-table-p                    [Function]
:h                              [Keyword] Abbreviated Break Loop Command.
:help                           [Keyword] Break Loop Command.
:h-file                         [Keyword] Added.
:hide                           [Keyword] Break Loop Command.
:hide-package                   [Keyword] Break Loop Command.
:host                           [Keyword]
\end{verbatim}

\newpage

\begin{verbatim}
host-namestring                 [Function]
identity                        [Function]
if                              [Special]
:if-does-not-exist              [Keyword]
:if-exists                      [Keyword]
ignore                          [Symbol] Declaration Specifier.
*ignore-maximum-pages*          [Variable] Added.
imagpart                        [Function]
import                          [Function]
in-package                      [Function]
incf                            [Special, Macro]
:include                        [Keyword]
:index                          [Keyword]
:inherited                      [Keyword]
:initial-contents               [Keyword]
:initial-element                [Keyword]
:initial-offset                 [Keyword]
:initial-value                  [Keyword]
inline                          [Symbol] Declaration Specifier.
:input                          [Keyword]
input-stream-p                  [Function]
inspect                         [Function]
int-char                        [Function]
integer-decode-float            [Function]
integer-length                  [Function]
integerp                        [Function]
intern                          [Function]
:intern                         [Keyword]
internal-time-units-per-second  [Constant]
intersection                    [Function]
:io                             [Keyword]
:ioc                            [Keyword] Added.
isqrt                           [Function]
:junk-allowed                   [Keyword]
:key                            [Keyword]
keywordp                        [Function]
:l                              [Keyword] Abbreviated Break Loop Command.
labels                          [Special]
lambda-list-keywords            [Constant]
lambda-parameters-limit         [Constant]
\end{verbatim}

\newpage

\begin{verbatim}
last                            [Function]
last-termination-message        [Function] Added.
lcm                             [Function]
ldb                             [Function]
ldb-test                        [Function]
ldiff                           [Function]
least-negative-double-float     [Constant]
least-negative-long-float       [Constant]
least-negative-short-float      [Constant]
least-negative-single-float     [Constant]
least-positive-double-float     [Constant]
least-positive-long-float       [Constant]
least-positive-short-float      [Constant]
least-positive-single-float     [Constant]
length                          [Function]
:length                         [Keyword]
let                             [Special]
let*                            [Special]
:level                          [Keyword]
lisp-implementation-type        [Function]
lisp-implementation-version     [Function]
list                            [Function]
:list                           [Keyword] Added.
list*                           [Function]
list-all-packages               [Function]
list-length                     [Function]
listen                          [Function] Different.
listp                           [Function]
load                            [Function]
*load-verbose*                  [Variable]
:local                          [Keyword] Break Loop Command.
locally                         [Special, Macro]
log                             [Function]
logand                          [Function]
logandc1                        [Function]
logandc2                        [Function]
logbitp                         [Function]
logcount                        [Function]
logeqv                          [Function]
logior                          [Function]
\end{verbatim}

\newpage

\begin{verbatim}
lognand                         [Function]
lognor                          [Function]
lognot                          [Function]
logorc1                         [Function]
logorc2                         [Function]
logtest                         [Function]
logxor                          [Function]
long-float-epsilon              [Constant]
long-float-negative-epsilon     [Constant]
long-site-name                  [Function]
loop                            [Special, Macro]
lower-case-p                    [Function]
machine-instance                [Function]
machine-type                    [Function]
machine-version                 [Function]
macro-function                  [Function]
macroexpand                     [Function]
macroexpand-1                   [Function]
*macroexpand-hook*              [Variable]
macrolet                        [Special]
make-array                      [Function]
make-broadcast-stream           [Function]
make-char                       [Function]
make-concatenated-stream        [Function]
make-dispatch-macro-character   [Function]
make-echo-stream                [Function]
make-hash-table                 [Function]
make-list                       [Function]
make-package                    [Function]
make-pathname                   [Function]
make-random-state               [Function]
make-sequence                   [Function]
make-string                     [Function]
make-string-input-stream        [Function]
make-string-output-stream       [Function]
make-symbol                     [Function]
make-synonym-stream             [Function]
make-two-way-stream             [Function]
makunbound                      [Function]
map                             [Function]
\end{verbatim}

\newpage

\begin{verbatim}
mapc                            [Function]
mapcan                          [Function]
mapcar                          [Function]
mapcon                          [Function]
maphash                         [Function]
mapl                            [Function]
maplist                         [Function]
mask-field                      [Function]
max                             [Function]
maximum-allocatable-pages       [Function] Added.
maximum-contiguous-pages        [Function] Added.
member                          [Function]
member-if                       [Function]
member-if-not                   [Function]
merge                           [Function]
merge-pathnames                 [Function]
min                             [Function]
minusp                          [Function]
mismatch                        [Function]
mod                             [Function]
*modules*                       [Variable]
most-negative-double-float      [Constant]
most-negative-fixnum            [Constant]
most-negative-long-float        [Constant]
most-negative-short-float       [Constant]
most-negative-single-float      [Constant]
most-positive-double-float      [Constant]
most-positive-fixnum            [Constant]
most-positive-long-float        [Constant]
most-positive-short-float       [Constant]
most-positive-single-float      [Constant]
multiple-value-bind             [Special, Macro]
multiple-value-call             [Special]
multiple-value-list             [Special, Macro]
multiple-value-prog1            [Special]
multiple-value-setq             [Special, Macro]
multiple-values-limit           [Constant]
:n                              [Keyword] Abbreviated Break Loop Command.
:name                           [Keyword]
name-char                       [Function]
\end{verbatim}

\newpage

\begin{verbatim}
:named                          [Keyword]
namestring                      [Function]
nbutlast                        [Function]
nconc                           [Function]
:new-version                    [Keyword]
:next                           [Keyword] Break Loop Command.
nil                             [Constant]
nintersection                   [Function]
ninth                           [Function]
not                             [Function]
notany                          [Function]
notevery                        [Function]
notinline                       [Symbol] Declaration Specifier.
nreconc                         [Function]
nreverse                        [Function]
nset-difference                 [Function]
nset-exclusive-or               [Function]
nstring-capitalize              [Function]
nstring-downcase                [Function]
nstring-upcase                  [Function]
nsublis                         [Function]
nsubst                          [Function]
nsubst-if                       [Function]
nsubst-if-not                   [Function]
nsubstitute                     [Function]
nsubstitute-if                  [Function]
nsubstitute-if-not              [Function]
nth                             [Function]
nthcdr                          [Function]
null                            [Function]
numberp                         [Function]
numerator                       [Function]
nunion                          [Function]
:ob-file                        [Keyword] Added.
object                          [Symbol] Declaration Specifier.  Added.
oddp                            [Function]
:o-file                         [Keyword] Added.
open                            [Function] Different.
optimize                        [Symbol] Declaration Specifier.
or                              [Special, Macro]
\end{verbatim}

\newpage

\begin{verbatim}
:output                         [Keyword]
:output-file                    [Keyword]
output-stream-p                 [Function]
:overwrite                      [Keyword]
*package*                       [Variable]
package-name                    [Function]
package-nicknames               [Function]
package-shadowing-symbols       [Function]
package-use-list                [Function]
package-used-by-list            [Function]
packagep                        [Function]
pairlis                         [Function]
:parent                         [Keyword] Added.
parse-integer                   [Function]
parse-namestring                [Function]
pathname                        [Function]
pathname-device                 [Function]
pathname-directory              [Function]
pathname-host                   [Function]
pathname-name                   [Function]
pathname-type                   [Function]
pathname-version                [Function]
pathnamep                       [Function]
peek-char                       [Function]
phase                           [Function]
pi                              [Constant]
plusp                           [Function]
pop                             [Macro]
position                        [Function]
position-if                     [Function]
position-if-not                 [Function]
pprint                          [Function]
:p                              [Keyword] Abbreviate Break Loop Command.
:predicate                      [Keyword]
:preserve-whitespace            [Keyword]
:pretty                         [Keyword]
:previous                       [Keyword] Break Loop Command.
prin1                           [Function]
prin1-to-string                 [Function]
\end{verbatim}

\newpage

\begin{verbatim}
princ                           [Function]
princ-to-string                 [Function]
print                           [Function]
:print                          [Keyword]
*print-array*                   [Variable]
*print-base*                    [Variable]
*print-case*                    [Variable]
*print-circle*                  [Variable]
*print-escape*                  [Variable]
:print-function                 [Keyword]
*print-gensym*                  [Variable]
*print-length*                  [Variable]
*print-level*                   [Variable]
*print-pretty*                  [Variable]
*print-radix*                   [Variable]
:probe                          [Keyword]
probe-file                      [Function]
process                         [Function] Added.
proclaim                        [Function]
proclamation                    [Function] Added.
prog                            [Special, Macro]
prog*                           [Special, Macro]
prog1                           [Special, Macro]
prog2                           [Special, Macro]
progn                           [Special]
progv                           [Special]
provide                         [Function]
psetf                           [Macro]
psetq                           [Special, Macro]
push                            [Special, Macro]
pushnew                         [Macro]
:q                              [Keyword] Abbreviated Break Loop Command.
*query-io*                      [Variable]
:quit                           [Keyword] Break Loop Command.
quote                           [Special]
:r                              [Keyword] Abbreviated Break Loop Command.
:radix                          [Keyword]
random                          [Function]
*random-state*                  [Variable]
random-state-p                  [Function]
rassoc                          [Function]
\end{verbatim}

\newpage

\begin{verbatim}
rassoc-if                       [Function]
rassoc-if-not                   [Function]
rational                        [Function]
rationalize                     [Function]
rationalp                       [Function]
read                            [Function]
*read-base*                     [Variable]
read-byte                       [Function] Different.
read-char                       [Function]
read-char-no-hang               [Function] Different.
*read-default-float-format*     [Variable]
read-delimited-list             [Function]
read-from-string                [Function]
read-line                       [Function]
:read-only                      [Keyword]
read-preserving-whitespace      [Function]
*read-suppress*                 [Variable]
*readtable*                     [Variable]
readtablep                      [Function]
realpart                        [Function]
reduce                          [Function]
:rehash-size                    [Keyword]
:rehash-threshold               [Keyword]
rem                             [Function]
remf                            [Macro]
remhash                         [Function]
remove                          [Function]
remove-duplicates               [Function]
remove-if                       [Function]
remove-if-not                   [Function]
remprop                         [Function]
:rename                         [Keyword]
:rename-and-delete              [Keyword]
rename-file                     [Function]
rename-package                  [Function]
replace                         [Function]
require                         [Function]
:resume                         [Keyword] Break Loop Command.
rest                            [Function]
return                          [Special, Macro]
\end{verbatim}

\newpage

\begin{verbatim}
return-from                     [Special]
revappend                       [Function]
reverse                         [Function]
room                            [Function]
:root                           [Function] Added.
rotatef                         [Macro]
round                           [Function]
rplaca                          [Function]
rplacd                          [Function]
safety                          [Symbol] Optimize Quality.
save                            [Function] Added.
sbit                            [Function]
scale-float                     [Function]
schar                           [Function]
search                          [Function]
second                          [Function]
set                             [Function]
set-char-bit                    [Function]
set-difference                  [Function]
set-dispatch-macro-character    [Function]
set-exclusive-or                [Function]
set-macro-character             [Function]
set-syntax-from-char            [Function]
setf                            [Special, Macro]
setq                            [Special]
seventh                         [Function]
shadow                          [Function]
shadowing-import                [Function]
shiftf                          [Macro]
short-float-epsilon             [Constant]
short-float-negative-epsilon    [Constant]
short-site-name                 [Function]
signum                          [Function]
simple-bit-vector-p             [Function]
simple-string-p                 [Function]
simple-vector-p                 [Function]
sin                             [Function]
single-float-epsilon            [Constant]
single-float-negative-epsilon   [Constant]
sinh                            [Function]
\end{verbatim}

\newpage

\begin{verbatim}
sixth                           [Function]
:size                           [Keyword]
sleep                           [Function]
software-type                   [Function]
software-version                [Function]
some                            [Function]
sort                            [Function]
space                           [Symbol] Optimize Quality.
special                         [Symbol] Declaration Specifier.
special-form-p                  [Function]
speed                           [Symbol] Optimize Quality.
sqrt                            [Function]
stable-sort                     [Function]
standard-char-p                 [Function]
*standard-input*                [Variable]
*standard-output*               [Variable]
:start                          [Keyword]
:start1                         [Keyword]
:start2                         [Keyword]
:static                         [Keyword] Added.
step                            [Macro]
:stream                         [Keyword]
stream-element-type             [Function]
streamp                         [Function]
string                          [Function]
string-capitalize               [Function]
string-char-p                   [Function]
string-downcase                 [Function]
string-equal                    [Function]
string-greaterp                 [Function]
string-left-trim                [Function]
string-lessp                    [Function]
string-not-equal                [Function]
string-not-greaterp             [Function]
string-not-lessp                [Function]
string-right-trim               [Function]
string-trim                     [Function]
string-upcase                   [Function]
string/=                        [Function]
string<                         [Function]
\end{verbatim}

\newpage

\begin{verbatim}
string<=                        [Function]
string=                         [Function]
string>                         [Function]
string>=                        [Function]
stringp                         [Function]
sublis                          [Function]
subseq                          [Function]
subsetp                         [Function]
subst                           [Function]
subst-if                        [Function]
subst-if-not                    [Function]
substitute                      [Function]
substitute-if                   [Function]
substitute-if-not               [Function]
subtypep                        [Function]
:supersede                      [Keyword]
svref                           [Function]
sxhash                          [Function]
symbol-function                 [Function]
symbol-name                     [Function]
symbol-package                  [Function]
symbol-plist                    [Function]
symbol-value                    [Function]
symbolp                         [Function]
system                          [Function] Added.
t                               [Constant]
:tags                           [Keyword] Break Loop Command.
tagbody                         [Special]
tailp                           [Function]
tan                             [Function]
tanh                            [Function]
tenth                           [Function]
*terminal-io*                   [Variable] Different.
termination-message             [Function] Added.
terpri                          [Function]
:test                           [Keyword]
:test-not                       [Keyword]
the                             [Special]
third                           [Function]
throw                           [Special]
\end{verbatim}

\newpage

\begin{verbatim}
time                            [Macro]
trace                           [Macro]
*trace-output*                  [Variable]
tree-equal                      [Function]
truename                        [Function]
truncate                        [Function]
type                            [Symbol] Declaration Specifier.
:type                           [Keyword]
type-of                         [Function]
typecase                        [Macro]
typep                           [Function]
unexport                        [Function]
unintern                        [Function]
union                           [Function]
:unhide                         [Keyword] Break Loop Command.
:unhide-package                 [Keyword] Break Loop Command.
unless                          [Special, Macro]
unread-char                     [Function]
untrace                         [Macro]
unuse-package                   [Function]
unwind-protect                  [Special]
upper-case-p                    [Function]
use-package                     [Function]
user-homedir-pathname           [Function]
:username                       [Keyword] Added.
:v                              [Keyword] Abbreviated Break Loop Command.
values                          [Function]
values-list                     [Function]
:variables                      [Keyword] Break Loop Command.
vector                          [Function]
vector-pop                      [Function]
vector-push                     [Function]
vector-push-extend              [Function]
vectorp                         [Function]
:verbose                        [Keyword]
:version                        [Keyword]
warn                            [Function]
when                            [Special, Macro]
&whole                          [Symbol] Defmacro-lambda Keyword.
:wild                           [Keyword] Added.
with-input-from-string          [Macro]
\end{verbatim}

\newpage

\begin{verbatim}
with-open-file                  [Macro]
with-open-stream                [Macro]
with-output-to-string           [Macro]
write                           [Function]
write-byte                      [Function] Different.
write-char                      [Function]
write-line                      [Function]
write-string                    [Function]
write-to-string                 [Function]
y-or-n-p                        [Function]
yes-or-no-p                     [Function]
zerop                           [Function]
\end{verbatim}

\newpage

\centerline{\large\bf Appendix B. An Overview of Kyoto Common Lisp}

\vspace{.4in}

\noindent {\it Kyoto Common Lisp}  (KCL for short) is a full implementation of the
Common
Lisp language.  KCL is a highly portable Common Lisp system intended for
several classes of machines, from mini/micro to mainframe.  The key idea
behind the portability is the use of the C language and its standard libraries
as the interface with
the underlying machines and operating systems:  The kernel of the system
is written in C and the rest of the system is written in Common
Lisp.  Even the compiler generates intermediate code in C.  KCL is also
an efficient and compact system:  KCL regards the runtime efficiency of
interpreted code as important as the efficiency of compiled code.  The small
size of the KCL system makes KCL suitable for the current computer technology,
such as the use of virtual memory and cache memory.  This document reports
the current status of KCL, its
implementation, and system performance.  This document is a draft:
the description is still incomplete and informal,
and some technical terms are used without
definition or explanation.  A full paper on the KCL implementation is in
preparation.

\vspace{.1in}

\noindent {\large\bf KCL is a full Common Lisp system.}\\

\medskip

\noindent KCL is a full implementation of the Common Lisp language described in
the  {\it Common Lisp Reference Manual}:

\vspace{.1in}

\centerline{\it Common Lisp: The Language.}
\centerline{by Guy L. Steele et al.}
\centerline{Digital Press, 1984}

\vspace{.1in}

\noindent KCL supports all Common Lisp functions, macros, and special forms defined
in the  {\it Common Lisp Reference Manual}.  All Common Lisp variables
and constants are defined in KCL exactly as
described in the  {\it Common Lisp Reference Manual}.

\vspace{.1in}

\noindent {\large\bf KCL is available on several machines already.}\\

\medskip

\noindent Currently, there are four major versions of KCL:

\begin{enumerate}
\item	 KCL/AOS
	   Machine:  Data General's Eclipse MV series super-minicomputers (MV10000, MV8000, MV6000, and MV4000) 
	   Operating System:  Data General's original AOS/VS (Advanced Operating System / Virtual Storage) 

\item KCL/VAX
	   Machine:  Digital Equipment Corporation's VAX 11 series machines (VAX 11/780 and VAX 11/750) 
	   Operating System: UNIX 4.2 bsd

\item KCL/SUN
	   Machine:  Sun Microsystems' Sun Workstation (MC68000 base) 
	   Operating System: UNIX 4.2 bsd

\item KCL/UST	 Machine: Sumitomo Electric Industries and Digital
Computer Laboratory's personal workstation Ustation E15 (MC68000 base)
	   Operating System: UNIX V (Uniplus' version)
\end{enumerate}

\noindent KCL/AOS is the original version of KCL, which was developed
at Research Institute for Mathematical Sciences (RIMS), Kyoto
University, with the cooperation of Nippon Data General Corporation.
Other versions are ported from KCL/AOS at RIMS.  All four versions
share most of the source files of KCL.  Improvements and error
corrections are performed on the common source files, and the most
recent revisions are brought to each machine from time to time.

\medskip

\noindent Ports to other machines and other operating systems are being
undertaken or are in preparation at other organizations.  KCL is
expected to become available on the following machines in the near
future.  

\begin{description} 
\item[*] IBM (and IBM-compatible) M
series machines 
\item[*] Apollo Domain 
\item[*] Perkins Elmer 
\item[*] VAX 11 (running VMS) 
\item[*] VAX 11 (running Eunice, the Unix emulator) 
\item[*] Eclipse MV (running DGUX, Data General's native
Unix) 
\end{description}

\noindent {\large\bf KCL is written in C and Lisp}\\

\medskip

\noindent The kernel of KCL is written in C, including:

\begin{description}
\item[*] memory management and garbage collection
\item[*] the evaluator (or interpreter)
\item[*] Common Lisp special forms
\end{description}

\noindent The KCL compiler is entirely written in Common Lisp.
\vspace{.1in}

\medskip

\noindent Each Common Lisp function or macro is written either in C or in Lisp.

\begin{verbatim}
        in C:
                418 Common Lisp functions
                11 Common Lisp macros

        in Lisp:
                133 Common Lisp functions
                59 Common Lisp macros
\end{verbatim}

\noindent The size of the source code is:

\begin{verbatim}
        C code         705 Kbytes
	Common Lisp functions and macros written in Lisp
                       173 Kbytes
        The compiler   264 Kbytes
	--------------------------- 
        total         1142 Kbytes
\end{verbatim}

\noindent Three routines in the kernel are partly written
in assembly language.  These routines are:

\begin{description}
\item[*] bignum multiplication
\item[*] bignum division
\item[*] bit table manipulation of the garbage collector 
\end{description}

\noindent The total size of assembly code is 20 to 30 lines, depending on the
version of KCL.

\vspace{.1in}

\noindent {\large\bf KCL/AOS is built up by old-fashioned bootstrapping}\\

\medskip

\noindent When KCL/AOS, the original version of KCL, was born, the following steps
were taken to build it up.

\begin{enumerate}
\item Compile all C code with the C compiler and link them
all.  A subset of KCL is ready to run at this moment. 

\item Load all Lisp code into KCL.  Now the full system is ready
to run, although the compiler and some Common Lisp functions and macros
run interpretively. 

\item Compile the source files of the KCL compiler
with the (interpreted) KCL compiler itself.  Load each Fasl-file (i.e., the
file created by the KCL compiler) immediately
after it is generated.  The compilation process becomes faster
toward the end of this step.  Finally, the whole KCL compiler is ready
to run by itself. 

\item Compile the Common Lisp functions and macros written in Lisp,
with the compiled KCL compiler.  Load the Fasl-files.  This completes
the generation of the full system.
\end{enumerate}

\noindent The same steps are taken whenever drastic changes are made
to the kernel.  On the other hand, the procedure to port KCL or to
revise the ported versions of KCL is much simpler, because all Lisp code has
been cross-compiled by the compiler of KCL/AOS beforehand.

\vspace{.1in}

\noindent {\large\bf Objects are represented by cells.}\\

\medskip

\noindent KCL does not support the so-called immediate data.  Any KCL object is
represented as (a pointer to) a cell that is allocated on the heap.  Each
cell consists of several words (1 word = 32 bit) whose first word is in the
format common to all data types: half of the word
is the type indicator and the other half
is used as the mark by the garbage collector.  For instance, a cons cell
consists of three words:

\begin{verbatim}
             
                |----------|-----------| 
                |  `CONS'  |  mark-bit |
                |----------|-----------| 
                |      car-pointer     |
                |----------------------| 
                |      cdr-pointer     |
                |----------------------| 
\end{verbatim}

\noindent and a fixnum cell consists of two words:

\begin{verbatim}
                |----------|-----------| 
                | 'FIXNUM' |  mark-bit |
                |----------|-----------| 
                |    fixnum-value      |
                |----------------------|
\end{verbatim}

\noindent Array headers and compiled-function headers are represented
in this way, and array elements and compiled code are placed
elsewhere.

\medskip

\noindent Internally in compiled functions, certain Lisp objects may
be represented simply by their values.  For example, a fixnum object
may be represented by its fixnum value, and a character object may be
represented by its character code.

\medskip

\noindent Cells of small fixnums ranging from -1024 to 1023 and cells
of characters are pre-allocated in fixed locations.  Thus, for
example,

\vspace{.1in}
 
\centerline{\tt	(eq 1023 1023)}

\vspace{.1in}
 
\noindent yields  t , whereas
 
\vspace{.1in}

\centerline{\tt	(eq 1024 1024)}
 
\vspace{.1in}

\noindent yields  nil.

\vspace{.1in}

\noindent {\large\bf The heap is divided into pages.}\\

\medskip

\noindent The whole heap of KCL is divided into pages (1 page = 2048
bytes).  Each page falls in one of the following classes:

\begin{description}
\item[*] pages that contain cells consisting of the same number of words
\item[*] pages that contain binary data such as compiled function code
\item[*] pages that contain relocatable data such as array elements
\end{description}

\noindent Free cells (i.e., those cells that are not used any more)
consisting of the same number of words are linked together to form a
free list.  When a new cell is requested, the first cell in the free
list (if it is not empty) is used and is removed from the list.  If
the free list is empty, then the garbage collector begins to run to
collect unused cells.  If the new free list is too short after the
garbage collection, then new pages are allocated dynamically.  Free
binary data are also linked together in the order of the size so that,
when a binary datum is being allocated on the heap, the smallest free
area that is large enough to hold the binary datum will be used.  Cell
pages are never compactified.  Once a page is allocated for cells with
{\tt n} words, the page is used for cells with n words only, even
after all the cells in the page become garbage.  The same rule holds
for binary pages.  In contrast, relocatable pages are sometimes
compactified.  That is, each relocatable datum may be moved to another
place.

\medskip

\noindent The actual configuration of the KCL heap is:

\vspace{.1in}

\centerline{\tt lower address \hspace*{3in}{}higher address}

\medskip

\centerline{\fbox{\tt cell pages and binary pages}  {\tt  hole } \fbox{\tt relocatable pages}}

\vspace{.1in}

\noindent There is a ``hole'' between the area for cell/binary pages and the area for
relocatable pages.  New pages are allocated in the hole for cell/binary pages,
whereas new relocatable pages are allocated by expanding the
heap to the higher address, i.e., to the right in this figure.  When
the hole becomes empty, the area for relocatable pages are shifted to the
right to reserve a certain number of pages as the hole.  During this process,
the relocatable data in the relocatable pages are compactified.  No free
list is maintained for relocatable data.

\medskip

\noindent Symbol print names and string bodies are usually allocated in relocatable
pages.  However, when the KCL system is created, i.e., when the object module
of KCL is created, such relocatable data are moved towards the area for
cell/binary pages and then the pages for relocatable data are
marked ``static''.  The garbage collector never tries to sweep static
pages.  Thus, within the object module of KCL, the heap looks like:
\vspace{.1in}

\centerline{\tt lower address \hspace*{3in}{}higher address}

\centerline{\fbox{\tt cell/binary pages and static pages}}

\vspace{.1in}

\noindent Notice that the hole is not included in the object module; it is allocated
only when the KCL system is started.  This saves secondary storage
a little bit.  The maximum size of the hole is about
100 pages (= 200 Kbytes).

\vspace{.1in}

\noindent {\large\bf KCL uses five stacks.}\\

\medskip

\noindent KCL uses the following stacks.

\begin{description}
\item[*] Value Stack, for
	     arguments/values passing
	     lexical variables allocation
	     temporary values saving

\item[*] Frame Stack, consisting of
	     catch, block, tagbody frames

\item[*] Bind Stack, for
	     shallow binding of dynamic variables

\item[*] Invocation History Stack, maintaining
	     information for debugging

\item[*] C Language Control Stack, sometimes used in compiled functions for:
	     arguments/values passing
	     typed lexical variables allocation
	     temporary values saving,
	  in addition to the obvious use such as function invocation
\end{description}

\noindent {\large\bf Arguments/values are passed via the value stack.}\\
 
\medskip

\noindent To show the argument/value passing mechanism, here we list the actual code
for the Common Lisp function  cons .

\begin{verbatim}
     Lcons()
     {
           object x;
           check_arg(2);
           x = alloc_object(t_cons);
           x->c.c_car = vs_base[0];
           x->c.c_cdr = vs_base[1];
           vs_base[0] = x;
           vs_pop;
     }
\end{verbatim}

\noindent We adopted the convention that the name of a function that
implements a Common Lisp function begins with ` L ', followed by the
name of the Common Lisp function.  (Strictly speaking, `{\tt -}' and `
$\ast$ ' in the Common Lisp function name are replaced by `{\tt \_}' and ` A
', respectively, to obey the syntax of C.)  Arguments to functions are
pushed on the value stack.  The stack pointer
{\tt vs\_base}  (value stack base) points to the first argument and
another pointer  {\tt vs\_top}  points to the stack location next to the
last argument.  Thus, for example, when  cons  is called
with the first argument  1  and the second argument  2 , 
the value stack looks like:

\begin{verbatim}
          |---------|
 vs_top ->|         |
          |---------| 
          |    2    |
          |---------| 
vs_base ->|    1    |
          |---------| 
          |         |
          :         :
          |         |
   bottom |---------| 
          value stack
\end{verbatim}

\noindent check\_arg(2) in the code of Lcons checks if exactly two
arguments are supplied to cons .  That is, it checks whether the
difference of vs\_top and vs\_base is 2 , and if not, it causes an
error.  allocate\_object(t\_cons) allocates a cons cell in the heap
and returns the pointer to the cell.  After the
{\tt car}  and the  {\tt cdr}  fields of the cell are set,
the cell pointer is put onto the value
stack.  The two stack pointers are used also on return from a function
call.   vs\_base  points to the first returned value
and  vs\_top  points to the stack location next
to the last returned value.   vs\_pop 
in the code above decrements  vs\_top  by one.

\begin{verbatim}
          |---------| 
          |         |
          |---------| 
 vs_top ->|         |
          |---------| 
vs_base ->| (1 . 2) |
          |---------| 
          |         |
          :         :
          |         |
   bottom |---------| 
          value stack
\end{verbatim}

\noindent Because the same stack pointers are used both for argument passing and
for return value passing, the Common Lisp function  values  does
almost nothing.

\begin{verbatim}
On the call of (values 1 2)    On return from (values 1 2)

          |---------|                |---------| 
 vs_top ->|         |       vs_top ->|         |
          |---------|                |---------| 
          |    2    |                |    2    |
          |---------|                |---------| 
vs_base ->|    1    |      vs_base ->|    1    |
          |---------|                |---------| 
          |         |                |         |
          :         :                :         :
          |         |                |         |
   bottom |---------|         bottom |---------| 
          value stack                 value stack
\end{verbatim}

\noindent In most cases, the caller of a function uses only the first returned value
which is pointed to by  vs\_base .  This is not the case, however, when
the called function returns no value at all.  In order to avoid the check
whether this is the case, each KCL function, on return from its call,
sets  nil  to the stack entry which is pointed to
by  vs\_base , whenever it returns no value at all.  Thus, for
instance, the actual code for the Common Lisp function  values  is:

\begin{verbatim}
     Lvalues()
     {
             vs_top[0] = Cnil;
     }
\end{verbatim}

\noindent where {\tt Cnil} is a global variable that always contains
the pointer to {\tt nil}.  See why this works.

\vspace{.1in}

\noindent {\large\bf The interpreter uses A-lists.}\\

\medskip

\noindent The KCL interpreter uses three A-lists (Association lists) to represent
lexical environments.

\begin{description}
\item[*] One for variable bindings
\item[*] One for local function/macro definitions
\item[*] One for tag/block bindings
\end{description}

\noindent When a function closure is created, the current three A-lists are
saved in the closure along with the lambda expression.  Later, when the
closure is invoked, the saved A-lists are
used to recover the lexical environment.

\medskip

\noindent {\large\bf The invocation history stack is used for debugging.}\\
 
\noindent The invocation history stack consists of two kinds of elements.  Each element
may be either a pair of a Lisp form and a pointer to lexical environment:

\vspace{.1in}

\centerline{\fbox{\tt \hspace*{.5in}{}form \hspace*{.5in}{} |
environment-pointer}}

\vspace{.1in}
 
\noindent or a pair of a function name and a pointer to the value stack:

\vspace{.1in}

\centerline{\fbox{\tt \hspace*{.2in}{}function-name \hspace*{.2in}{} |
value-stack-pointer}}

\vspace{.1in}

\noindent The former is pushed on the invocation history stack
when an interpreted code is evaluated.  The  {\it form} 
is the interpreted code itself and the  {\it environment-pointer}  points to
the three consecutive memory words each of which holds the A-list that
represents the lexical environment.  The latter is pushed
when a compiled function is invoked.  The  {\it function-name} 
is the name of the called function and the  {\it value-stack-pointer} 
points to the value stack location which is pointed to by  vs\_base 
when the function is called.  For both kinds, the element on the invocation
history stack is poped at the end of the evaluation.

\medskip

\noindent Let us see how the invocation history stack is used for debugging.

\begin{verbatim}
>(defun fact (x)                ;;;  Wrong definition of the 
   (if (= x 0)                  ;;;  factorial function. 
       one                      ;;; one  should be  1 . 
       (* x (fact (1- x)))))
fact 
	
>(fact 3)                       ;;;  Tries  3!
	
Error: The variable ONE is unbound.
Error signalled by IF.
	
Broken at IF.
>>:b                            ;;;  Backtrace. 
Backtrace: eval > fact > if > fact > if > fact > if > fact > IF
                                ;;;  Currently at the last  if.
>>:h                            ;;;  Help. 

:c(urrent)              Show current function.
:p(revious)             Move to previous function.
:n(ext)                 Move to next function.
:b(acktrace)            Backtrace.
:h(elp)                 Help.
:q(uit)                 Return to top-level.
:r(esume)               Return to the caller
:l(ocal)                Show n-th local value.
:v(ariables)            Show local variables.
:functions              Show local functions.
:blocks                 Show block names.
:tags                   Show tags.
:hide                   Hide a function
:hide-package           Hide a package.
:unhide                 Unhide a function
:unhide-package	        Unhide a package.

>>:p                        ;;;  Move to the last call of  fact.
Broken at FACT.
	
>>:b
Backtrace: eval > fact > if > fact > if > fact > if > FACT > if
                            ;;;  Now at the last  fact.
>>:v                        ;;;  The environment at the last call 
Local variables: x.         ;;;  to  fact  is recovered. 
                            ;;; x  is the only bound variable. 
>>x
0                           ;;;  The value of  x  is  0.
	
>>:blocks
Block names: fact.          ;;;  The block  fact  is established. 
	
>>(return-from fact 1)      ;;;  Return from the last call of 
6                           ;;; fact  with the value of  0.
                            ;;;  The execution is resumed and 
>                           ;;;  the value  6  is returned. 
                            ;;;  Again at the top-level loop. 
\end{verbatim}

\noindent {\large\bf The KCL compiler generates intermediate code in C.}\\
 
\medskip

\noindent The KCL compiler is essentially a translator from Common Lisp to C.  Given
a Lisp source file, the compiler first generates three intermediate files:

\begin{description}
\item[*] a C-file which consists of the C version of the Lisp program
\item[*] an H-file which consists of declarations referenced in the C-file
\item[*] a Data-file which consists of Lisp data to be used at load time
\end{description}

\noindent The KCL compiler then invokes the C compiler to compile the C-file into
an object file.  Finally, the contents of the Data-file is appended to
the object file to make a  {\it Fasl-file}.  The generated Fasl-file can
be loaded into the KCL system by the Common Lisp
function  {\tt load}.  By default, the three intermediate files
are deleted after the compilation, but, if asked, the compiler
leaves them.

\medskip

\noindent The merits of the use of C as the intermediate language are:

\begin{description}
\item[*]  The KCL compiler is highly portable.  Indeed the four versions
of KCL share the same compiler.  Only the calling sequence
of the C compiler and the handling of the intermediate files are different
in these versions. 

\item[*]  Cross compilation is possible, because the contents
of the intermediate files are common to all versions of KCL.  For example,
one can compile his or her Lisp program by the KCL compiler on Eclipse,
bring the intermediate files to SUN, compile the C-file with the C compiler
on SUN, and then append the Data-file
to the object file.  This procedure generates the Fasl-file for
the KCL system on SUN.  This kind of cross compilation makes it easier to
port KCL. 

\item[*]  Hardware-dependent optimizations such as register allocations
are done by the C compiler. 
\end{description}

\medskip

\noindent The demerits are:

\begin{description}
\item[*]  At those sites where no C compiler is available,
the users cannot compile their Lisp programs. 

\item[*]  The compilation time is long.  70\% to 80\%
of the compilation time is used by the C compiler.  The KCL compiler is
perhaps the slowest compiler in the Lisp world. 
\end{description}

\noindent {\large\bf The compiler mimics human C programmer.}\\
 
\medskip

\noindent The format of the intermediate C code generated by the KCL compiler is the
same as the hand-coded C code of the KCL source programs.  For example,
supposing that the Lisp source file contains the
following function definition:

\begin{verbatim} 
            (defun add1 (x) (1+ x))
\end{verbatim}

\noindent The compiler generates the following intermediate C code.

\begin{verbatim}
     init_code(start,size,data)char *start;int size;object data;
     {      register object *base=vs_top;
            register object *sup=base+VM2;
            vs_check;
            Cstart=start;Csize=size;Cdata=data;
            set_VV(VV,VM1,data);
            MF(VV[0],L1,start,size,data);
            vs_top=vs_base=base;
     }
     /*     function definition for ADD1     */
	
     static L1()
     {      register object *base=vs_base;
            register object *sup=base+VM3;
            vs_reserve(VM3);
            check_arg(1);
            vs_top=sup;
            base[1]=one_plus(base[0]);
            vs_top=(vs_base=base+1)+1;
            return;
     }
\end{verbatim}

\noindent The C function {\tt L1}  implements the Lisp
function {\tt add1}.  This relation is established by  MF  in
the initialization function  init\_code , which is invoked at
load time.  There,
the vector {\tt VV}  consists of Lisp objects; {\tt VV[0]}  in this
example holds the Lisp symbol {\tt add1}.  {\tt VM3}  in the definition
of {\tt L1}  is a C macro declared in the corresponding H-file.  The actual
value of  VM3  is the number of value stack locations used
by {\tt L1}, i.e.,  2  in this example.  Thus the following
macro definition is found in the H-file.

\begin{verbatim}
         #define VM3 2\\
\end{verbatim}

\noindent When the compiled  add1  is called, the value stack looks like:

\begin{verbatim}
    On the call of (add1 1)    On return from (add1 1)

              |---------|                 |---------| 
              |         |       vs_top -> |         |
              |---------|                 |---------| 
     vs_top ->|         |       vs_base ->|    2    |
              |---------|                 |---------| 
    vs_base ->|    1    |                 |    1    |
              |---------|                 |---------| 
              |         |                 |         |
              :         :                 :         :
              |         |                 |         |
       bottom |---------|          bottom |---------|
              value stack                 value stack
\end{verbatim}

\noindent Note that the two value stack pointers need not be moved
in this example.  This shows that the KCL compiler still has room
for improvement.

\vspace{.1in}

\noindent {\large\bf Lexical environment of compiled closures is represented by a 
list.}\\
 
\medskip

\noindent The KCL compiler takes two passes before it invokes the C
compiler.  The major role of the first pass is to detect function
closures and to detect, for each function closure, those lexical
objects (i.e., lexical variable, local function definitions, tas, and
block-names) to be enclosed within the closure.  This check must be
done before the C code generation in the second pass, because lexical
objects to be enclosed in function closures are treated in a different
way from those not enclosed.

\medskip

\noindent Ordinarily, lexical variables in a compiled function {\it f} 
are allocated on the value stack.  However, if a lexical variable
is to be enclosed in function closures, it is allocated on a list,
called the "environment list", which is local to {\it f}.  In addition,
one entity is reserved on the value stack, 
in which the pointer to the variable's location (within the environment list)
is stored, so that the variable may be accessed by indexing
rather than by list traversal.  The environment list is
a pushdown list:  It is empty when {\it f}  is called.  An
element is pushed on the environment list
when a variable to be enclosed in closures is bound, and is popped
when the binding is no more in effect.  That is, at any moment during
execution of {\it f}, the environment list contains
those lexical variables whose
binding is still in effect and which should be enclosed in closures.  When
a compiled closure is created during execution of {\it f}, 
the compiled code for the closure is coupled with the environment list at that
moment to form the compiled closure.  Later, when the compiled closure is
invoked, as many entities as the elements in the environment list is
reserved on the value stack, each of which points to a lexical object in the
environment list, so that, again, each object may be referenced by indexing.

\medskip

\noindent Let us see an example.  Suppose the following function has been compiled.

\begin{verbatim}
    (defun foo (x)
        (let ((a \#'(lambda () (incf x)))
              (y x))
          (values a \#'(lambda () (incf x y)))))
\end{verbatim} 

\noindent {\tt foo}  returns two compiled closures.  The first closure increments
{\tt x}  by one, whereas the second closure increments {\tt x} 
by the initial value of {\tt x}.  Both closures return the incremented
value of {\tt x}.

\begin{verbatim} 
        >(multiple-value-setq (f g) (foo 10))
        \#<compiled-closure nil>

        >(funcall f)
        11

        >(funcall g)
        21

        >
\end{verbatim}

\noindent After this, the two compiled closures look like:

\begin{verbatim}
second closure       y:                     x:
|-------|------|      |-------|------|       |------|------| 
|  **   |    --|----->|  10   |    --|------>|  21  | nil  |
|-------|------|      |-------|------|       |------|------| 
                                                ^
                      first closure             |
                      |-------|------|          |
                      |   *   |    --|----------| 
                      |-------|------| 

 * : address of the compiled code for #'(lambda () (incf x))
** : address of the compiled code for #'(lambda () (incf x y))
\end{verbatim}

\noindent {\large\bf Declarations increase code efficiency.}\\
 
\medskip

\noindent Declarations, especially  type  and  function  declarations,
increase the efficiency of the compiled code.  For example, for the
following Lisp source file, with two Common Lisp declarations added,

\begin{verbatim}
   (eval-when (compile)
     (proclaim '(function tak (fixnum fixnum fixnum) fixnum))

   (defun tak (x y z)
     (declare (fixnum x y z))
     (if (not (< y x))
         z
         (tak (tak (1- x) y z)
              (tak (1- y) z x)
              (tak (1- z) x y))))
\end{verbatim}

\noindent the compiler generates the following C code.

\begin{verbatim}
     /*  local entry for function TAK  */
     static int LI2(V4,V5,V6)
     int V4,V5,V6;
     {      VMB3 VMS3 VMV3
            if((V5)<(V4)){
            goto T4;}
            VMR3(V6)
     T4:;
            {int V7=LI2((V4)-1,V5,V6);
            {int V8=LI2((V5)-1,V6,V4);
            VMR3(LI2(V7,V8,LI2((V6)-1,V4,V5)))}}
     }
     /*  global entry for the function TAK  */
     static L2()
     {      register object *base=vs_base;
            base[0]=make_fixnum(LI2(fix(base[0]),
                                    fix(base[1]),
                                    fix(base[2])));
            vs_base=base; vs_top=base+1;
     }
\end{verbatim}
 
\noindent The main part of the  tak  function is  LI2 .  If
redundant parentheses are removed, macros are expanded, and
identifiers are renamed, we obtain the following code equivalent
to  LI2 .

\begin{verbatim}
     /*  local entry for function TAK  */
     static int tak(x,y,z)
     int x,y,z;
     {
                       if(y<x) goto L;
                       return(z);
     L:
                       {      int t1=tak(x-1,y,z);
                              int t2=tak(y-1,z,x);
                              return(tak(t1,t2,tak(z-1,x,y)));
                       }
     }
\end{verbatim}

\noindent This is almost hand-written {\tt tak}  code in C.  The only overhead is
the use of the temporary variables {\tt t1}  and {\tt t2}.  This is
necessary to make sure that the arguments are evaluated
in the correct order (i.e., from left to right), since the
C language does not specify the order of argument evaluation.  If the
compiler generated the following code,

\begin{verbatim}
     return(tak(tak(x-1,y,z),tak(y-1,z,x),tak(z-1,x,y)));
\end{verbatim} 

\noindent the C compiler of Eclipse AOS/VS evaluates the three inner calls
to  tak  from left to right (this is all right),
whereas the C compiler of Unix evaluates from
right to left (this is bad).  In this example of  tak ,
the order of evaluation
does not matter actually, because  tak  causes no side effects.  But
the KCL compiler does not know that.  The KCL compiler still has room
for improvements.

\vspace{.1in}

\noindent {\large\bf KCL does not have ``disassembler''.}\\

\medskip

\noindent Common Lisp defines a function  disassemble , which is supposed to
disassemble a compiled function and
to display the assembler code.  According to the  {\it Common Lisp
Reference Manual},

\vspace{.1in}

     {\it This is primary useful for debugging the compiler}, ..\\
 
\medskip

\noindent This is, however,  {\it useless} in our case, because we are not concerned
with assembly language.  Rather, we are interested in the C code generated by
the KCL compiler.  Thus the  disassemble  function in KCL accepts
not-yet-compiled functions only and displays the translated C code.

\begin{verbatim}
  >(defun add1 (x) (1+ x))
  add1

  >(disassemble 'add1)
  init_code(start,size,data)char *start;int size;object data;
  {       register object *base=vs_top;
          register object *sup=base+VM2;
          vs_check;
          Cstart=start;Csize=size;Cdata=data;set_VV(VV,VM1,data);
          MF(VV[0],L1,start,size,data);
          vs_top=vs_base=base;
  }
  /*      function definition for ADD1    */
	
  static L1()
  {       register object *base=vs_base;
          register object *sup=base+VM3;
          vs_check;
          vs_top=sup;
          base[1]=one_plus(base[0]);
          vs_top=(vs_base=base+1)+1;
          return;
  }
	
  >
 \end{verbatim}

\noindent {\large\bf KCL/AOS has its own screen editor.}\\
 
\medskip

\noindent KCL/AOS has an embedded full-screen editor which resembles EMACS.  The editor
is called FeCl2 as the acronym of Full-screen Editor as a Common Lisp
TOOl.  It is invoked by the Common Lisp function {\tt ed}.  Unfortunately,
FeCl2 is not supported by other versions of KCL, simply because we are
too lazy to port it (it is written in C).  For these versions, {\tt ed} 
invokes the  {\tt vi}  editor of Unix.

\vspace{.1in}

\noindent {\large\bf KCL has C language interface.}\\
 
\medskip

\noindent The user can embed his or her own C code into Lisp source code.  The
idea is very simple:  The specified C code is inserted in the intermediate
C code that is generated by the KCL compiler.  In the following example,
{\tt Clines}  and  {\tt defentry}  are top-level macros specific
to KCL.  The  {\tt Clines}  macro form specifies the C code to be embedded,
in terms of strings, and the  {\tt defentry}  form defines an entry
of the specified C function from KCL.

\begin{verbatim}
    (Clines
    "   int tak(x, y, z)                       "
    "   int x, y, z;                           "
    "   {   if (y >= x) return(z);             "
    "       else return(tak(tak(x-1, y, z),    "
    "                       tak(y-1, z, x),    "
    "                       tak(z-1, x, y)));  "
    "   }                                      "
    )

    (defentry tak (int int int) (int "tak"))
\end{verbatim}

\noindent {\large\bf Port to VAX took three days.}\\
 
\medskip

\noindent Although KCL is made to be highly portable, certain minor changes had to
be done, when it was ported to VAX Unix 4.2 bsd.  These changes include:

\begin{enumerate}
\item The compiler top-level was slightly changed, because of
the differences of the calling sequence of the C compiler and of the handling
of object files. 

\item File system interface was changed to fit Unix 4.2 bsd. 

\item The following system parameters were redefined because
Vax's representation of floating point numbers differs from that of Eclipse.
\begin{verbatim} 
		most-positive-short-float
		most-negative-short-float
		least-positive-short-float
		least-negative-short-float
		most-positive-long-float
		most-positive-double-float
		most-positive-single-float
		most-negative-long-float
		most-negative-double-float
		most-negative-single-float
		least-positive-long-float
		least-positive-double-float
		least-positive-single-float
		least-negative-long-float
		least-negative-double-float
		least-negative-single-float
		short-float-epsilon
		short-float-negative-epsilon
		long-float-epsilon
		double-float-epsilon
		single-float-epsilon
		long-float-negative-epsilon
		double-float-negative-epsilon
		single-float-negative-epsilon
\end{verbatim}
\item For the same reason as above, the following machine-dependent
Common Lisp functions were rewritten.
\begin{verbatim} 
		decode-float
		scale-float
		float-radix
		float-digits
		float-precision
		integer-decode-float
\end{verbatim}
\item The three assembler routines were rewritten.

\item The in-core loader that loads Fasl-files into the KCL memory was
changed.  This was a simple job because we used the standard linkage
editor {\tt ld}  of Unix. 

\item The memory dump routine was rewritten.
\end{enumerate}

\noindent The whole job of poring KCL to VAX Unix 4.2 bsd took three days.  Later,
we spent some more days,
to fix bugs in the ported version of KCL.

\vspace{.1in}

\noindent {\large\bf Port to SUN took three evenings.}\\
 
\medskip

\noindent The port to the SUN Workstation was much easier than the port to the VAX, mainly because the
operating system is the same for both VAX and SUN.
\begin{enumerate}
\item The compiler top-level of KCL/VAX was used without changes.

\item The file system of KCL/VAX was used without changes.

\item The system parameters that depend on the representation of
floating point numbers were rewritten. 

\item The Common Lisp functions that depend on the representation of
floating point numbers were redefined. 

\item The three assembler routines were rewritten.

\item The in-core loader of KCL/VAX was used without changes.

\item The memory dump routines of KCL/VAX was used without changes.
\end{enumerate}

\noindent The whole job of poring KCL to SUN took three evenings.  Most of
the time was spent for the three assembler routines, because we did not know
anything about the MC68000 assembler at first.

\vspace{.1in}

\noindent {\large\bf Port to Ustation took one week.}\\
 
\medskip

\noindent The port to the Ustation was relatively a hard job.  It took almost a week.  
The major difficulity was that
the C compiler of Unix V on the Ustation recognized identifiers only by
the first seven characters.  As already mentioned, we used the convention that
the C function that implements the Common Lisp
function {\it function-name}  is given
the name  {\tt L} {\it function-name} .  Thus, for example, the Common Lisp functions on packages such as

\begin{verbatim} 
     package-name
     package-nickname
     package-shadowing-symbols
     package-use-list
     package-used-by-list
     packagep
\end{verbatim}

\noindent are implemented by the C functions whose names all begin
with  Lpackage .  These C functions are regarded
as having the same name by the
C compiler.  This problem was solved by preparing a preprocessor program which
maps long identifiers into smaller ones.  This program is now used by the KCL
compiler on Ustation before the C compiler is called.

\vspace{.1in}

\noindent {\large\bf KCL is relatively compact.}\\
 
\medskip

\noindent The size of the object module of the whole KCL system (including the Compiler)
is
\begin{verbatim}
     KCL/AOS      1.78 Mbytes
     KCL/VAX      1.45 Mbytes
     KCL/SUN      1.56 Mbytes
     KCL/UST      1.56 Mbytes
\end{verbatim}

\noindent Since all system initialization (such as loading the database of the KCL
compiler) has been done when the object module is created, the object module
size roughly corresponds to the initial size of the KCL process when
a KCL session is started, minus the initial size of the hole
in the heap (about 200 Kbytes).

\vspace{.1in}

\noindent {\large\bf Gabriel's benchmark.}\\
 
\medskip

\noindent The following table shows the results of Richard Gabriel's Lisp benchmark
tests with the four versions of KCL.  The results with
five other Common Lisp systems are also listed for comparison.  Each
number represents the CPU time (in seconds) for the
compiled program.  ` * ' indicates that the time
includes garbage-collection time.  The data of S-1 Lisp and Spice Lisp are
found in:

\vspace{.1in}

\centerline{\it Performance and Evaluation of Lisp Systems}
\centerline{\it by}
\centerline{Richard P. Gabriel}
\centerline{Computer Systems Ser. Research Reports,}
\centerline {MIT Press, 1985}

\vspace{.1in}

\noindent We received the data of Symbolics, DEC Common Lisp, and DG Common Lisp
directly from Dr. Richard Gabriel in April 1985.  We measured the
data for KCL in July 1985.  For the details of the benchmark
tests, refer to the book above.

\medskip

\begin{tabular}{|l|l|l|l|l|l|} \hline
Benchmark &   Boyer  &  Browse  & Destruct & Traverse & Traverse \\
  Test    &          &          &          &Initialize&    Run   \\ \hline

 Kyoto CL &   11.02  &   18.09  &    3.15  &    5.75  &   44.16  \\
  MV10000 &          &          &          &          &          \\
                                                          
 Kyoto CL &   43.73  &   68.15* &    8.00  &   14.42  &  151.20  \\
  VAX 780 &          &          &          &          &          \\
                                                            
 Kyoto CL &   43.60* &   73.08* &   10.23  &   20.38  &  118.60  \\
   E15    &          &          &          &          &          \\
                                                            
 Kyoto CL &   47.00  &   81.37  &   14.10  &   26.30  &  160.58  \\
   SUN    &          &          &          &          &          \\
                                                            
Symbolics &   11.99  &   30.8   &    3.03  &    8.62  &   49.95  \\
   3600   &          &          &          &          &          \\
                                                            
  S-1 CL  &   10.03  &   10.2   &    0.91  &    1.93  &   30.1   \\
 Mark IIA &          &          &          &          &          \\
                                                            
  Spice   &  134.79  &  359.63  &   17.78  &   41.75  &  490.6   \\
   Perq   &          &          &          &          &          \\
               
  DEC CL  &   46.79  &  118.51  &    6.38  &   20.76  &  161.68  \\
  VAX 780 &          &          &          &          &          \\

   DG CL  &   29.3   &   59.91  &    6.95  &   27.77  &   45.86  \\
  MV10000 &          &          &          &          &          \\ \hline
\end{tabular}
\newpage  
\begin{tabular}{|l|l|l|l|l|l|} \hline
  Benchmark &    Tak   &   Stak   &   Ctak   &   Takl   &   Takr   \\
    Test    &          &          &          &          &          \\ 
\hline

   Kyoto CL &    0.42  &    1.90  &    4.35  &    5.13  &    0.54  \\
    MV10000 &          &          &          &          &          \\

   Kyoto CL &    1.45  &    6.03  &   14.02  &   19.97  &    1.75  \\
    VAX 780 &          &          &          &          &          \\

   Kyoto CL &    1.17  &    7.63  &    9.58  &   16.10  &    1.38  \\
     E15    &          &          &          &          &          \\

   Kyoto CL &    1.48  &   11.02  &   16.88  &   23.35  &    1.67  \\
     SUN    &          &          &          &          &          \\

  Symbolics &    0.6   &    2.58  &    7.65  &    6.44  &    0.6   \\
     3600   &          &          &          &          &          \\

    S-1 CL  &    0.29  &    4.31  &    0.82  &    2.92  &    0.58  \\
   Mark IIA &          &          &          &          &          \\

    Spice   &    4.7   &   13.5   &    8.4   &   24.0   &    7.7   \\
     Perq   &          &          &          &          &          \\

    DEC CL  &    1.83  &    4.11  &    8.09  &    7.34  &    3.42  \\
    VAX 780 &          &          &          &          &          \\

     DG CL  &    0.89  &    3.09  &    1.79  &    5.52  &    1.21  \\
    MV10000 &          &          &          &          &          \\ 
\hline
\end{tabular}
\newpage
\begin{tabular}{|l|l|l|l|l|l|} \hline
  Benchmark &   Deriv  &  DDeriv  &   Div2   &   Div2   &    FFT   \\
    Test    &          &          & Iterative& Recursive&          \\ 
\hline

   Kyoto CL &    4.85  &    5.93  &    1.99  &    2.73  &    1.55  \\
    MV10000 &          &          &          &          &          \\

   Kyoto CL &   18.98  &   23.07  &    7.48  &   11.25  &    9.07  \\
    VAX 780 &          &          &          &          &          \\

   Kyoto CL &   22.07* &   25.38* &    9.95* &   12.60* &   74.62  \\
     E15    &          &          &          &          &          \\

   Kyoto CL &   20.72  &   24.77  &    9.32  &   12.30  &   94.07  \\
     SUN    &          &          &          &          &          \\

  Symbolics &    5.12  &    5.24  &    1.85  &    2.89  &    4.75  \\
     3600   &          &          &          &          &          \\

    S-1 CL  &    4.99  &    3.27  &    0.82  &    1.49  &    1.44  \\
   Mark IIA &          &          &          &          &          \\

    Spice   &   71.8   &   77.7   &   28.15  &   40.69  &   59.0   \\
     Perq   &          &          &          &          &          \\

    DEC CL  &   13.76  &   ---    &    5.0   &    9.84  &   32.69  \\
    VAX 780 &          &          &          &          &          \\

     DG CL  &    5.6   &    8.11  &    2.8   &    4.48  &   62.78  \\
    MV10000 &          &          &          &          &          \\ 
\hline
\end{tabular}
\newpage
\begin{tabular}{|l|l|l|l|l|l|} \hline
  Benchmark &   Puzzle &  Triang  &  Fprint  &   Fread  &  Tprint  \\
    Test    &          &          &          &          &          \\ 
\hline

   Kyoto CL &    6.76  &  104.85  &    1.98  &    2.45  &    1.74  \\
    MV10000 &          &          &          &          &          \\

   Kyoto CL &   20.57  &  366.12  &    5.73  &    5.77  &    6.55  \\
    VAX 780 &          &          &          &          &          \\

   Kyoto CL &   41.30  &  341.23* &    9.83  &    6.07  &   11.58  \\
     E15    &          &          &          &          &          \\

   Kyoto CL &   49.13  &  499.68  &   10.05  &    7.62  &    8.50  \\
     SUN    &          &          &          &          &          \\

  Symbolics &   13.89  &  151.7   &    2.6   &    4.6   &    4.9   \\
     3600   &          &          &          &          &          \\

    S-1 CL  &    1.82  &   62.06  &   ---    &   ---    &   ---    \\
   Mark IIA &          &          &          &          &          \\

    Spice   &   75.14  & 1488.85  &   20.0   &   26.0   &   22.6   \\
     Perq   &          &          &          &          &          \\

    DEC CL  &   47.48  &  360.85  &    3.94  &    7.24  &    2.85  \\
    VAX 780 &          &          &          &          &          \\

     DG CL  &  138.2   &  151.2   &    2.35  &    4.65  &    2.83  \\
    MV10000 &          &          &          &          &          \\ 
\hline
\end{tabular} 

\newpage

\centerline{\large\bf Appendix C. Kyoto Common Lisp Installation Guide}
 
\vspace{.4in}

\noindent This appendix explains how to install the KCL system, separately for
each version of KCL.

\vspace{.1in}

\noindent {\large\bf C.1. Installation of KCL/AOS}\\

\medskip

\noindent 1. Prepare a directory (hereafter called  {\it KCL directory}) for Kyoto 
Common
Lisp.  In the following examples, we suppose that the KCL directory is
{\tt :UDD:KCL}.

\medskip

\noindent 2. Load the distribution tape to the KCL directory.

\begin{verbatim}
     ) DIR
     :UDD:KCL
     ) LOAD
\end{verbatim}

\noindent You will find that the subdirectory  PORT  has been created.  The  PORT  subdirectory contains everything that is needed to run KCL.  Files in this directory are:

\begin{verbatim} 
   Documents:
       README                  this file

   Executable files:
       KCL.PR                  the KCL interpreter and compiler
       KCL.ST 
       BUILD_FASL.PR           the fasl-file builder
       FECL2.PR                the FeCl2 editor

   Command files:
       KCL.CLI                 to invoke KCL
       LC.CLI                  to invoke the KCL compiler
       LC1.CLI                 to invoke the KCL compiler
       FECL2.CL1               to invoke the FeCl2 editor
 
   Header file:
       CMPINCLUDE.H            the header file for the KCL compiler
 
   Miscellaneous:
       FECL2.CMD               FeCl2 editor command table
\end{verbatim}

\noindent 3. Customize the command files.

\medskip

\noindent The command file  KCL.CLI  consists of the following command lines
to invoke the KCL interpreter.

\begin{verbatim}
     push;prom pop
     sea :usr:dgc [!sea]
     x :udd:[!user]:port:%0-% :udd:[!user]:port:
     pop
\end{verbatim}

\noindent Replace the two occurrences of " [!user] " with the name of the KCL directory
(i.e.,  KCL  in our example).

\begin{verbatim}
     push;prom pop
     sea :usr:dgc [!sea]
     x :udd:KCL:port:%0-% :udd:KCL:port:
     pop
\end{verbatim} 

\noindent And move this file to an appropriate command directory, say  :UTIL,  so
that all KCL users can access it.

\medskip

\noindent If the name of the directory that includes DG's C compiler is not
 :USR:DGC, you should replace it with the appropriate directory name,
so that the KCL compiler can access the C compiler by  CC.PR.

\medskip

\noindent You can use the commands  {\tt LC.CLI}  and  {\tt LC1.CLI}  to invoke the compiler directly
from the CLI.  The content of  {\tt LC.CLI}  is:

\begin{verbatim}
     push
      prompt pop level
      sea :usr:dgc [!sea]
      WRITE Compiling %1%.LSP.
       proc/def/ioc/block/pri=3 \&
       :udd:[!user]:port:kcl :udd:[!user]:port: \%1\% \%1\% U10000
     pop
\end{verbatim}

\noindent Customize these command files in the same way as for the  KCL.CLI  command file
above.

\medskip

\noindent 4. Install the header file

\medskip

\noindent Copy the header file  {\tt CMPINCLUDE.H}  to the standard directory for C include
files, say  {\tt :USR:DGC}.

\vspace{.1in}

\noindent {\large\bf C.2. Installation of KCL/VAX}\\

\medskip

\noindent 1. Prepare a directory (hereafter called  {\it KCL directory}) for Kyoto Common
Lisp.  In the following examples, we suppose that the KCL directory is
{\tt /usr/kcl}.

\medskip

\noindent 2. Load the distribution tape to the KCL directory.

\begin{verbatim}
     % pwd
     usr/kcl
     % tar x
\end{verbatim}

\noindent You will find that the subdirectory  {\tt unixport}  has been created.  The 
{\tt unixport}  subdirectory contains everything that is needed to run KCL and
the KCL compiler.  Files in this directory are:

\begin{verbatim}
  Documents:
     readme          this file
 
  Executable files:
     saved_kcl       the KCL interpreter and compiler

  Command files:
     kcl             to invoke KCL
     lc              to invoke the KCL compiler
     lc1             to invoke the KCL compiler
 
  Header file:
     cmpinclude.h    the header file for the KCL compiler
\end{verbatim}

\noindent 3.  Customize the command files.

\medskip

\noindent The command file  kcl  consists of a single line command to invoke the KCL
interpreter.

\begin{verbatim}
     #
     ~/unixport/saved_kcl ~/unixport/
\end{verbatim}

\noindent Replace two ' ~ 's with the pathname of the KCL directory (i.e.,  /usr/kcl  in our example).

\begin{verbatim}
     #
     /usr/kcl/unixport/saved_kcl /usr/kcl/unixport/
\end{verbatim}

\noindent And move this file to an appropriate command directory, say  {\tt /usr/bin}, so
that all KCL users can access it.

\medskip

\noindent You can use the commands  lc  and  lc1  to invoke the compiler directly from the
shell.  The content of  lc  is:

\begin{verbatim}
     #
     echo Compiling $1.lsp
     ~/unixport/saved_kcl ~/unixport/ $1 $1 U1000
\end{verbatim}

\noindent Customize these command files in the same way as for the kcl
command file above.

\vspace{.1in}

\noindent 4.  Install the header file

\medskip

\noindent Copy the header file  {\tt cmpinclude.h}  to the standard directory for C include
files, say {\tt /usr/include}.

\vspace{.1in}

\noindent {\large\bf C.3. Installation of KCL/SUN}\\

\medskip

\noindent 1.   Prepare a directory (hereafter called  {\it KCL directory}) for Kyoto Common
Lisp.  In the following examples, we suppose that the {\it KCL directory} is
 {\tt /usr/kcl}.

\medskip

\noindent 2.  Load the distribution tape to the KCL directory.

\begin{verbatim}
     % pwd
     /usr/kcl
     % tar x
\end{verbatim}

\noindent You will find that the subdirectory {\tt unixport} has been
created.  The {\tt unixport} subdirectory contains everything that is
needed to run KCL and the KCL compiler.  Files in this directory are:

\begin{verbatim} 
   Documents:
       readme            this file
 
   Executable files:
       saved_kcl         the KCL interpreter and compiler

   Command files:
       kcl               to invoke KCL
       lc                to invoke the KCL compiler
       lc1               to invoke the KCL compiler
 
   Header file:
       cmpinclude.h      the header file for the KCL compiler
\end{verbatim}

\noindent 3.   Customize the command files.

\medskip

\noindent The command file  {\tt kcl}  consists of a single line command to invoke the KCL
interpreter.

\begin{verbatim}
     #
     ~/unixport/saved_kcl ~/unixport/
\end{verbatim}

\noindent Replace two ` ~ 's with the pathname of the KCL directory (i.e.,  /usr/kcl  in
our example).
  
\begin{verbatim}
     #
     /usr/kcl/unixport/saved_kcl /usr/kcl/unixport/
\end{verbatim}

\noindent And move this file to an appropriate command directory, say {\tt /usr/bin}, so
that all KCL users can access it.

\medskip

\noindent You can use the commands lc and lc1 to invoke the compiler directly from the
shell.  The content of lc is:

\begin{verbatim}
     #
     echo Compiling $1.lsp
     ~/unixport/saved_kcl ~/unixport/ $1 $1 U1000
\end{verbatim}

\noindent Customize these command files in the same way as for the kcl command file
above.

\vspace{.1in}

\noindent 4.   Install the header file

\medskip

\noindent Copy the header file {\tt cmpinclude.h}  to the standard directory for C include
files, say  {\tt /usr/include}.

\vspace{.1in}

\noindent {\large\bf C.4. Installation of KCL/UST}\\
 
\medskip

\noindent 1.   Prepare a directory (hereafter called  {\it KCL directory} ) for Kyoto Common
Lisp.  In the following examples, we suppose that the KCL directory is
{\tt /usr/kcl}.

\medskip

\noindent 2.   Three floppy disks are used for the distribution.  Load the floppy disks
to the KCL directory by the multi-volume option of the tar command.  (Insert
the first disk to the drive and issue the tar command.  Then, you will be
prompted to change the disks.)

\begin{verbatim} 
     % pwd
     /usr/kcl
     % tar xvfBM /dev/rdy0g 1976
\end{verbatim}

\noindent You will find that the subdirectory  {\tt unixport}  has been created.  The
{\tt  unixport}  subdirectory contains everything that is needed to run KCL and
the KCL compiler.  Files in this directory are:

\begin{verbatim}
   Documents:
       readme             this file

   Executable files:
       saved_kcl          the KCL interpreter and compiler
       ild                incremental loader
       trans              translator from Unix 4.2 to Unix V

   Command Source files:
       kcl.c              to invoke KCL
       lc.c               to invoke the KCL compiler
       lc1.c              to invoke the KCL compiler
 
   Header file:
       cmpinclude.h       the header file for the KCL compiler
\end{verbatim}

\noindent 3.   Customize the command files.

\medskip

\noindent The source file  {\tt kcl.c}  consists of a C-language program to invoke the KCL
interpreter.  Replace all  {\tt /usr/ukcl}  in this file with the pathname of the KCL directory
(i.e.,  {\tt /usr/kcl}  in our example), and compile this file.

\begin{verbatim}
     % cc -o kcl kcl.c
\end{verbatim}

\noindent And move the object file to an appropriate command directory, say  {\tt/usr/bin} ,
so that all KCL users can access it.

\medskip

\noindent You can use the source files  {\tt lc.c}  and {\tt lc1.c}  to invoke the compiler directly
from the shell.  Customize these source files in the same way as for the kcl command file above.

\vspace{.1in}

\noindent 4.   Install the header file

\medskip

\noindent Copy the header file  {\tt cmpinclude.h}  to the standard directory for C include
files, say {\tt /usr/include}.


\end{document}





