diff options
Diffstat (limited to 'scm.texi')
| -rw-r--r-- | scm.texi | 354 |
1 files changed, 180 insertions, 174 deletions
@@ -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 |