aboutsummaryrefslogtreecommitdiffstats
path: root/scm.texi
diff options
context:
space:
mode:
Diffstat (limited to 'scm.texi')
-rw-r--r--scm.texi354
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