
\(progn

  (defmacro set-page (name) `(setq ,name *page-number*))
  (defun date ()
    (multiple-value-bind (sec min hour date month year) (get-decoded-time)
      (do-string
	(format nil
                "~[January~;February~;March~;April~;May~;June~;July~;~
		   August~;September~;October~;November~;December~] ~
                 ~d, ~d"
		(1- month)
                date
                year))))
  (defun fr () (setq *current-font* *font-roman*))
  (defun fi () (setq *current-font* *font-italic*))
  (defun fs () (setq *current-font* *font-symbol*))
  (defun fp () (setq *current-font* *font-prop*))
  (defun fg () (setq *current-font* *font-big*))
  (defun sm () (setq *old-left-margin* *left-margin*)
	       (setq *left-margin* (+ (mark-column) *left-margin*)))
  (defun rm () (do-line-so-far) (setq *left-margin* *old-left-margin*))
  (defun ra () (right-adjust))
  (defun ce () (centering))
  (defun br () (break-line))
  (defun lm (n) (setq *left-margin* n))
  (defun bd () (setq *left-margin* 100))
  (defun endd () (do-line-so-far) (setq *left-margin* 0))
  (defun reserve (n)
                 (do-line-so-far)
                 (when (< *bottom-hight*
			  (* (1+ n)
			     (+ (font-ils *font-prop*)
				(font-hight *font-prop*))))
		       (do-page)))
)














\(fg) 
\(ce)Kyoto Common Lisp Report
\(fr)








\(ce)Taiichi Yuasa and Masami Hagiya

\(ce)Research Institute for Mathematical Sciences, Kyoto University


\(fg) 

\(ce)Preface
\(set-page pp-preface)
\(fr)
Kyoto Common Lisp (KCL for short) is a full
implementation of the Common Lisp language described in
the \(fi)Common Lisp Reference Manual\(fr):


\(ce)\(fi)Common Lisp: The Language\(fr).
\(ce)by Guy L. Steele et al.
\(ce)Digital Press, 1984

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 \(fi)Common Lisp
Reference Manual\(fr).  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 \(fi)Common Lisp Reference Manual\(fr) and if this report
does not describe the difference explicitly, then there must be a bug in
KCL.  All Common Lisp variables and constants are
defined in KCL exactly as described in the \(fi)Common Lisp Reference Manual\(fr).

     Currently, there are four major versions of KCL:

	1. \(sm)KCL/AOS, under the AOS/VS operating system for Data General's ECLIPSE MV series machines.\(rm)

	2. \(sm)KCL/VAX, under the Unix 4.2 bsd operating system for Digital Equipment Corporation's VAX 11 series machines.\(rm)

	3. \(sm)KCL/SUN, under the Unix 4.2 bsd operating system for Sun Microsystems' Sun Workstation.\(rm)

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

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.  The other three
versions, which are collectively called \(fi)KCL on Unix\(fr),
are transplanted versions of KCL/AOS.

     This report is intended to complement the \(fi)Common Lisp Reference
Manual\(fr).  This report describes deviations of KCL from Common Lisp,
those features specific to KCL,
and the implementation-dependent functions of Common Lisp.
\(fg)

\(ce)Acknowledgements
\(set-page pp-acknowledgements)
\(fr)
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 project of KCL.

     First of all, we are grateful to the contributors of 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.  The benchmark tests are indebted to Dr. Richard Gabriel at Stanford
University.
     Dr. Daniel Weinreb at Symbolics solved most of our questions about the
language specification.  He also sent us the definition
of \(fp)rationalize\(ri 'rationalize)\(fr) 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 advices to improve 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 many
advises concerning with 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 onto 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 advises from people at Hagiwara Laboratory.
     Prof. Shuji Doshita at Kyoto University offered the SUN Workstation at
his Laboratory and gave us
a lot of advises for transplantation to SUN Workstation.
     Mr. Takashi Hattori at RIMS gave us useful information about Motorola
68000, the CPU chip of SUN Workstation.

     NDG helped us build up the KROFF (\(fi)K\(fr)yoto \(fi)ROFF\(fr))
system, with which this report was produced.  They offered the character
font sets from
which the font sets used in KROFF were constructed.  We also received some
technical
advises from NDG about the output devise of KROFF, i.e., NDG's 5880 series
laser beam
printers.  Incidentally, all the programs that constitute the KROFF system,
including tools
to maintain KROFF font sets, are written in the Common Lisp language
and are running
under KCL.

\(fg) 

\(ce)Table of Contents
\(set-page pp-contents)
\(fr)

Insert the first page of "Table of Contents" here.

\(fg) 

\(ce)Table of Contents (Cont.)

\(fr)

Insert the second page of "Table of Contents" here.

\(fg) 

\(ce)Chapter 1. How to Start and End a KCL Session
\(set-page pp-1)
\(fr)
KCL on Unix is invoked by the Shell command \(fp)kcl\(fr).
\(reserve 2)\(fp)
        % kcl
	KCL (Kyoto Common Lisp)  \(do-string (lisp-implementation-version))
\(fr)

\(fr)---------------------- \(fi)Note to KCL/AOS users\(fr) ----------------------

KCL/AOS is invoked by the CLI command \(fp)KCL\(fr).
\(reserve 2)\(fp)
        ) KCL
	KCL (Kyoto Common Lisp)  \(do-string (lisp-implementation-version))\(fr)

\(fr)--------------------------- \(fi)End of Note\(fr) ----------------------------


When invoked, KCL will print the banner
and initializes the system.  The date in the KCL banner
identifies the revision of KCL.  "\(fp)\(do-string (lisp-implementation-version))\(fr)" is the value of the
function \(fp)lisp-implementation-version\(ri 'lisp-implementation-version)\(fr).

     If there exists a file named \(fp)init.lsp\(fr) 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) by \(fp)init.lsp\(fr).

     After the initialization, KCL enters the \(fi)top-level loop\(fr) and
prints the prompt '\(fp)>\(fr)'.
\(fp)
	>
\(fr)
The prompt indicates that KCL is now ready to receive a form from the terminal
and to evaluate it.

     Usually, the current package (i.e., the value
of \(fp)*package*\(ri '*package*)\(fr)) is the \(fp)user\(fr) package, and the prompt appears
as above.  If, however, the current package is other than the \(fp)user\(fr)
package, then the prompt will be prefixed by the package name.

	\(fi)package-name\(fp)>\(fr)

     To exit from KCL,
call the function \(fp)bye\(ri 'bye)\(fr) (or \(fp)by\(ri 'by)\(fr)).
\(reserve 3)\(fp)
	>(bye)
	Bye.
	%
\(fr)

\(fr)---------------------- \(fi)Note to KCL/AOS users\(fr) ----------------------

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 '\(fp)%\(fr)' in most examples.

\(fr)--------------------------- \(fi)End of Note\(fr) ----------------------------


Alternatively, you may type ^D (control-D),
i.e., press the key D while pressing down the
CNTL key.
\(reserve 2)\(fp)
	>^DBye.
	%
\(fr)
     The top-level loop of KCL is almost the same as that
defined in Section 20.2 of the \(fi)Common Lisp Reference
Manual\(fr).  Since the input from the terminal is in line mode,
each top-level form should be followed by a newline.  If more
than one values are 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.
\(reserve 7)\(fp)
	>(values 1 2)
	1
	2

	>(values)
	
	>
\(fr)
     When an error is signalled, control will enter the break loop.
\(reserve 12)\(fp)
	>(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.
	>>
\(fr)
'\(fp)>>\(fr)' 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 \(fp)user\(fr) package.

     To go back to the top-level loop, type \(fp):q\(ri ':q)\(fr).
\(reserve 4)\(fp)
	>>:q

	Top level.
	>\(fr)

See Section 5.4 for the details of the break loop.

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

     Example:
\(fp)
	>(defun foo () (do () (nil)))
	foo

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

	Broken at FOO.
	>>
\(fr)

\(fr)---------------------- \(fi)Note to KCL/AOS users\(fr) ----------------------

In KCL/AOS, the console interrupt caused by typing ^C (control-C)
followed by ^A (control-A)
is a kind of error.  Typing ^C and ^A breaks the running program
and calls the break loop.  On the other hand, the console interrupt
caused by ^C and ^B (control-B) will immediately terminate KCL.
\(reserve 12)
     Example:
\(fp)
	>(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
	)\(fr)

\(fr)--------------------------- \(fi)End of Note\(fr) ----------------------------

\(fg) 

\(ce)Chapter 2. Data Types
\(set-page pp-2)
\(fr)
KCL supports all Common Lisp data types exactly as defined in the
\(fi)Common Lisp Reference Manual\(fr).  This chapter simply complements
Chapter 2 of the \(fi)Common Lisp Reference Manual\(fr), by
describing implementation dependent features of Common Lisp data
types.  Each section in this chapter corresponds to the section in Chapter 2
of the \(fi)Common Lisp Reference Manual\(fr), with the same section title.

\(reserve 5)\(fg)
2.1. Numbers\(set-page pp-2-1)

2.1.1. Integers\(set-page pp-2-1-1)
\(fr)
     Fixnums in KCL are those integers
in the range \(fp)-\(fr)(\(fp)2\(fr) to the power of \(fp)31\(fr)) to
(\(fp)2\(fr) to the power of \(fp)31\(fr))\(fp)-1\(fr),
inclusive.  Other integers are bignums.  Thus
\(fp)25\(fr) factorial (\(fp)25!\(fr))
\(fp)
    15511210043330985984000000
\(fr)
is certainly a bignum in KCL.

     Common Lisp constants related to integers have the following values
in KCL.
\(fp)
    most-positive-fixnum = 2147483647 = \(fr)(\(fp)2\(fr) to the power of \(fp)31\(fr))\(fp)-1\(ri 'most-positive-fixnum)
    most-negative-fixnum = -2147483648 = -\(fr)(\(fp)2\(fr) to the power of \(fp)31\(fr))\(ri 'most-negative-fixnum)
\(fp)
    boole-1 = 3\(ri 'boole-1)
    boole-2 = 5\(ri 'boole-2)
    boole-and = 1\(ri 'boole-and)
    boole-andc1 = 4\(ri 'boole-andc1)
    boole-andc2 = 2\(ri 'boole-andc2)
    boole-c1 = 12\(ri 'boole-c1)
    boole-c2 = 10\(ri 'boole-c2)
    boole-clr = 0\(ri 'boole-clr)
    boole-eqv = 9\(ri 'boole-eqv)
    boole-ior = 7\(ri 'boole-ior)
    boole-nand = 14\(ri 'boole-nand)
    boole-nor = 8\(ri 'boole-nor)
    boole-orc1 = 13\(ri 'boole-orc1)
    boole-orc2 = 11\(ri 'boole-orc2)
    boole-set = 15\(ri 'boole-set)
    boole-xor = 6\(ri 'boole-xor)
\(fr)
See Chapter 12 of the \(fi)Common Lisp Reference Manual\(fr) for their
meanings.

\(reserve 5)\(fg)
2.1.2. Ratios\(set-page pp-2-1-2)
\(fr)
There are no implementation-dependent features for ratios.

\(reserve 5)\(fg)
2.1.3. Floating-Point Numbers\(set-page pp-2-1-3)
\(fr)
KCL provides two distinct internal floating-point formats.  One format
is \(fi)short\(fr); the other
is \(fi)single\(fr) and serves also as \(fi)double\(fr) and
\(fi)long\(fr).  The data types
\(fp)single-float\(fr), \(fp)double-float\(fr), and \(fp)long-float\(fr)
are considered to be identical, but \(fp)short-float\(fr) is
distinct.  An expression such
as \(fp)(eql 1.0s0 1.0d0)\(fr) is false, but
\(fp)(eql 1.0f0 1.0d0)\(fr) is true.  Similarly,
\(fp)(typep 1.0L0 'short-float)\(fr) is false, but
\(fp)(typep 1.0L0 'single-float)\(fr) is true.  For output purposes all
floating-point numbers are assumed to be of \(fi)short\(fr)
or \(fi)single\(fr) format.

     The floating-point precisions are:
\(reserve 6)
    \(fi)Format	\(fr)KCL/AOS		KCL/VAX	KCL/SUN		KCL/UST
    \(fs)----------------------------------------------------------------\(fr)
    Short		24 bits		23 bits		24 bits		24 bits
    Single	56 bits		55 bits		53 bits		53 bits
    Double	56 bits		55 bits		53 bits		53 bits
    Long		56 bits		55 bits		53 bits		53 bits

The floating-point exponent sizes are:
\(reserve 6)
    \(fi)Format	\(fr)KCL/AOS		KCL/VAX	KCL/SUN		KCL/UST
    \(fs)----------------------------------------------------------------\(fr)
    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

There is no "minus zero."  \(fp)(eql 0.0 -0.0)\(fr) is true.

     Common Lisp constants related to floating-point numbers
have the following values in KCL.
\(reserve 5)\(fp)
    most-positive-short-float\(ri 'most-positive-short-float)
      = - most-negative-short-float\(ri 'most-negative-short-float)
      = 7.237005s75 \(fr)(KCL/AOS)\(fp)
        1.701412s38 \(fr)(KCL/VAX)\(fp)
        3.402823s38 \(fr)(KCL/SUN and KCL/UST)\(fp)
\(reserve 5)
    least-positive-short-float\(ri 'least-positive-short-float)
      = - least-negative-short-float\(ri 'least-negative-short-float)
      = 5.397605s-79 \(fr)(KCL/AOS)\(fp)
        2.938736s-39 \(fr)(KCL/VAX)\(fp)
        1.401298s-45 \(fr)(KCL/SUN and KCL/UST)\(fp)
\(reserve 9)
    most-positive-long-float\(ri 'most-positive-long-float)
      = most-positive-double-float\(ri 'most-positive-double-float)
      = most-positive-single-float\(ri 'most-positive-single-float)
      = - most-negative-long-float\(ri 'most-negative-long-float)
      = - most-negative-double-float\(ri 'most-negative-double-float)
      = - most-negative-single-float\(ri 'most-negative-single-float)
      = 7.237005577332264f75 \(fr)(KCL/AOS)\(fp)
        1.701411834604692f38 \(fr)(KCL/VAX)\(fp)
        1.797693134862315f308 \(fr)(KCL/SUN and KCL/UST)\(fp)
\(reserve 9)
    least-positive-long-float\(ri 'least-positive-long-float)
      = least-positive-double-float\(ri 'least-positive-double-float)
      = least-positive-single-float\(ri 'least-positive-single-float)
      = - least-negative-long-float\(ri 'least-negative-long-float)
      = - least-negative-double-float\(ri 'least-negative-double-float)
      = - least-negative-single-float\(ri 'least-negative-single-float)
      = 5.397605346934027f-79 \(fr)(KCL/AOS)\(fp)
        2.938735877055719f-39 \(fr)(KCL/VAX)\(fp)
        4.940656458412469f-324 \(fr)(KCL/SUN and KCL/UST)\(fp)
\(reserve 4)
    short-float-epsilon\(ri 'short-float-epsilon)
      = 4.468372s-7 \(fr)(KCL/AOS)\(fp)
        6.938894s-18 \(fr)(KCL/VAX)\(fp)
        2.980232s-8 \(fr)(KCL/SUN and KCL/UST)\(fp)
\(reserve 4)
    short-float-negative-epsilon\(ri 'short-float-negative-epsilon)
      = 2.980232s-8 \(fr)(KCL/AOS)\(fp)
        6.938894s-18 \(fr)(KCL/VAX)\(fp)
        2.980232s-8 \(fr)(KCL/SUN and KCL/UST)\(fp)
\(reserve 6)
    long-float-epsilon\(ri 'long-float-epsilon)
      = double-float-epsilon\(ri 'double-float-epsilon)
      = single-float-epsilon\(ri 'single-float-epsilon)
      = 1.110223024625157f-16 \(fr)(KCL/AOS)\(fp)
        6.938893903907228f-18 \(fr)(KCL/VAX)\(fp)
        5.5511151231257827f-17 \(fr)(KCL/SUN and KCL/UST)\(fp)
\(reserve 6)
    long-float-negative-epsilon\(ri 'long-float-negative-epsilon)
      = double-float-negative-epsilon\(ri 'double-float-negative-epsilon)
      = single-float-negative-epsilon\(ri 'single-float-negative-epsilon)
      = 6.938893903907228f-18 \(fr)(KCL/AOS)\(fp)
        6.938893903907228f-18 \(fr)(KCL/VAX)\(fp)
        5.5511151231257827f-17 \(fr)(KCL/SUN and KCL/UST)\(fp)

    pi = 3.141592653589793\(ri 'pi)
\(fr)
See Chapter 12 of the \(fi)Common Lisp Reference Manual\(fr) for their
meanings.

\(reserve 5)\(fg)
2.1.4. Complex Numbers\(set-page pp-2-1-4)
\(fr)
There are no implementation-dependent features for complex numbers.

\(reserve 5)\(fg)
2.2. Characters\(set-page pp-2-2)

2.2.1. Standard Characters\(set-page pp-2-2-1)
\(fr)
KCL supports all standard and semi-standard characters listed in
Section 2.2.1 of the \(fi)Common Lisp Reference Manual\(fr).  Non-printing
characters have the following character code.
\(reserve 10)
    \(fi)Character		Code \(fr)(in octal)
    \(fs)--------------------------------\(fp)
    #\\Space		040
    #\\Newline		012
    #\\Backspace		010
    #\\Tab		011
    #\\Linefeed		012
    #\\Page		014
    #\\Return		015
    #\\Rubout		177
\(fr)
Note that \(fp)#\\Linefeed\(fr) is synonymous with \(fp)#\\Newline\(fr) and
thus is a member of \(fp)standard-char\(fr).  Other semi-standard characters
are not members of \(fp)standard-char\(fr).


\(fr)---------------------- \(fi)Note to KCL/AOS users\(fr) ----------------------

KCL/AOS uses \(fp)025\(fr) (in octal) as the character code of \(fp)#\\Backspace\(fr).

\(fr)--------------------------- \(fi)End of Note\(fr) ----------------------------


\(reserve 5)\(fg)
2.2.2. Line Divisions\(set-page pp-2-2-2)
\(fr)
Since KCL represents the \(fp)#\\Newline\(fr) character by a single
code \(fp)12\(fr), problems with line divisions discussed in Section 2.2.2
of the \(fi)Common Lisp Reference Manual\(fr) cause no problem in KCL.

\(reserve 5)\(fg)
2.2.3. Non-standard Characters\(set-page pp-2-2-3)
\(fr)
KCL supports no additional non-standard characters.

\(reserve 5)\(fg)
2.2.4. Character Attributes\(set-page pp-2-2-4)
\(fr)
The bit and font fields of KCL characters are always \(fp)0\(fr).

     Common Lisp constants related to characters
have the following values in KCL.
\(fp)
    char-bits-limit = 1 \(ri 'char-bits-limit)
    char-code-limit = 256 \(ri 'char-code-limit)
    char-control-bit = 0 \(ri 'char-control-bit)
    char-font-limit = 1 \(ri 'char-font-limit)
    char-hyper-bit = 0 \(ri 'char-hyper-bit)
    char-meta-bit = 0 \(ri 'char-meta-bit)
    char-super-bit = 0 \(ri 'char-super-bit)
\(fr)
See Chapter 13 of the \(fi)Common Lisp Reference Manual\(fr) for their
meanings.

\(reserve 5)\(fg)
2.2.5. String Characters\(set-page pp-2-2-5)
\(fr)
Since the bit and font fields of KCL characters are always \(fp)0\(fr),
\(fp)string-char\(fr) is considered to be identical to \(fp)character\(fr).

\(reserve 5)\(fg)
2.3. Symbols\(set-page pp-2-3)
\(fr)
The print name of a symbol may consists of up to 16777216 (i.e., the value
of \(fp)array-total-size-limit\(fr)) characters.  However, when a symbol is
read, the number of characters (not counting escape characters)
in the print name is limited to 2048.

\(reserve 5)\(fg)
2.4. Lists and Conses\(set-page pp-2-4)
\(fr)
There are no implementation-dependent features for lists and conses.

\(reserve 5)\(fg)
2.5. Arrays\(set-page pp-2-5)
\(fr)
     KCL arrays can have up to 64 ranks.

     When the value of the Common Lisp
variable \(fp)*print-array*\(ri '*print-array*)\(fr) (see Section 22.1.6 of
the \(fi)Common Lisp Reference
Manual\(fr)) is \(fp)nil\(fr), then bit-vectors are printed as
\(fp)#<a bit-vector>\(fr), other vectors are printed
as \(fp)#<a vector>\(fr), and other arrays are printed as \(fp)#<an array>\(fr).

     Common Lisp constants related to arrays
have the following values in KCL.
\(fp)
    array-dimension-limit = 16777216\(ri 'array-dimension-limit)
    array-rank-limit = 64 \(ri 'array-rank-limit)
    array-total-size-limit = 16777216 \(ri 'array-total-size-limit)
\(fr)
See Section 17.1 of the \(fi)Common Lisp Reference Manual\(fr) for
their meanings.

\(reserve 5)\(fg)
2.5.1. Vectors\(set-page pp-2-5-1)
\(fr)
In KCL, array elements are represented in one of the six ways depending
on the type of the array.
\(reserve 8)\(fp)
 \(fi)Array Type					Element Representation\(fr)
 \(fs)---------------------------------------------------------------\(fr)
 \(fp)(array t)\(fr) and \(fp)(vector t)\(fr)			a cell pointer
 \(fp)(array fixnum)\(fr) and \(fp)(vector fixnum)\(fr)		32 bit signed integer
 \(fp)(array string-char)\(fr) and \(fp)string\(fr)			8 bit code
 \(fp)(array short-float)\(fr) and \(fp)(vector short-float)\(fr)	32 bit floating point
 \(fp)(array long-float)\(fr) and \(fp)(vector long-float)\(fr)	64 bit floating point
 \(fp)(array bit)\(fr) and \(fp)bit-vector\(fr)			1 bit bit

\(reserve 5)\(fg)
2.5.2. Strings\(set-page pp-2-5-2)
\(fr)
A string may consists of up to 16777216 (i.e., the value
of \(fp)array-total-size-limit\(fr)) characters.  However, when a string is
read, the number of characters (not counting escape characters)
in the string is limited to 2048.

\(reserve 5)\(fg)
2.5.3. Bit-Vectors\(set-page pp-2-5-3)
\(fr)
There are no implementation-dependent features for bit-vectors.

\(reserve 5)\(fg)
2.6. Hash Tables\(set-page pp-2-6)
\(fr)
All hash tables are printed as \(fp)#<a hash-table>\(fr).

\(reserve 5)\(fg)
2.7. Readtables\(set-page pp-2-7)
\(fr)
All readtables are printed as \(fp)#<a readtable>\(fr).

\(reserve 5)\(fg)
2.8. Packages\(set-page pp-2-8)
\(fr)
     The following packages are built into KCL.
\(fp)
    lisp  user  keyword  system  compiler
\(fr)
The \(fp)compiler\(fr) package contains symbols used by the KCL
compiler.  Other packages are described in Section 11.6 of the \(fi)Common
Lisp Reference Manual\(fr).  The \(fp)system\(fr) package has two nicknames
\(fp)sys\(fr) and \(fp)si\(fr); \(fp)system:\(fi)symbol\(fr) may be
written as \(fp)sys:\(fi)symbol\(fr) or \(fp)si:\(fi)symbol\(fr).  Other
packages have no nicknames.

     Packages are printed as \(fp)#<\(fi)package-name\(fp) package>\(fr).

\(reserve 5)\(fg)
2.9. Pathnames\(set-page pp-2-9)
\(fr)
     KCL provides a \(fp)#\(fr) macro \(fp)#"\(fr) that reads a
pathname:  \(fp)#"\(fi)string\(fr)\(fp)"\(fr) is equivalent
to \(fp)(pathname\(ri 'pathname) "\(fi)string\(fp)")\(fr).  For example,
\(fp)
	#"foo.lsp"
\(fr)
is equivalent to
\(fp)
	(pathname\(ri 'pathname) "foo.lsp").
\(fr)
The same format is used when a pathname is printed.

     The initial value of the Common Lisp variable \(fp)*default-pathname-defaults*\(ri '*default-pathname-defaults*)\(fr)
is \(fp)#""\(fr) (or, equivalently, \(fp)(pathname "")\(fr)).

     A pathname in the file system of Common Lisp
consists of the following six elements:
\(fp)
	host  device  directory  name  type  version
\(fr)
Among these elements, KCL does not use \(fp)host\(fr), \(fp)device\(fr),
and \(fp)version\(fr).  That is, when converting a namestring into a pathname, KCL
turns these three elements into \(fp)nil\(fr).  Conversely, when converting a
pathname into a namestring, KCL ignores these three
elements.

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

     If a namestring contains one or more periods '\(fp).\(fr)',
the last period separates the namestring
into the file name and the filetype.
\(reserve 3)
	\(fp)"foo.lsp"\(fr)
		name:		\(fp)"foo"\(fr)
		type:		\(fp)"lsp"
\(reserve 3)
	\(fp)"a.b.c"\(fr)
		name:		\(fp)"a.b"\(fr)
		type:		\(fp)"c"\(fr)

If a namestring ends with a period, the filetype
becomes the null string.
\(reserve 3)
	\(fp)"foo."\(fr)
		name:		\(fp)"foo"\(fr)
		type:		\(fp)""\(fr) (null string)

If a namestring begins with a period, the file name becomes \(fp)nil\(fr).
\(reserve 3)
	\(fp)".lsp"\(fr)
		name:		\(fp)nil\(fr)
		type:		\(fp)"lsp"\(fr)

If a namestring contains no period, the filetype is \(fp)nil\(fr).
\(reserve 3)
	\(fp)"foo"\(fr)
		name:		\(fp)"foo"\(fr)
		type:		\(fp)nil\(fr)
\(reserve 3)
In a pathname, the file directory is represented as a list.
\(reserve 4)
	\(fp)"common/demo/foo.lsp"\(fr)
		directory:	\(fp)("common"\(fr) \(fp)"demo")\(fr)
		name:		\(fp)"foo"\(fr)
		type:		\(fp)"lsp"\(fr)

If a namestring does not contain a directory,
the directory component of the pathname is \(fp)nil\(fr).
\(reserve 4)
	\(fp)"foo.lsp"\(fr)
		directory:	\(fp)nil\(fr)
		name:		\(fp)"foo"\(fr)
		type:		\(fp)"lsp"\(fr)

In a pathname, the root directory is represented
by the keyword \(fp):root\(ri ':root)\(fr).
\(reserve 4)
	\(fp)"/usr/common/foo.lsp"
	\(fr)	directory:	 \(fp)(:root "usr" "common")\(fr)
		name:		\(fp)"foo"\(fr)
		type:		\(fp)"lsp"\(fr)

The abbreviation symbols '\(fp).\(fr)'
and '\(fp)..\(fr)' may be used in a namestring.
\(reserve 4)
	\(fp)"./demo/queen.lsp"\(fr)
		directory:	\(fp)(:current\(ri ':current) "demo")\(fr)
		name:		\(fp)"queen"\(fr)
		type:		\(fp)"lsp"\(fr)
\(reserve 4)
	\(fp)"../../demo/queen.lsp"\(fr)
		directory:	\(fp)(:parent\(ri ':parent) :parent "demo")\(fr)
		name:		\(fp)"queen"\(fr)
		type:		\(fp)"lsp"\(fr)

\(fp):current\(fr) and \(fp):parent\(fr)
represent the current directory and the parent
directory, respectively.

    The part of a namestring after the last slash '\(fp)/\(fr)' is always
regarded to represent the file name and the filetype.  In order to represent
a pathname with both the name and the filetype \(fp)nil\(fr), end the
pathname with a slash.
\(reserve 4)
	\(fp)"/usr/common/"\(fr)
		directory:	\(fp)(:root "usr" "common")\(fr)
		name:		\(fp)nil\(fr)
		type:		\(fp)nil\(fr)
\(reserve 4)
	\(fp)"/usr/common/.lsp"\(fr)
		directory:	\(fp)(:root "usr" "common")\(fr)
		name:		\(fp)nil\(fr)
		type:		\(fp)"lsp"\(fr)

'\(fp)*\(fr)' in the place of file name or filetype becomes \(fp):wild\(ri ':wild)\(fr).
\(reserve 4)
	\(fp)"*.lsp"\(fr)
		name:		\(fp):wild\(fr)
		type:		\(fp)"lsp"\(fr)
\(reserve 4)
	\(fp)"foo.*"\(fr)
		name:		\(fp)"foo"\(fr)
		type:		\(fp):wild\(fr)


\(fr)---------------------- \(fi)Note to KCL/AOS users\(fr) ----------------------

In KCL/AOS, all the lower-case letters are turned into
upper-case letters by pathname conversions.  Thus, for example,
\(reserve 3)
	\(fp)"foo.lsp"\(fr)
		name:		\(fp)"FOO"\(fr)
		type:		\(fp)"LSP"
\(fr)
KCL/AOS follows the convention of the AOS/VS file system:  The symbols
'\(fp)/\(fr)',  '\(fp).\(fr)',  '\(fp)..\(fr)', and '\(fp)*\(fr)' in the examples
above should be replaced by
'\(fp):\(fr)',  '\(fp)=\(fr)',  '\(fp)^\(fr)', and '\(fp)-\(fr)',
respectively, in KCL/AOS.

\(fr)--------------------------- \(fi)End of Note\(fr) ----------------------------


\(reserve 5)\(fg)
2.10. Streams\(set-page pp-2-10)
\(fr)
Streams are printed in the following formats.

 \(fp)#<input stream \(fi)file-name\(fp)>\(fr)
     An input stream from the file \(fi)file-name\(fr).

 \(fp)#<output stream \(fi)file-name\(fp)>\(fr)
     An output stream to the file \(fi)file-name\(fr).

 \(fp)#<string-input stream from \(fi)string\(fp)>\(fr)
     An input stream generated by \(fp)(make-string-input-stream \(fi)string\(fp))\(fr)\(ri 'make-string-input-stream).

 \(fp)#<a string-output stream>\(fr)
     An output stream generated by the function \(fp)make-string-output-stream\(fr)\(ri 'make-string-output-stream).

 \(fp)#<a two-way stream>\(fr)
     A stream generated by the function \(fp)make-two-way-stream\(fr)\(ri 'make-two-way-stream).

 \(fp)#<an echo stream>\(fr)
     A bidirectional stream generated by the function \(fp)make-echo-stream\(fr)\(ri 'make-echo-stream).

 \(fp)#<synonym stream to \(fi)symbol\(fp)>\(fr)
     The stream generated by \(fp)(make-synonym-stream \(fi)symbol\(fp))\(fr)\(ri 'make-synonym-stream).

 \(fp)#<a concatenated stream>\(fr)
     An input stream generated by the function \(fp)make-concatenated-stream\(fr)\(ri 'make-concatenated-stream).

 \(fp)#<a broadcast stream>\(fr)
     An output stream generated by the function \(fp)make-broadcast-stream\(fr)\(ri 'make-broadcast-stream).

\(reserve 5)\(fg)
2.11. Random-States\(set-page pp-2-11)
\(fr)
KCL provides a \(fp)#\(fr) macro '\(fp)#$\(fr)' that reads a random
state.  \(fp)#$\(fi)integer\(fr) is equivalent
to \(fp)(make-random-state\(ri 'make-random-state)
\(fi)integer\(fp))\(fr).  The same format is used when a random state is
printed.

\(reserve 5)\(fg)
2.12. Structures\(set-page pp-2-12)
\(fr)
There are no implementation-dependent features for structures.

\(reserve 5)\(fg)
2.13. Functions\(set-page pp-2-13)
\(fr)
An interpreted function (including macro expansion functions) is
represented in one of the following formats.

\(fp)(lambda \(fi)lambda-list\(fr) . \(fi)body\(fp))\(fr)\(bd)\(br)
A lambda-expression with null lexical environment and with no implicit
block around it.  This type of functions
typically appear when
\(fp)'(lambda \(fi)lambda-list\(fr) . \(fi)body\(fp))\(fr) is evaluated.
\(endd)

\(fp)(lambda-block \(fi)block-name\(fr) \(fi)lambda-list\(fr) . \(fi)body\(fp))\(fr)\(bd)\(br)
A lambda-expression with null lexical environment but with an implicit
block around it.  This type of functions
typically appear when
\(fp)(defun\(ri 'defun) \(fi)function-name\(fr) \(fi)lambda-list\(fr) . \(fi)body\(fp))\(fr) is evaluated.  In this case, \(fi)block-name\(fr) is identical to \(fi)function-name\(fr).
\(endd)

\(fp)(lambda-closure \(fi)env1\(fr) \(fi)env2\(fr) \(fi)env3\(fr) \(fi)lambda-list\(fr) . \(fi)body\(fp))\(fr)\(bd)\(br)
A lambda-expression with lexical environments but with no implicit
block around it.  This type of functions
typically appear when
\(fp)#'(lambda \(fi)lambda-list\(fr) . \(fi)body\(fp))\(fr) (or, equivalently,
\(fp)(function\(ri 'function) (lambda \(fi)lambda-list\(fr) . \(fi)body\(fp)))\(fr) ) is
evaluated.  \(fi)env1\(fr), \(fi)env2\(fr), and \(fi)env3\(fr) represent
the variable bindings, the local function/macro definitions, and
the tag/block-name establishments, respectively, at the time the closure
was created.
\(endd)

\(fp)(lambda-block-closure \(fi)env1\(fr) \(fi)env2\(fr) \(fi)env3\(fr) \(fi)block-name\(fr) \(fi)lambda-list\(fr) . \(fi)body\(fp))\(fr)\(bd)\(br)
A lambda-expression with lexical environments and with an implicit
block around it.  Local functions and local macros are represented in this
format.  \(fi)env1\(fr), \(fi)env2\(fr), and \(fi)env3\(fr) 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 \(fp)flet\(ri 'flet)\(fr),
\(fp)labels\(ri 'labels)\(fr), or \(fp)macrolet\(ri 'macrolet)\(fr).  The
\(fi)block-name\(fr) is identical to the local function/macro name.
\(endd)

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

    \(fp)#<compiled-function \(fi)name\(fp)>\(fr)
 or
    \(fp)#<compiled-closure nil>\(fr)

Incidentally, the value of \(fp)(symbol-function \(fi)special-form-name\(fp))\(fr) is a
list,

    \(fp)(special . \(fi)address\(fp))\(fr)

if \(fi)special-form-name\(fr) names a special form.

     Common Lisp constants related to functions
have the following values in KCL.
\(reserve 5)\(fp)
    call-arguments-limit = 64 \(ri 'call-arguments-limit)
    lambda-list-keywords = (&optional &rest &key &allow-other-keys &aux
                            &whole &environment &body)\(ri 'lambda-list-keywords)
    lambda-parameters-limit = 64 \(ri 'lambda-parameters-limit)
    multiple-values-limit = 32 \(ri 'multiple-values-limit)
\(fr)
Refer to the \(fi)Common Lisp Reference Manual\(fr) for their meanings.

\(reserve 5)\(fg)
2.14. Unreadable Data Objects\(set-page pp-2-14)
\(fr)
There are no implementation-dependent features for unreadable data objects.

\(reserve 5)\(fg)
2.15. Overlap, Inclusion, and Disjointness of Types\(set-page pp-2-15)
\(fr)
In KCL, the types \(fp)number\(fr) and \(fp)array\(fr) are certainly
subtypes of \(fp)common\(fr), since KCL does not extend the set of objects
of these types.

\(fg) 

\(ce)Chapter 3. Input and Output
\(set-page pp-3)
\(fr)
\(fg)
3.1. Read Macros\(set-page pp-3-1)
\(fr)
     The following \(fp)#\(fr) macros are introduced in KCL.
\(reserve 2)
\(fp)	#"	#"\(fi)string\(fp)"\(fr) reads a pathname.
\(fp)		#"\(fi)string\(fr)\(fp)"\(fr) is equivalent to \(fp)(pathname\(ri 'pathname) "\(fi)string\(fp)")\(fr).
\(reserve 2)
\(fp)	#$	#$\(fi)integer\(fr) reads a random state.
\(fp)		#$\(fi)integer\(fr) is equivalent to \(fp)(make-random-state\(ri 'make-random-state) \(fi)integer\(fp))\(fr).

     The \(fp)#\(fr) macro '\(fp)#,\(fr)' works as described
in the \(fi)Common Lisp Reference Manual\(fr),
only if it is included in a constant object.  The forms immediately
after '\(fp)#,\(fr)' below will be evaluated when the compiled code is loaded.
\(reserve 4)\(fp)
	'#,x
	'(a b c (d #,e f) g)
	#(1 2 3 #,(+ a b c) 5 6)
	#C(0.0 #,(exp 1))
\(fr)
Otherwise, the effect of using '\(fp)#,\(fr)' is unpredictable.  Note that, when an interpreted code is loaded, '\(fp)#,\(fr)'
has the same effect as the \(fp)#\(fr) macro '\(fp)#.\(fr)'.

\(reserve 5)\(fg)
3.2. Input and Output Functions\(set-page pp-3-2)
\(fr)
The input and output functions of KCL almost follow
the definitions in Chapter 22 of the \(fi)Common Lisp Reference
Manual\(fr).  Most of the differences come from the fact that, in KCL,
the input from the terminal is always in line mode
and the binary I/O is not supported.

     In KCL, \(fp)*terminal-io*\(ri '*terminal-io*)\(fr) 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.

     Those functions that deviate from the definitions
in the \(fi)Common Lisp Reference Manual\(fr) are listed below.


\(fp)load\(ri 'load) \(fi)pathname\(fp) &key :print\(ri ':print) :verbose\(ri ':verbose) :if-does-not-exist\(ri ':if-does-not-exist)\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
If \(fi)pathname\(fr) does not specify the filetype of the input file, then
\(fp)load\(fr) first tries to load a file with
the filetype \(fp).o\(fr), i.e., the fasl file (see
Chapter 6).  If it fails, then \(fp)load\(fr) tries to load a file with
the filetype \(fp).lsp\(fr).  KCL assumes that \(fp).lsp\(fr) is the standard
filetype for source files.  If it fails again, then \(fp)load\(fr) will load
the specified file with no filetype.

\(fp)load\(fr) recognizes a file as a fasl file if and only if
the filetype of the file is \(fp).o\(fr).  Other files are assumed to be source files.


\(fr)---------------------- \(fi)Note to KCL/AOS users\(fr) ----------------------

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

\(fr)--------------------------- \(fi)End of Note\(fr) ----------------------------

\(endd)

\(fp)open\(ri 'open)\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
The argument to the keyword variable \(fp):element-type\(ri ':element-type)\(fr) is ignored
and \(fp):element-type\(fr) is always bound to the value
\(fp)string-char\(fr).
\(endd)

\(fp)close\(ri 'close)\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
The keyword variable \(fp):abort\(ri ':abort)\(fr) is always ignored.
\(endd)

\(fp)listen\(ri 'listen)\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
\(fp)listen\(fr) always returns \(fp)t\(fr).
\(endd)

\(fp)read-char-no-hang\(ri 'read-char-no-hang)\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
\(fp)read-char-no-hang\(fr) is equivalent to \(fp)read-char\(ri 'read-char)\(fr).
\(endd)

\(fp)clear-input\(ri 'clear-input)\(fr)\(ra)[\(fi)Function\(fr)]
\(fp)clear-output\(ri 'clear-output)\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
\(fp)clear-input\(fr) and \(fp)clear-output\(fr) simply
return \(fp)nil\(fr) without doing anything.
\(endd)

\(fp)read-byte\(ri 'read-byte)\(fr)\(ra)[\(fi)Function\(fr)]
\(fp)write-byte\(ri 'write-byte)\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
These functions may operate on any stream.  They read or write a byte (8 bits) at a time.
\(endd)

\(fp)princ\(ri 'princ)\(fr)\(ra)[\(fi)Function\(fr)]
\(fp)write-char\(ri 'write-char)\(fr)\(ra)[\(fi)Function\(fr)]
\(fp)write-byte\(ri 'write-byte)\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
These functions do not always flush the stream.  The stream is flushed when

1. a newline character is written, or

2. the input from the terminal is requested in case that these functions operate on \(fp)*terminal-io*\(ri '*terminal-io*)\(fr).
\(endd)

\(fg) 

\(ce)Chapter 4. Memory Management
\(set-page pp-4)
\(fr)
\(fg)
4.1. Implementation Types\(set-page pp-4-1)
\(fr)
Each KCL object belongs to
one of the 22 \(fi)implementation types\(fr).  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;
\(fp)cfun\(fr) is the type of compiled functions without environment,
and \(fp)cclosure\(fr) is the type of compiled functions with environment
(i.e., the type of compiled closures).  \(fp)spice\(fr)
is the type of internal data used by KCL,
and does not correspond to any Common Lisp data type.
\(reserve 24)
		Table 4-1  Implementation Types

	\(fi)Implementation Type	Common Lisp Data Type\(fr)
	\(fs)----------------------------------------------------------------\(fr)
\(fp)	cons			cons
	fixnum			fixnum
	bignum			bignum
	ratio			ratio
	short-float		short-float
	long-float		long-float (= double-float = single-float)
	complex			complex
	character		character
	symbol			symbol
	package			package
	hash-table		hash-table
	array			(and array (not vector))
	vector			(and vector (not string) (not bit-vector))
	string			string
	bit-vector		bit-vector
	structure		structure
	stream			stream
	random-state		random-state
	readtable		readtable
	cfun			compiled-function \(fr)without environment\(fp)
	cclosure		compiled-function \(fr)with environment\(fp)
	spice			\(fr)none\(fp)

\(fr)
     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.

     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.
\(reserve 10)
		Table 4-2  Classification of Implementation Types

	\(fi)Class	Implementation Types\(fr)
	\(fs)----------------------------------------------------------------\(fr)
	    1	\(fp)cons bignum ratio long-float complex\(fr)
	    2	\(fp)fixnum short-float character random-state readtable spice\(fr)
	    3	\(fp)symbol package\(fr)
	    4	\(fp)array hash-table vector bit-vector stream pathname cclosure\(fr)
	    5	\(fp)string cfun\(fr)
	    6	\(fp)structure\(fr)


     For objects of the (implementation) types
\(fp)readtable\(fr), \(fp)symbol\(fr), \(fp)package\(fr),
\(fp)array\(fr), \(fp)hash-table\(fr),
\(fp)vector\(fr), \(fp)bit-vector\(fr), \(fp)stream\(fr), \(fp)cclosure\(fr),
\(fp)string\(fr), \(fp)cfun\(fr), and \(fp)structure\(fr),
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.  A
memory space occupied by the body of such an object
is called a \(fi)block\(fr).  A block is either \(fi)contiguous\(fr) or
\(fi)relocatable\(fr)
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.
\(reserve 16)
		Table 4-3  Types with Bodies

	\(fi)Type		Body			Block\(fr)
	\(fs)-----------------------------------------------------------\(fr)
	\(fp)readtable\(fr)	read table		contiguous
	\(fp)symbol\(fr)		symbol name		relocatable
	\(fp)package\(fr)		hash table		contiguous
	\(fp)array\(fr)		array body		relocatable or contiguous
	\(fp)hash-table\(fr)	hash table		relocatable
	\(fp)vector\(fr)		vector body		relocatable or contiguous
	\(fp)bit-vector\(fr)	bit-vector body		relocatable or contiguous
	\(fp)stream\(fr)		I/O buffer		contiguous
	\(fp)cclosure\(fr)	code			contiguous
	\(fp)string\(fr)		string body		relocatable or contiguous
	\(fp)cfun\(fr)		code			contiguous
	\(fp)structure\(fr)	structure body		relocatable


     Usually, the body of an array, a vector, a bit-vector, or a string
is allocated as a relocatable block.  In KCL, the
function \(fp)make-array\(ri 'make-array)\(fr) takes
an extra keyword argument \(fp):static\(ri ':static)\(fr).  If
the \(fp):static\(fr) argument is supplied with a non-\(fp)nil\(fr) value,
then the body of the array is allocated as a contiguous block.
\(endd)

\(reserve 5)\(fg)
4.2. Heap and Relocatable Areas\(set-page pp-4-2)
\(fr)
    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.

     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.

     The user may specify the maximum number of pages
that can be allocated for each type class
by calling the KCL specific function \(fp)allocate\(ri 'allocate)\(fr).  There
is also a limit in the number of pages for contiguous blocks;
the limit can be altered by calling the KCL specific function
\(fp)allocate-contiguous-pages\(ri 'allocate-contiguous-pages)\(fr).  The
size of the relocatable area is specified
by the KCL specific function \(fp)allocate-relocatable-pages\(ri 'allocate-relocatable-pages)\(fr).  See Section 4.4 for these functions.

     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 not been allocated.

     The heap lies in the memory with the lower address
than the relocatable area
and there is a "hole" between the two areas (see Figure 4-1).  On the
request of a new page for 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.
\(reserve 6)
		Figure 4-1  Heap and Relocatable Area
\(fp)
     lower address                                  higher address
	\(fs)1--------------------2 - - - 2------------------3\(fp)
	|        heap        | hole  | relocatable area \(fs)|
	7--------------------8 - - - 8------------------9
\(fr)

\(reserve 5)\(fg)
4.3. The Garbage Collector\(set-page pp-4-3)
\(fr)
The garbage collector of KCL has three levels
according to what it collects:
\(reserve 3)
	1. cells
	2. cells and relocatable blocks
	3. cells, relocatable blocks and contiguous blocks.

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.

     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.

     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 a garbage.

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

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

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

	* The hole is exhausted (2).

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

	* \(sm)The contiguous blocks are exhausted
after the maximum number of pages have been allocated for contiguous blocks (3).\(rm)

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

\(fp)gbc\(ri 'gbc)\(fi) x\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
The garbage collector is invoked with the level specified
by \(fi)x\(fr).  If \(fi)x\(fr) is \(fp)nil\(fr),
the garbage collector is invoked for
level 1 garbage collection.  If \(fi)x\(fr) is \(fp)t\(fr),
it is invoked for level 3 garbage collection.  Otherwise,
it is invoked level 2 garbage collection.
\(endd)

\(reserve 5)\(fg)
4.4. Allocation Functions\(set-page pp-4-4)
\(fr)
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.

\(fp)allocate\(ri 'allocate)\(fi) type number\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
Sets the maximum number of pages for the type class of the implementation type
\(fi)type\(fr) to \(fi)number\(fr).  If more than \(fi)number\(fr) pages have already been allocated,
an error is signalled.
\(endd)

\(fp)allocated-pages\(ri 'allocated-pages)\(fi) type\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
Returns the number of pages currently allocated
for the type class of the implementation type \(fi)type\(fr).
\(endd)

\(fp)maximum-allocatable-pages\(ri 'maximum-allocatable-pages)\(fi) type\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
Returns the current maximum number of pages
for tye type class of the implementation type \(fi)type\(fr).
\(endd)

\(fp)allocate-contiguous-pages\(fi) number\(fr)\(ri 'allocate-contiguous-pages)\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
Sets the maximum number of pages for contiguous blocks to \(fi)number\(fr).
\(endd)

\(fp)allocated-contiguous-pages\(ri 'allocated-contiguous-pages)\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
Returns the number of pages allocated for contiguous blocks.
\(endd)

\(fp)maximum-contiguous-pages\(ri 'maximum-contiguous-pages)\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
Returns the current maximum number of pages for contiguous blocks.
\(endd)

\(fp)allocate-relocatable-pages\(fi) number\(fr)\(ri 'allocate-relocatable-pages)\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
Sets the maximum number of pages for relocatable blocks
to \(fi)number\(fr).  The relocatable area is expanded to \(fi)number\(fr)
pages immediately.  Therefore, "the current maximum number" and "the
number of pages allocated" have the same meanings for relocatable blocks.
\(endd)

\(fp)allocated-relocatable-pages\(ri 'allocated-relocatable-pages)\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
Returns the number of pages allocated for relocatable blocks.
\(endd)

     If the pages for a particular type class is 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 \(fp)*ignore-maximum-pages*\(ri '*ignore-maximum-pages*)\(fr).  If
the value is \(fp)nil\(fr),
then KCL signals a correctable error and enters the break loop.  The
user can reset the maximum number by calling \(fp)allocate\(fr)
and then continue the execution of the program by typing \(fp):r\(fr).
\(reserve 16)
     Example:
\(fp)
	>(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 ............
\(fr)
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 \(fp)*ignore-maximum-pages*\(ri '*ignore-maximum-pages*)\(fr)
is non-\(fp)nil\(fr),
then KCL automatically increments the maximum number of pages for the
class by 50 percent.  The initial value of \(fp)*ignore-maximum-pages*\(ri '*ignore-maximum-pages*)\(fr) is
\(fp)t\(fr).

\(reserve 5)\(fg)
4.5. Storage Information\(set-page pp-4-5)
\(fr)
\(fp)room\(ri 'room) &optional\(fi) x\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
The function \(fp)room\(fr) prints the storage information.  The argument
\(fi)x\(fr) is simply ignored and
the output of \(fp)room\(fr) is always in the same
format.  \(fp)room\(fr) prints the following information:
\(reserve 19)
	* for each type class
		* \(sm)the number of pages so-far allocated for the type class\(rm)
		* the maximum number of pages for the type class
		* \(sm)the percentage of used cells to cells so-far allocated\(rm)
		* \(sm)the number of times the garbage collector has been called to collect cells of the type class\(rm)
		* the implementation types that belongs to the type class
	* the number of pages actually allocated for contiguous blocks
	* the maximum number of pages for contiguous blocks
	* \(sm)the number of times the garbage collector has been called to collect contiguous blocks\(rm)
	* the number of pages in the hole
	* the maximum number of pages for relocatable blocks
	* \(sm)the number of times the garbage collector has been called to collect relocatable blocks\(rm)
	* 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.

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

     In the following example,
the maximum of \(fp)531\(fr) pages have already been allocated
for the type class to which \(fp)cons\(fr) 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.
\(reserve 17)\(fp)
 >(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
 
 >
\(fr)
\(endd)

\(fg) 

\(ce)Chapter 5. Debugging Facilities
\(set-page pp-5)
\(fr)
\(fg)
5.1. The Tracer\(set-page pp-5-1)
\(fr)
The Tracer causes selected functions to be traced.  When such a traced function is invoked, it prints

	\(fi)level\(fp) > (\(fi)name\(fp) \(fi)arg1\(fp) \(fi)...\(fp) \(fi)argn\(fp))\(fr)

On return from a traced function, it prints

	\(fp)< \(fi)level\(fp) (\(fi)name\(fp) \(fi)value1\(fp) \(fi)...\(fp) \(fi)valuen\(fp))\(fr)

\(fi)name\(fr) is the name of the traced function,
\(fi)arg\(fr)s are the arguments,
and \(fi)value\(fr)s are the return values.  \(fi)level\(fr) is a number which is incremented each time
a traced function is invoked and is decremented at the completion of the
invocation.  Trace print-outs are indented according to the \(fi)level\(fr).

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


\(fp)trace\(ri 'trace) \(fr){\(fi)function-name\(fr)}*\(ra)[\(fi)Macro\(fr)]\(bd)
Causes one or more functions to be traced.  \(fi)function-name\(fr)s 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 \(fp)notinline\(ri 'notinline)\(fr) declaration for the called function (see
Chapter 7).  \(fp)trace\(fr) returns a name list of those functions that were
traced by the call to \(fp)trace\(fr).  If no \(fi)function-name\(fr) is
given, \(fp)trace\(fr) simply returns
a name list of all the currently traced functions.
\(endd)

\(fp)untrace\(ri 'untrace) \(fr){\(fi)function-name\(fr)}*\(ra)[\(fi)Macro\(fr)]\(bd)
Causes the specified functions to be not traced any more.  \(fi)function-name\(fr)s must be symbols and they are not evaluated.  \(fp)untrace\(fr) returns a name list of those functions that were untraced by
the call to \(fp)untrace\(fr).  If no \(fi)function-name\(fr) is given, \(fp)untrace\(fr) will untrace
all the currently traced functions and will return a list of their names.
\(endd)
\(reserve 5)\(fg)
5.2. The Stepper\(set-page pp-5-2)
\(fr)
\(fp)step\(ri 'step) \(fi)form\(fr)\(ra)[\(fi)Macro\(fr)]\(bd)
Starts evaluating the \(fi)form\(fr) 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 \(fp)*print-level*\(ri '*print-level*)\(fr) and \(fp)*print-length*\(ri '*print-length*)\(fr)
both to \(fp)2\(fr), 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
\(fp)n\(fr) was abbreviated.

The Stepper commands are:
\(br)
\(fp)n\(fr)	\(sm)Next.  Evaluates the current form in the single-step mode.\(rm)

\(fp)s\(fr)	\(sm)Skip.  Evaluates the current form in the ordinary mode.  The single-step mode will be resumed at completion
of the evaluation.\(rm)

\(fp)p\(fr)	\(sm)Print.  Pretty-prints the current form and then prompts again.\(rm)

\(fp)f\(fr) \(fi)fn\(fr)	\(sm)Function.  Evaluates the current form in the ordinary mode until the specified
function \(fi)fn\(fr) is invoked.  If the specified function is not invoked at all, then this command has the same effects as the \(fp)q\(fr) command below.\(rm)

\(fp)q\(fr)	\(sm)Quit.  Evaluates the current form and any other forms in the ordinary mode.\(rm)

\(fp)e\(fr) \(fi)form\(fr)	\(sm)Eval.  Evaluates the specified form in the ordinary mode and prints the resulted values.  Then prompts again with the same current form.\(rm)

\(fp)?\(fr)	\(sm)Help.  Lists the Stepper commands.\(rm)
\(endd)
\(reserve 5)\(fg)
5.3.  Errors\(set-page pp-5-3)
\(fr)
\(fp)*break-enable*\(ri '*break-enable*)\(fr)\(ra)[\(fi)Variable\(fr)]\(bd)
This variable is used to determine whether to enter the
break loop (see Section 5.4) when an error occurs.  Even the function
\(fp)break\(ri 'break)\(fr) checks this variable.  Initially, this variable is set to \(fp)t\(fr), and thus
an error will invoke the break loop.  If the value is \(fp)nil\(fr),
functions that cause fatal errors, such as \(fp)error\(ri 'error)\(fr),
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 \(fp)cerror\(ri 'cerror)\(fr),
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 \(fp)*break-enable*\(ri '*break-enable*)\(fr) is \(fp)nil\(fr),
no backtrace appears on the screen.

When the break loop is entered, \(fp)*break-enable*\(ri '*break-enable*)\(fr)
will be bound to \(fp)nil\(fr).
\(endd)
\(reserve 5)\(fg)
5.4.  The Break Loop\(set-page pp-5-4)
\(fr)
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 \(fp)keyword\(fr)
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 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 resulted values
will be printed on the terminal.

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

     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 \(fp)1\(fr)).  The invocation sequence is maintained in a pushdown stack of \(fi)event\(fr)s.  An event consists of an \(fi)event function\(fr) and an \(fi)event
environment\(fr).  An event function is:

	1. \(sm)an interpreted (i.e., not compiled) function (global function, local function, lambda-expression, or closure),\(rm)
	2. \(sm)a special form within an interpreted function,\(rm)
	3. \(sm)a macro expansion function called from an interpreted function,\(rm)
	4. \(sm)a compiled function called from an interpreted function, or\(rm)
	5. \(sm)a compiled function called from another compiled
function which was compiled while the \(fp)safety\(ri 'safety)\(fr) optimize
level is \(fp)3\(fr) or with a \(fp)notinline\(ri 'notinline)\(fr)
declaration for the called function (see Chapter 7).\(rm)

     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.

     By break level commands,
the user can choose one of the events as \(fi)the current event\(fr).  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 \(fp)go\(ri 'go)\(fr).  If the current function is a compiled function,
Lisp forms are evaluated in the null environment.

     Within the break loop, each event is represented by \(fi)the event
symbol\(fr).  The \(fp):backtrace\(fr)
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 \(fp)lambda\(fr) (or
\(fp)lambda-closure\(fr)) is used.

     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 \(fp)system\(fr).  When the break loop is entered,
the last visible event becomes the current event.

     The break loop commands are described below.  Some of the commands
allows abbreviation in the keywords that identify them.  For example, the user may abbreviate \(fp):current\(fr) as \(fp):c\(fr).  The break loop commands return no values at all.


\(fp):current\(ri ':current)\(fr)\(ra)[\(fi)Break Loop Command\(fr)]
\(fp):c\(ri ':c)\(fr)\(ra)[\(fi)Abbreviated Break Loop Command\(fr)]\(bd)
Prints the event symbol of the current event.
\(endd)

\(fp):previous\(ri ':previous) &optional \(fi)n\(fr)\(ra)[\(fi)Break Loop Command\(fr)]
\(fp):p\(ri ':p) &optional \(fi)n\(fr)\(ra)[\(fi)Abbreviated Break Loop Command\(fr)]\(bd)
Makes the \(fi)n\(fr)-th previous visible event the
new current event.  Invisible events are not counted.  If there are less than \(fi)n\(fr) previous
events, then the first visible event in the invocation sequence
becomes the new current event.  \(fi)n\(fr) must be a positive integer and the default is \(fp)1\(fr).
\(endd)

\(fp):next\(ri ':next) &optional \(fi)n\(fr)\(ra)[\(fi)Break Loop Command\(fr)]
\(fp):n\(ri ':n) &optional \(fi)n\(fr)\(ra)[\(fi)Abbreviated Break Loop Command\(fr)]\(bd)
Makes the \(fi)n\(fr)-th next visible event the
new current event.  If there are less than \(fi)n\(fr) next events,
then the last visible event in the invocation sequence
becomes the new current event.  \(fi)n\(fr) must be a positive integer and the default is \(fp)1\(fr).
\(endd)

\(fp):backtrace\(ri ':backtrace)\(fr)\(ra)[\(fi)Break Loop Command\(fr)]
\(fp):b\(ri ':b)\(fr)\(ra)[\(fi)Abbreviated Break Loop Command\(fr)]\(bd)
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-cases.
\(endd)

\(fp):help\(ri ':help)\(fr)\(ra)[\(fi)Break Loop Command\(fr)]
\(fp):h\(ri ':h)\(fr)\(ra)[\(fi)Abbreviated Break Loop Command\(fr)]\(bd)
Lists the break loop commands.
\(endd)

\(fp):quit\(ri ':quit) &optional \(fi)n\(fr)\(ra)[\(fi)Break Loop Command\(fr)]
\(fp):q\(ri ':q) &optional \(fi)n\(fr)\(ra)[\(fi)Abbreviated Break Loop Command\(fr)]\(bd)
Returns control to the level \(fi)n\(fr) break loop.  If \(fi)n\(fr) is \(fp)0\(fr) or if \(fi)n\(fr) is omitted, then
control will return to the top-level loop.  \(fi)n\(fr) must be a non-negative integer smaller than
the current break level.
\(endd)

\(fp):resume\(ri ':resume)\(fr)\(ra)[\(fi)Break Loop Command\(fr)]
\(fp):r\(ri ':r)\(fr)\(ra)[\(fi)Abbreviated Break Loop Command\(fr)]\(bd)
Returns control to the caller of the break loop.  If the break loop has been
entered from \(fp)cerror\(ri 'cerror)\(fr),
\(fp)cerror\(fr) returns \(fp)nil\(fr) 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).
\(endd)

\(fp):variables\(ri ':variables)\(fr)\(ra)[\(fi)Break Loop Command\(fr)]
\(fp):v\(ri ':v)\(fr)\(ra)[\(fi)Abbreviated Break Loop Command\(fr)]\(bd)
Prints the names of the bound variables in the current
environment.  To see the value of a bound variable, just type the
variable name.
\(endd)

\(fp):functions\(ri ':functions)\(fr)\(ra)[\(fi)Break Loop Command\(fr)]\(bd)
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 \(fp)function\(fr) special form in the
usual way.  That is, \(fp)(function \(fi)name\(fp))\(fr) will return the
definition of the local function or macro
whose name is \(fi)name\(fr).  Local functions and local macros
may be invoked as usual.
\(endd)

\(fp):blocks\(ri ':blocks)\(fr)\(ra)[\(fi)Break Loop Command\(fr)]\(bd)
Prints the names of the blocks established in the current
environment.  If a block \(fi)block\(fr) is established,
then the \(fp)return-from\(ri 'return-from)\(fr) form
\(fp)(return-from \(fi)block\(fp) \(fi)value\(fp))\(fr)
works as usual.  That is, the block form that established \(fi)block\(fr)
will return \(fi)value\(fr) as its value and control will resume at
that point.
\(endd)

\(fp):tags\(ri ':tags)\(fr)\(ra)[\(fi)Break Loop Command\(fr)]\(bd)
Prints the tags established in the current environment.  If a tag \(fi)tag\(fr) is established,
then the \(fp)go\(ri 'go)\(fr) form
\(fp)(go \(fi)tag\(fp))\(fr) works as usual.  That is, control will resume at the position of \(fi)tag\(fr) in the
surrounding \(fp)tagbody\(ri 'tagbody)\(fr).
\(endd)

\(fp):local\(ri ':local) &optional \(fi)n\(fr)\(ra)[\(fi)Break Loop Command\(fr)]
\(fp):l\(ri ':l) &optional \(fi)n\(fr)\(ra)[\(fi)Abbreviated Break Loop Command\(fr)]\(bd)
If \(fi)n\(fr) is \(fp)0\(fr) 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.  \(fi)n\(fr) is an offset from that entry.  If \(fi)n\(fr) is positive, then the value of
the \(fi)n\(fr)-th next (i.e., toward the top of the main stack) entry
is printed.  If \(fi)n\(fr) is negative, then the value of
the | \(fi)n\(fr) |-th previous (i.e., toward the bottom of the main stack) entry
is printed.  \(fi)n\(fr) must be an integer.  It is an error if the specified entry does not lie between the bottom and
the top of the stack.
\(endd)

\(fp):hide\(ri ':hide) \(fi)symbol\(fr)\(ra)[\(fi)Break Loop Command\(fr)]\(bd)
Hides all events whose event symbol is \(fi)symbol\(fr).  In particular, by \(fp)(:hide 'lambda)\(fr) and
\(fp)(:hide 'lambda-closure)\(fr), all events become invisible
whose event functions are lambda-expressions and closures, respectively.  If the event symbol of the current event happens to be \(fi)symbol\(fr),
then the last previous visible event will become the new current event.  \(fi)symbol\(fr) must be a symbol.

Events of \(fp)eval\(ri 'eval)\(fr) and \(fp)evalhook\(ri 'evalhook)\(fr) may never become
invisible and attempts to hide them are simply ignored.  It is always
the case that the first event function is either \(fp)eval\(fr)
or \(fp)evalhook\(fr).  Keeping both of them visible is the simplest way
to avoid the silly attempts of the user to hide all events.
\(endd)

\(fp):hide-package\(ri ':hide-package) \(fi)package\(fr)\(ra)[\(fi)Break Loop Command\(fr)]\(bd)
Hides all events whose event symbol belongs to the package
\(fi)package\(fr).  \(fi)package\(fr) 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 \(fi)package\(fr),
then the last previous visible event will
become the new current event.  Even if \(fp)lisp\(fr) package was
specified as \(fi)package\(fr),
events of \(fp)eval\(ri 'eval)\(fr) and \(fp)evalhook\(ri 'evalhook)\(fr)
do not become invisible.  See the description of \(fp):hide\(fr) above.
\(endd)

\(fp):unhide\(ri ':unhide) \(fi)symbol\(fr)\(ra)[\(fi)Break Loop Command\(fr)]\(bd)
\(fp):unhide\(fr) is the inverse command of \(fp):hide\(fr).  If, however, \(fi)symbol\(fr) belongs to one of the \(fp):hide-package\(fr)d
packages, events of \(fi)symbol\(fr) become visible only after the
package is \(fp):unhide-package\(fr)'d.  \(fi)symbol\(fr) must be a symbol.
\(endd)

\(fp):unhide-package\(ri ':unhide-package) package\(fr)\(ra)[\(fi)Break Loop Command\(fr)]\(bd)
\(fp):unhide-package\(fr) is the inverse
command of \(fp):hide-package\(fr).  However, an event whose event symbol belongs to \(fi)package\(fr) becomes
visible only after the symbol is \(fp):unhide\(fr)'d, if the symbol
was \(fp):hide\(fr)'d before.  \(fi)package\(fr) may be any object that represents a package, i.e., a package object, a symbol, or a string.
\(endd)

     Example:
\(fp)
	>(defun fact (x) (if (= x 0) one (* x (fact (1- x)))))
	fact			;;; \(fr)Wrong definition for \(fp)fact\(fr), the factorial.\(fp)
	
	>(fact 6)		;;; \(fr)Tries to calculate factorial 6.\(fp)

	Error: The variable ONE is unbound.
	Error signalled by IF.
	
	Broken at IF.		;;; \(fr)Enters the break-loop.\(fp)
	>>:h			;;; \(fr)Help.\(fp)
	: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			;;; \(fr)Backtrace.\(fp)
	Backtrace: eval > fact > if > fact > if > fact > if > fact > if >
	fact > if > fact > if > fact > IF
	
	>>:p			;;; \(fr)Moves to the previous event.\(fp)
	Broken at FACT.
	
	>>:b			;;; \(fr)Now inside of \(fp)fact\(fr) but outside of \(fp)if\(fr).\(fp)
	Backtrace: eval > fact > if > fact > if > fact > if > fact > if >
	fact > if > fact > if > FACT > if
	
	>>:v			;;; \(fr)Shows local variables.\(fp)
	Local variables: x.
	
	>>x			;;; \(fr)The value of \(fp)x\(fr) is \(fp)0\(fr).\(fp)
	0
	
	>>:blocks		;;; \(fr)Shows blocks.\(fp)
	Block names: fact.
	
	>>(return-from fact 1)	;;; \(fr)Returns from the \(fp)fact\(fr) block with value \(fp)1\(fr).\(fp)
	720			;;; \(fr)Now the correct answer.\(fp)

	>			;;; \(fr)Top-level.
\(fr)
\(reserve 5)\(fg)
5.5. Describe and Inspect\(set-page pp-5-5)
\(fr)
\(fp)describe\(ri 'describe) \(fi)object\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
Prints the information about \(fi)object\(fr) to the stream that is
the value of \(fp)*standard-output*\(ri '*standard-output*)\(fr).  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, \(fp)deftype\(ri 'deftype)\(fr) definition,
properties.
\(endd)

\(fp)inspect\(ri 'inspect) \(fi)object\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
Prints the information about \(fi)object\(fr)
in an interactive manner.  The output of \(fp)inspect\(fr) is similar to that of \(fp)describe\(fr),
but after printing the label and the value of a field
(the value itself is not \(fp)describe\(fr)'d),
it prompts the user to input a one-character command.  The input to \(fp)inspect\(fr) is taken from the stream
that is the value of \(fp)*query-io*\(ri '*query-io*)\(fr).  Normally, the
inspection of \(fi)object\(fr) terminates
after all of its fields have been inspected.  The following commands are
supported:
\(br)
\(fp)n\(fr)	\(sm)Next.  Goes to the next level; the field is inspected recursively.\(rm)

\(fp)s\(fr)	\(sm)Skip.  Skips the inspection of the field. \(fp)inspect\(fr) proceeds to the next field.\(rm)

\(fp)p\(fr)	\(sm)Print.  Pretty-prints the field and prompts again.\(rm)

\(fp)u \(fi)form\(fr)	\(sm)Update.  The \(fi)form\(fr) is evaluated and the field is replaced by the resulted value.  If the field cannot be updated, the message \(fp)Not updated.\(fr) will be printed.\(rm)

\(fp)a\(fr)	\(sm)Abort.  Aborts the inspection of the current object.  The field and the rest of the fields are not inspected.\(rm)

\(fp)e \(fi)form\(fr)	\(sm)Eval.  Evaluates the specified form in the null environment and prints the resulted values.  Then prompts again with the same field.\(rm)

\(fp)q\(fr)	\(sm)Quit.  Aborts the entire inspection.\(rm)

\(fp)?\(fr)	\(sm)Help.  Lists the \(fp)inspect\(fr) commands.\(rm)
\(endd)

\(fg) 

\(ce)Chapter 6. The Compiler
\(set-page pp-6)
\(fr)
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
\(fi)fasl file\(fr) (or \(fi)o-file\(fr) because of the actual filetype).  The compiled program in a fasl file is loaded by
the function \(fp)load\(ri 'load)\(fr).

     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 \(fp)optimize\(fr) declarations (see Section 7.1).

     The KCL compiler processes
the \(fp)eval-when\(ri 'eval-when)\(fr) special form
exactly as specified in the \(fi)Common Lisp Reference
Manual\(fr).  However, all top-level forms in the source file are normally
processed in \(fi)compile-time-too\(fr) mode, not
in \(fi)not-compile-time\(fr) mode (see Section 5.3.3 of the
\(fi)Common Lisp Reference Manual\(fr)).  That is, each top-level form
\(fi)top-level-form\(fr) is processed as if it were surrounded by the
\(fp)eval-when\(fr) special form with the situations \(fp)compile\(fr),
\(fp)load\(fr), and \(fp)eval\(fr).
\(fp)
    (eval-when (compile load eval) \(fi)top-level-form\(fp))
\(fr)
There is no exception for this rule.  Thus, for instance, in the example of
\(fp)set-macro-character\(fr) form in Section 5.3.3 of the \(fi)Common Lisp
Reference Manual\(fr), the surrounding \(fp)eval-when\(fr) form is
unnecessary in KCL.  If it is desired that each top-level form be
processed in \(fi)not-compile-time\(fr) mode, change the
value of the KCL specific variable
\(fp)*eval-when-compile*\(ri '*eval-when-compile*)\(fr) as described below.

     The KCL compiler is invoked by the functions \(fp)compile-file\(fr),
\(fp)compile\(fr), and \(fp)disassemble\(fr) described below.  In addition,
the KCL compiler may
be invoked directly by the Shell
commands \(fp)lc\(fr) or
\(fp)lc1\(fr).  These commands require the file name of the source file as
their argument.  Both \(fp)lc\(fr) and \(fp)lc1\(fr) simply
adds \(fp)".lsp"\(fr) to the file name argument to obtain the full name of the
source file.
\(fp)
	% lc \(fi)filename
\(fr)
has the same effects as the compiler invocation \(fp)(compile-file "\(fi)filename\(fp)")\(fr) from within
KCL, and
\(fp)
	% lc1 \(fi)filename
\(fr)
has the same effects as \(fp)(compile-file "\(fi)filename\(fp)" :o-file t :c-file t :h-file t :data-file t)\(fr).


\(fp)compile-file\(ri 'compile-file) \(fi)input-pathname\(fp) \(fr)\(ra)[\(fi)Function\(fr)]
	\(fp)&key :output-file\(ri ':output-file) :o-file\(ri ':o-file) :c-file\(ri ':c-file) :h-file\(ri ':h-file) :data-file\(ri ':data-file)\(fr)\(bd)\(br)
\(fp)compile-file\(fr) compiles the Lisp program stored in the file
specified by \(fi)input-pathname\(fr), and generates a fasl file.  Also \(fp)compile-file\(fr) generates the following temporary files.
\(reserve 5)
	\(fi)Temporary File	Contents\(fr)
	\(fs)------------------------------------------------\(fr)
	\(fi)c-file\(fr)		C version of the Lisp program
	\(fi)h-file\(fr)		The include file referenced in the c-file
	\(fi)data-file\(fr)		The Lisp data to be used at load time

If files of these names already exist, the old files will be
deleted first.  Usually,
these intermediate files are automatically deleted after execution of
\(fp)compile-file\(fr).

     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
\(fp).lsp\(fr) will be used.  The keyword parameter \(fp):output-file\(fr)
defines the default directory and the default name to be applied to
the output files (i.e., the fasl file and
the temporary files).  \(fp):output-file\(fr) itself defaults
to \(fi)input-pathname\(fr).  That is, if \(fp):output-file\(fr) 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.
\(reserve 6)
	\(fi)Output File	Filetype\(fr)
	\(fs)----------------------\(fr)
	fasl file		\(fp).o\(fr)
	c-file		\(fp).c\(fr)
	h-file		\(fp).h\(fr)
	data-file		\(fp).data\(fr)

Each output file can be specified by the corresponding keyword
parameter.  If the value of the keyword parameter is \(fp)nil\(fr), then
the output file will
be deleted after execution of \(fp)compile-file\(fr).  If the value of
the keyword
parameter is \(fp)t\(fr), 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 \(fp):o-file\(fr)
is \(fp)t\(fr), and the default values of
\(fp):c-file\(fr), \(fp):h-file\(fr),
and \(fp):data-file\(fr) are all \(fp)nil\(fr).

     Example:
\(reserve 3)
	\(fp)(compile-file 'foo)\(fr)
		The source file is \(fp)"FOO.lsp"\(fr) and the fasl file is \(fp)"FOO.o"\(fr)
		both in the current directory.
\(reserve 2)
	\(fp)(compile-file 'foo.lish)\(fr)
		The source file is \(fp)"FOO.LISH"\(fr) and the fasl file is \(fp)"FOO.o"\(fr).
\(reserve 3)
	\(fp)(compile-file "/usr/mas/foo" :output-file "/usr/tai/baa")\(fr)
		The source file is \(fp)"foo.lsp"\(fr) in the directory \(fp)"/usr/mas"\(fr),
		and the fasl file is \(fp)"baa.o"\(fr) in the directory \(fp)"/usr/tai"\(fr).

\(endd)
\(fr)---------------------- \(fi)Note to KCL/AOS users\(fr) ----------------------

The compiler of KCL/AOS generates the following output files.
\(reserve 6)
	\(fi)Output File	Filetype		Contents\(fr)
	\(fs)------------------------------------------------------------\(fr)
	fasl file		\(fp).fasl\(fr)	The fasl file
	c-file		\(fp).c\(fr)	C version of the Lisp program
	h-file		\(fp).h\(fr)	The include file referenced in the c-file
	ob-file		\(fp).ob\(fr)	The object file generated by the C compiler
	data-file		\(fp).data\(fr)	The Lisp data to be used at load time

Note that the filetype of the fasl file is \(fp).fasl\(fr) in KCL/AOS.  Also
note that the compiler of KCL/AOS generates
an additional file \(fi)ob-file\(fr).  Accordingly, the function
\(fp)compile-file\(fr) has a slightly different definition:

\(fp)compile-file\(ri 'compile-file) \(fi)input-pathname\(fp) \(fr)\(ra)[\(fi)Function\(fr)]
	\(fp)&key :output-file\(ri ':output-file) :fasl-file\(ri ':fasl-file) :c-file\(ri ':c-file) :h-file\(ri ':h-file) :ob-file\(ri ':ob-file) :data-file\(ri ':data-file)\(fr)

The keyword parameter \(fp):fasl-file\(fr) corresponds to the keyword
parameter \(fp):o-file\(fr) in KCL on Unix.  In particular, the default
value of \(fp):fasl-file\(fr) is \(fp)t\(fr) and the default values of
\(fp):c-file\(fr), \(fp):h-file\(fr), \(fp):ob-file\(fr), and
\(fp):data-file\(fr) are all \(fp)nil\(fr).  In KCL/AOS,
\(fp)
	) lc1 \(fi)filename\(fr)

has the same effects as \(fp)(compile-file "\(fi)filename\(fp)" :fasl-file t :c-file t :h-file t :ob-file t :data-file t)\(fr).

     Because KCL/AOS follows the convention of the AOS/VS file system, the
last example above should be replaced as:
\(reserve 3)
	\(fp)(compile-file ":udd:mas:foo" :output-file ":udd:tai:baa")\(fr)
		The source file is \(fp)"FOO.LSP"\(fr) in the directory \(fp)":UDD:MAS"\(fr),
		and the fasl file is \(fp)"BAA.FASL"\(fr) in the directory \(fp)":UDD:TAI"\(fr).

\(fr)--------------------------- \(fi)End of Note\(fr) ----------------------------


\(fp)compile\(ri 'compile) \(fi)name\(fp) &optional \(fi)definition\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
If \(fi)definition\(fr) is not supplied, \(fi)name\(fr) should be the name
of a not-yet-compiled function.  In this case,\(fp) compile\(fr) compiles the
function, replaces the previous definition of \(fi)name\(fr)
with the compiled function, and returns
\(fi)name\(fr).  If\(fi) definition\(fr) is supplied, it should be a
lambda-expression to be compiled and \(fi)name\(fr) should
be a symbol.  If \(fi)name\(fr) is a non-\(fp)nil\(fr) symbol,
then \(fp)compile\(fr) installs the compiled function as the function
definition
of \(fi)name\(fr) and returns \(fi)name\(fr).  If\(fi) name\(fr)
is \(fp)nil\(fr), then \(fp)compile\(fr) simply returns the
compiled function.

     The KCL compiler is essentially a file compiler, and forms to be compiled
are supposed to be stored in a file.  Thus \(fp)compile\(fr) actually
creates a source file which
contains the form designated by the arguments.  Then \(fp)compile\(fr)
calls \(fp)compile-file\(ri 'compile-file)\(fr) to get a fasl file, which
is then loaded into KCL.  The source file and the fasl file are given the
names \(fp)gazonk.lsp\(fr) and \(fp)gazonk.fasl\(fr), respectively.  These files are not
deleted automatically after the execution of \(fp)compile\(fr).
\(endd)

\(fp)disassemble\(ri 'disassemble) \(fp)&optional \(fi)thing\(fp) &key :h-file :data-file\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
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 \(fi)thing\(fr) is not supplied, or if it is \(fp)nil\(fr), then
the previously compiled form by \(fp)disassemble\(fr) will be
compiled again.  If \(fi)thing\(fr) is a symbol other than \(fp)nil\(fr),
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 \(fi)thing\(fr)
is a lambda-expression
\(fp)(lambda \(fi)lambda-list \(fp). \(fi)body\(fp))\(fr), then
\(fp)disassemble\(fr) first creates a function definition \(fp)(defun gazonk \(fi)lambda-list\(fp) . \(fi)body\(fp))\(fr) and this definition
is compiled.  (The function name \(fp)gazonk\(fr) has
no special meanings.  Indeed,
the displayed code is essentially independent
of the function name.)  Otherwise, \(fi)thing\(fr) itself
will be compiled as a top-level form.  In any case, \(fp)disassemble\(fr)
does not install the compiled
function.  \(fp)disassemble\(fr) returns no value.

    No intermediate h-file is created if the keyword parameter
\(fp):h-file\(fr) is \(fp)nil\(fr) or if \(fp):h-file\(fr) is not
supplied.  Otherwise, an intermediate h-file is created under the name
specified by \(fp):h-file\(fr).  Similarly, the intermediate data-file
is specified by the keyword parameter \(fp):data-file\(fr).
\(endd)

\(fp)*eval-when-compile*\(ri '*eval-when-compile*)\(fr)\(ra)[\(fi)Variable\(fr)]\(bd)
The compiler processes each top-level form
in \(fi)not-compile-time\(fr) mode if the value of this
variable is \(fp)nil\(fr), and in \(fi)compile-time-too\(fr) mode,
otherwise.  See Section 5.3.3 of \(fi)Common Lisp Reference Manual\(fr)
for these two modes.  The initial value of this variable is \(fp)t\(fr).
\(endd)


\(fg) 

\(ce)Chapter 7. Declarations
\(set-page pp-7)
\(fr)
KCL supports all kinds of declarations described in the
\(fi)Common Lisp Reference Manual\(fr).  Any valid declaration
will affect the KCL environment in some way or another, although information
obtained by declarations, other than \(fp)special\(fr) declarations,
is mainly used by the KCL compiler.

     As described in the \(fi)Common Lisp Reference Manual\(fr),
Common Lisp declarations are divided into two classes: \(fi)proclamations\(fr)
and others.  A proclamation is a global declaration given by the function
\(fp)proclaim\(ri 'proclaim)\(fr), the top-level
macro \(fp)defvar\(ri 'defvar)\(fr), or the top-level
macro \(fp)defparameter\(ri 'defparameter)\(fr).  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 \(fi)local
declaration\(fr) and is given only by the special
form \(fp)declare\(ri 'declare)\(fr).  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 \(fi)Common Lisp Reference Manual\(fr),
\(reserve 6)\(fp)
    (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)))
\(fr)
the \(fp)inline\(fr) and the \(fp)special\(fr) declarations both remain
in effect within the surrounding \(fp)let\(fr) form.  In this case,
we say that the \(fp)let\(fr) form is the \(fi)surrounding
construct\(fr) of these declarations.

\(fp)proclamation\(ri 'proclamation) \(fi)decl-spec\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
This function is introduced to KCL so that the user can see currently
effective proclamations.  The argument \(fi)decl-spec\(fr) specifies the
proclamation to be checked.  It may be any declaration specification that
can be a valid argument to the function \(fp)proclaim\(fr).  The
function \(fp)proclamation\(fr) returns \(fp)t\(fr) if the specified
proclamation is still in effect.  Otherwise, it returns \(fp)nil\(fr).
For example,
\(reserve 2)\(fp)
    >(proclaim '(special *x*))  ;;; \(fr)The variable \(fp)*x*\(fr) is\(fp)
    nil                         ;;; \(fr)proclaimed to be globally special.\(fp)
\(reserve 2)
    >(proclamation '(special *x*))
    t
\(reserve 2)
    >(defvar *y*)               ;;; \(fr)Another way to proclaim a variable\(fp)
    nil                         ;;; \(fr)to be globally special.\(fp)
\(reserve 2)
    >(proclamation '(special *y*))
    t
\(fr)
\(endd)
\(fp)the\(ri 'the) \(fi)value-type\(fr) \(fi)form\(fr)\(ra)[\(fi)Special Form\(fr)]\(bd)
The KCL interpreter does actually check whether the value of the
\(fi)form\(fr) conforms to the data type specified by \(fi)value-type\(fr) and
signals an error if the value does not.  The type checking is performed by
the function \(fp)typep\(ri 'typep)\(fr).  For example,
\(fp)
    (the fixnum (foo))
\(fr)
is equivalent to
\(reserve 7)\(fp)
 (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)))))
\(fr)
On the other hand, the KCL compiler uses the \(fp)the\(fr) special form to
obtain type information for compiled code optimization.  No code for runtime
type-checking is embedded in the compiled code.
\(endd)
\(reserve 5)\(fg)
7.1. Declaration Specifiers\(set-page pp-7-1)
\(fr)
KCL recognizes all declaration specifiers defined in the
\(fi)Common Lisp Reference Manual\(fr).  The syntax of each such declaration
specifier is exactly the same as defined
in the \(fi)Common Lisp Reference Manual\(fr).  In addition, KCL recognizes the
\(fp)object\(ri 'object)\(fr) declaration specifier which is specific to KCL.

\(fp)special\(ri 'special)\(fr) { \(fi)variable-name\(fr) }*\(ra)[\(fi)Declaration Specifier\(fr)]\(bd)
The interpreter and the compiler of KCL both treat \(fp)special\(fr)
declarations exactly as described in the \(fi)Common Lisp Reference Manual\(fr).
\(endd)

\(fp)type\(ri 'type) \(fi)type\(fr) { \(fi)variable-name\(fr) }*\(ra)[\(fi)Declaration Specifier\(fr)]\(bd)
A \(fp)type\(fr) proclamation \(fp)(type \(fi)type var1
var2\(fr) ...\(fp))\(fr) specifies that the dynamic values of the
named variables are of the type \(fi)type\(fr).  A local \(fp)type\(fr)
declaration specifies that the variables mentioned are bound by the
surrounding construct and have values of the type \(fi)type\(fr) 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
\(fp)type\(fr) declarations is used by the compiler to optimize
the compiled code.  The behavior of the compiled code
is unpredictable if a wrong \(fp)type\(fr) declaration is supplied.  The
compiler detects certain wrong \(fp)type\(fr) declarations at compile
time.  For example,
\(reserve 5)\(fp)
	>(defun foo (x y)
	   (declare (fixnum x) (character y))
	   (setq x y)
	  ...))
	foo
\(reserve 4)
	>(compile 'foo)

	; (defun foo ...) is being compiled.
	;; Warning: Type mismatches between x and y.\(fr)

See Section 7.3 for further information on \(fp)type\(fr) declarations.
\(endd)

\(fi)type\(fr) { \(fi)variable-name\(fr) }*\(ra)[\(fi)Declaration Specifier\(fr)]\(bd)
\(fp)(\(fi)type var1 var2\(fr) ...\(fp))\(fr) is equivalent to
\(fp)(type \(fi)type var1 var2\(fr) ...\(fp))\(fr), provided
that \(fi)type\(fr) is one of the symbols in Table 4-1
of the \(fi)Common Lisp Reference Manual\(fr), other
than \(fp)function\(fr).  Declaration specification that begins
with \(fp)function\(fr) are
regarded as \(fp)function\(fr) declarations (see below).
\(endd)

\(fp)function\(ri 'function) \(fi)function-name argument-types\(fr) . \(fi)return-types\(fr)\(ra)[\(fi)Declaration Specifier\(fr)]\(bd)
A \(fp)function\(fr) declaration is used to obtain type
information for function call forms.
That is, a \(fp)function\(fr) declaration specifies
the argument and the return types
types of each form that calls the named function.
\(reserve 3)\(fp)
    (defun foo ()
      (declare (function bar (character) fixnum))
      (+ (bar (atcholi1)) (bar (atcholi2))))
\(fr)
In this example, the \(fp)function\(fr) declaration
specifies that
the two functions \(fp)atcholi1\(fr) and \(fp)atcholi2\(fr) both return
character objects when called
within the body of \(fp)foo\(fr), and that the function \(fp)bar\(fr)
returns fixnum objects when called within the body of \(fp)foo\(fr).
The type information given by
\(fp)function\(fr) declarations is used by the compiler to optimize
the compiled code.  The behavior of the compiled code
is unpredictable if a wrong \(fp)function\(fr) declaration is supplied.
The compiler detects certain wrong \(fp)function\(fr) declarations at compile
time.  For example,
\(reserve 5)\(fp)
    >(defun foo (x)
       (declare (fixnum x)
                (function bar (character) fixnum))
       (bar x))
    foo
\(reserve 4)
    >(compile 'foo)

    ; (defun foo ...) is being compiled.
    ;; Warning: The type of the form x is not character.
\(fr)
However, the compiler does not check the number of arguments, and thus,
the following function definition will be compiled successfully without
any warnings.
\(reserve 3)\(fp)
    (defun foo ()
      (declare (function bar (character character) fixnum))
      (+ (bar (atcholi1)) (bar (atcholi2) (atcholi3) (atcholi4))))
\(fr)
For this definition, the compiler assumes that the three functions
\(fp)atcholi1\(fr), \(fp)atcholi2\(fr), and \(fp)atcholi3\(fr) will
return fixnum objects.  The return type of \(fp)atcholi4\(fr) is
unknown at compile time.

The complete syntax of a \(fp)function\(fr) declaration is:
\(reserve 4)\(fp)
    (function \(fi)function-name\(fp)
      ( \(fr){\(fp) \(fi)type\(fp) \(fr)}*\(fp) \(fr)[\(fp) \(fr){\(fp) &optional \(fr)|\(fp) &rest \(fr)|\(fp) &key \(fr)}\(fp) \(fr){\(fp) \(fi)thing\(fp) \(fr)}*\(fp) \(fr)]\(fp) )
      \(fr){\(fp) (values \(fr){\(fp) \(fi)type\(fp) \(fr)}* \(fp)) \(fr)|\(fp) \(fr){\(fp) \(fi)type\(fp) \(fr)}*\(fp) \(fr)}\(fp)
     )
\(fr)
Although \(fp)&optional\(fr), \(fp)&rest\(fr), and \(fp)&key\(fr) markers
may appear in the list of argument types, only those \(fi)type\(fr)s are
recognized that appear before any such markers and the rest of the
list is simply ignored.  Note that
functions with \(fp)&optional\(fr), \(fp)&rest\(fr), or \(fp)&key\(fr)
parameters may still be declared by \(fp)function\(fr) declarations because
of the use of \(fp)function\(fr) declarations mentioned above.

The \(fp)values\(fr) construct in the specification of return types is almost
useless:  \(fp)(function \(fi)function-name argument-types\(fp)
(values \(fi)type1 type2 \(fr)...\(fp)))\(fr) is equivalent
to \(fp)(function \(fi)function-name
argment-types \(fi)type1 type2 \(fr)...\(fp))\(fr).  We, the implementors of
KCL wonder why the \(fp)value\(fr) construct was introduced in Common Lisp.

See Section 7.3 for further information on \(fp)function\(fr) declarations.
\(endd)

\(fp)ftype\(ri 'ftype) \(fi)function-type\(fr) { \(fi)function-name\(fr) }*\(ra)[\(fi)Declaration Specifier\(fr)]\(bd)
\(fi)function-type\(fr) must be a list whose first element
is the symbol \(fp)function\(fr).
\(fp)(ftype (function \(fr). \(fi)rest\(fp)) \(fi)function-name-1\(fr) ... \(fi)function-name-n\(fp))\(fr) is
equivalent to \(fi)n\(fr) consecutive \(fp)function\(fr) declarations
\(fp)(function \(fi)function-name-1\(fr) . \(fi)rest\(fp))\(fr) ...
\(fp)(function \(fi)function-name-n\(fr) . \(fi)rest\(fp))\(fr).
\(endd)

\(fp)notinline\(ri 'notinline) \(fr){ \(fi)function-name\(fr) }*\(ra)[\(fi)Declaration Specifier\(fr)]\(bd)
\(fp)(notinline \(fi)function1 function2\(fr) ...\(fp))\(fr) 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.
\(endd)

\(fp)inline\(ri 'inline) \(fr){ \(fi)function-name\(fr) }*\(ra)[\(fi)Declaration Specifier\(fr)]\(bd)
An \(fp)inline\(fr) proclamation cancels currently
effective \(fp)notinline\(fr) proclamations, and a local
\(fp)inline\(fr) declaration locally shadows currently effective
\(fp)notinline\(fr) declarations.
\(reserve 4)\(fp)
    >(defun foo (x)
       (cons (car x)
             (locally (declare (inline car)) (car x))))
    foo
\(reserve 4)
    >(defun bar (x)
       (cons (car x)
             (locally (declare (inline car)) (car x))))
    foo
\(reserve 2)
    >(proclaim '(notinline car))
    nil
\(reserve 2)
    >(compile 'foo)
    ...
\(reserve 2)
    >(proclaim '(inline car))
    nil
\(reserve 2)
    >(compile 'bar)
    ...
\(fr)
Usually, primitive functions such as \(fp)car\(fr) are
compiled in-line.  Therefore, in this example, only the first
call to \(fp)car\(fr) within \(fp)foo\(fr) is compiled not in-line,

In general, the KCL compiler compiles functions in-line
whenever possible.  Thus an \(fp)inline\(fr)
declaration \(fp)(inline \(fi)function1
function2\(fr) ...\(fp))\(fr) is worthless if none of the named functions
have previously been declared to be \(fp)notinline\(fr).
\(endd)

\(fp)ignore\(ri 'ignore) \(fr){ \(fi)variable-name\(fr) }*\(ra)[\(fi)Declaration Specifier\(fr)]\(bd)
Usually, the compiler issues a warning if a lexical variable is
never referred to.  \(fp)(ignore \(fi)var1\(fr) ... \(fi)varn\(fp))\(fr)
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.  \(fp)ignore\(fr) proclamations are simply ignored.
\(endd)

\(fp)optimize\(ri 'optimize) \(fr){ {\(fp) (\(fi)quality value\(fp)) \(fr)| \(fi)quality \(fr)} }*\(ra)[\(fi)Declaration Specifier\(fr)]\(bd)
KCL supports the four \(fp)optimize\(fr) qualities listed in the
\(fi)Common Lisp Reference Manual\(fr).  \(fp)speed\(ri 'speed)\(fr)
and \(fp)compilation-speed\(ri 'compilation-speed)\(fr) 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).  \(fp)(optimize (speed \(fi)n\(fp)))\(fr) and
\(fp)(optimize (compilation-speed \(fi)m\(fp)))\(fr) are equivalent,
where \(fi)n\(fr) and \(fi)m\(fr) are integers between \(fp)0\(fr)
and \(fp)3\(fr), and \(fi)m\(fr) is equal to \(fp)3-\(fi)n\(fr).  When
a KCL session is started, the \(fp)speed\(fr) quality is set
to \(fp)3\(fr).  That is, by default, the compiler generates the fastest
code in the longest compilation time.  The \(fp)space\(ri 'space)\(fr) quality
specifies whether the code size is important or not:  The compiled code
is a little bit larger and faster when compiled with the \(fp)space\(fr)
quality \(fp)0\(fr), than when compiled with the \(fp)space\(fr) quality
\(fp)1\(fr), \(fp)2\(fr), or \(fp)3\(fr).  When a KCL session is started,
the \(fp)space\(fr) quality is set to \(fp)0\(fr).  The \(fp)safety\(ri 'safety)\(fr)
quality determines how much runtime error checking code should be embedded in
the compiled code.  If the \(fp)safety\(fr) quality is \(fp)0\(fr), the
compiled code
scarcely does runtime error checking.  If
the \(fp)safety\(fr) quality is \(fp)1\(fr), then the compiled code for a
function will check the number of arguments to the function
at runtime.  If the \(fp)safety\(fr) quality is \(fp)2\(fr) or \(fp)3\(fr), then the
compiled code does full runtime error checking.  In addition, the
highest quality value \(fp)3\(fr) causes the compiler to treat all
functions as if they were declared to be \(fp)notinline\(fr).  When a KCL
session is started, the \(fp)safety\(fr) quality is set to
\(fp)0\(fr).
\(endd)

\(fp)declaration\(ri 'declaration) \(fr){ \(fi)name\(fr) }*\(ra)[\(fi)Declaration Specifier\(fr)]\(bd)
A \(fp)declaration\(fr) declaration is used exactly as specified in the
\(fi)Common Lisp Reference Manual\(fr).
\(endd)

\(fp)object\(ri 'object) \(fr){ \(fi)variable-name\(fr) }*\(ra)[\(fi)Declaration Specifier\(fr)]\(bd)
This is the only declaration specifier that is specific to KCL.  \(fp)(object
\(fi)var1\(fr) ... \(fi)varn\(fp))\(fr) 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.  \(fp)object\(fr) proclamations are simply ignored.
\(endd)
\(reserve 5)\(fg)
7.2. Significant Type Specifiers\(set-page pp-7-2)
\(fr)
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 \(fi)significant type specifiers\(fr).
\(reserve 19)\(fp)
          \(fs)1------------\(fp)  fixnum\(fs) 
          |
          \(fs)4------------\(fp)  character\(fs) 
          |
          \(fs)4------------\(fp)  short-float\(fs) 
          |
          \(fs)4------------\(fp)  long-float\(fs) 
          |
     \(fp)t  \(fs)--5--\(fp)  (array t)  \(fs)------------\(fp)  (vector t)\(fs) 
          |
          \(fs)4--\(fp)  (array fixnum)  \(fs)-------\(fp)  (vector fixnum)\(fs) 
          |
          \(fs)4--\(fp)  (array string-char)  \(fs)--\(fp)  string\(fs) 
          |
          \(fs)4--\(fp)  (array short-float)  \(fs)--\(fp)  (vector short-float)\(fs) 
          |
          \(fs)4--\(fp)  (array long-float)  \(fs)---\(fp)  (vector long-float)\(fs) 
          |
          \(fs)7--\(fp)  (array bit)  \(fs)----------\(fp)  bit-vector\(fs) 
\(fr)
Here, the lines indicate subtype relations; the right type
is a subtype of the left type.  For instance, \(fp)(vector t)\(fr)
is a subtype of \(fp)(array t)\(fr) and \(fp)t\(fr), and
\(fp)(array t)\(fr) itself is a subtype of \(fp)t\(fr).  However,
\(fp)(array t)\(fr) and \(fp)(array string-char)\(fr) are disjoint types.

     The function \(fp)subtypep\(fr) is used for the conversion to
significant type specifiers:  If the
first value of \(fp)(subtypep \(fi)raw-type type\(fp))\(fr) is
\(fp)t\(fr) for one of the significant type specifiers \(fi)type\(fr),
then the type specifier \(fi)raw-type\(fr) in
the declaration is converted to \(fi)type\(fr).  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 \(fp)fixnum\(fr), \(fp)(mod 3)\(fr), and
\(fp)(member 0 1)\(fr) are all converted to \(fp)fixnum\(fr), though they are
also subtypes of \(fp)t\(fr).

     Because of this type specifier conversion, KCL may sometimes regard
two seemingly distinct declarations as the same.  For example,
the following \(fp)type\(ri 'type)\(fr) declarations are
completely equivalent, internally in KCL.
\(fp)
    (declare (type fixnum x))

    (declare (type (mod 3) x))

    (declare (type (member 0 1) x))
\(fr)
Type specifiers in declaration specifications passed to the
KCL specific function
\(fp)proclamation\(fr) are also converted to significant type specifiers.  Thus, for example,
\(reserve 2)\(fp)
    >(proclaim '(function foo (fixnum) fixnum))
    nil
\(reserve 2)
    >(proclamation '(function foo ((mod 3)) (member 0 1)))
    t
\(reserve 2)
    >(proclamation '(function foo (number) character))
    nil
\(fr)
The first call to \(fp)proclamation\(fr) returns \(fp)t\(fr) because
both \(fp)(mod 3)\(fr) and \(fp)(member 0 1)\(fr) are converted to
\(fp)fixnum\(fr) before the function type of \(fp)foo\(fr) is checked.

\(reserve 5)\(fg)
7.3. Treatment of Type Declarations\(set-page pp-7-3)
\(fr)
KCL has several runtime stacks.  One of them is called the \(fi)value
stack\(fr) which is the "main stack" of KCL:  Arguments to functions and
resulted 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 \(fi)C stack\(fr), which can be accessed more efficiently
than the value stack.  In addition, arguments and resulted 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 \(fi)raw data\(fr) 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.

     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 \(fp)x\(fr) 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.)
\(reserve 6)\(fp)
    (defun foo ()
      (let ((x 0))
        ....
        (bar x)
        ....
        ))
\(fr)
Also suppose that the function \(fp)bar\(fr) expects its argument to be
passed via the value stack rather than via the C stack.  (This situation
typically occurs when \(fp)foo\(fr) and \(fp)bar\(fr) are defined in separate
source files.  See below.)  On call to \(fp)bar\(fr), the compiled code
of \(fp)foo\(fr) will allocate a fixnum cell on the heap and push the pointer
to this cell on the value stack as the argument to \(fp)bar\(fr).

     Another deficiency is that it is sometimes dangerous to allocate
a cell pointer onto the C stack.  (This occurs when
\(fp)object\(ri 'object)\(fr) 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
poped.

\(reserve 5)\(fg)
7.3.1. Variable Allocations\(set-page pp-7-3-1)
\(fr)
If a lexical variable is declared to be of \(fp)fixnum\(fr),
\(fp)character\(fr), \(fp)short-float\(fr), \(fp)long-float\(fr), 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 \(fp)0\(fr)), 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 \(fp)object\(ri 'object)\(fr) 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 \(fp)object\(fr) variable may
never be garbage collected unexpectedly.  For example,
\(reserve 5)\(fp)
    (do ((x (foo) (cdr x)))
        ((endp x))
        (let ((y (car x)))
             (declare (object y))
          (bar y)))
\(fr)
this \(fp)object\(fr) declaration is completely safe because the value of
the variable \(fp)y\(fr) is always a substructure of the value
of \(fp)x\(fr), which in turn is protected against garbage
collection.  Incidentally, loop variables of \(fp)dolist\(fr) may always be
declared as \(fp)object\(fr) variables, since the \(fp)dolist\(fr) form has
essentially the same control structure as the \(fp)do\(fr) form above.  On
the other hand, the result of evaluation of the following form is
unpredictable, because the cons cell pointed to from the \(fp)object\(fr)
variable \(fp)z\(fr) may be garbage collected before \(fp)bar\(fr) is called.
\(reserve 4)\(fp)
    (let ((z (cons x y)))
         (declare (object z))
      (foo (cons x y))
      (bar z))
\(fr)
     Lexical variables that are not declared to be of \(fp)fixnum\(fr),
\(fp)character\(fr), \(fp)short-float\(fr), \(fp)long-float\(fr), or
their subtypes, and that are not named in \(fp)object\(fr) declarations are
usually allocated on the value stack, but may possibly
be allocated on the C stack automatically by the compiler.

\(reserve 5)\(fg)
7.3.2. Built-in Functions that Operate on Raw Data Directly \(set-page pp-7-3-2)
\(fr)
Some built-in Common Lisp functions can directly operate on raw data, if
appropriate declarations are supplied.  The addition function \(fp)+\(fr) is
among such functions.
\(reserve 6)\(fp)
    (let ((x 1))
         (declare (fixnum x))
      ....
      (setq x (+ x 2))
      ....
      )
\(fr)
In the compiled code for this \(fp)let\(fr) form, the raw fixnum datum (i.e.,
the 32 bit signed integer) stored
in \(fp)x\(fr) is simply incremented by 2 and the resulted 32 bit signed
integer is stored back into \(fp)x\(fr).  The compiler is sure that
the addition for 32 bit signed integers
will be performed on the call to \(fp)+\(fr), because
the arguments are both fixnums
and the return value must be also a fixnum since the value
is to be assigned to the \(fp)fixnum\(fr) 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.
\(fp)
    (setq x (+ (* x 3) 2))
\(fr)
In order to obtain the optimal code,
a \(fp)the\(ri 'the)\(fr) special form should surround the multiplication.
\(fp)
    (setq x (+ (the fixnum (* x 3)) 2))
\(fr)

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

 1. arithmetic functions such as \(fp)+\(fr), \(fp)-\(fr),
\(fp)1+\(fr), \(fp)1-\(fr), \(fp)*\(fr), \(fp)floor\(fr), \(fp)mod\(fr),
\(fp)/\(fr), and \(fp)expt\(fr).

 2. predicates such as \(fp)eq\(fr), \(fp)eql\(fr), \(fp)equal\(fr), \(fp)zerop\(fr), \(fp)plusp\(fr), \(fp)minusp\(fr), \(fp)=\(fr), \(fp)/=\(fr), \(fp)<\(fr), \(fp)<=\(fr), \(fp)>\(fr), \(fp)>=\(fr), \(fp)char=\(fr), \(fp)char/=\(fr), \(fp)char<\(fr), \(fp)char<=\(fr), \(fp)char>\(fr), and \(fp)char>=\(fr).

 3. sequence processing functions that receive or return one or more
fixnum values, such as \(fp)nth\(fr), \(fp)nthcdr\(fr), \(fp)length\(fr), and \(fp)elt\(fr).

 4. array access functions such as \(fp)svref\(fr), \(fp)char\(fr), \(fp)schar\(fr), and \(fp)aref\(fr) (see below).

 5. system-internal functions for array update (see below).
 
 6. type-specific functions such as \(fp)char-code\(fr), \(fp)code-char\(fr), and \(fp)float\(fr).

     As mentioned in Section 2.5.1, array elements are represented in one of the 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,
\(reserve 13)\(fp)
    (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)))
      ....
      )
\(fr)
The \(fp)setf\(fr) form replaces the \(fp)i\(fr)-th element of the
array \(fp)a\(fr) by the raw fixnum value of \(fp)i\(fr).  The
\(fp)aref\(fr) form retrieves the raw fixnum datum stored
in \(fp)a\(fr).  This raw datum is then added to the raw fixnum
value of the fixnum variable \(fp)sum\(fr), producing the raw fixnum datum to be stored
in \(fp)sum\(fr).  The similar raw data handling is possible for
arrays of types
\(fp)(array fixnum)\(fr), \(fp)(vector fixnum)\(fr),
\(fp)(array string-char)\(fr), \(fp)string\(fr),
\(fp)(array short-float)\(fr), \(fp)(vector short-float)\(fr),
\(fp)(array long-float)\(fr), and \(fp)(vector long-float)\(fr).

\(reserve 5)\(fg)
7.3.3. Arguments/Values Passing\(set-page pp-7-3-3)
\(fr)
Function proclamations \(fp)(function \(fi)function-name\(fp) (\(fi)arg-type1 arg-type2\(fp) ...) \(fi)return-type\(fp) )\(fr)
or its equivalents give the compiler the
chance to generate the compiled code so that arguments to the named functions
and resulted values of the named functions 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 resulted 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.

     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.
\(reserve 12)\(fp)
    (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).
\(fr)
When \(fp)tak\(fr) is called with the arguments \(fp)18\(fr), \(fp)12\(fr),
and \(fp)6\(fr), the raw fixnum data of the arguments are set to the
parameters \(fp)x\(fr), \(fp)y\(fr), \(fp)z\(fr) 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 resulted values for
recursive calls to \(fp)tak\(fr) are passed via the C stack, and the
built-in functions \(fp)<\(fr) and \(fp)1-\(fr) directly operate on the
raw data.  Only at the return from the top-level call of \(fp)tak\(fr),
the resulted raw data value (which happens to be \(fp)7\(fr)) is reallocated
on the heap.  Note that both the \(fp)function\(fr)
proclamation and the
local \(fp)fixnum\(fr) declaration are necessary to obtain the optimal
code.  The \(fp)function\(fr) proclamation is necessary for arguments/values
passing via the C stack and the \(fp)fixnum\(fr) declaration is necessary to
allocate the parameters onto the C stack.


\(fg) 

\(ce)Chapter 8. Operating System Interface
\(set-page pp-8)
\(fr)

     KCL provides the following facilities that are not
defined in the \(fi)Common Lisp Reference Manual\(fr).


\(fp)save\(ri 'save)\(fi) filename\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
\(fp)save\(fr) saves the current memory
image into a program file \(fi)filename\(fr).  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.


\(fr)---------------------- \(fi)Note to KCL/AOS users\(fr) ----------------------

In KCL/AOS, if the filename does not contain the filetype \(fp).pr\(fr),
then the program file
is given the name \(fi)filename\(fp).pr\(fr).  Also \(fp)save\(fr) saves a
symbol table file with
the filetype \(fp).st\(fr).  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 \(fp)save\(fr),
these streams are not effective when the program file
is executed.  The function \(fp)save\(fr) of KCL/AOS does not terminate
the KCL process.

\(fr)--------------------------- \(fi)End of Note\(fr) ----------------------------


\(endd)
     Example:
\(fp)
	>(defun plus (x y) (+ x y))
	plus

	>(save "savefile")
	%

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

	>(plus 2 3)
	5

	>(bye)
	Bye.
	%
\(fr)

\(fr)---------------------- \(fi)Note to KCL/AOS users\(fr) ----------------------

Here is the example of \(fp)save\(fr) in
KCL/AOS.
\(fp)
	>(defun plus (x y) (+ x y))
	plus

	>(save "savefile")
	t

	>(bye)
	Bye.
	)

	) X SAVEFILE

	>(plus 2 3)
	5

	>(bye)
	Bye.
	)\(fr)

\(fr)--------------------------- \(fi)End of Note\(fr) ----------------------------


\(fp)system\(ri 'system) \(fi)string\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
Executes a Shell command as if \(fi)string\(fr) is an input to the Shell.  On return from the Shell command, \(fp)system\(fr) returns the exit code
of the command as an integer.


\(fr)---------------------- \(fi)Note to KCL/AOS users\(fr) ----------------------

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

\(fr)--------------------------- \(fi)End of Note\(fr) ----------------------------

\(endd)

\(fp)bye\(ri 'bye) &optional\(fi) exit-code\(fr)\(ra)[\(fi)Function\(fr)]
\(fp)by\(ri 'by)  &optional\(fi) exit-code\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
Terminates KCL and returns the \(fi)exit-code\(fr) to the parent process.  \(fi)exit-code\(fr) must be an integer and its default value is \(fp)0\(fr).
\(endd)


\(fr)---------------------- \(fi)Note to KCL/AOS users\(fr) ----------------------

The functions \(fp)bye\(fr) and \(fp)by\(fr) of KCL/AOS accept a string
instead of an \(fi)exit-code\(fr).  If \(fi)string\(fr) is supplied, these functions return the \(fi)string\(fr) to the father as the termination message.

\(fr)--------------------------- \(fi)End of Note\(fr) ----------------------------


The following functions \(fp)process\(ri 'process)\(fr), 
\(fp)termination-message\(ri 'termination-message)\(fr), and
\(fp)last-termination-message\(ri 'last-termination-message)\(fr)
are specific to KCL/AOS and are not supported in KCL on Unix.

\(fp)process\(ri 'process)\(fi) progname \(sm)\(fp)&optional \(fi)ipc-message\(fr)\(ra)[\(fi)Function\(fr)]
\(fp)&key \(sm):block\(ri ':block) :console\(ri ':console) :debug\(ri ':debug) :dir\(ri ':dir)\(br)
\(fp):input\(ri ':input) :output\(ri ':output) :username\(ri ':username)\(br)
:list\(ri ':list) :data\(ri ':data) :ioc\(ri ':ioc)\(fr)\(rm)\(bd)\(br)
This function is defined only in KCL/AOS.  \(fp)process\(fr) creates a process in the way as specified by
its arguments.

	\(fi)progname\(fr)		\(sm)The name of the process to create.  Must be a string.\(rm)

	\(fi)ipc-message\(fr)	\(sm)The IPC message passed to the process.  Must be a string.  Arguments in the message must be separated with commas '\(fp),\(fr)'.\(rm)

	\(fp):block\(fr)		\(sm)If non-\(fp)nil\(fr), KCL blocks its execution while the son executes.  Defaults to \(fp)t\(fr).\(rm)

	\(fp):console\(fr)	\(sm)The name of the file to be associated to \(fp)@console\(fr).  Must be a string.  No file is associated if \(fp):console\(fr) is not specified and if the \(fp):ioc\(fr) argument (see below) is specified with a non-\(fp)nil\(fr) value.  \(fp):console\(fr) supercedes \(fp):ioc\(fr).\(rm)

	\(fp):debug\(fr)		If non-\(fp)nil\(fr), the son runs in the debug mode.

	\(fp):input\(fr)		\(sm)The name of the file to be associated to \(fp)@input\(fr).  Must be a string.  No file is associated if \(fp):input\(fr) is not specified and if the \(fp):ioc\(fr) argument (see below) is specified with a non-\(fp)nil\(fr) value.  \(fp):input\(fr) supercedes \(fp):ioc\(fr).\(rm)

	\(fp):output\(fr)		\(sm)The name of the file to be associated to \(fp)@output\(fr).  Must be a string.  No file is associated if \(fp):output\(fr) is not specified and if the \(fp):ioc\(fr) argument (see below) is specified with a non-\(fp)nil\(fr) value.  \(fp):output\(fr) supercedes \(fp):ioc\(fr).\(rm)

	\(fp):username\(fr)	\(sm)The user-name of sub-process.  Must be a string.  If not specified, the current user-name is used.\(rm)

	\(fp):list\(fr)		\(sm)If a string, the name of the file to be associated to \(fp)@list\(fr).  If \(fp)t\(fr), the file currently associated to \(fp)@list\(fr) is used.  If \(fp)nil\(fr), or if not specified, no list file is passed to the son.\(rm)

	\(fp):data\(fr)		\(sm)If a string, the name of the file to be associated to \(fp)@data\(fr).  If \(fp)t\(fr), the file currently associated to \(fp)@data\(fr) is used. If \(fp)nil\(fr), or if not specified, no data file is passed to the son.\(rm)

	\(fp):ioc\(fr)		\(sm)If non-\(fp)nil\(fr), current \(fp)@input\(fr), \(fp)@output\(fr), and \(fp)@console\(fr) files are passed to the son.  If not specified, these files are not passed unless specified by the \(fp):console\(fr), \(fp):input\(fr), or \(fp):output\(fr) arguments.\(rm)
\(endd)
     Example:
\(fp)
	>(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

	>
\(fr)

\(fp)termination-message\(ri 'termination-message)\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
This function is defined only in KCL/AOS.  \(fp)termination-message\(fr) returns a string consisting of the termination message of a son.  Used in connection with the function \(fp)process\(fr).
\(endd)

\(fp)last-termination-message\(ri 'last-termination-message)\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
This function is defined only in KCL/AOS.  \(fp)last-termination-message\(fr)
flushes all the messages currently spooled and
returns the last termination message.
\(endd)

\(fg) 

\(ce)Chapter 9. Macros
\(set-page pp-9)
\(fr)
\(fg)
9.1. System Macros\(set-page pp-9-1)
\(fr)
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.
\(reserve 6)\(fp)
    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
\(fr)
For these macro forms, the functions \(fp)macro-function\(fr) and
\(fp)special-form-p\(fr) both return non-\(fp)nil\(fr) values:
\(fp)macro-function\(fr) returns the macro expansion function
and \(fp)special-form-p\(fr) returns \(fp)t\(fr).  Of course,
functions such as \(fp)macroexpand\(ri 'macroexpand)\(fr) and
\(fp)macroexpand-1\(ri 'macroexpand-1)\(fr) will successfully
expand macro forms for these system macros.

\(reserve 5)\(fg)
9.2. Defmacro Lambda-Lists\(set-page pp-9-2)
\(fr)
A \(fi)defmacro lambda-list\(fr) is a lambda-list-like construct that is used
as the third element in the \(fp)defmacro\(fr) form,
\(fp)
    (defmacro \(fi)name\(fp) \(fi)defmacro-lambda-list\(fp) \(fr){\(fi)declaration\(fp) \(fr)|\(fp) \(fi)doc-string\(fr)}*\(fp) \(fr){\(fi)form\(fr)}* \(fp))\(fr)

The description of defmacro lambda-lists in the \(fi)Common Lisp Reference Manual\(fr) is quite
ambiguous.  KCL employs the
following syntax.
\(reserve 12)
The complete syntax of a defmacro lambda-list is:
\(fp)
( \(fr)[\(fp) &whole \(fi)var\(fp) \(fr)]\(fp)
  \(fr)[\(fp) &environment \(fi)var\(fp) \(fr)]\(fp)
  \(fr){\(fp) \(fi)pseudo-var\(fp) \(fr)}*\(fp)
  \(fr)[\(fp) &optional \(fr){\(fp) \(fi)var\(fp) \(fr)|\(fp) ( \(fi)pseudo-var\(fp) \(fr)[\(fp) \(fi)initform\(fp) \(fr)[\(fp) \(fi)pseudo-var\(fp) \(fr)]\(fp) \(fr)]\(fp) ) \(fr)}*\(fp) \(fr)]\(fp)
  \(fr){\(fp)  \(fr)[\(fp) \(fr){\(fp) &rest \(fr)|\(fp) &body \(fr)}\(fp) \(fi)pseudo-var\(fp) \(fr)]\(fp)
     \(fr)[\(fp) &key \(fr){\(fp) \(fi)var\(fp) \(fr)|\(fp) ( \(fr){\(fp) \(fi)var\(fp) \(fr)|\(fp) ( \(fi)keyword\(fp) \(fi)pseudo-var\(fp) ) \(fr)}\(fp) \(fr)[\(fp) \(fi)initform\(fp) \(fr)[\(fp) \(fi)pseudo-var\(fp) \(fr)] ]\(fp) ) \(fr)}*\(fp)
	    \(fr)[\(fp) &allow-other-keys \(fr)] ]\(fp)
     \(fr)[\(fp) &aux \(fr){\(fp) \(fi)var\(fp) \(fr)|\(fp) ( \(fi)pseudo-var\(fp) \(fr)[\(fp) \(fi)initform\(fp) \(fr)]\(fp) ) \(fr)}*\(fp) \(fr)]\(fp)
  \(fr)|\(fp)  . \(fi)var\(fp) \(fr)}\(fp)
 )
\(fr)
where \(fi)pseudo-var\(fr) is either a symbol or a list of the following form:
\(reserve 8)\(fp)
( \(fr){\(fp) \(fi)pseudo-var\(fp) \(fr)}*\(fp)
  \(fr)[\(fp) &optional \(fr){\(fp) \(fi)var\(fp) \(fr)|\(fp) ( \(fi)pseudo-var\(fp) \(fr)[\(fp) \(fi)initform\(fp) \(fr)[\(fp) \(fi)pseudo-var\(fp) \(fr)]\(fp) \(fr)]\(fp) ) \(fr)}*\(fp) \(fr)]\(fp)
  \(fr){\(fp)  \(fr)[\(fp) \(fr){\(fp) &rest \(fr)|\(fp) &body \(fr)}\(fp) \(fi)pseudo-var\(fp) \(fr)]\(fp)
     \(fr)[\(fp) &key \(fr){\(fp) \(fi)var\(fp) \(fr)|\(fp) ( \(fr){\(fp) \(fi)var\(fp) \(fr)|\(fp) ( \(fi)keyword\(fp) \(fi)pseudo-var\(fp) ) \(fr)}\(fp) \(fr)[\(fp) \(fi)initform\(fp) \(fr)[\(fp) \(fi)pseudo-var\(fp) \(fr)] ]\(fp) ) \(fr)}*\(fp)
	    \(fr)[\(fp) &allow-other-keys \(fr)] ]\(fp)
     \(fr)[\(fp) &aux \(fr){\(fp) \(fi)var\(fp) \(fr)|\(fp) ( \(fi)pseudo-var\(fp) \(fr)[\(fp) \(fi)initform\(fp) \(fr)]\(fp) ) \(fr)}*\(fp) \(fr)]\(fp)
  \(fr)|\(fp)  . \(fi)var\(fp) \(fr)}\(fp)
 )
\(fr)
The defmacro lambda-list keyword \(fp)&whole\(ri '&whole)\(fr) may
appear only at the top-level,
first in the defmacro lambda-list.  It is not allowed within
\(fi)pseudo-var\(fr).  Use of the \(fp)&whole\(fr) keyword does not affect
the processing of the rest of the defmacro lambda-list:
\(fp)
    (defmacro foo (&whole w x y) ... )
\(fr)
and
\(fp)
    (defmacro foo (x y) ... )
\(fr)
both bind the variables \(fp)x\(fr) and \(fp)y\(fr) to the second and the
third elements, respectively, of macro forms of \(fp)foo\(fr).

     The defmacro lambda-list keyword \(fp)&environment\(ri '&environment)\(fr) may
appear only at the
top-level, first in the defmacro lambda-list if \(fp)&whole\(ri '&whole)\(fr) is not
supplied, or immediately after the variable that follows \(fp)&whole\(fr), if
\(fp)&whole\(fr) is supplied.  \(fp)&environment\(fr) is not allowed within
\(fi)pseudo-var\(fr).  Like \(fp)&whole\(fr), use of \(fp)&environment\(fr)
does not affect the processing of the rest of
the defmacro lambda-list.  If an \(fp)&environment\(fr) parameter is supplied and if 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 \(fp)ignore\(fr) declaration.

     The defmacro lambda-list keyword \(fp)&body\(fr) is completely equivalent to
the \(fp)&rest\(fr) keyword.  KCL takes no special action for \(fp)&body\(fr)
parameters.

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

     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 \(fp)safety\(ri 'safety)\(fr)
optimize level is zero (that is,
while the value of \(fp)(proclamation '(optimize (safety 0)))\(fr) is
\(fp)t\(fr)), then the generated code does not perform argument
checking at all.  Otherwise, the compiled
code does check the validity of arguments.

\(fg) 

\(ce)Chapter 10. The C Language Interface
\(set-page pp-10)
\(fr)
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.

     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 \(fi)c-file\(fr), 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 \(fp)Clines\(fr) and \(fp)defCfun\(fr) 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
\(fp)#define\(fr) and \(fp)#include\(fr) into the c-file.  In order that
such C-language functions be invoked from KCL, another top-level macro
\(fp)defentry\(ri 'defentry)\(fr) is used.  This macro defines
a Lisp function whose body consists of the calling
sequence to the specified C-language function.

     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 \(fp)Clines\(fr) or \(fp)defCfun\(fr) 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.

     We define some terminology here which are used throughout
this Chapter.  A \(fi)C-id\(fr) is either a Lisp string consisting of a
valid C-language identifier, or a Lisp symbol
whose print-name, with all its alphabets turned into lower cases,
is a valid C identifier.  Thus the
symbol \(fp)foo\(fr) is equivalent to the string \(fp)"foo"\(fr)
when used as a C-id.  Similarly, a \(fi)C-expr\(fr) is a
string or a symbol that may be regarded as a C-language expression.  A \(fi)C-type\(fr) is one of
the Lisp symbols\(fp) int\(fr), \(fp)char\(fr), \(fp)float\(fr), \(fp)double\(fr), and\(fp) object\(fr).  Each corresponds to a data
type in the C language; \(fp)object\(fr) is the type of Lisp object and
other C-types are primitive
data types in the C language.


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

     In order to clearly distinguish C code from other part of Lisp programs,
we, the implementors of KCL, make it our rule to start each C code line
with a percent sign '\(fp)%\(fr)'.  We define \(fp)%\(fr) as a read macro
which returns the rest of the line as a string.  For \(fp)\(fr)example,
\(reserve 12)\(fp)
	;;; 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)));
	%	}

	)
\(fr)
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.
\(reserve 3)\(fp)
	(set-macro-character
	    #\\%
	    #'(lambda (stream char) (values (read-line stream)))))
\(fr)
Here, the lambda-expression returns the first value of \(fp)read-line\(ri 'read-line)\(fr) by using \(fp)values\(ri 'values)
\(fr)as a filter.

     When interpreted, a \(fp)Clines\(fr) macro form expands to \(fp)nil\(fr).
\(endd)

\(fp)defentry\(ri 'defentry) \(fi)function\(fr) \(fi)parameter-list\(fr) \(fi)C-function\(fr)\(ra)[\(fi)Macro\(fr)]\(bd)
\(fp)defentry\(fr) defines a Lisp function whose body consists of
the calling sequence to a
C-language function.  \(fi)function\(fr) is the name of the Lisp function
to be defined, and\(fi) C-function\(fr) specifies the C function
to be invoked.  \(fi)C-function\(fr) must be either a list
\(fp)(\(fi)type\(fp) \(fi)C-id\(fp))\(fr) or \(fi)C-id\(fr),
where \(fi)type\(fr) and \(fi)C-id\(fr) are the type and
the name of the C function.  \(fi)type\(fr) must be a C-type or
the symbol \(fp)void\(fr) which means that the C function returns
no value.  \(fp)(object \(fi)C-id\(fp))\(fr) may be abbreviated
as \(fi)C-id\(fr).  \(fi)parameter-list\(fr) is a list of C-types
for the parameters of the C function.  For example,
the following \(fp)defentry
\(fr)form defines a Lisp function \(fp)tak\(fr) from
which the C function \(fp)tak\(fr) above is called.
\(fp)
	(defentry tak (int int int) (int tak))
\(fr)
The Lisp function \(fp)tak\(fr) defined by this \(fp)defentry\(fr) form
requires three arguments.  The arguments are converted to
\(fp)int\(fr) values before they are passed to the C function.  On return
from the C
function, the returned \(fp)int\(fr) 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.

     A \(fp)defentry\(fr) form is treated in the above way only when it appears as a top-level form of a Lisp source file.  Otherwise, a \(fp)defentry\(fr) form expands to \(fp)nil\(fr).
\(endd)

\(fp)defla\(ri 'defla) \(fi)name\(fr) \(fi)lambda-list\(fr) {\(fi)declaration\(fr) | \(fi)doc-string\(fr)}* {\(fi)form\(fr)}*\(ra)[\(fi)Macro\(fr)]\(bd)
When interpreted, \(fp)defla\(fr) is exactly the same as \(fp)defun\(fr).  That is, \(fp)(defla\(fr) \(fi)name
lambda-list\(fr) . \(fi)body\(fp))\(fr)
expands to \(fp)(defun\(ri 'defun)\(fr) \(fi)name lambda-list\(fr) . \(fi)body\(fp))\(fr).  However, \(fp)defla
\(fr)forms are completely ignored by the compiler; no C-language code will be
generated for \(fp)defla\(fr) forms.  The primary use of \(fp)defla\(fr) 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.  \(fp)defla\(fr) is short for\(fi) DEF\(fr)ine \(fi)L\(fr)isp\(fi) A\(fr)lternative.

     Suppose you have a Lisp source file whose contents are:
\(reserve 12)\(fp)
	;;; 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)));
	%	}

	)
\(reserve 2)
	;;;  TAK calls the C function tak defined above.
	(defentry tak (int int int) (int tak))
\(reserve 7)
	;;;  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))))
\(fr)
When this file is loaded into KCL, the interpreter uses the Lisp version of the \(fp)tak
\(fr)definition.  Once this file have been compiled, and when the generated fasl file is
loaded into KCL, function call to tak is actually the call to the C version of \(fp)tak\(fr).
\(endd)

\(fp)defCfun\(ri 'defCfun) \(fi)header\(fr) \(fi)n\(fr) {\(fi)element\(fr)}*\(ra)[\(fi)Macro\(fr)]\(bd)
\(fp)defCfun\(fr) defines a C-language function which calls
Lisp functions and/or which
handles Lisp objects.  \(fi)header\(fr) is a string consisting of the C
code for
\(reserve 3)
	the optional \(fi)type-specifier\(fr) of the C function,
	the \(fi)function-declarator\(fr) of the C function, and
	the \(fi)type-decl-list\(fr) of the parameters to the C function.

(For the C-language terminology, refer to \(fi)The C Programming Language\(fr) by Brian W.  Kernighan and Dennis M. Ritchie.)  The rest of the C function
definition, i.e., the
\(fi)function-statement\(fr), is given by\(fi) element\(fr)s.  Each \(fi)element\(fr) may be a string, in which case
the string is treated in the same way as the arguments to the \(fp)Clines\(fr) macro.  Or else,
the \(fi)element\(fr) is a list
\(fp)((\(fi)name arg1\(fr) ... \(fi)argn\(fp)) \(fi)place1\(fr) ... \(fi)placem\(fp))\(fr).  The compiler
translates this list into a calling sequence to the Lisp function
whose name is \(fi)name\(fr).  As will be
mentioned later, \(fi)name\(fr) may be \(fp)quote\(ri 'quote)\(fr),
but \(fi)name\(fr) may not be the name of other special
form or a macro.  The \(fi)arg\(fr)s specify the arguments to the function
and the \(fi)place\(fr)s
specify where the values should go.  Thus the list-formed \(fi)element\(fr) could be regarded
as something like the Lisp form:
\(reserve 3)\(fp)
	(multiple-value-setq
	    (\(fi)place1\(fr) ... \(fi)placem\(fp))
	    (\(fi)name\(fr) \(fi)arg1\(fr) ... \(fi)argn\(fp))).
\(fr)
Each \(fi)arg\(fr) is a list\(fp) (\(fi)C-type\(fp) \(fi)C-expr\(fp))\(fr), where \(fi)C-expr\(fr) is any C-language expression of the
type \(fi)C-type\(fr).  If \(fi)type\(fr) is \(fp)object\(fr), then \(fi)arg\(fr) may be written simply as \(fi)C-expr\(fr).  Similarly,
each \(fi)place\(fr) is a list\(fp) (\(fi)C-type\(fp) \(fi)C-expr\(fp))\(fr), or it may be abbreviated as\(fi) C-expr\(fr) if \(fi)C-type\(fr) is
\(fp)object\(fr).  The \(fi)C-expr\(fr) in this case is any \(fi)lvalue\(fr) (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.

     The function call is performed as follows.  The \(fi)arg\(fr)s 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 \(fi)place\(fr), i.e., the first returned value goes to \(fi)place1\(fr), the second to \(fi)place2\(fr),
and so on.  If there are more \(fi)place\(fr)s than the values returned, extra values of \(fp)nil
\(fr)are assigned to the remaining \(fi)place\(fr)s.  If there are more values than \(fi)place\(fr)s, the
excess values are simply discarded.  If necessary, Lisp-to-C type conversion may
take place before each returned value is assigned.

     If the Lisp function is called just for side-effects, then the list-formed \(fi)element
\(fr)may be abbreviated as a one-level list\(fp) (\(fi)name\(fp) \(fi)arg1\(fr) ... \(fi)argn\(fp))\(fr).

     As a special case, if a list-formed \(fi)element\(fr) is of the form\(fp) ((quote \(fi)value\(fp)) \(fi)place\(fr)),
the Lisp object \(fi)value\(fr) is assigned to \(fi)place\(fr).  Here \(fi)value\(fr) may be any Lisp object.

     The following \(fp)defCfun\(fr) form defines the C function\(fp) silly\(fr) which adds \(fp)100\(fr) to
the value of the parameter \(fp)x\(fr) and prints the result in three different ways.  The
second argument to\(fp) defCfun\(fr) will be described later, and the user may ignore it.
\(reserve 8)\(fp)
	(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"))
	)
\(fr)
     When a C function handles Lisp objects (i.e., data of type \(fp)object\(fr)), 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.
\(reserve 7)\(fp)
	(defCfun "object list2(x,y) object x,y;" 0
	%	object z;
		('nil z)
		((cons y z) z)
		((cons x z) z)
	%	return(z);
	)
\(fr)
When invoked, \(fp)list2\(fr) first sets \(fp)nil\(fr) to the variable \(fp)z\(fr), conses \(fp)y\(fr) to \(fp)z\(fr), and then conses
\(fp)x\(fr).  Each time \(fp)cons\(fr) is called, a new cons cell is allocated and the pointer to this cell
is stored in \(fp)z\(fr).  However, there is no way to inform
the garbage collector that the cells are referenced from the C variable \(fp)z\(fr).  Suppose
that the cons cell allocated by the first \(fp)cons\(fr) is the last cons cell available at that
time.  Then, during execution of the second call to \(fp)cons\(fr), the garbage collector
begins to run and, unfortunately, the cons cell in \(fp)z\(fr) will be destroyed so that the
cell can be recycled for further use.

     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 \(fi)n\(fr) to \(fp)defCfun\(fr) is used to reserve \(fi)n\(fr) such places for each call to the
C function.  In the body of the C function, these reserved places are referenced as
\(fp)vs[0]\(fr), ..., \(fp)vs[\(fi)n-1\(fp)]\(fr).  The function \(fp)list2\(fr) above, therefore, should be revised as
\(fp)\(fr)follows.
\(reserve 6)\(fp)
	(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]);
	)
\(fr)
Notice that \(fp)return\(fr) is replaced by \(fp)Creturn\(fr).  \(fp)Creturn\(fr) is similar to \(fp)return\(fr) except
that \(fp)Creturn\(fr) releases the reserved places on
return from the function.  In the C
code within a \(fp)defCfun\(fr) form,
write "\(fp)Creturn(\(fi)value\(fp));\(fr)" instead of
"\(fp)return(\(fi)value\(fp));\(fr)", and
write "\(fp)Cexit;\(fr)" instead of "\(fp)return;\(fr)".

     Again, a \(fp)defCfun\(fr) form has the above meaning only when it appears as a top-level form in a Lisp source file.  Otherwise, the form expands to \(fp)nil\(fr).\(endd)

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

     Here we list the complete syntax of \(fp)Clines\(fr), \(fp)defentry\(fr), and \(fp)defCfun\(fr) macro forms.
\(reserve 2)
	\(fp)Clines\(fr)-form:
		\(fp)(Clines \(fr){ \(fi)string\(fr) }* \(fp))
\(reserve 4)
	defentry\(fr)-form:
		\(fp)(defentry \(fi)function-symbol
			\(fp)( \(fr){ \(fi)C-type\(fr) }*\(fp) )
			\(fr){ \(fi)C-function-name\(fr) | \(fp)( \(fr){ \(fi)C-type\(fr) | \(fp)void\(fr) } \(fi)C-function-name\(fp) ) \(fr)} \(fp))
\(reserve 5)
	defCfun\(fr)-form:
		\(fp)(defCfun \(fi)string  non-negative-integer
			\(fr){ \(fi)string
			\(fr)  | \(fp)(\(fi)function-symbol\(fr) { \(fi)value\(fr) }* \(fp))
			\(fr)  | \(fp)((\(fi)function-symbol\(fr) { \(fi)value\(fr) }* \(fp)) \(fr){ \(fi)place\(fr) }* \(fp)) \(fr)} \(fp))
\(reserve 3)
	\(fr)value:
	place:
		{ \(fi)C-expr\(fr) | \(fp)(\(fi)C-type C-expr\(fp))\(fr) }
\(reserve 3)
	C-function-name:
	C-expr:
		{ \(fi)string\(fr) | \(fi)symbol\(fr) }
\(reserve 2)
	C-type:
		{ \(fp)object\(fr) | \(fp)int\(fr) | \(fp)char\(fr) | \(fp)float\(fr) | \(fp)double\(fr) }

\(fg) 

\(ce)Chapter 11. The Editor
\(set-page pp-11)
\(fr)

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

\(fp)ed\(ri 'ed) &optional\(fi) filename\(fr)\(ra)[\(fi)Function\(fr)]\(bd)
\(fp)ed\(fr) invokes FeCl2
and sets the edit file of FeCl2 to \(fi)filename\(fr).  If the filetype of the file is not explicitly specified,
then the \(fi)filename\(fr) is
first merged into \(fp)#".lsp"\(fr).
\(endd)

The FeCl2 editor is not supported by other versions of KCL.  The function \(fp)ed\(fr) of KCL/VAX, KCL/SUN, and KCL/UST calls the vi editor.  If you hate vi, define your own \(fp)ed\(fr) function using the function
\(fp)system\(ri 'system)\(fr) described in Chapter 8.  

\(fg) 

\(ce)Appendix A. KCL Summary
\(set-page pp-summary)
\(fr)
The following table lists all symbols defined in KCL.  Each line has one of the
following form.

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

\(load 'summary.lsp)

\(fg) 

\(ce)Appendix B. An Overview of Kyoto Common Lisp
\(set-page pp-overview)
\(fr)
\(fi)Kyoto Common Lisp\(fr) (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.


\(reserve 5)\(fg)
KCL is a full Common Lisp system.
\(fr)
KCL is a full implementation of the Common Lisp language described in
the \(fi)Common Lisp Reference Manual\(fr):


\(ce)\(fi)Common Lisp: The Language\(fr).
\(ce)by Guy L. Steele et al.
\(ce)Digital Press, 1984

KCL supports all Common Lisp functions, macros, and special forms defined
in the \(fi)Common Lisp Reference Manual\(fr).  All Common Lisp variables
and constants are defined in KCL exactly as
described in the \(fi)Common Lisp Reference Manual\(fr).


\(reserve 5)\(fg)
KCL is available on several machines already.
\(fr)
Currently, there are four major versions of KCL:

	1. KCL/AOS
	   Machine: \(sm)Data General's Eclipse MV series super-minicomputers (MV10000, MV8000, MV6000, and MV4000)\(rm)
	   Operating System: \(sm)Data General's original AOS/VS (Advanced Operating System / Virtual Storage)\(rm)

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

	3. KCL/SUN
	   Machine: \(sm)Sun Microsystems' Sun Workstation (MC68000 base)\(rm)
	   Operating System: UNIX 4.2 bsd

	4. KCL/UST
	   Machine: \(sm)Sumitomo Electric Industries and Digital Computer Laboratory's personal workstation Ustation E15 (MC68000 base)\(rm)
	   Operating System: UNIX V (Uniplus' version)

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.

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

	* IBM (and IBM-compatible) M series machines
	* Apollo Domain
	* Perkins Elmer
	* VAX 11 (running VMS)
	* VAX 11 (running Eunice, the Unix emulator)
	* Eclipse MV (running DGUX, Data General's native Unix)


\(reserve 5)\(fg)
KCL is written in C and Lisp
\(fr)
The kernel of KCL is written in C, including:

	* memory management and garbage collection
	* the evaluator (or interpreter)
	* Common Lisp special forms

The KCL compiler is entirely written in Common Lisp.

Each Common Lisp function or macro is written either in C or in Lisp.
\(reserve 3)
	in C:
		418 Common Lisp functions
		11 Common Lisp macros
\(reserve 3)
	in Lisp:
		133 Common Lisp functions
		59 Common Lisp macros

The size of the source code is:
\(reserve 6)
	C code		 705 Kbytes
	Common Lisp functions and macros written in Lisp
			 173 Kbytes
	The compiler	 264 Kbytes
	\(fs)-------------------------\(fr)
		total	1142 Kbytes

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

	* bignum multiplication
	* bignum division
	* \(sm)bit table manipulation of the garbage collector\(rm)

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


\(reserve 5)\(fg)
KCL/AOS is built up by old-fashioned bootstrapping
\(fr)
When KCL/AOS, the original version of KCL, was born, the following steps
were taken to build it up.

	1. \(sm)Compile all C code with the C compiler and link them
all.  A subset of KCL is ready to run at this moment.\(rm)

	2. \(sm)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.\(rm)

	3. \(sm)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.\(rm)

	4. \(sm)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.\(rm)

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.


\(reserve 5)\(fg)
Objects are represented by cells.
\(fr)
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:
\(reserve 7)\(fp)
		\(fs)1----------2-----------3\(fp)
		|  'CONS'  |  mark-bit \(fs)|
		\(fs)4----------8-----------6\(fp)
		|      car-pointer     \(fs)|
		\(fs)4----------------------6\(fp)
		|      cdr-pointer     \(fs)|
		\(fs)7----------------------9\(fp)
\(fr)
and a fixnum cell consists of two words:
\(reserve 5)\(fp)
		\(fs)1----------2-----------3\(fp)
		| 'FIXNUM' |  mark-bit \(fs)|
		\(fs)4----------8-----------6\(fp)
		|    fixnum-value      \(fs)|
		\(fs)7----------------------9\(fp)
\(fr)
Array headers and compiled-function headers are represented in this way, and
array elements and compiled code are placed elsewhere.

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.

Cells of small fixnums ranging from \(fp)-1024\(fr) to \(fp)1023\(fr) and
cells of characters
are pre-allocated in fixed locations.  Thus, for example,
\(fp)
	(eq 1023 1023)
\(fr)
yields \(fp)t\(fr), whereas
\(fp)
	(eq 1024 1024)
\(fr)
yields \(fp)nil\(fr).


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

	* pages that contain cells consisting of the same number of words
	* pages that contain binary data such as compiled function code
	* pages that contain relocatable data such as array elements

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
\(fi)n\(fr) words, the page is used for cells with \(fi)n\(fr) 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.

The actual configuration of the KCL heap is:
\(reserve 4)\(fp)
  lower address                                             higher address
	\(fs)1-------------------------------2--------2---------------------3\(fp)
	|  cell pages and binary pages  |  hole  |  relocatable pages  \(fs)|
	\(fs)7-------------------------------8--------8---------------------9\(fp)
\(fr)
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 the 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.

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:
\(reserve 4)\(fp)
  lower address                        higher address
	\(fs)1--------------------------------------3\(fp)
	|  cell/binary pages and static pages  \(fs)|
	\(fs)7--------------------------------------9\(fp)
\(fr)
Notice that the hole is not included in the object module; it is allocated
only when the KCL system is started.  This saves the secondary storage
a little bit.  The maximum size of the hole is about
100 pages (= 200 Kbytes).


\(reserve 5)\(fg)
KCL uses five stacks.
\(fr)
KCL uses the following stacks.

	* Value Stack, for
	     arguments/values passing
	     lexical variables allocation
	     temporary values saving

	* Frame Stack, consisting of
	     catch, block, tagbody frames

	* Bind Stack, for
	     shallow binding of dynamic variables

	* Invocation History Stack, maintaining
	     information for debugging

	* 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


\(reserve 5)\(fg)
Arguments/values are passed via the value stack.
\(fr)
To show the argument/value passing mechanism, here we list the actual code
for the Common Lisp function \(fp)cons\(fr).
\(reserve 10)\(fp)
	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;
	}
\(fr)
We adopted the convention that the name of a function
that implements a Common Lisp function begins with '\(fp)L\(fr)', followed
by the name of the Common Lisp function.  (Strictly speaking,
'\(fp)-\(fr)' and '\(fp)*\(fr)' in the Common Lisp function name are replaced
by '\(fp)_\(fr)' and '\(fp)A\(fr)', respectively,
to obey the syntax of C.)  Arguments to
functions are pushed on the value stack.  The stack pointer
\(fp)vs_base\(fr) (value stack base) points to the first argument and
another pointer \(fp)vs_top\(fr) points to the stack location next to the
last argument.  Thus, for example, when \(fp)cons\(fr) is called
with the first argument \(fp)1\(fr) and the second argument \(fp)2\(fr), 
the value stack looks:
\(reserve 12)\(fp)
	          \(fs)4---------6\(fp)
	 vs_top \(fs)->\(fp)|         \(fs)|
	          \(fs)4---------6\(fp)
	          |    2    \(fs)|
	          \(fs)4---------6\(fp)
	vs_base \(fs)->\(fp)|    1    \(fs)|
	          \(fs)4---------6\(fp)
	          |         |
	          :         :
	          |         \(fs)|
	  \(fp)bottom  \(fs)7---------9\(fp)
                  value stack
\(fr)
\(fp)check_arg(2)\(fr) in the code of \(fp)Lcons\(fr) checks if exactly
two arguments are supplied to \(fp)cons\(fr).  That is, it checks whether
the difference of \(fp)vs_top\(fr) and \(fp)vs_base\(fr) is \(fp)2\(fr), and
if not, it causes an error.  \(fp)allocate_object(t_cons)\(fr) allocates a
cons cell in the heap and returns the pointer to the cell.  After the
\(fp)car\(fr) and the \(fp)cdr\(fr) 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.  \(fp)vs_base\(fr) points to the first returned value
and \(fp)vs_top\(fr) points to the stack location next
to the last returned value.  \(fp)vs_pop\(fr)
in the code above decrements \(fp)vs_top\(fr) by one.
\(reserve 12)\(fp)
	          \(fs)4---------6\(fp)
	          |         \(fs)|
	          \(fs)4---------6\(fp)
	 vs_top \(fs)->\(fp)|         \(fs)|
	          \(fs)4---------6\(fp)
	vs_base \(fs)->\(fp)| (1 . 2) \(fs)|
	          \(fs)4---------6\(fp)
	          |         |
	          :         :
	          |         \(fs)|
	  \(fp)bottom  \(fs)7---------9\(fp)
                  value stack
\(fr)
Because the same stack pointers are used both for argument passing and
for return value passing, the Common Lisp function \(fp)values\(fr) does
almost nothing.
\(reserve 16)\(fp)
	On the call of (values 1 2)    On return from (values 1 2)

	          \(fs)4---------6\(fp)                \(fs)4---------6\(fp)
	 vs_top \(fs)->\(fp)|         |       vs_top \(fs)->\(fp)|         \(fs)|
	          \(fs)4---------6\(fp)                \(fs)4---------6\(fp)
	          |    2    |                |    2    \(fs)|
	          \(fs)4---------6\(fp)                \(fs)4---------6\(fp)
	vs_base \(fs)->\(fp)|    1    |      vs_base \(fs)->\(fp)|    1    \(fs)|
	          \(fs)4---------6\(fp)                \(fs)4---------6\(fp)
	          |         |                |         |
	          :         :                :         :
	          |         |                |         \(fs)|
	  \(fp)bottom  \(fs)7---------9\(fp)        bottom  \(fs)7---------9\(fp)
                  value stack                 value stack
\(fr)
In most cases, the caller of a function uses only the first returned value
which is pointed to by \(fp)vs_base\(fr).  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 \(fp)nil\(fr) to the stack entry which is pointed to
by \(fp)vs_base\(fr), whenever it returns no value at all.  Thus, for
instance, the actual code for the Common Lisp function \(fp)values\(fr) is:
\(reserve 4)\(fp)
	Lvalues()
	{
		vs_top[0] = Cnil;
	}
\(fr)
where \(fp)Cnil\(fr) is a global variable that always contains the pointer to
\(fp)nil\(fr).  See why this works.


\(reserve 5)\(fg)
The interpreter uses A-lists.
\(fr)
The KCL interpreter uses three A-lists (Association lists) to represent
lexical environment.

	* One for variable bindings
	* One for local function/macro definitions
	* One for tag/block bindings

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.


\(reserve 5)\(fg)
The invocation history stack is used for debugging.
\(fr)
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:
\(reserve 3)\(fp)
	\(fs)1---------------------2---------------------3\(fp)
	|        form         | environment-pointer \(fs)|
	\(fs)7---------------------8---------------------9\(fp)
\(fr)
or a pair of a function name and a pointer to the value stack:
\(reserve 3)\(fp)
	\(fs)1---------------------2---------------------3\(fp)
	|    function-name    | value-stack-pointer \(fs)|
	\(fs)7---------------------8---------------------9\(fp)
\(fr)
The former is pushed on the invocation history stack
when an interpreted code is evaluated.  The \(fi)form\(fr)
is the interpreted code itself and the \(fi)environment-pointer\(fr) 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 \(fi)function-name\(fr)
is the name of the called function and the \(fi)value-stack-pointer\(fr)
points to the
value stack location which is pointed to by \(fp)vs_base\(fr)
when the function is called.  For both kinds, the element on the invocation
history stack is poped at the end of the evaluation.

Let us see how the invocation history stack is used for debugging.
\(fp)
	>(defun fact (x)		;;; \(fr)Wrong definition of the\(fp)
	   (if (= x 0)			;;; \(fr)factorial function.\(fp)
	       one			;;; one\(fr) should be \(fp)1\(fr).\(fp)
	       (* x (fact (1- x)))))
	fact
	
	>(fact 3)			;;; \(fr)Tries \(fp)3!
	
	Error: The variable ONE is unbound.
	Error signalled by IF.
	
	Broken at IF.
	>>:b				;;; \(fr)Backtrace.\(fp)
	Backtrace: eval > fact > if > fact > if > fact > if > fact > IF
					;;; \(fr)Currently at the last \(fp)if.
	>>:h				;;; \(fr)Help.\(fp)

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


\(reserve 5)\(fg)
The KCL compiler generates intermediate code in C.
\(fr)
The KCL compiler is essentially a translator from Common Lisp to C.  Given
a Lisp source file, the compiler first generates three intermediate files:

	* a C-file which consists of the C version of the Lisp program
	* an H-file which consists of declarations referenced in the C-file
	* a Data-file which consists of Lisp data to be used at load time

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 \(fi)Fasl-file\(fr).  The generated Fasl-file can
be loaded into the KCL system by the Common Lisp
function \(fp)load\(fr).  By default, the three intermediate files
are deleted after the compilation, but, if asked, the compiler
leaves them.

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

	* \(sm)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.\(rm)

	* \(sm)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.\(rm)

	* \(sm)Hardware-dependent optimizations such as register allocations
are done by the C compiler.\(rm)

The demerits are:

	* \(sm)At those sites where no C compiler is available,
the users cannot compile their Lisp programs.\(rm)

	* \(sm)The compilation time takes 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.\(rm)


\(reserve 5)\(fg)
The compiler mimics human C programmer.
\(fr)
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:
\(fp)
	(defun add1 (x) (1+ x))
\(fr)
The compiler generates the following intermediate C code.
\(reserve 21)\(fp)
	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;
	}
\(fr)
The C function \(fp)L1\(fr) implements the Lisp
function \(fp)add1\(fr).  This relation is established by \(fp)MF\(fr) in
the initialization function \(fp)init_code\(fr), which is invoked at
load time.  There,
the vector \(fp)VV\(fr) consists of Lisp objects; \(fp)VV[0]\(fr) in this
example
holds the Lisp symbol \(fp)add1\(fr).  \(fp)VM3\(fr) in the definition
of \(fp)L1\(fr) is a C macro declared in the corresponding H-file.  The actual
value of \(fp)VM3\(fr) is the number of value stack locations used
by \(fp)L1\(fr), i.e., \(fp)2\(fr) in this example.  Thus the following
macro definition is found in the H-file.
\(fp)
	#define VM3 2
\(fr)
When the compiled \(fp)add1\(fr) is called, the value stack looks:
\(reserve 14)\(fp)
	On the call of (add1 1)    On return from (add1 1)

	          \(fs)4---------6\(fp)                \(fs)4---------6\(fp)
	          |         |       vs_top \(fs)->\(fp)|         \(fs)|
	          \(fs)4---------6\(fp)                \(fs)4---------6\(fp)
	 vs_top \(fs)->\(fp)|         |      vs_base \(fs)->\(fp)|    2    \(fs)|
	          \(fs)4---------6\(fp)                \(fs)4---------6\(fp)
	vs_base \(fs)->\(fp)|    1    |                |    1    \(fs)|
	          \(fs)4---------6\(fp)                \(fs)4---------6\(fp)
	          |         |                |         |
	          :         :                :         :
	          |         |                |         \(fs)|
	  \(fp)bottom  \(fs)7---------9\(fp)        bottom  \(fs)7---------9\(fp)
                  value stack                 value stack
\(fr)
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.


\(reserve 5)\(fg)
Lexical environment of compiled closures is represented by a list.
\(fr)
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.

Ordinarily, lexical variables in a compiled function \(fi)f\(fr)
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 "environment list", which is local to \(fi)f\(fr).  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 \(fi)f\(fr) is called.  An
element is pushed on the environment list
when a variable to be enclosed in closures is bound, and is poped
when the binding is no more in effect.  That is, at any moment during
execution of \(fi)f\(fr), 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 \(fi)f\(fr), 
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.

Let us see an example.  Suppose the following function has been compiled.
\(fp)
	(defun foo (x)
	  (let ((a #'(lambda () (incf x)))
	        (y x))
	    (values a #'(lambda () (incf x y)))))
\(fr)
\(fp)foo\(fr) returns two compiled closures.  The first closure increments
\(fp)x\(fr) by one, whereas the second closure increments \(fp)x\(fr)
by the initial value of \(fp)x\(fr).  Both closures return the incremented
value of \(fp)x\(fr).
\(fp)
	>(multiple-value-setq (f g) (foo 10))
	#<compiled-closure nil>

	>(funcall f)
	11

	>(funcall g)
	21

	>
\(fr)
After this, the two compiled closures look:
\(reserve 12)\(fp)
	second closure        y:                    x:
	\(fs)1-------2------3\(fp)      \(fs)1-------2------3\(fp)      \(fs)1------2------3\(fp)
	|  **   |    \(fs)--5----->\(fp)|  10   |    \(fs)--5----->\(fp)|  21  | nil  \(fs)|
	\(fs)7-------8------9\(fp)      \(fs)7-------8------9\(fp)      \(fs)7------8------9\(fp)
	                                                \(fs)^\(fp)
	                      first closure             \(fs)|
	                      \(fs)1-------2------3\(fp)          \(fs)|
	                      \(fp)|   *   |    \(fs)--5----------9\(fp)
	                      \(fs)7-------8------9\(fp)

   * : \(fr)address of the compiled code for \(fp)#'(lambda () (incf x))
  ** : \(fr)address of the compiled code for \(fp)#'(lambda () (incf x y))
\(fr)


\(reserve 5)\(fg)
Declarations increase code efficiency.
\(fr)
Declarations, especially \(fp)type\(fr) and \(fp)function\(fr) declarations,
increase the efficiency of the compiled code.  For example, for the
following Lisp source file, with two Common Lisp declarations added,
\(reserve 10)\(fp)
	(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))))
\(fr)
the compiler generates the following C code.
\(reserve 20)\(fp)
	/*  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;
	}
\(fr)
The main part of the \(fp)tak\(fr) function is \(fp)LI2\(fr).  If
redundant parentheses are removed, macros are expanded, and
identifiers are renamed, we obtain the following code equivalent
to \(fp)LI2\(fr).
\(reserve 12)\(fp)
	/*  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)));
		}
	}
\(fr)
This is almost hand-written \(fp)tak\(fr) code in C.  The only overhead is
the use of the temporary variables \(fp)t1\(fr) and \(fp)t2\(fr).  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,
\(fp)
	return(tak(tak(x-1,y,z),tak(y-1,z,x),tak(z-1,x,y)));
\(fr)
the C compiler of Eclipse AOS/VS evaluates the three inner calls
to \(fp)tak\(fr) 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 \(fp)tak\(fr),
the order of evaluation
does not matter actually, because \(fp)tak\(fr) causes no side effects.  But
the KCL compiler does not know that.  The KCL compiler still has room
for improvements.


\(reserve 5)\(fg)
KCL does not have "disassembler".
\(fr)
Common Lisp defines a function \(fp)disassemble\(fr), which is supposed to
disassemble a compiled function and
to display the assembler code.  According to the \(fi)Common Lisp
Reference Manual\(fr),
\(fi)
	This is primary useful for debugging the compiler, ..
\(fr)
This is, however, \(fi)useless\(fr) 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 \(fp)disassemble\(fr) function in KCL accepts
not-yet-compiled functions only and displays the translated C code.
\(fp)
	>(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;
	}
	
	>
\(fr)


\(reserve 5)\(fg)
KCL/AOS has its own screen editor.
\(fr)
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 \(fp)ed\(fr).  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, \(fp)ed\(fr)
invokes the \(fp)vi\(fr) editor of Unix.


\(reserve 5)\(fg)
KCL has C language interface.
\(fr)
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,
\(fp)Clines\(fr) and \(fp)defentry\(fr) are top-level macros specific
to KCL.  The \(fp)Clines\(fr) macro form specifies the C code to be embedded,
in terms of strings, and the \(fp)defentry\(fr) form defines an entry
of the specified C function from KCL.
\(reserve 11)\(fp)
	(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"))
\(fr)


\(reserve 5)\(fg)
Port to VAX took three days.
\(fr)
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:

	1. \(sm)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.\(rm)

	2. \(sm)File system interface was changed to fit Unix 4.2 bsd.\(rm)

	3. \(sm)The following system parameters were redefined because
Vax's representation of floating point numbers differs from that of Eclipse.
\(fp)
		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
\(fr)\(rm)
	4. \(sm)For the same reason as above, the following machine-dependent
Common Lisp functions were rewritten.
\(fp)
		decode-float
		scale-float
		float-radix
		float-digits
		float-precision
		integer-decode-float
\(fr)\(rm)
	5. The three assembler routines were rewritten.

	6. \(sm)The in-core loader that loads Fasl-file into the KCL memory was
changed.  This was a simple job because we used the standard linkage
editor \(fp)ld\(fr) of Unix.\(rm)

	7. \(sm)The memory dump routine was rewritten.\(rm)

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.


\(reserve 5)\(fg)
Port to SUN took three evenings.
\(fr)
Port to SUN Workstation was much easier than port to VAX, mainly because the
operating system is the same for both VAX and SUN.

	1. The compiler top-level of KCL/VAX was used without changes.

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

	3. \(sm)The system parameters that depend on the representation of
floating point numbers were rewritten.\(rm)

	4. \(sm)The Common Lisp functions that depend on the representation of
floating point numbers were redefined.\(rm)

	5. The three assembler routines were rewritten.

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

	7. The memory dump routines of KCL/VAX was used without changes.

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.


\(reserve 5)\(fg)
Port to Ustation took one week.
\(fr)
Port to Ustation was relatively a hard job.  It took almost a week.  
The major difficulity was that
the C compiler of Unix V on 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 \(fi)function-name\(fr) is given
the name \(fp)L\(fi)function-name\(fr).  Thus, for example, the Common Lisp functions on packages such as
\(fp)
		package-name
		package-nickname
		package-shadowing-symbols
		package-use-list
		package-used-by-list
		packagep
\(fr)
are implemented by the C functions whose names all begin
with \(fp)Lpackage\(fr).  These C functions are regarded
to have 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.


\(reserve 5)\(fg)
KCL is relatively compact.
\(fr)
The size of the object module of the whole KCL system (including the Compiler)
is:
\(reserve 4)
		KCL/AOS		1.78 Mbytes
		KCL/VAX	1.45 Mbytes
		KCL/SUN		1.56 Mbytes
		KCL/UST		1.56 Mbytes

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).


\(reserve 5)\(fg)
Gabriel's benchmark.
\(fr)
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 second) for
compiled program.  '\(fp)*\(fr)' indicates that the time
includes garbage-collection time.  The data of S-1 Lisp and Spice Lisp are
found in:
\(reserve 6)
\(fi)
\(ce)Performance and Evaluation of Lisp Systems
\(ce)by
\(fr)\(ce)Richard P. Gabriel
\(ce)Computer Systems Ser. Research Reports,
\(ce)MIT Press, 1985

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 paper above.


\(reserve 30)\(fp)
 \(fp)Benchmark |   Boyer  |  Browse  | Destruct | Traverse | Traverse \(fs)|
 \(fp)  Test    |          |          |          |Initialize|    Run   \(fs)|
 \(fs)-------------------------------------------------------------------\(fp)
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp) Kyoto CL |   11.02  |   18.09  |    3.15  |    5.75  |   44.16  \(fs)|
 \(fp)  MV10000 |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp) Kyoto CL |   43.73  |   68.15* |    8.00  |   14.42  |  151.20  \(fs)|
 \(fp)  VAX 780 |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp) Kyoto CL |   43.60* |   73.08* |   10.23  |   20.38  |  118.60  \(fs)|
 \(fp)   E15    |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp) Kyoto CL |   47.00  |   81.37  |   14.10  |   26.30  |  160.58  \(fs)|
 \(fp)   SUN    |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)Symbolics |   11.99  |   30.8   |    3.03  |    8.62  |   49.95  \(fs)|
 \(fp)   3600   |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)  S-1 CL  |   10.03  |   10.2   |    0.91  |    1.93  |   30.1   \(fs)|
 \(fp) Mark IIA |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)  Spice   |  134.79  |  359.63  |   17.78  |   41.75  |  490.6   \(fs)|
 \(fp)   Perq   |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)  DEC CL  |   46.79  |  118.51  |    6.38  |   20.76  |  161.68  \(fs)|
 \(fp)  VAX 780 |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)   DG CL  |   29.3   |   59.91  |    6.95  |   27.77  |   45.86  \(fs)|
 \(fp)  MV10000 |          |          |          |          |          \(fs)|
 \(fp)
 
 
 \(fp)Benchmark |    Tak   |   Stak   |   Ctak   |   Takl   |   Takr   \(fs)|
 \(fp)  Test    |          |          |          |          |          \(fs)|
 \(fs)-------------------------------------------------------------------\(fp)
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp) Kyoto CL |    0.42  |    1.90  |    4.35  |    5.13  |    0.54  \(fs)|
 \(fp)  MV10000 |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp) Kyoto CL |    1.45  |    6.03  |   14.02  |   19.97  |    1.75  \(fs)|
 \(fp)  VAX 780 |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp) Kyoto CL |    1.17  |    7.63  |    9.58  |   16.10  |    1.38  \(fs)|
 \(fp)   E15    |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp) Kyoto CL |    1.48  |   11.02  |   16.88  |   23.35  |    1.67  \(fs)|
 \(fp)   SUN    |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)Symbolics |    0.6   |    2.58  |    7.65  |    6.44  |    0.6   \(fs)|
 \(fp)   3600   |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)  S-1 CL  |    0.29  |    4.31  |    0.82  |    2.92  |    0.58  \(fs)|
 \(fp) Mark IIA |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)  Spice   |    4.7   |   13.5   |    8.4   |   24.0   |    7.7   \(fs)|
 \(fp)   Perq   |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)  DEC CL  |    1.83  |    4.11  |    8.09  |    7.34  |    3.42  \(fs)|
 \(fp)  VAX 780 |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)   DG CL  |    0.89  |    3.09  |    1.79  |    5.52  |    1.21  \(fs)|
 \(fp)  MV10000 |          |          |          |          |          \(fs)|
 \(fp)
 
 
 \(fp)Benchmark |   Deriv  |  DDeriv  |   Div2   |   Div2   |    FFT   \(fs)|
 \(fp)  Test    |          |          | Iterative| Recursive|          \(fs)|
 \(fs)-------------------------------------------------------------------\(fp)
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp) Kyoto CL |    4.85  |    5.93  |    1.99  |    2.73  |    1.55  \(fs)|
 \(fp)  MV10000 |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp) Kyoto CL |   18.98  |   23.07  |    7.48  |   11.25  |    9.07  \(fs)|
 \(fp)  VAX 780 |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp) Kyoto CL |   22.07* |   25.38* |    9.95* |   12.60* |   74.62  \(fs)|
 \(fp)   E15    |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp) Kyoto CL |   20.72  |   24.77  |    9.32  |   12.30  |   94.07  \(fs)|
 \(fp)   SUN    |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)Symbolics |    5.12  |    5.24  |    1.85  |    2.89  |    4.75  \(fs)|
 \(fp)   3600   |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)  S-1 CL  |    4.99  |    3.27  |    0.82  |    1.49  |    1.44  \(fs)|
 \(fp) Mark IIA |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)  Spice   |   71.8   |   77.7   |   28.15  |   40.69  |   59.0   \(fs)|
 \(fp)   Perq   |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)  DEC CL  |   13.76  |   ---    |    5.0   |    9.84  |   32.69  \(fs)|
 \(fp)  VAX 780 |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)   DG CL  |    5.6   |    8.11  |    2.86  |    4.48  |   62.78  \(fs)|
 \(fp)  MV10000 |          |          |          |          |          \(fs)|
 \(fp)
 
 
 \(fp)Benchmark |   Puzzle |  Triang  |  Fprint  |   Fread  |  Tprint  \(fs)|
 \(fp)  Test    |          |          |          |          |          \(fs)|
 \(fs)-------------------------------------------------------------------\(fp)
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp) Kyoto CL |    6.76  |  104.85  |    1.98  |    2.45  |    1.74  \(fs)|
 \(fp)  MV10000 |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp) Kyoto CL |   20.57  |  366.12  |    5.73  |    5.77  |    6.55  \(fs)|
 \(fp)  VAX 780 |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp) Kyoto CL |   41.30  |  341.23* |    9.83  |    6.07  |   11.58  \(fs)|
 \(fp)   E15    |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp) Kyoto CL |   49.13  |  499.68  |   10.05  |    7.62  |    8.50  \(fs)|
 \(fp)   SUN    |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)Symbolics |   13.89  |  151.7   |    2.6   |    4.6   |    4.9   \(fs)|
 \(fp)   3600   |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)  S-1 CL  |    1.82  |   62.06  |   ---    |   ---    |   ---    \(fs)|
 \(fp) Mark IIA |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)  Spice   |   75.14  | 1488.85  |   20.0   |   26.0   |   22.6   \(fs)|
 \(fp)   Perq   |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)  DEC CL  |   47.48  |  360.85  |    3.94  |    7.24  |    2.85  \(fs)|
 \(fp)  VAX 780 |          |          |          |          |          \(fs)|
 \(fp)          |          |          |          |          |          \(fs)|
 \(fp)   DG CL  |  138.2   |  151.2   |    2.35  |    4.65  |    2.83  \(fs)|
 \(fp)  MV10000 |          |          |          |          |          |
\(fr)


\(fg) 

\(ce)Appendix C. Kyoto Common Lisp Installation Guide
\(set-page pp-installation)
\(fr)
This appendix explains how to install the KCL system, separately for
each version of KCL.


\(reserve 5)\(fg)
C.1. Installation of KCL/AOS\(set-page pp-install-aos)
\(fr)
\(reserve 3)
1. Prepare a directory (hereafter called \(fi)KCL directory\(fr)) for Kyoto Common
Lisp.  In the following examples, we suppose that the KCL directory is
\(fp):UDD:KCL\(fr).

\(reserve 3)
2. Load the distribution tape to the KCL directory.
\(reserve 3)\(fp)
	) DIR
	:UDD:KCL
	) LOAD
\(fr)
You will find that the subdirectory \(fp)PORT\(fr) has been created.  The \(fp)PORT\(fr) subdirectory contains everything that is needed to run KCL.  Files in this directory are:
\(reserve 2)
    Documents:
	\(fp)README\(fr)			this file
\(reserve 5)
    Executable files:
	\(fp)KCL.PR\(fr)			the KCL interpreter and compiler
	\(fp)KCL.ST\(fr)
	\(fp)BUILD_FASL.PR\(fr)		the fasl-file builder
	\(fp)FECL2.PR\(fr)		the FeCl2 editor
\(reserve 5)
    Command files:
	\(fp)KCL.CLI\(fr)			to invoke KCL
	\(fp)LC.CLI\(fr)			to invoke the KCL compiler
	\(fp)LC1.CLI\(fr)			to invoke the KCL compiler
	\(fp)FECL2.CLI\(fr)		to invoke the FeCl2 editor
\(reserve 2)
     Header file:
	\(fp)CMPINCLUDE.H\(fr)		the header file for the KCL compiler
\(reserve 2)
     Miscellaneous:
	\(fp)FECL2.CMD\(fr)		FeCl2 editor command table

\(reserve 3)
3. Customize the command files.

The command file \(fp)KCL.CLI\(fr) consists of the following command lines
to invoke the KCL interpreter.
\(reserve 4)\(fp)
	push;prom pop
	sea :usr:dgc [!sea]
	x :udd:[!user]:port:%0-% :udd:[!user]:port:
	pop
\(fr)
Replace the two occurrences of "\(fp)[!user]\(fr)" with the name of the KCL directory
(i.e., \(fp)KCL\(fr) in our example).
\(reserve 4)\(fp)
	push;prom pop
	sea :usr:dgc [!sea]
	x :udd:KCL:port:%0-% :udd:KCL:port:
	pop
\(fr)
And move this file to an appropriate command directory, say \(fp):UTIL,\(fr) so
that all KCL users can access it.

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

You can use the commands \(fp)LC.CLI\(fr) and \(fp)LC1.CLI\(fr) to invoke the compiler directly
from the CLI.  The content of \(fp)LC.CLI\(fr) is:
\(reserve 7)\(fp)
	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
\(fr)
Customize these command files in the same way as for the \(fp)KCL.CLI\(fr) command file
above.

\(reserve 3)
4. Install the header file

Copy the header file \(fp)CMPINCLUDE.H\(fr) to the standard directory for C include
files, say \(fp):USR:DGC\(fr).

\(reserve 5)\(fg)
C.2. Installation of KCL/VAX\(set-page pp-install-vax)
\(fr)
\(reserve 3)
1. Prepare a directory (hereafter called \(fi)KCL directory\(fr)) for Kyoto Common
Lisp.  In the following examples, we suppose that the KCL directory is
\(fp)/usr/kcl\(fr).

\(reserve 3)
2. Load the distribution tape to the KCL directory.
\(reserve 3)\(fp)
	% pwd
	/usr/kcl
	% tar x
\(fr)
You will find that the subdirectory \(fp)unixport\(fr) has been created.  The \(fp)unixport\(fr) subdirectory contains everything that is needed to run KCL and
the KCL compiler.  Files in this directory are:
\(reserve 2)
    Documents:
	\(fp)readme\(fr)			this file
\(reserve 2)
    Executable files:
	\(fp)saved_kcl\(fr)		the KCL interpreter and compiler
\(reserve 4)
    Command files:
	\(fp)kcl\(fr)			to invoke KCL
	\(fp)lc\(fr)			to invoke the KCL compiler
	\(fp)lc1\(fr)			to invoke the KCL compiler
\(reserve 2)
     Header file:
	\(fp)cmpinclude.h\(fr)		the header file for the KCL compiler

\(reserve 3)
3. Customize the command files.

The command file \(fp)kcl\(fr) consists of a single line command to invoke the KCL
interpreter.
\(reserve 2)\(fp)
	#
	~/unixport/saved_kcl ~/unixport/
\(fr)
Replace two '\(fp)~\(fr)'s with the pathname of the KCL directory (i.e., \(fp)/usr/kcl\(fr) in our example).
\(reserve 2)\(fp)
	#
	/usr/kcl/unixport/saved_kcl /usr/kcl/unixport/
\(fr)
And move this file to an appropriate command directory, say \(fp)/usr/bin\(fr), so
that all KCL users can access it.

You can use the commands \(fp)lc\(fr) and \(fp)lc1\(fr) to invoke the compiler directly from the
shell.  The content of \(fp)lc\(fr) is:
\(reserve 3)\(fp)
	#
	echo Compiling $1.lsp
	~/unixport/saved_kcl ~/unixport/ $1 $1 U1000
\(fr)
Customize these command files in the same way as for the kcl command file
above.

\(reserve 3)
4. Install the header file

Copy the header file \(fp)cmpinclude.h\(fr) to the standard directory for C include
files, say \(fp)/usr/include\(fr).


\(reserve 5)\(fg)
C.3. Installation of KCL/SUN\(set-page pp-install-sun)
\(fr)
\(reserve 3)
1. Prepare a directory (hereafter called \(fi)KCL directory\(fr)) for Kyoto Common
Lisp.  In the following examples, we suppose that the KCL directory is
\(fp)/usr/kcl\(fr).

\(reserve 3)
2. Load the distribution tape to the KCL directory.
\(reserve 3)\(fp)
	% pwd
	/usr/kcl
	% tar x
\(fr)
You will find that the subdirectory \(fp)unixport\(fr) has been created.  The \(fp)unixport\(fr) subdirectory contains everything that is needed to run KCL and
the KCL compiler.  Files in this directory are:
\(reserve 2)
    Documents:
	\(fp)readme\(fr)			this file
\(reserve 2)
    Executable files:
	\(fp)saved_kcl\(fr)		the KCL interpreter and compiler
\(reserve 4)
    Command files:
	\(fp)kcl\(fr)			to invoke KCL
	\(fp)lc\(fr)			to invoke the KCL compiler
	\(fp)lc1\(fr)			to invoke the KCL compiler
\(reserve 2)
     Header file:
	\(fp)cmpinclude.h\(fr)		the header file for the KCL compiler

\(reserve 3)
3. Customize the command files.

The command file \(fp)kcl\(fr) consists of a single line command to invoke the KCL
interpreter.
\(reserve 2)\(fp)
	#
	~/unixport/saved_kcl ~/unixport/
\(fr)
Replace two '\(fp)~\(fr)'s with the pathname of the KCL directory (i.e., \(fp)/usr/kcl\(fr) in
our example).
\(reserve 2)\(fp)
	#
	/usr/kcl/unixport/saved_kcl /usr/kcl/unixport/
\(fr)
And move this file to an appropriate command directory, say \(fp)/usr/bin\(fr), so
that all KCL users can access it.

You can use the commands lc and lc1 to invoke the compiler directly from the
shell.  The content of lc is:
\(reserve 3)\(fp)
	#
	echo Compiling $1.lsp
	~/unixport/saved_kcl ~/unixport/ $1 $1 U1000
\(fr)
Customize these command files in the same way as for the kcl command file
above.

\(reserve 3)
4. Install the header file

Copy the header file \(fp)cmpinclude.h\(fr) to the standard directory for C include
files, say \(fp)/usr/include\(fr).


\(reserve 5)\(fg)
C.4. Installation of KCL/UST\(set-page pp-install-ust)
\(fr)
\(reserve 3)
1. Prepare a directory (hereafter called \(fi)KCL directory\(fr)) for Kyoto Common
Lisp.  In the following examples, we suppose that the KCL directory is
\(fp)/usr/kcl\(fr).

\(reserve 3)
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.)
\(reserve 3)\(fp)
	% pwd
	/usr/kcl
	% tar xvfBM /dev/rdy0g 1976
\(fr)
You will find that the subdirectory \(fp)unixport\(fr) has been created.  The \(fp)unixport\(fr) subdirectory contains everything that is needed to run KCL and
the KCL compiler.  Files in this directory are:
\(reserve 2)
    Documents:
	\(fp)readme\(fr)			this file
\(reserve 4)
    Executable files:
	\(fp)saved_kcl\(fr)		the KCL interpreter and compiler
	\(fp)ild\(fr)			incremental loader
	\(fp)trans\(fr)			translator from Unix 4.2 to Unix V
\(reserve 4)
    Command Source files:
	\(fp)kcl.c\(fr)			to invoke KCL
	\(fp)lc.c\(fr)			to invoke the KCL compiler
	\(fp)lc1.c\(fr)			to invoke the KCL compiler
\(reserve 2)
     Header file:
	\(fp)cmpinclude.h\(fr)		the header file for the KCL compiler

\(reserve 3)
3. Customize the command files.

The source file \(fp)kcl.c\(fr) consists of a C-language program to invoke the KCL
interpreter.  Replace all \(fp)/usr/ukcl\(fr) in this file with the pathname of the KCL directory
(i.e., \(fp)/usr/kcl\(fr) in our example), and compile this file.
\(fp)
	% cc -o kcl kcl.c
\(fr)
And move the object file to an appropriate command directory, say \(fp)/usr/bin\(fr),
so that all KCL users can access it.

You can use the source files \(fp)lc.c\(fr) and \(fp)lc1.c\(fr) to invoke the compiler directly
from the shell.  Customize these source files in the same way as for the kcl command file above.

\(reserve 3)
4. Install the header file

Copy the header file \(fp)cmpinclude.h\(fr) to the standard directory for C include
files, say \(fp)/usr/include\(fr).

\(setq *page-number* (1- pp-contents))

\(fg) 

\(ce)Table of Contents

\(fr)\(bd)
 Preface\(ra)\(do-string (format nil "~3d" pp-preface))
 Acknowledgements\(ra)\(do-string (format nil "~3d" pp-acknowledgements))
 Table of Contents\(ra)\(do-string (format nil "~3d" pp-contents))

 Chapter 1. How to Start and End a KCL Session\(ra)\(do-string (format nil "~3d" pp-1))

 Chapter 2. Data Types\(ra)\(do-string (format nil "~3d" pp-2))
        2.1. Numbers\(ra)\(do-string (format nil "~3d" pp-2-1))
	  2.1.1. Integers\(ra)\(do-string (format nil "~3d" pp-2-1-1))
	  2.1.2. Ratios\(ra)\(do-string (format nil "~3d" pp-2-1-2))
	  2.1.3. Floating-point Numbers\(ra)\(do-string (format nil "~3d" pp-2-1-3))
	  2.1.4. Complex Numbers\(ra)\(do-string (format nil "~3d" pp-2-1-4))
	2.2. Characters\(ra)\(do-string (format nil "~3d" pp-2-2))
	  2.2.1. Standard Characters\(ra)\(do-string (format nil "~3d" pp-2-2-1))
	  2.2.2. Line Divisions\(ra)\(do-string (format nil "~3d" pp-2-2-2))
	  2.2.3. Non-standard Characters\(ra)\(do-string (format nil "~3d" pp-2-2-3))
	  2.2.4. Character Attributes\(ra)\(do-string (format nil "~3d" pp-2-2-4))
	  2.2.5. String Characters\(ra)\(do-string (format nil "~3d" pp-2-2-5))
	2.3. Symbols\(ra)\(do-string (format nil "~3d" pp-2-3))
	2.4. Lists and Conses\(ra)\(do-string (format nil "~3d" pp-2-4))
	2.5. Arrays\(ra)\(do-string (format nil "~3d" pp-2-5))
	  2.5.1. Vectors\(ra)\(do-string (format nil "~3d" pp-2-5-1))
	  2.5.2. Strings\(ra)\(do-string (format nil "~3d" pp-2-5-2))
	  2.5.3. Bit-Vectors\(ra)\(do-string (format nil "~3d" pp-2-5-3))
	2.6. Hash Tables\(ra)\(do-string (format nil "~3d" pp-2-6))
	2.7. Readtables\(ra)\(do-string (format nil "~3d" pp-2-7))
	2.8. Packages\(ra)\(do-string (format nil "~3d" pp-2-8))
	2.9. Pathnames\(ra)\(do-string (format nil "~3d" pp-2-9))
	2.10. Streams\(ra)\(do-string (format nil "~3d" pp-2-10))
	2.11. Random-States\(ra)\(do-string (format nil "~3d" pp-2-11))
	2.12. Structures\(ra)\(do-string (format nil "~3d" pp-2-12))
	2.13. Functions\(ra)\(do-string (format nil "~3d" pp-2-13))
	2.14. Unreadable Data Objects\(ra)\(do-string (format nil "~3d" pp-2-14))
	2.15. Overlap, Inclusion, and Disjointness of Types\(ra)\(do-string (format nil "~3d" pp-2-15))

 Chapter 3. Input and Output\(ra)\(do-string (format nil "~3d" pp-3))
	3.1. Read Macros\(ra)\(do-string (format nil "~3d" pp-3-1))
	3.2. Input and Output Functions\(ra)\(do-string (format nil "~3d" pp-3-2))

 Chapter 4. Memory Management\(ra)\(do-string (format nil "~3d" pp-4))
	4.1. Implementation Types\(ra)\(do-string (format nil "~3d" pp-4-1))
	4.2. Heap and Relocatable Areas\(ra)\(do-string (format nil "~3d" pp-4-2))
	4.3. The Garbage Collector\(ra)\(do-string (format nil "~3d" pp-4-3))
	4.4. Allocation Functions\(ra)\(do-string (format nil "~3d" pp-4-4))
	4.5. Storage Information\(ra)\(do-string (format nil "~3d" pp-4-5))

 Chapter 5. Debugging Facilities\(ra)\(do-string (format nil "~3d" pp-5))
	5.1. The Tracer\(ra)\(do-string (format nil "~3d" pp-5-1))
	5.2. The Stepper\(ra)\(do-string (format nil "~3d" pp-5-2))
	5.3. Errors\(ra)\(do-string (format nil "~3d" pp-5-3))
	5.4. The Break Loop\(ra)\(do-string (format nil "~3d" pp-5-4))
	5.5. Describe and Inspect\(ra)\(do-string (format nil "~3d" pp-5-5))

 Chapter 6. The Compiler\(ra)\(do-string (format nil "~3d" pp-6))

 Chapter 7. Declarations\(ra)\(do-string (format nil "~3d" pp-7))
	7.1. Declaration Specifiers\(ra)\(do-string (format nil "~3d" pp-7-1))
	7.2. Significant Type Specifiers\(ra)\(do-string (format nil "~3d" pp-7-2))
	7.3. Treatment of Type Declarations\(ra)\(do-string (format nil "~3d" pp-7-3))
	  7.3.1. Variable Allocations\(ra)\(do-string (format nil "~3d" pp-7-3-1))
	  7.3.2. Built-in Functions that Operate on Raw Data Directly\(ra)\(do-string (format nil "~3d" pp-7-3-2))
	  7.3.3. Arguments/Values Passing\(ra)\(do-string (format nil "~3d" pp-7-3-3))

 Chapter 8. Operating System Interface\(ra)\(do-string (format nil "~3d" pp-8))

 Chapter 9. Macros\(ra)\(do-string (format nil "~3d" pp-9))
	9.1. System Macros\(ra)\(do-string (format nil "~3d" pp-9-1))
	9.2. Defmacro Lambda-Lists\(ra)\(do-string (format nil "~3d" pp-9-2))

 Chapter 10. The C Language Interface\(ra)\(do-string (format nil "~3d" pp-10))

 Chapter 11. The Editor\(ra)\(do-string (format nil "~3d" pp-11))

 Appendix A. KCL Summary\(ra)\(do-string (format nil "~3d" pp-summary))

 Appendix B. An Overview of Kyoto Common Lisp\(ra)\(do-string (format nil "~3d" pp-overview))

 Appendix C. Kyoto Common Lisp Installation Guide\(ra)\(do-string (format nil "~3d" pp-installation))
	C.1. Installation of KCL/AOS\(ra)\(do-string (format nil "~3d" pp-install-aos))
	C.2. Installation of KCL/VAX\(ra)\(do-string (format nil "~3d" pp-install-vax))
	C.3. Installation of KCL/SUN\(ra)\(do-string (format nil "~3d" pp-install-sun))
	C.4. Installation of KCL/UST\(ra)\(do-string (format nil "~3d" pp-install-ust))
