Import Upstream version 5c3upstream/5c3

1 files changed, 354 insertions, 128 deletions

diff --git a/scm.texi b/scm.texi
index 5d93f63..199ebd9 100644
--- a/scm.texi
+++ b/scm.texi
@@ -4,16 +4,16 @@
 @settitle SCM
 @setchapternewpage on
 @c Choices for setchapternewpage are {on,off,odd}.
-@paragraphindent 2
+@paragraphindent 0
 @defcodeindex ft
 @syncodeindex ft tp
-@c @dircategory Scheme
-@c @direntry
-@c * SCM: (scm).                        A Scheme interpreter.
-@c @end direntry
-
 @c %**end of header
 
+@dircategory The Algorithmic Language Scheme
+@direntry
+* SCM: (scm).           A Scheme interpreter.
+@end direntry
+
 @iftex
 @finalout
 @c DL: lose the egregious vertical whitespace, esp. around examples
@@ -24,13 +24,13 @@
 @titlepage
 @title SCM
 @subtitle Scheme Implementation
-@subtitle Version 5b3
-@subtitle May 1997
+@subtitle Version 5c3
+@subtitle April 1998
 @author by Aubrey Jaffer
 
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997 Free Software Foundation
+Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998 Free Software Foundation
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -53,10 +53,11 @@ by the author.
 @ifinfo
 This manual documents the SCM Scheme implementation.  The most recent
 information about SCM can be found on SCM's @dfn{WWW} home page:
-@center http://www-swiss.ai.mit.edu/~jaffer/SCM.html
 
+@center @url{http://swissnet.ai.mit.edu/~jaffer/SCM.html}
 
-Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997 Free Software Foundation
+
+Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998 Free Software Foundation
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -87,9 +88,7 @@ by the author.
 * The Language::                Reference.
 * Packages::                    Optional Capabilities.
 * The Implementation::          How it works.
-* Procedure and Macro Index::   
-* Variable Index::              
-* Type Index::                  
+* Index::                       
 @end menu
 
 @node Overview, Installing SCM, Top, Top
@@ -103,15 +102,7 @@ machine independent platform for [JACAL], a symbolic algebra system.
 @noindent
 The most recent information about SCM can be found on SCM's @dfn{WWW}
 home page:
-@ifset html
-<A HREF="http://www-swiss.ai.mit.edu/~jaffer/SCM.html">
-@end ifset
-
-@center http://www-swiss.ai.mit.edu/~jaffer/SCM.html
-
-@ifset html
-</A>
-@end ifset
+@center @url{http://swissnet.ai.mit.edu/~jaffer/SCM.html}
 @end iftex
 
 @menu
@@ -439,40 +430,40 @@ low priority.  SLIB is available from the same sites as SCM:
 @ifclear html
 @itemize @bullet
 @item
-ftp-swiss.ai.mit.edu:/pub/scm/slib2c0.tar.gz
+swissnet.ai.mit.edu:/pub/scm/slib2c3.tar.gz
 @item
-prep.ai.mit.edu:/pub/gnu/jacal/slib2c0.tar.gz
+prep.ai.mit.edu:/pub/gnu/jacal/slib2c3.tar.gz
 @item
-ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2c0.tar.gz
+ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2c3.tar.gz
 @item
-ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib2c0.tar.gz
+ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib2c3.tar.gz
 @end itemize
 @end ifclear
 
 @ifset html
-<A HREF="file://ftp-swiss.ai.mit.edu/pub/scm/slib2c0.tar.gz">
-ftp-swiss.ai.mit.edu:/pub/scm/slib2c0.tar.gz
+<A HREF="file://swissnet.ai.mit.edu/pub/scm/slib2c3.tar.gz">
+swissnet.ai.mit.edu:/pub/scm/slib2c3.tar.gz
 </A>
-<A HREF="file://prep.ai.mit.edu/pub/gnu/jacal/slib2c0.tar.gz">
-prep.ai.mit.edu:/pub/gnu/jacal/slib2c0.tar.gz
+<A HREF="file://prep.ai.mit.edu/pub/gnu/jacal/slib2c3.tar.gz">
+prep.ai.mit.edu:/pub/gnu/jacal/slib2c3.tar.gz
 </A>
-<A HREF="file://ftp.maths.tcd.ie/pub/bosullvn/jacal/slib2c0.tar.gz">
-ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2c0.tar.gz
+<A HREF="file://ftp.maths.tcd.ie/pub/bosullvn/jacal/slib2c3.tar.gz">
+ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2c3.tar.gz
 </A>
-<A HREF="file://ftp.cs.indiana.edu/pub/scheme-repository/code/lib/slib2c0.tar.gz">
-ftp.cs.indiana.edu:/pub/scheme-repository/code/lib/slib2c0.tar.gz
+<A HREF="file://ftp.cs.indiana.edu/pub/scheme-repository/code/lib/slib2c3.tar.gz">
+ftp.cs.indiana.edu:/pub/scheme-repository/code/lib/slib2c3.tar.gz
 </A>
 @end ifset
 
 @noindent
-Unpack SLIB (@samp{tar xzf slib2c0.tar.gz} or @samp{unzip -ao
-slib2c0.zip}) in an appropriate directory for your system; both
+Unpack SLIB (@samp{tar xzf slib2c3.tar.gz} or @samp{unzip -ao
+slib2c3.zip}) in an appropriate directory for your system; both
 @code{tar} and @code{unzip} will create the directory @file{slib}.
 
 @noindent
 Then create a file @file{require.scm} in the SCM
 @dfn{implementation-vicinity} (this is the same directory as where the
-file @file{Init.scm} is installed).  @file{require.scm} should have the
+file @file{Init5c3.scm} is installed).  @file{require.scm} should have the
 contents:
 
 @example
@@ -551,7 +542,7 @@ bash$ ./build.scm
 @print{}
 #!/bin/sh
 rm -f scmflags.h
-echo '#define IMPLINIT "/home/jaffer/scm/Init.scm"'>>scmflags.h
+echo '#define IMPLINIT "/home/jaffer/scm/Init5c3.scm"'>>scmflags.h
 echo '#define BIGNUMS'>>scmflags.h
 echo '#define FLOATS'>>scmflags.h
 echo '#define ARRAYS'>>scmflags.h
@@ -572,7 +563,7 @@ bash$ ./build.scm -p vms
 $DELETE scmflags.h
 $CREATE scmflags.h
 $DECK
-#define IMPLINIT "/home/jaffer/scm/Init.scm"
+#define IMPLINIT "/home/jaffer/scm/Init5c3.scm"
 #define BIGNUMS
 #define FLOATS
 #define ARRAYS
@@ -675,7 +666,7 @@ specifies that that @var{flag} will be put on linker command-lines.
 @deffn {Build Option} -s @var{pathname}
 @deffnx {Build Option} ---scheme-initial=@var{pathname}
 specifies that @var{pathname} should be the default location of the SCM
-initialization file @file{Init.scm}.  SCM tries several likely locations
+initialization file @file{Init5c3.scm}.  SCM tries several likely locations
 before resorting to @var{pathname} (@pxref{File-System Habitat}).
 If not specified, the current directory (where build is building) is
 used.
@@ -912,7 +903,7 @@ bash$ build -c foo.c -i init_foo
 @print{}
 #!/bin/sh
 rm -f scmflags.h
-echo '#define IMPLINIT "/home/jaffer/scm/Init.scm"'>>scmflags.h
+echo '#define IMPLINIT "/home/jaffer/scm/Init5c3.scm"'>>scmflags.h
 echo '#define COMPILED_INITS init_foo();'>>scmflags.h
 echo '#define BIGNUMS'>>scmflags.h
 echo '#define FLOATS'>>scmflags.h
@@ -931,7 +922,7 @@ bash$ build -t dll -c foo.c
 @print{}
 #!/bin/sh
 rm -f scmflags.h
-echo '#define IMPLINIT "/home/jaffer/scm/Init.scm"'>>scmflags.h
+echo '#define IMPLINIT "/home/jaffer/scm/Init5c3.scm"'>>scmflags.h
 echo '#define BIGNUMS'>>scmflags.h
 echo '#define FLOATS'>>scmflags.h
 echo '#define ARRAYS'>>scmflags.h
@@ -1090,6 +1081,7 @@ the compilation command lines or add a @code{#define @var{flag}} line to
 -------         ----------
 ARM_ULIB        Huw Rogers free unix library for acorn archimedes
 AZTEC_C         Aztec_C 5.2a
+__CYGWIN32__    cygwin32(?)
 _DCC            Dice C on AMIGA
 __GNUC__        Gnu CC (and DJGPP)
 __EMX__         Gnu C port (gcc/emx 0.8e) to OS/2 2.0
@@ -1097,9 +1089,12 @@ __HIGHC__       MetaWare High C
 __IBMC__        C-Set++ on OS/2 2.1
 _MSC_VER        MS VisualC++ 4.2
 MWC             Mark Williams C on COHERENT
+__MWERKS__      Metrowerks Compiler; Macintosh and WIN32 (?)
+_POSIX_SOURCE   ??
 _QC             Microsoft QuickC
 __STDC__        ANSI C compliant
 __TURBOC__      Turbo C and Borland C
+__USE_POSIX     ??
 __WATCOMC__     Watcom C on MS-DOS
 __ZTC__         Zortech C
 
@@ -1111,6 +1106,7 @@ GNUDOS          DJGPP (obsolete in version 1.08)
 __GO32__        DJGPP (future?)
 hpux            HP-UX
 linux           Linux
+macintosh       Macintosh (THINK_C and __MWERKS__ define)
 MCH_AMIGA       Aztec_c 5.2a on AMIGA
 MSDOS           Microsoft C 5.10 and 6.00A
 __MSDOS__       Turbo C, Borland C, and DJGPP
@@ -1214,14 +1210,14 @@ Don't try to run as subproccess
 @item remove @dots{} in scmfig.h and recompile scm
 @itemx add @dots{} in scmfig.h and recompile scm
 Do it and recompile files.
-@item ERROR: @file{Init.scm} not found
+@item ERROR: @file{Init5c3.scm} not found
 Assign correct IMPLINIT in makefile or @file{scmfig.h} or define
 environment variable @code{SCM_INIT_PATH} to be the full pathname of
-@file{Init.scm} (@pxref{Installing SCM}).
+@file{Init5c3.scm} (@pxref{Installing SCM}).
 @item WARNING: require.scm not found
 define environment variable @code{SCHEME_LIBRARY_PATH} to be the full
 pathname of the scheme library [SLIB] or change @code{library-vicinity} in
-@file{Init.scm} to point to library or remove. @xref{Installation, , , slib,
+@file{Init5c3.scm} to point to library or remove. @xref{Installation, , , slib,
 SLIB}.
 
 Make sure the value of @code{(library-vicinity)} has a trailing file
@@ -1291,7 +1287,7 @@ smaller than @code{HEAP_SEG_SIZE}).
 @item ERROR: Rogue pointer in Heap.
 See above under machine crashes.
 @item Newlines don't appear correctly in output files.
-Check file mode (define OPEN_@dots{} in @file{Init.scm}
+Check file mode (define OPEN_@dots{} in @file{Init5c3.scm}
 @item Spaces or control characters appear in symbol names
 Check character defines in @file{scmfig.h}.
 @item Negative numbers turn positive.
@@ -1371,7 +1367,7 @@ variable @var{SCM_INIT_PATH}.
 If @var{SCM_INIT_PATH} is not defined or if the file it names is not
 present, @code{scm} tries to find the directory containing the
 executable file.  If it is able to locate the executable, @code{scm}
-looks for the initialization file (usually @file{Init.scm}) in
+looks for the initialization file (usually @file{Init5c3.scm}) in
 platform-dependent directories relative to this directory.
 @xref{File-System Habitat} for a blow-by-blow description.
 
@@ -1382,13 +1378,13 @@ compile parameter @var{IMPLINIT} (defined in the makefile or
 
 @noindent
 Unless the option @code{-no-init-file} or @code{--no-init-file} occurs
-in the command line, @file{Init.scm} checks to see if there is file
+in the command line, @file{Init5c3.scm} checks to see if there is file
 @file{ScmInit.scm} in the path specified by the environment variable
 @var{HOME} (or in the current directory if @var{HOME} is undefined). If
 it finds such a file it is loaded.
 
 @noindent
-@file{Init.scm} then looks for command input from one of three sources:
+@file{Init5c3.scm} then looks for command input from one of three sources:
 From an option on the command line, from a file named on the command
 line, or from standard input.
 
@@ -1558,7 +1554,7 @@ Like above but @code{rev4-optional-procedures} are also loaded.
 
 @defvr {Environment Variable} SCM_INIT_PATH
 is the pathname where @code{scm} will look for its initialization
-code. The default is the file @file{Init.scm} in the source directory.
+code. The default is the file @file{Init5c3.scm} in the source directory.
 @end defvr
 
 @defvr {Environment Variable} SCHEME_LIBRARY_PATH
@@ -1566,7 +1562,7 @@ is the [SLIB] Scheme library directory.
 @end defvr
 
 @defvr {Environment Variable} HOME
-is the directory where @file{Init.scm} will look for the user
+is the directory where @file{Init5c3.scm} will look for the user
 initialization file @file{ScmInit.scm}.
 @end defvr
 
@@ -1655,18 +1651,7 @@ Editing of Scheme code is supported by emacs.  Buffers holding files
 ending in .scm are automatically put into scheme-mode.  EMACS for MS-DOS
 and MS-Windows systems is available (free) from:
 
-@ifclear html
-@itemize @bullet
-@item
-http://simtel.coast.net/SimTel/gnu/demacs.html
-@end itemize
-@end ifclear
-
-@ifset html
-<A HREF="http://simtel.coast.net/SimTel/gnu/demacs.html">
-http://simtel.coast.net/SimTel/gnu/demacs.html
-</A>
-@end ifset
+@center @url{http://simtel.coast.net/SimTel/gnu/demacs.html}
 
 If your Emacs can run a process in a buffer you can use the Emacs
 command @samp{M-x run-scheme} with SCM.  Otherwise, use the emacs
@@ -1800,7 +1785,7 @@ offers source code debugging from
 GNU Emacs.  PSD runs slowly, so start by instrumenting only a few
 functions at a time.
 @lisp
-ftp-swiss.ai.mit.edu:pub/scm/slib-psd1-3.tar.gz
+swissnet.ai.mit.edu:pub/scm/slib-psd1-3.tar.gz
 prep.ai.mit.edu:pub/gnu/jacal/slib-psd1-3.tar.gz
 ftp.maths.tcd.ie:pub/bosullvn/jacal/slib-psd1-3.tar.gz
 ftp.cs.indiana.edu:/pub/scheme-repository/utl/slib-psd1-3.tar.gz
@@ -1899,14 +1884,14 @@ signal warnings and errors.
 @defun warn arg1 arg2 arg3 @dots{}
 Alias for @ref{System, slib:warn, , slib, SLIB}.  Outputs an error
 message containing the arguments.  @code{warn} is defined in
-@file{Init.scm}.
+@file{Init5c3.scm}.
 @end defun
 
 @defun error arg1 arg2 arg3 @dots{}
 Alias for @ref{System, slib:error, , slib, SLIB}.  Outputs an error
 message containing the arguments, aborts evaluation of the current form
 and resumes the top level read-eval-print loop.  @code{Error} is defined
-in @file{Init.scm}.
+in @file{Init5c3.scm}.
 @end defun
 
 @noindent
@@ -1927,7 +1912,7 @@ systems.
 @defun stack-trace
 Prints information describing the stack of partially evaluated
 expressions.  @code{stack-trace} returns @code{#t} if any lines were
-printed and @code{#f} otherwise.  See @file{Init.scm} for an example of
+printed and @code{#f} otherwise.  See @file{Init5c3.scm} for an example of
 the use of @code{stack-trace}.
 @end defun
 
@@ -1958,7 +1943,7 @@ top-level have @r{#@@} prepended.
 
 @noindent
 For instance, @code{open-input-file} is defined as follows in
-@file{Init.scm}:
+@file{Init5c3.scm}:
 
 @example
 (define (open-input-file str)
@@ -2016,7 +2001,7 @@ interactive, or should quit after the command line is processed.
 @var{*interactive*} is controlled directly by the command-line options
 @samp{-b}, @samp{-i}, and @samp{-s} (@pxref{Invoking SCM}).  If none of
 these options are specified, the rules to determine interactivity are
-more complicated; see @file{Init.scm} for details.
+more complicated; see @file{Init5c3.scm} for details.
 @end defvar
 
 @defun abort
@@ -2072,7 +2057,7 @@ also gives the hexadecimal heap segment and stack bounds.
 @end defun
 
 @defvr Constant *scm-version*
-Contains the version string (e.g. @file{5b3}) of SCM.
+Contains the version string (e.g. @file{5c3}) of SCM.
 @end defvr
 
 @subsection Executable path
@@ -2088,6 +2073,7 @@ by calling @code{execpath} with the pathname.
 Returns the path (string) which SCM uses to find the executable file
 whose invocation the currently running session is, or #f if the path is
 not set.
+
 @defunx execpath #f
 @defunx execpath newpath
 Sets the path to @code{#f} or @var{newpath}, respectively.  The old path
@@ -2701,9 +2687,15 @@ These procedures generalize and extend the standard capabilities in
 @ref{Ports, , ,r4rs, Revised(4) Scheme}.
 
 @defun open-file string modes
+@defunx try-open-file string modes
 Returns a port capable of receiving or delivering characters as
 specified by the @var{modes} string.  If a file cannot be opened
 @code{#f} is returned.
+
+Internal functions opening files @dfn{callback} to the SCM function
+@code{open-file}.  You can extend @code{open-file} by redefining it.
+@code{try-open-file} is the primitive procedure; Do not redefine
+@code{try-open-file}!
 @end defun
 
 @defvr Constant open_read
@@ -2784,6 +2776,10 @@ interactive port that has no ready characters.
 @c end rationale
 @end deffn
 
+@defun isatty? port
+Returns @code{#t} if @var{port} is input or output to a serial non-file device.
+@end defun
+
 
 @node Soft Ports, Syntax Extensions, Files and Ports, The Language
 @section Soft Ports
@@ -2915,7 +2911,64 @@ If @var{identifier} is unbound in the top level environment, then
 @var{initial-value} as if the @code{defvar} form were instead the form
 @code{(define identifier initial-value)} .  If @var{identifier} already
 has a value, then @var{initial-value} is @emph{not} evaluated and
-@var{identifier}'s value is not changed.
+@var{identifier}'s value is not changed.  @code{defconst} is valid only
+when used at top-level.
+@end defspec
+
+@defspec defconst identifier value
+If @var{identifier} is unbound in the top level environment, then
+@var{identifier} is @code{define}d to the result of evaluating the form
+@var{value} as if the @code{defconst} form were instead the form
+@code{(define identifier value)} .  If @var{identifier} already has a
+value, then @var{value} is @emph{not} evaluated, @var{identifier}'s
+value is not changed, and an error is signaled.  @code{defconst} is
+valid only when used at top-level.
+@end defspec
+
+@defspec casev key clause1 clause2 @dots{}
+@code{casev} is an extension of standard Scheme @code{case}: Each
+@var{clause} of a @code{casev} statement must have as first element a
+list containing elements which are:
+
+@itemize @bullet
+@item
+literal datums, or
+@item
+a comma followed by the name of a symbolic constant, or
+@item
+a comma followed by an at-sign (@@) followed by the name of a symbolic
+constant whose value is a list.
+@end itemize
+
+A @code{casev} statement is equivalent to a @code{case} statement in
+which these symbolic constants preceded by commas have been replaced by
+the values of the constants, and all symbolic constants preceded by
+comma-at-signs have been replaced by the elements of the list values of
+the constants.  This use of comma, (or, equivalently, @code{unquote}) is
+similar to that of @code{quasiquote} except that the unquoted
+expressions must be @dfn{symbolic constants}.
+
+Symbolic constants are defined using @code{defconst}, their values are
+substituted in the head of each @code{casev} clause during macro
+expansion.  @code{defconst} constants should be defined before use.
+@code{casev} can be substituted for any correct use of @code{case}.
+
+@format
+@t{(defconst unit '1)
+(defconst semivowels '(w y))
+(casev (* 2 3)
+  ((2 3 5 7) 'prime)
+  ((,unit 4 6 8 9) 'composite))        ==>  composite
+(casev (car '(c d))
+  ((a) 'a)
+  ((b) 'b))                            ==>  @emph{unspecified}
+(casev (car '(c d))
+  ((a e i o u) 'vowel)
+  ((,@@semivowels) 'semivowel)
+  (else 'consonant))                   ==>  consonant
+}
+@end format
+
 @end defspec
 
 @noindent
@@ -2966,9 +3019,13 @@ from @var{proc} which has been passed to
 
 (trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})).
 @end example
+@end defun
 
-An @dfn{environment} is a list of @dfn{environment frames}.  There are 2
-types of environment frames:
+@defun environment->tree env
+An @dfn{environment} is an opaque object representing lexical bindings.
+@code{environment->tree} returns a representation of the environment
+@var{env} as a list of environment frames.  There are 2 types of
+environment frames:
 
 @table @code
 @item ((lambda (variable1 @dots{}) @dots{}) value1 @dots{})
@@ -2989,8 +3046,19 @@ result in an environment frame for each variable:
 @end defun
 
 @defspec @@apply procedure argument-list
-Returns the result of applying procedure to argument-list.  (apply
-procedure argument-list) will produce the same result.
+Returns the result of applying @var{procedure} to @var{argument-list}.
+@code{@@apply} differs from @code{apply} when the identifiers bound by
+the closure being applied are @code{set!}; setting affects
+@var{argument-list}.
+
+@example
+(define lst (list 'a 'b 'c))
+(@@apply (lambda (v1 v2 v3) (set! v1 (cons v2 v3))) lst)
+lst           @result{} ((b . c) b c)
+@end example
+
+Thus a mutable environment can be treated as both a list and local
+bindings.
 @end defspec
 
 @defspec @@call-with-current-continuation procedure)
@@ -3022,7 +3090,7 @@ use the predicate @code{symbol?}.
 
 A synthetic identifier includes two data: a parent, which is an
 identifier, and an environment, which is either @code{#f} or a lexical
-environment which has been passed to a macro expander
+environment which has been passed to a @dfn{macro expander}
 (a procedure passed as an argument to @code{procedure->macro},
 @code{procedure->memoizing-macro}, or @code{procedure->syntax}).
 
@@ -3149,10 +3217,10 @@ redefinition, for example:
 * Dump::                        Create Fast-Booting Executables
 * Numeric::                     Numeric Language Extensions
 * Arrays::                      As in APL
-* I/O-Extensions::              'i/o-extensions
-* Posix Extensions::            'posix
-* Regular Expression Pattern Matching::  'regex
-* Line Editing::                'edit-line
+* I/O-Extensions::              i/o-extensions
+* Posix Extensions::            posix
+* Regular Expression Pattern Matching::  regex
+* Line Editing::                edit-line
 * Curses::                      Screen Control
 * Sockets::                     Cruise the Net
 @end menu
@@ -3183,7 +3251,7 @@ scm -e'(link-named-scm"cute""cube")'
   (lambda (fp)
     (for-each
       (lambda (string) (write-line string fp))
-      '("#define IMPLINIT \"/home/jaffer/scm/Init.scm\""
+      '("#define IMPLINIT \"/home/jaffer/scm/Init5c3.scm\""
         "#define COMPILED_INITS init_cube();"
         "#define BIGNUMS"
         "#define FLOATS"
@@ -3520,7 +3588,7 @@ is not real.
 
 @menu
 * Conventional Arrays::         
-* Array Mapping::               
+* Array Mapping::               array-for-each
 * Uniform Array::               
 * Bit Vectors::                 
 @end menu
@@ -3829,8 +3897,7 @@ Returns @code{#t} if the @var{obj} is an array of type corresponding to
 
 @defun make-uniform-array prototype bound1 bound2 @dots{}
 Creates and returns a uniform array of type corresponding to
-@var{prototype} that has as many dimensions as there are @var{bound}s
-and fills it with @var{prototype}.
+@var{prototype} that has as many dimensions as there are @var{bound}s.
 @end defun
 
 @defun array-prototype array
@@ -3890,6 +3957,34 @@ omitted, in which case it defaults to the value returned by
 @code{(current-output-port)}.
 @end defun
 
+@defun logaref array index1 index2 @dots{}
+If an @var{index} is provided for each dimension of @var{array} returns
+the @var{index1}, @var{index2}, @dots{}'th element of @var{array}.  If
+one more @var{index} is provided, then the last index specifies bit
+position of the twos-complement representation of the array element
+indexed by the other @var{index}s returning @code{#t} if the bit is 1,
+and @code{#f} if 0.  It is an error if this element is not an exact
+integer.
+
+@example
+(logaref '#(#b1101 #b0010) 0)       @result{} #b1101
+(logaref '#(#b1101 #b0010) 0 1)     @result{} #f
+(logaref '#2((#b1101 #b0010)) 0 0)  @result{} #b1101
+@end example
+@end defun
+
+@defun logaset! array val index1 index2 @dots{}
+If an @var{index} is provided for each dimension of @var{array} sets the
+@var{index1}, @var{index2}, @dots{}'th element of @var{array} to
+@var{val}.  If one more @var{index} is provided, then the last index
+specifies bit position of the twos-complement representation of an exact
+integer array element, setting the bit to 1 if @var{bool} is @code{#t}
+and to 0 if @var{bool} is @code{#f} if 0.  In this case it is an error
+if the array element is not an exact integer or if @var{val} is not
+boolean.
+@end defun
+
+
 @node Bit Vectors,  , Uniform Array, Arrays
 @subsection Bit Vectors
 
@@ -3947,10 +4042,6 @@ Returns
 If @code{'i/o-extensions} is provided (by linking in @file{ioext.o}),
 @ref{Line I/O, , , slib, SLIB}, and the following functions are defined:
 
-@defun isatty? port
-Returns @code{#t} if @var{port} is input or output to a serial non-file device.
-@end defun
-
 @defun stat <port-or-string>
 Returns a vector of integers describing the argument.  The argument
 can be either a string or an open input port. If the argument is an
@@ -5242,7 +5333,7 @@ Returns the host address number (integer) for host @var{string} or
 
 @defun inet:address->string address
 Converts an internet (integer) address to a string in numbers and dots
-notation.  This is an inverse function to inet:address.
+notation.
 @end defun
 
 @defun inet:network address
@@ -5461,7 +5552,7 @@ or you can use a client written in scheme:
 @end example
 
 
-@node The Implementation, Procedure and Macro Index, Packages, Top
+@node The Implementation, Index, Packages, Top
 @chapter The Implementation
 
 @menu
@@ -5705,8 +5796,14 @@ Returns non-zero if @var{x} is a @code{tc3_cons} or isn't, respectively.
 
 @deftp Cell tc3_closure
 applicable object returned by (lambda (args) @dots{}).
-@code{tc3_closure}s have a pointer to other the body of the procedure in
-the @code{CAR} and a pointer to the environment in the @code{CDR}.
+@code{tc3_closure}s have a pointer to the body of the procedure in the
+@code{CAR} and a pointer to the environment in the @code{CDR}.  Bits 1
+and 2 (zero-based) in the @code{CDR} indicate a lower bound on the
+number of required arguments to the closure, which is used to avoid
+allocating rest argument lists in the environment cache.  This encoding
+precludes an immediate value for the @code{CDR}:  In the case of
+an empty environment all bits above 2 in the @code{CDR} are zero.
+
 
 @defmac CLOSUREP x
 Returns non-zero if @var{x} is a @code{tc3_closure}.
@@ -5717,6 +5814,11 @@ Returns non-zero if @var{x} is a @code{tc3_closure}.
 Returns the code body or environment of closure @var{x}, respectively.
 @end defmac
 
+@defmac ARGC x
+Returns the a lower bound on the number of required arguments to closure
+@var{x}, it cannot exceed 3.
+@end defmac
+
 @end deftp
 
 @node Header Cells, Subr Cells, Cells, Data Types
@@ -6077,7 +6179,7 @@ gloc    PPPPPPPPPPPPPPPPPPPPPPPPPPPPP001}
         1s and 0s here indicate type.     G missing means sys (not GC'd)
         SIMPLE:}
 @t{cons    ..........SCM car..............0  ...........SCM cdr.............G
-closure ..........SCM code...........011  ...........SCM env.............G
+closure ..........SCM code...........011  ...........SCM env...........CCG
         HEADERs:
 ssymbol .........long length....G0000101  ..........char *chars...........
 msymbol .........long length....G0000111  ..........char *chars...........
@@ -6139,6 +6241,7 @@ array   ...short rank..cxxxxxxxxG1111111  ............*array..............}
 
 @menu
 * Garbage Collection::          Automatically reclaims unused storage
+* Memory Management for Environments::  
 * Signals::                     
 * C Macros::                    
 * Changing Scm::                
@@ -6152,7 +6255,7 @@ array   ...short rank..cxxxxxxxxG1111111  ............*array..............}
 * Evaluation::                  Why SCM is fast
 @end menu
 
-@node Garbage Collection, Signals, Operations, Operations
+@node Garbage Collection, Memory Management for Environments, Operations, Operations
 @subsection Garbage Collection
 
 The garbage collector is in the latter half of @file{sys.c}.  The
@@ -6237,7 +6340,116 @@ object is freed.  If the type header of smob is collected, the smob's
 @code{free} procedure is called to free its storage.
 @end deftypefun
 
-@node Signals, C Macros, Garbage Collection, Operations
+@node Memory Management for Environments, Signals, Garbage Collection, Operations
+@subsection Memory Management for Environments
+
+@itemize @bullet
+@item
+@dfn{Ecache} was designed and implemented by Radey Shouman.
+
+@item
+This documentation of ecache was written by Tom Lord.
+@end itemize
+
+The memory management component of SCM contains special features which
+optimize the allocation and garbage collection of environments.
+
+The optimizations are based on certain facts and assumptions:
+
+The SCM evaluator creates many environments with short lifetimes and
+these account of a @emph{large portion} of the total number of objects
+allocated.
+
+The general purpose allocator allocates objects from a freelist, and
+collects using a mark/sweep algorithm.  Research into garbage
+collection suggests that such an allocator is sub-optimal for object
+populations containing a large portion of short-lived members and that
+allocation strategies involving a copying collector are more
+appropriate.
+
+It is a property of SCM, reflected throughout the source code, that a
+simple copying collector can not be used as the general purpose memory
+manager: much code assumes that the run-time stack can be treated as a
+garbage collection root set using @dfn{conservative garbage collection}
+techniques, which are incompatible with objects that change location.
+
+Nevertheless, it is possible to use a mostly-separate
+copying-collector, just for environments.  Roughly speaking, cons
+pairs making up environments are initially allocated from a small heap
+that is collected by a precise copying collector.  These objects must
+be handled specially for the collector to work.  The (presumably)
+small number of these objects that survive one collection of the
+copying heap are copied to the general purpose heap, where they will
+later be collected by the mark/sweep collector.  The remaining pairs
+are more rapidly collected than they would otherwise be and all of
+this collection is accomplished without having to mark or sweep any
+other segment of the heap.
+
+Allocating cons pairs for environments from this special heap is a
+heuristic that approximates the (unachievable) goal:
+
+@quotation
+allocate all short-lived objects from the copying-heap, at no extra cost
+in allocation time.
+@end quotation
+
+	   
+@subsubheading Implementation Details
+
+A separate heap (@code{ecache_v}) is maintained for the copying
+collector.  Pairs are allocated from this heap in a stack-like fashion.
+Objects in this heap may be protected from garbage collection by:
+
+@enumerate
+@item
+Pushing a reference to the object on a stack specially maintained for
+that purpose.  This stack (@code{scm_estk}) is used in place of the C
+run-time stack by the SCM evaluator to hold local variables which refer
+to the copying heap.
+
+@item
+Saving a reference to every object in the mark/sweep heap which directly
+references the copying heap in a root set that is specially maintained
+for that purpose (@code{scm_egc_roots}).  If no object in the mark/sweep
+heap directly references an object from the copying heap, that object
+can be preserved by storing a direct reference to it in the
+copying-collector root set.
+@item
+Keeping no other references to these objects, except references between
+the objects themselves, during copying collection.
+@end enumerate
+
+When the copying heap or root-set becomes full, the copying collector is
+invoked.  All protected objects are copied to the mark-sweep heap.  All
+references to those objects are updated.  The copying collector root-set
+and heap are emptied.
+
+References to pairs allocated specificly for environments are
+inaccessible to the Scheme procedures evaluated by SCM.  These pairs
+are manipulated by only a small number of code fragments in the
+interpreter.  To support copying collection, those code fragments
+(mostly in @file{eval.c}) have been modified to protect environments from
+garbage collection using the three rules listed above.
+
+During a mark-sweep collection, the copying collector heap is marked
+and swept almost like any ordinary segment of the general purpose
+heap.  The only difference is that pairs from the copying heap that
+become free during a sweep phase are not added to the freelist.
+
+The environment cache is disabled by adding @code{#define NO_ENV_CACHE}
+to @file{eval.c}; all environment cells are then allocated from the
+regular heap.
+
+@subsubheading Relation to Other Work
+
+This work seems to build upon a considerable amount of previous work
+into garbage collection techniques about which a considerable amount
+of literature is available.
+
+
+
+
+@node Signals, C Macros, Memory Management for Environments, Operations
 @subsection Signals
 
 @defun init_signals
@@ -6263,9 +6475,10 @@ macros @code{DEFER_INTS} and @code{ALLOW_INTS}.
 
 @defmac DEFER_INTS
 sets the global variable @code{ints_disabled} to 1.  If an interrupt
-occurs during a time when @code{ints_disabled} is 1 one of the global
-variables @code{sig_deferred} or @code{alrm_deferred} is set to 1 and
-the handler returns.
+occurs during a time when @code{ints_disabled} is 1, then
+@code{deferred_proc} is set to non-zero, one of the global variables
+@code{SIGINT_deferred} or @code{SIGALRM_deferred} is set to 1, and the
+handler returns.
 
 @defmacx ALLOW_INTS
 Checks the deferred variables and if set the appropriate handler is
@@ -6348,7 +6561,8 @@ SCM_dummy1 = (SCM) &@i{foo};
 @noindent
 @code{SCM_dummy} variables are not currently defined.  Passing the
 address of the local @code{SCM} variable to @emph{any} procedure also
-protects it.
+protects it.  The procedure @code{scm_protect_temp} is provided for
+this purpose.
 
 @noindent
 Also, if you maintain a static pointer to some (non-immediate)
@@ -6436,7 +6650,7 @@ will append a symbol @code{'@i{foo}} to the (list) value of
 put any scheme code which needs to be run as part of your package into
 @file{I@i{foo}.scm}.
 @item
-put an @code{if} into @file{Init.scm} which loads @file{I@i{foo}.scm} if
+put an @code{if} into @file{Init5c3.scm} which loads @file{I@i{foo}.scm} if
 your package is included:
 
 @example
@@ -6695,7 +6909,7 @@ The source code for these routines are found in @file{rope.c}.
 @deftypefun int scm_ldfile (char *@var{file})
 Loads the Scheme source file @var{file}.  Returns 0 if successful, non-0
 if not.  This function is used to load SCM's initialization file
-@file{Init.scm}.
+@file{Init5c3.scm}.
 @end deftypefun
 
 @deftypefun int scm_ldprog (char *@var{file})
@@ -6979,24 +7193,6 @@ the size down, certain @code{EVALCAR} calls which don't need to be fast
 (because they rarely occur or because they are part of expensive
 operations) are instead calls to the C function @code{evalcar}.
 
-There was some discussion a year ago about a "Forth" style Scheme
-interpreter.  This is the only improvement I know of which would beat
-SCM in speed.
-
-@quotation
-Provided there is still type code space available in SCM, if we devote
-some of the IMCAR codes to "inlined" operations, we should get a
-significant performance boost.  What is eliminated is the having to look
-up a @code{GLOC} or @code{ILOC} and then dispatch on the subr type.  The
-IMCAR operation would be dispatched to directly.  Another way to view
-this is that we make available special form versions of @code{CAR},
-@code{CDR}, etc.  Since the actual operation code is localized in the
-interpreter, it is much easier than uncompilation and then recompilation
-to handle @code{(trace car)}; For instance a switch gets set which tells
-the interpreter to instead always look up the values of the associated
-symbols.
-@end quotation
-
 @defvar symhash
 Top level symbol values are stored in the @code{symhash} table.
 @code{symhash} is an array of lists of @code{ISYM}s and pairs of symbols
@@ -7011,6 +7207,18 @@ far in to go for the value.  When this immediate object is subsequently
 encountered, the value can be retrieved quickly.
 @end deftp
 
+@code{ILOC}s work up to a maximum depth of 4096 frames or 4096
+identifiers in a frame.  Radey Shouman added @dfn{FARLOC}
+@tindex FARLOC
+to handle cases exceeding these limits.  A @code{FARLOC} consists of a
+pair whose CAR is the immediate type @code{IM_FARLOC_CAR} or
+@code{IM_FARLOC_CDR}, and whose CDR is a pair of INUMs specifying the
+frame and distance with a larger range than @code{ILOC}s span.
+
+Adding @code{#define TEST_FARLOC} to @file{eval.c} causes @code{FARLOC}s
+to be generated for all local identifiers; this is useful only for
+testing memoization.
+
 @deftp Immediate GLOC
 Pointers to symbols not defined in local environments are changed to one
 plus the value cell address in symhash.  This incremented pointer is
@@ -7145,7 +7353,7 @@ subdirectory.  For example, the executable might be
 @subsection Executable Pathname
 
 @noindent
-For purposes of finding @file{Init.scm}, dumping an executable, and
+For purposes of finding @file{Init5c3.scm}, dumping an executable, and
 dynamic linking, a SCM session needs the pathname of its executable
 image.
 
@@ -7230,6 +7438,8 @@ Returns the number of argument strings in @var{argv}.
 
 @itemize @bullet
 @item
+Allow users to set limits for @code{malloc()} storage.
+@item
 Prefix and make more uniform all C function, variable, and constant
 names.  Provide a file full of #define's to provide backward
 compatability.
@@ -7248,10 +7458,6 @@ Currently, @code{dump}ing an executable does not preserve ports.  When
 loading a @code{dump}ed executable, disk files could be reopened to the
 same file and position as they had when the executable was dumped.
 @item
-Compaction could be done to @code{malloc}ed objects by freeing and
-reallocing all the malloc objects encountered in a scan of the heap.
-Whether compactions would actually occur is system depenedent.
-@item
 Copying all of the stack is wasteful of storage.  Any time a
 call-with-current-continuation is called the stack could be re-rooted
 with a frame which calls the contin just created.  This in combination
@@ -7274,6 +7480,25 @@ This is trickier than it first looks because the must_malloc() routine
 is also used for allocating heap segments, which do not have the
 @code{LENGTH} field restriction.  Putting the 24 bit test into
 @code{must_malloc()} should be tested for speed impact.
+
+@item
+In the quest for speed, there has been some discussion about a "Forth"
+style Scheme interpreter.
+
+@quotation
+Provided there is still type code space available in SCM, if we devote
+some of the IMCAR codes to "inlined" operations, we should get a
+significant performance boost.  What is eliminated is the having to look
+up a @code{GLOC} or @code{ILOC} and then dispatch on the subr type.  The
+IMCAR operation would be dispatched to directly.  Another way to view
+this is that we make available special form versions of @code{CAR},
+@code{CDR}, etc.  Since the actual operation code is localized in the
+interpreter, it is much easier than uncompilation and then recompilation
+to handle @code{(trace car)}; For instance a switch gets set which tells
+the interpreter to instead always look up the values of the associated
+symbols.
+@end quotation
+
 @end itemize
 
 @menu
@@ -7534,21 +7759,22 @@ copying various files over to MS-DOS/WINDOWS.
 @end itemize
 
 
-@node Procedure and Macro Index, Variable Index, The Implementation, Top
+@node Index,  , The Implementation, Top
+@c @node Procedure and Macro Index, Variable Index, The Implementation, Top
 @unnumbered Procedure and Macro Index
 
 This is an alphabetical list of all the procedures and macros in SCM.
 
 @printindex fn
 
-@node Variable Index, Type Index, Procedure and Macro Index, Top
+@c @node Variable Index, Type Index, Procedure and Macro Index, Top
 @unnumbered Variable Index
 
 This is an alphabetical list of all the global variables in SCM.
 
 @printindex vr
 
-@node Type Index,  , Variable Index, Top
+@c @node Type Index,  , Variable Index, Top
 @unnumbered Type Index
 
 This is an alphabetical list of data types and feature names in SCM.