Import Upstream version 5e3upstream/5e3

1 files changed, 180 insertions, 174 deletions

diff --git a/scm.texi b/scm.texi
index 2625130..02c9f49 100644
--- a/scm.texi
+++ b/scm.texi
@@ -1,7 +1,7 @@
 \input texinfo @c -*-texinfo-*-
 @c %**start of header
 @setfilename scm.info
-@settitle SCM
+@settitle scm
 @include version.txi
 @setchapternewpage on
 @c Choices for setchapternewpage are {on,off,odd}.
@@ -10,6 +10,31 @@
 @syncodeindex ft tp
 @c %**end of header
 
+@copying
+@noindent
+This manual is for SCM (version @value{SCMVERSION}, @value{SCMDATE}),
+and algorithmic language Scheme implementation.
+
+@noindent
+Copyright @copyright{} 1990-2006 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the author.
+@end quotation
+@end copying
+
 @dircategory The Algorithmic Language Scheme
 @direntry
 * SCM: (scm).           A Scheme interpreter.
@@ -26,61 +51,19 @@
 @title SCM
 @subtitle Scheme Implementation
 @subtitle Version @value{SCMVERSION}
-@author by Aubrey Jaffer
-
+@author Aubrey Jaffer
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1990-1999 Free Software Foundation
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the entire
-resulting derived work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation approved
-by the author.
+@insertcopying
 @end titlepage
 
-@node Top, Overview, (dir), (dir)
-
-
-@ifinfo
-This manual documents the SCM Scheme implementation.  SCM version
-@value{SCMVERSION} was released @value{SCMDATE}.  The most recent
-information about SCM can be found on SCM's @dfn{WWW} home page:
-
-@center @url{http://swiss.csail.mit.edu/~jaffer/SCM}
-
-
-Copyright (C) 1990-1999 Free Software Foundation
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
+@contents
 
-@end ignore
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the entire
-resulting derived work is distributed under the terms of a permission
-notice identical to this one.
+@ifnottex
+@node Top, Overview, (dir), (dir)
+@top SCM
 
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation approved
-by the author.
-@end ifinfo
+@insertcopying
 
 @menu
 * Overview::                    
@@ -91,6 +74,7 @@ by the author.
 * The Implementation::          How it works.
 * Index::                       
 @end menu
+@end ifnottex
 
 @node Overview, Installing SCM, Top, Top
 @chapter Overview
@@ -150,7 +134,7 @@ and @code{eval}.
 @item
 @code{Char-code-limit}, @code{most-positive-fixnum},
 @code{most-negative-fixnum}, @code{and internal-time-units-per-second}
-constants.  @code{*Features*} and @code{*load-pathname*} variables.
+constants.  @code{slib:features} and @code{*load-pathname*} variables.
 @item
 Arrays and bit-vectors.  String ports and software emulation ports.
 I/O extensions providing ANSI C and POSIX.1 facilities.
@@ -293,7 +277,7 @@ OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
 @subsection SIOD copyright
 @sp 1
 
-@center COPYRIGHT (c) 1989 BY
+@center COPYRIGHT @copyright{} 1989 BY
 @center PARADIGM ASSOCIATES INCORPORATED, CAMBRIDGE, MASSACHUSETTS.
 @center ALL RIGHTS RESERVED
 
@@ -533,34 +517,34 @@ low priority.  SLIB is available from the same sites as SCM:
 @ifclear html
 @itemize @bullet
 @item
-swiss.csail.mit.edu:/pub/scm/slib3a3.tar.gz
+swiss.csail.mit.edu:/pub/scm/slib3a4.tar.gz
 @item
-ftp.gnu.org:/pub/gnu/jacal/slib3a3.tar.gz
+ftp.gnu.org:/pub/gnu/jacal/slib3a4.tar.gz
 @item
-ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib3a3.tar.gz
+ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib3a4.tar.gz
 @end itemize
 @end ifclear
 
 @ifset html
 @itemize @bullet
 @item
-<A HREF="http://swiss.csail.mit.edu/ftpdir/scm/slib3a3.zip">
-http://swiss.csail.mit.edu/ftpdir/scm/slib3a3.zip
+<A HREF="http://swiss.csail.mit.edu/ftpdir/scm/slib3a4.zip">
+http://swiss.csail.mit.edu/ftpdir/scm/slib3a4.zip
 </A>
 @item
-<A HREF="ftp://ftp.gnu.org/pub/gnu/jacal/slib3a3.tar.gz">
-ftp.gnu.org:/pub/gnu/jacal/slib3a3.tar.gz
+<A HREF="ftp://ftp.gnu.org/pub/gnu/jacal/slib3a4.tar.gz">
+ftp.gnu.org:/pub/gnu/jacal/slib3a4.tar.gz
 </A>
 @item
-<A HREF="ftp://ftp.cs.indiana.edu/pub/scheme-repository/code/lib/slib3a3.tar.gz">
-ftp.cs.indiana.edu:/pub/scheme-repository/code/lib/slib3a3.tar.gz
+<A HREF="ftp://ftp.cs.indiana.edu/pub/scheme-repository/code/lib/slib3a4.tar.gz">
+ftp.cs.indiana.edu:/pub/scheme-repository/code/lib/slib3a4.tar.gz
 </A>
 @end itemize
 @end ifset
 
 @noindent
-Unpack SLIB (@samp{tar xzf slib3a3.tar.gz} or @samp{unzip -ao
-slib3a3.zip}) in an appropriate directory for your system; both
+Unpack SLIB (@samp{tar xzf slib3a4.tar.gz} or @samp{unzip -ao
+slib3a4.zip}) in an appropriate directory for your system; both
 @code{tar} and @code{unzip} will create the directory @file{slib}.
 
 @noindent
@@ -598,6 +582,8 @@ absolute pathnames are recommended.
 @node Building SCM, Installing Dynamic Linking, SLIB, Installing SCM
 @section Building SCM
 
+@cindex build
+@cindex build.scm
 The file @dfn{build} loads the file @dfn{build.scm}, which constructs a
 relational database of how to compile and link SCM executables.
 @file{build.scm} has information for the platforms which SCM has been
@@ -1022,20 +1008,51 @@ Remember to delete the file @file{slibcat} after modifying the file
 @node Saving Images, Automatic C Preprocessor Definitions, Configure Module Catalog, Installing SCM
 @section Saving Images
 
-@noindent
 In SCM, the ability to save running program images is called @dfn{dump}
 (@pxref{Dump}).  In order to make @code{dump} available to SCM, build
 with feature @samp{dump}.  @code{dump}ed executables are compatible with
 dynamic linking.
 
-@noindent
 Most of the code for @dfn{dump} is taken from
 @file{emacs-19.34/src/unex*.c}.  No modifications to the emacs source
 code were required to use @file{unexelf.c}.  Dump has not been ported to
 all platforms.  If @file{unexec.c} or @file{unexelf.c} don't work for
 you, try using the appropriate @file{unex*.c} file from emacs.
 
+The @samp{dscm4} and @samp{dscm5} targets in the SCM @file{Makefile}
+save images from @file{udscm4} and @file{udscm5} executables
+respectively.
+
+Recent Linux innovations interfere with @code{dump}.  For:
+
+@table @asis
+@item Fedora-Core-1
+Remove the @samp{#} from the line @samp{#SETARCH = setarch i386} in
+the @file{Makefile}.
+
+@item Fedora-Core-3
+@url{http://jamesthornton.com/writing/emacs-compile.html} writes:
+[For FC3] combreloc has become the default for recent GNU ld, which
+breaks the unexec/undump on all versions of both Emacs and
+XEmacs...
+
+Override by adding the following to @file{udscm5.opt}:
+@samp{--linker-options="-z nocombreloc"}
+
+@item Kernels later than 2.6.11 
+@url{http://www.opensubscriber.com/message/emacs-devel@@gnu.org/1007118.html}
+mentions the @dfn{exec-shield} feature.  Kernels later than 2.6.11
+must do (as root):
+
+@example
+echo 0 > /proc/sys/kernel/randomize_va_space
+@end example
+
+before dumping.  @file{Makefile} has this @file{randomize_va_space}
+stuffing scripted for targets @samp{dscm4} and @samp{dscm5}.  You must
+either set @file{randomize_va_space} to 0 or run as root to dump.
 
+@end table
 
 @node Automatic C Preprocessor Definitions, Problems Compiling, Saving Images, Installing SCM
 @section Automatic C Preprocessor Definitions
@@ -1298,8 +1315,10 @@ tracking effects of changes to SCM on performance.
 @tab Check character defines in @file{scmfig.h}.
 @item Negative numbers turn positive.
 @tab Check SRS in @file{scmfig.h}.
+@item ;ERROR: bignum: numerical overflow
+@tab Increase NUMDIGS_MAX in @file{scmfig.h} and recompile.
 @item VMS: Couldn't unwind stack.
-@tab @t{#define CHEAP_CONTIUATIONS} in @file{scmfig.h}.
+@tab @t{#define CHEAP_CONTINUATIONS} in @file{scmfig.h}.
 @item VAX: botched longjmp.
 @end multitable
 
@@ -1391,10 +1410,11 @@ 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@value{SCMVERSION}.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.
+in the command line, or if @code{scm} is being invoked as a script,
+@file{Init@value{SCMVERSION}.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, then it is loaded.
 
 @noindent
 @file{Init@value{SCMVERSION}.scm} then looks for command input from one
@@ -1721,8 +1741,8 @@ After editing, the modified file will be loaded.
 @section Debugging Scheme Code
 
 @noindent
-The @code{cautious} and @code{stack-limit} options of @code{build}
-(@pxref{Build Options}) support debugging in Scheme.
+The @code{cautious} option of @code{build}
+(@pxref{Build Options}) supports debugging in Scheme.
 
 @table @dfn
 @item CAUTIOUS
@@ -1742,18 +1762,14 @@ program execution can be resumed by @code{(continue)}.
 In this configuration one can interrupt a running Scheme program with
 @key{C-c}, inspect or modify top-level values, trace or untrace
 procedures, and continue execution with @code{(continue)}.
-
-@item STACK_LIMIT
-If SCM is built with the @samp{STACK_LIMIT} flag, the interpreter will
-check stack size periodically.  If the size of stack exceeds a certain
-amount (default is @code{HEAP_SEG_SIZE/2}), SCM generates a
-@code{segment violation} interrupt.
-
-The usefulness of @samp{STACK_LIMIT} depends on the user.  I don't use
-it; but the user I added this feature for got primarily this type of
-error.
 @end table
 
+If @code{verbose} (@pxref{Internal State, verbose}) is called with an
+argument greater than 2, then the interpreter will check stack size
+periodically.  If the size of stack in use exceeds the C #define
+@code{STACK_LIMIT} (default is @code{HEAP_SEG_SIZE}), SCM generates a
+@samp{stack} @code{segment violation}.
+
 @noindent
 There are several SLIB macros which so useful that SCM automatically
 loads the appropriate module from SLIB if they are invoked.
@@ -2191,7 +2207,8 @@ a prompt is printed.
 messages bracketing file loading are printed.
 @item >= 3
 the CPU time is printed after each top level form evaluated;
-notifications of heap growth printed.
+notifications of heap growth printed; the interpreter checks stack
+depth periodically.
 @item >= 4
 a garbage collection summary is printed after each top level form
 evaluated;
@@ -3240,14 +3257,13 @@ combined.
 @end deffn
 
 @deffn {Read syntax} #+ feature form
-If feature is @code{provided?} (by @code{*features*}) then @var{form} is
-read as a scheme expression.  If not, then @var{form} is treated as
-whitespace.
+If feature is @code{provided?} then @var{form} is read as a scheme
+expression.  If not, then @var{form} is treated as whitespace.
 
 Feature is a boolean expression composed of symbols and @code{and},
 @code{or}, and @code{not} of boolean expressions.
 
-For more information on @code{provided?} and @code{*features*},
+For more information on @code{provided?},
 @xref{Require, , , slib, SLIB}.
 @end deffn
 
@@ -4230,29 +4246,28 @@ Return the hyperbolic sine, cosine, and tangent of @var{z}
 Return the inverse hyperbolic sine, cosine, and tangent of @var{z}
 @end defun
 
-@defun $sqrt x
-@defunx $abs x
-@defunx $exp x
-@defunx $log x
-@defunx $sin x
-@defunx $cos x
-@defunx $tan x
-@defunx $asin x
-@defunx $acos x
-@defunx $atan x
-
-@defunx $sinh x
-@defunx $cosh x
-@defunx $tanh x
-@defunx $asinh x
-@defunx $acosh x
-@defunx $atanh x
+@defun real-sqrt x
+@defunx real-exp x
+@defunx real-ln x
+@defunx real-sin x
+@defunx real-cos x
+@defunx real-tan x
+@defunx real-asin x
+@defunx real-acos x
+@defunx real-atan x
+
+@defunx real-sinh x
+@defunx real-cosh x
+@defunx real-tanh x
+@defunx real-asinh x
+@defunx real-acosh x
+@defunx real-atanh x
 Real-only versions of these popular functions.  The argument @var{x}
 must be a real number.  It is an error if the value which should be
 returned by a call to these procedures is @emph{not} real.
 @end defun
 
-@defun $log10 x
+@defun real-log10 x
 Real-only base 10 logarithm.
 @end defun
 
@@ -4261,9 +4276,9 @@ Computes @code{(angle (make-rectangular x y))} for real numbers @var{y}
 and @var{x}.
 @end defun
 
-@defun $expt x1 x2
+@defun real-expt x1 x2
 Returns real number @var{x1} raised to the real power @var{x2}.  It is
-an error if the value which should be returned by a call to @code{$expt}
+an error if the value which should be returned by a call to @code{real-expt}
 is not real.
 @end defun
 
@@ -6602,31 +6617,43 @@ the elements of string @var{x} or its length, respectively.
 @end defmac
 @end deftp
 
-@deftp Header tc7_bvect
+@deftp Header tc7_Vbool
 uniform vector of booleans (bit-vector)
 @end deftp
 
-@deftp Header tc7_ivect
+@deftp Header tc7_VfixZ32
 uniform vector of integers
 @end deftp
 
-@deftp Header tc7_uvect
+@deftp Header tc7_VfixN32
 uniform vector of non-negative integers
 @end deftp
 
-@deftp Header tc7_svect
+@deftp Header tc7_VfixN16
+uniform vector of non-negative short integers
+@end deftp
+
+@deftp Header tc7_VfixZ16
 uniform vector of short integers
 @end deftp
 
-@deftp Header tc7_fvect
+@deftp Header tc7_VfixN8
+uniform vector of non-negative bytes
+@end deftp
+
+@deftp Header tc7_VfixZ8
+uniform vector of signed bytes
+@end deftp
+
+@deftp Header tc7_VfloR32
 uniform vector of short inexact real numbers
 @end deftp
 
-@deftp Header tc7_dvect
+@deftp Header tc7_VfloR64
 uniform vector of double precision inexact real numbers
 @end deftp
 
-@deftp Header tc7_cvect
+@deftp Header tc7_VfloC64
 uniform vector of double precision inexact complex numbers
 @end deftp
 
@@ -6692,10 +6719,10 @@ These subrs are handled specially.  If inexact numbers are enabled, the
 @code{double}.  Conversions are handled in the interpreter.
 
 @code{floor}, @code{ceiling}, @code{truncate}, @code{round},
-@code{$sqrt}, @code{$abs}, @code{$exp}, @code{$log}, @code{$sin},
-@code{$cos}, @code{$tan}, @code{$asin}, @code{$acos}, @code{$atan},
-@code{$sinh}, @code{$cosh}, @code{$tanh}, @code{$asinh}, @code{$acosh},
-@code{$atanh}, and @code{exact->inexact} are defined this way.
+@code{real-sqrt}, @code{real-exp}, @code{real-ln}, @code{real-sin},
+@code{real-cos}, @code{real-tan}, @code{real-asin}, @code{real-acos}, @code{real-atan},
+@code{real-sinh}, @code{real-cosh}, @code{real-tanh}, @code{real-asinh}, @code{real-acosh},
+@code{real-atanh}, and @code{exact->inexact} are defined this way.
 
 If the @code{CDR} is @code{0} (@code{NULL}), the name string of the
 procedure is used to control traversal of its list structure argument.
@@ -6914,8 +6941,8 @@ as elements @pxref{Conventional Arrays}) and uniform arrays (those with
 elements of a uniform type @pxref{Uniform Array}).
 
 Conventional Arrays have a pointer to a vector for their @code{CDR}.
-Uniform Arrays have a pointer to a Uniform Vector type (string, bvect,
-ivect, uvect, fvect, dvect, or cvect) in their @code{CDR}.
+Uniform Arrays have a pointer to a Uniform Vector type (string, Vbool,
+VfixZ32, VfixN32, VfloR32, VfloR64, or VfloC64) in their @code{CDR}.
 @end deftp
 
 
@@ -6945,33 +6972,35 @@ ssymbol .........long length....G0000101  ..........char *chars...........
 msymbol .........long length....G0000111  ..........char *chars...........
 string  .........long length....G0001101  ..........char *chars...........
 vector  .........long length....G0001111  ...........SCM **elts...........
-bvect   .........long length....G0010101  ..........long *words...........
- spare                          G0010111
-ivect   .........long length....G0011101  ..........long *words...........
-uvect   .........long length....G0011111  ......unsigned long *words......
- spare                          G0100101
-svect   .........long length....G0100111  ........ short *words...........
-fvect   .........long length....G0101101  .........float *words...........
-dvect   .........long length....G0101111  ........double *words...........
-cvect   .........long length....G0110101  ........double *words...........
-
-contin  .........long length....G0111101  .............*regs..............
-specfun ................xxxxxxxxG1111111  ...........SCM name.............
-cclo    ..short length..xxxxxx10G1111111  ...........SCM **elts...........}
+Vbool   .........long length....G0010101  ..........long *words...........
+ spare                          00010111
+VfixN8  .........long length....G0011101  ......unsigned char *words......
+VfixZ8  .........long length....G0011111  ..........char *words...........
+VfixN16 .........long length....G0100101  ......unsigned short *words.....
+VfixZ16 .........long length....G0100111  ........ short *words...........
+VfixN32 .........long length....G0101101  ......unsigned long *words......
+VfixZ32 .........long length....G0101111  ..........long *words...........
+VfloR32 .........long length....G0110101  .........float *words...........
+VfloC32 .........long length....G0110111  .........float *words...........
+VfloR64 .........long length....G0111101  ........double *words...........
+VfloC64 .........long length....G0111111  ........double *words...........
+
+ spare                          01000101
+contin  .........long length....G1001101  .............*regs..............
+specfun ................xxxxxxxxG1001111  ...........SCM name.............
+cclo    ..short length..xxxxxx10G1001111  ...........SCM **elts...........}
 @r{                        PTOBs@:}
-@t{   port int portnum.CwroxxxxxxxxG0110111  ..........FILE *stream..........
- socket int portnum.C001xxxxxxxxG0110111  ..........FILE *stream..........
- inport int portnum.C011xxxxxxxxG0110111  ..........FILE *stream..........
-outport int portnum.0101xxxxxxxxG0110111  ..........FILE *stream..........
- ioport int portnum.C111xxxxxxxxG0110111  ..........FILE *stream..........
-fport   int portnum.C   00000000G0110111  ..........FILE *stream..........
-pipe    int portnum.C   00000001G0110111  ..........FILE *stream..........
-strport 00000000000.0   00000010G0110111  ..........FILE *stream..........
-sfport  int portnum.C   00000011G0110111  ..........FILE *stream..........}
+@t{   port int portnum.CwroxxxxxxxxG1000111  ..........FILE *stream..........
+ socket int portnum.C001xxxxxxxxG1000111  ..........FILE *stream..........
+ inport int portnum.C011xxxxxxxxG1000111  ..........FILE *stream..........
+outport int portnum.0101xxxxxxxxG1000111  ..........FILE *stream..........
+ ioport int portnum.C111xxxxxxxxG1000111  ..........FILE *stream..........
+fport   int portnum.C   00000000G1000111  ..........FILE *stream..........
+pipe    int portnum.C   00000001G1000111  ..........FILE *stream..........
+strport 00000000000.0   00000010G1000111  ..........FILE *stream..........
+sfport  int portnum.C   00000011G1000111  ..........FILE *stream..........}
 @r{        SUBRs@:}
-@t{ spare                          010001x1
- spare                          010011x1
-subr_0  ..........int hpoff.....01010101  ...........SCM (*f)()...........
+@t{subr_0  ..........int hpoff.....01010101  ...........SCM (*f)()...........
 subr_1  ..........int hpoff.....01010111  ...........SCM (*f)()...........
 cxr     ..........int hpoff.....01011101  .........double (*f)()..........
 subr_3  ..........int hpoff.....01011111  ...........SCM (*f)()...........
@@ -7066,7 +7095,7 @@ unmarked, gc_mark sets the mark bit in @var{obj}, then calls
 @code{gc_mark()} is tail-called (looped).
 @end deftypefun
 
-@deftypefun void mark_locations (STACKITEM @var{x}[], sizet @var{len}))
+@deftypefun void mark_locations (STACKITEM @var{x}[], sizet @var{len})
 The function @code{mark_locations} is used for marking segments of
 C-stack or saved segments of C-stack (marked continuations).  The
 argument @var{len} is the size of the stack in units of size
@@ -7424,7 +7453,7 @@ add_feature("@i{foo}");
 @end example
 
 will append a symbol @code{'@i{foo}} to the (list) value of
-@code{*features*}.
+@code{slib:features}.
 @item
 put any scheme code which needs to be run as part of your package into
 @file{I@i{foo}.scm}.
@@ -8637,33 +8666,10 @@ that have been linked against it.
 @end enumerate
 
 
-
+@ifinfo
 @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
-
-@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
-
-@c @node Type Index,  , Variable Index, Top
-@unnumbered Type Index
-
-This is an alphabetical list of data types and feature names in SCM.
-
-@printindex tp
-
-This is an alphabetical list of concepts introduced in this manual.
-
-@unnumbered Concept Index
-@printindex cp
+@unnumbered Index
+@end ifinfo
 
-@contents
+@include indexes.texi
 @bye