aboutsummaryrefslogtreecommitdiffstats
path: root/scm.texi
diff options
context:
space:
mode:
Diffstat (limited to 'scm.texi')
-rwxr-xr-x[-rw-r--r--]scm.texi1520
1 files changed, 929 insertions, 591 deletions
diff --git a/scm.texi b/scm.texi
index 3547f12..743881d 100644..100755
--- a/scm.texi
+++ b/scm.texi
@@ -20,7 +20,7 @@ Copyright @copyright{} 1990-2007 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2 or
+under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the section entitled ``GNU Free
@@ -84,9 +84,9 @@ The most recent information about SCM can be found on SCM's @dfn{WWW}
home page:
@ifset html
-<A HREF="http://swiss.csail.mit.edu/~jaffer/SCM">
+<A HREF="http://people.csail.mit.edu/jaffer/SCM">
@end ifset
-@center @url{http://swiss.csail.mit.edu/~jaffer/SCM}
+@center @url{http://people.csail.mit.edu/jaffer/SCM}
@ifset html
</A>
@end ifset
@@ -153,7 +153,7 @@ timing information printed interactively (the @code{verbose} function).
@section Authors
@table @b
-@item Aubrey Jaffer (agj @@ alum.mit.edu)
+@item Aubrey Jaffer (agj@@alum.mit.edu)
Most of SCM.
@item Radey Shouman
Arrays, @code{gsubr}s, compiled closures, records, Ecache, syntax-rules
@@ -400,37 +400,119 @@ Documentation of the Xlib - SCM Language X Interface.
@node Installing SCM, Operational Features, Overview, Top
@chapter Installing SCM
+SCM runs on a wide variety of platforms. ``Distributions'' is the
+starting point for all platforms. The process described in ``GNU
+configure and make'' will work on most Unix and GNU/Linux platforms.
+If it works for you, then you may skip the later sections of
+``Installing SCM''.
+
@menu
-* Making SCM:: Bootstrapping.
-* SLIB:: REQUIREd reading.
+* Distributions:: Source and Binaries
+* GNU configure and make:: For Unix and GNU/Linux
* Building SCM::
-* Installing Dynamic Linking::
-* Configure Module Catalog::
-* Saving Images:: Make Fast-Booting Executables
-* Automatic C Preprocessor Definitions::
-* Problems Compiling::
-* Problems Linking::
-* Problems Running::
-* Testing::
-* Reporting Problems::
+* Saving Executable Images:: For Faster Startup
+* Installation::
+* Troubleshooting and Testing::
+@end menu
+
+@node Distributions, GNU configure and make, Installing SCM, Installing SCM
+@section Distributions
+
+@noindent
+The SCM homepage contains links to precompiled binaries and source
+distributions.
+
+@noindent
+Downloads and instructions for installing the precompiled binaries are
+at @uref{http://people.csail.mit.edu/jaffer/SCM#QuickStart}.
+
+@noindent
+If there is no precompiled binary for your platform, you may be able
+to build from the source distribution. The rest of these instructions
+deal with building and installing SCM and SLIB from sources.
+
+@noindent
+Download (both SCM and SLIB of) either the last release or current
+development snapshot from
+@uref{http://people.csail.mit.edu/jaffer/SCM#BuildFromSource}.
+
+@noindent
+Unzip both the SCM and SLIB zips. For example, if you are working in
+@file{/usr/local/src/}, this will create directories
+@file{/usr/local/src/scm/} and @file{/usr/local/src/slib/}.
+
+
+@node GNU configure and make, Building SCM, Distributions, Installing SCM
+@section GNU configure and make
+
+@file{scm/configure} and @file{slib/configure} are Shell scripts which
+create the files @file{scm/config.status} and
+@file{slib/config.status} on Unix and MinGW systems.
+
+The @file{config.status} files are used (included) by the Makefile to
+control where the packages will be installed by @code{make install}.
+With GNU shell (bash) and utilities, the following commands should
+build and install SCM and SLIB:
+
+@example
+bash$ (cd slib; ./configure --prefix=/usr/local/)
+bash$ (cd scm
+> ./configure --prefix=/usr/local/
+> make scmlit
+> sudo make all
+> sudo make install)
+bash$ (cd slib; sudo make install)
+@end example
+
+If the install commands worked, skip to @ref{Testing}.
+
+If @file{configure} doesn't work on your system, make
+@file{scm/config.status} and @file{slib/config.status} be empty files.
+
+For additional help on using the @file{configure} script, run
+@w{@samp{./configure --help}}.
+
+@samp{make all} will attempt to create a dumped executable
+(@pxref{Saving Executable Images}), which has very small startup
+latency. If that fails, it will try to compile an ordinary @samp{scm}
+executable.
+
+Note that the compilation output may contain error messages; be
+concerned only if the @samp{make install} transcripts contain errors.
+
+@samp{sudo} runs the command after it as user @dfn{root}. On recent
+GNU/Linux systems, dumping requires that @samp{make all} be run as
+user root; hence the use of @samp{sudo}.
+
+@samp{make install} requires root privileges if you are installing to
+standard Unix locations as specified to (or defaulted by)
+@samp{./configure}. Note that this is independent of whether you did
+@w{@samp{sudo make all}} or @w{@samp{make all}}.
+
+@menu
+* Making scmlit::
+* Makefile targets::
@end menu
-@node Making SCM, SLIB, Installing SCM, Installing SCM
-@section Making SCM
+@node Making scmlit, Makefile targets, GNU configure and make, GNU configure and make
+@subsection Making scmlit
-The SCM distribution has @dfn{Makefile} which contains rules for
-making @dfn{scmlit}, a ``bare-bones'' version of SCM sufficient for
-running @file{build}. @file{build} is used to compile (or create
-scripts to compile) full featured versions (@pxref{Building SCM}).
+@noindent
+The SCM distribution @file{Makefile} contains rules for making
+@dfn{scmlit}, a ``bare-bones'' version of SCM sufficient for running
+@file{build}. @file{build} is a Scheme program used to compile (or
+create scripts to compile) full featured versions of SCM
+(@pxref{Building SCM}). To create scmlit, run @w{@samp{make scmlit}}
+in the @file{scm/} directory.
-Makefiles are not portable to the majority of platforms. If
-@file{Makefile} works for you, good; If not, I don't want to hear about
-it. If you need to compile SCM without build, there are several ways to
+@noindent
+Makefiles are not portable to the majority of platforms. If you need
+to compile SCM without @samp{scmlit}, there are several ways to
proceed:
@itemize @bullet
@item
-Use the @uref{http://swiss.csail.mit.edu/~jaffer/buildscm.html, build}
+Use the @uref{http://people.csail.mit.edu/jaffer/buildscm.html, build}
web page to create custom batch scripts for compiling SCM.
@item
@@ -445,48 +527,25 @@ script to build SCM;
Create your own script or @file{Makefile}.
@end itemize
+@subheading Finding SLIB
-@node SLIB, Building SCM, Making SCM, Installing SCM
-@section SLIB
+If you didn't create scmlit using @samp{make scmlit}, then you must
+create a file named @file{scm/require.scm}. For most installations,
+@file{scm/require.scm} can just be copied from
+@file{scm/requires.scm}, which is part of the SCM distribution.
@noindent
-[SLIB] is a portable Scheme library meant to provide compatibility and
-utility functions for all standard Scheme implementations. Although
-SLIB is not @emph{neccessary} to run SCM, I strongly suggest you obtain
-and install it. Bug reports about running SCM without SLIB have very
-low priority. SLIB is available from the same sites as SCM:
+If, when executing @samp{scmlit} or @samp{scm}, you get a message
+like:
-@ifclear html
-@itemize @bullet
-@item
-swiss.csail.mit.edu:/pub/scm/slib-3b1.tar.gz
-@item
-ftp.gnu.org:/pub/gnu/jacal/slib-3b1.tar.gz
-@end itemize
-@end ifclear
-
-@ifset html
-@itemize @bullet
-@item
-<A HREF="http://swiss.csail.mit.edu/ftpdir/scm/slib-3b1.zip">
-http://swiss.csail.mit.edu/ftpdir/scm/slib-3b1.zip
-</A>
-@item
-<A HREF="ftp://ftp.gnu.org/pub/gnu/jacal/slib-3b1.tar.gz">
-ftp.gnu.org:/pub/gnu/jacal/slib-3b1.tar.gz
-</A>
-@end itemize
-@end ifset
-
-@noindent
-Unpack SLIB (@samp{tar xzf slib-3b1.tar.gz} or @samp{unzip -ao
-slib-3b1.zip}) in an appropriate directory for your system; both
-@code{tar} and @code{unzip} will create the directory @file{slib}.
+@example
+ERROR: "LOAD couldn't find file " "/usr/local/src/scm/require"
+@end example
@noindent
-Then create a file @file{require.scm} in the SCM
+then create a file @file{require.scm} in the SCM
@dfn{implementation-vicinity} (this is the same directory as where the
-file @file{Init@value{SCMVERSION}.scm} is installed).
+file @file{Init@value{SCMVERSION}.scm} is).
@file{require.scm} should have the contents:
@example
@@ -494,12 +553,21 @@ file @file{Init@value{SCMVERSION}.scm} is installed).
@end example
@noindent
-where the pathname string @file{/usr/local/lib/slib/} is to be replaced
-by the pathname into which you installed SLIB. Absolute pathnames are
-recommended here; if you use a relative pathname, SLIB can get confused
-when the working directory is changed (@pxref{I/O-Extensions, chmod}).
-The way to specify a relative pathname is to append it to the
-implementation-vicinity, which is absolute:
+where the pathname string @file{/usr/local/lib/slib/} is to be
+replaced by the pathname into which you unzipped (or installed) SLIB.
+
+@noindent
+Alternatively, you can set the (shell) environment variable
+@code{SCHEME_LIBRARY_PATH} to the pathname of the SLIB directory
+(@pxref{SCM Variables, SCHEME_LIBRARY_PATH, Environment Variables}).
+If set, this environment variable overrides @file{scm/require.scm}.
+
+@noindent
+Absolute pathnames are recommended here; if you use a relative
+pathname, SLIB can get confused when the working directory is changed
+(@pxref{I/O-Extensions, chmod}). The way to specify a relative
+pathname is to append it to the implementation-vicinity, which is
+absolute:
@example
(define library-vicinity
@@ -507,59 +575,204 @@ implementation-vicinity, which is absolute:
(lambda () lv)))
@end example
+
+
+@node Makefile targets, , Making scmlit, GNU configure and make
+@subsection Makefile targets
+
+Each of the following four @samp{make} targets creates an executable
+named @file{scm}. Each target takes its build options from a file
+with an @samp{.opt} suffix. If that options file doesn't exist,
+making that target will create the file with the @samp{-F} features:
+cautious, bignums, arrays, inexact, engineering-notation, and
+dynamic-linking. Once that @samp{.opt} file exists, you can edit it
+to your taste and it will be preserved.
+
+@table @code
+@item make scm4
+Produces a R4RS executable named @file{scm} lacking hygienic macros
+(but with defmacro). The build options are taken from
+@file{scm4.opt}. If build or the executable fails, try removing
+@samp{dynamic-linking} from @file{scm4.opt}.
+
+@item make scm5
+R5RS; like @samp{make scm4} but with @samp{-F macro}. The build
+options are taken from @file{scm5.opt}. If build or the executable
+fails, try removing @samp{dynamic-linking} from @file{scm5.opt}.
+
+@item make dscm4
+Produces a R4RS executable named @file{udscm4}, which it starts and
+dumps to a low startup latency executable named @file{scm}. The build
+options are taken from @file{udscm4.opt}.
+
+If the build fails, then @samp{build scm4} instead. If the dumped
+executable fails to run, then send me a bug report (and use
+@w{@samp{build scm4}} until the problem with dump is corrected).
+
+@item make dscm5
+Like @samp{make dscm4} but with @samp{-F macro}. The build options
+are taken from @file{udscm5.opt}.
+
+If the build fails, then @samp{build scm5} instead. If the dumped
+executable fails to run, then send me a bug report (and use
+@w{@samp{build scm5}} until the problem with dump is corrected).
+
+@end table
+
@noindent
-Alternatively, you can set the (shell) environment variable
-@code{SCHEME_LIBRARY_PATH} to the pathname of the SLIB directory
-(@pxref{SCM Variables, SCHEME_LIBRARY_PATH, Environment Variables}). If
-set, the environment variable overrides @file{require.scm}. Again,
-absolute pathnames are recommended.
+If the above builds fail because of @w{@samp{-F dynamic-linking}},
+then (because they can't be dynamically linked) you will likely want
+to add some other features to the build's @samp{.opt} file. See the
+@samp{-F} build option in @ref{Build Options}.
+
+@noindent
+If dynamic-linking is working, then you will likely want to compile
+most of the modules as @dfn{DLL}s. The build options for compiling
+DLLs are in @file{dlls.opt}.
+
+@table @code
+@item make x.so
+The @code{Xlib} module;
+@ref{Top, ,SCM Language X Interface , Xlibscm, Xlibscm}.
-@node Building SCM, Installing Dynamic Linking, SLIB, Installing SCM
+@item make myturtle
+Creates a DLL named @file{turtlegr.so} which is a simple graphics API.
+
+@item make wbscm.so
+The @code{wb} module;
+@ref{Top, ,B-tree database implementation , wb, wb}.
+Compiling this requires that wb source be in a peer directory to scm.
+
+@item make dlls
+Compiles all the distributed library modules, but not @file{wbscm.so}.
+Many of the module compiles are recursively invoked in such a way that
+failure of one (which could be due to a system library not being
+installed) doesn't cause the top-level @samp{make dlls} to fail. If
+@samp{make dlls} fails as a whole, it is time to submit a bug report
+(@pxref{Reporting Problems}).
+
+@end table
+
+
+
+@node Building SCM, Saving Executable Images, GNU configure and make, 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.
+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
-ported to (of which I have been notified). Some of this information is
-old, incorrect, or incomplete. Send corrections and additions to jaffer
-@@ ai.mit.edu.
+ported to (of which I have been notified). Some of this information
+is old, incorrect, or incomplete. Send corrections and additions to
+agj@@alum.mit.edu.
@menu
* Invoking Build::
-* Build Options::
+* Build Options:: build --help
* Compiling and Linking Custom Files::
@end menu
+
@node Invoking Build, Build Options, Building SCM, Building SCM
@subsection Invoking Build
+This section teaches how to use @file{build}, a Scheme program for
+creating compilation scripts to produce SCM executables and library
+modules. The options accepted by @samp{build} are documented in
+@ref{Build Options}.
+
@noindent
-The @emph{all} method will also work for MS-DOS and unix. Use
-the @emph{all} method if you encounter problems with @file{build}.
+Use the @emph{any} method if you encounter problems with the other two
+methods (MS-DOS, Unix).
@table @asis
@item MS-DOS
From the SCM source directory, type @samp{build} followed by up to 9
command line arguments.
-@item unix
+@item Unix
From the SCM source directory, type @samp{./build} followed by command
line arguments.
-@item @emph{all}
+@item @emph{any}
From the SCM source directory, start @samp{scm} or @samp{scmlit} and
type @code{(load "build")}. Alternatively, start @samp{scm} or
@samp{scmlit} with the command line argument @samp{-ilbuild}.
+This method will also work for MS-DOS and Unix.
+
+After loading various SLIB modules, the program will print:
+
+@example
+type (b "build <command-line>") to build
+type (b*) to enter build command loop
+@end example
+
+The @samp{b*} procedure enters into a @dfn{build shell} where you can
+enter commands (with or without the @samp{build}). Blank lines are
+ignored. To create a build script with all defaults type
+@samp{build}.
+
+If the build-shell encouters an error, you can reenter the build-shell
+by typing @samp{(b*)}. To exit scm type @samp{(quit)}.
@end table
@noindent
-Invoking build without the @samp{-F} option will build or create a shell
-script with the @code{arrays}, @code{inexact}, and @code{bignums}
-options as defaults.
+Here is a transcript of an interactive (b*) build-shell.
+
+@example
+bash$ scmlit
+SCM version 5e7, Copyright (C) 1990-2006 Free Software Foundation.
+SCM comes with ABSOLUTELY NO WARRANTY; for details type `(terms)'.
+This is free software, and you are welcome to redistribute it
+under certain conditions; type `(terms)' for details.
+> (load "build")
+;loading build
+; loading /home/jaffer/slib/getparam
+; loading /home/jaffer/slib/coerce
+...
+; done loading build.scm
+type (b "build <command-line>") to build
+type (b*) to enter build command loop
+;done loading build
+#<unspecified>
+> (b*)
+;loading /home/jaffer/slib/comparse
+;done loading /home/jaffer/slib/comparse.scm
+build> -t exe
+#! /bin/sh
+# unix (linux) script created by SLIB/batch Wed Oct 26 17:14:23 2011
+# [-p linux]
+# ================ Write file with C defines
+rm -f scmflags.h
+echo '#define IMPLINIT "Init5e7.scm"'>>scmflags.h
+echo '#define BIGNUMS'>>scmflags.h
+echo '#define FLOATS'>>scmflags.h
+echo '#define ARRAYS'>>scmflags.h
+# ================ Compile C source files
+gcc -c continue.c scm.c scmmain.c findexec.c script.c time.c repl.c scl.c eval.c sys.c subr.c debug.c unif.c rope.c
+# ================ Link C object files
+gcc -rdynamic -o scm continue.o scm.o scmmain.o findexec.o script.o time.o repl.o scl.o eval.o sys.o subr.o debug.o unif.o rope.o -lm -lc
+"scm"
+build> -t exe -w myscript.sh
+"scm"
+build> (quit)
+@end example
+
+@noindent
+No compilation was done. The @samp{-t exe} command shows the compile
+script. The @samp{-t exe -w myscript.sh} line creates a file
+@file{myscript.sh} containing the compile script. To actually compile
+and link it, type @samp{./myscript.sh}.
+
+@noindent
+Invoking build without the @samp{-F} option will build or create a
+shell script with the @code{arrays}, @code{inexact}, and
+@code{bignums} options as defaults. Invoking @samp{build} with
+@samp{-F lit -o scmlit} will make a script for compiling
+@samp{scmlit}.
@example
bash$ ./build
@@ -630,7 +843,7 @@ files:
@table @file
@item dlls.opt
-Options for Makefile targets mydlls, myturtle, and x.so.
+Options for Makefile targets dlls, myturtle, and x.so.
@item gdb.opt
Options for udgdbscm and gdbscm.
@item libscm.opt
@@ -833,119 +1046,8 @@ dynamic-loading), you can load the compiled file with the Scheme command
add a compiled dll file to SLIB's catalog.
-@node Installing Dynamic Linking, Configure Module Catalog, Building SCM, Installing SCM
-@section Installing Dynamic Linking
-
-@noindent
-Dynamic linking has not been ported to all platforms. Operating systems
-in the BSD family (a.out binary format) can usually be ported to
-@dfn{DLD}. The @dfn{dl} library (@code{#define SUN_DL} for SCM) was a
-proposed POSIX standard and may be available on other machines with
-@dfn{COFF} binary format. For notes about porting to MS-Windows and
-finishing the port to VMS @ref{VMS Dynamic Linking}.
-
-@noindent
-@dfn{DLD} is a library package of C functions that performs
-@dfn{dynamic link editing} on GNU/Linux, VAX (Ultrix), Sun 3 (SunOS
-3.4 and 4.0), SPARCstation (SunOS 4.0), Sequent Symmetry (Dynix), and
-Atari ST. It is available from:
-
-@ifclear html
-@itemize @bullet
-@item
-ftp.gnu.org:pub/gnu/dld-3.3.tar.gz
-@end itemize
-@end ifclear
-
-@ifset html
-<A HREF="ftp://ftp.gnu.org/pub/gnu/dld-3.3.tar.gz">
-ftp.gnu.org:pub/gnu/dld-3.3.tar.gz
-</A>
-@end ifset
-
-@noindent
-These notes about using libdl on SunOS are from @file{gcc.info}:
-
-@quotation
-On a Sun, linking using GNU CC fails to find a shared library and
-reports that the library doesn't exist at all.
-
-This happens if you are using the GNU linker, because it does only
-static linking and looks only for unshared libraries. If you have
-a shared library with no unshared counterpart, the GNU linker
-won't find anything.
-
-We hope to make a linker which supports Sun shared libraries, but
-please don't ask when it will be finished--we don't know.
-
-Sun forgot to include a static version of @file{libdl.a} with some
-versions of SunOS (mainly 4.1). This results in undefined symbols when
-linking static binaries (that is, if you use @samp{-static}). If you
-see undefined symbols @samp{_dlclose}, @samp{_dlsym} or @samp{_dlopen}
-when linking, compile and link against the file
-@file{mit/util/misc/dlsym.c} from the MIT version of X windows.
-@end quotation
-
-
-@node Configure Module Catalog, Saving Images, Installing Dynamic Linking, Installing SCM
-@section Configure Module Catalog
-
-@noindent
-The SLIB module @dfn{catalog} can be extended to define other
-@code{require}-able packages by adding calls to the Scheme source file
-@file{mkimpcat.scm}. Within @file{mkimpcat.scm}, the following
-procedures are defined.
-
-@defun add-link feature object-file lib1 @dots{}
-@var{feature} should be a symbol. @var{object-file} should be a string
-naming a file containing compiled @dfn{object-code}. Each @var{lib}n
-argument should be either a string naming a library file or @code{#f}.
-
-If @var{object-file} exists, the @code{add-link} procedure registers
-symbol @var{feature} so that the first time @code{require} is called
-with the symbol @var{feature} as its argument, @var{object-file} and the
-@var{lib1} @dots{} are dynamically linked into the executing SCM
-session.
-
-If @var{object-file} exists, @code{add-link} returns @code{#t},
-otherwise it returns @code{#f}.
-
-For example, to install a compiled dll @file{foo}, add these lines to
-@file{mkimpcat.scm}:
-
-@example
- (add-link 'foo
- (in-vicinity (implementation-vicinity) "foo"
- link:able-suffix))
-@end example
-
-
-@end defun
-
-@defun add-alias alias feature
-@var{alias} and @var{feature} are symbols. The procedure
-@code{add-alias} registers @var{alias} as an alias for @var{feature}.
-An unspecified value is returned.
-
-@code{add-alias} causes @code{(require '@var{alias})} to behave like
-@code{(require '@var{feature})}.
-@end defun
-
-@defun add-source feature filename
-@var{feature} is a symbol. @var{filename} is a string naming a file
-containing Scheme source code. The procedure @code{add-source}
-registers @var{feature} so that the first time @code{require} is called
-with the symbol @var{feature} as its argument, the file @var{filename}
-will be @code{load}ed. An unspecified value is returned.
-@end defun
-
-@noindent
-Remember to delete the file @file{slibcat} after modifying the file
-@file{mkimpcat.scm} in order to force SLIB to rebuild its cache.
-
-
-@node Saving Images, Automatic C Preprocessor Definitions, Configure Module Catalog, Installing SCM
-@section Saving Images
+@node Saving Executable Images, Installation, Building SCM, Installing SCM
+@section Saving Executable Images
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
@@ -962,7 +1064,8 @@ The @samp{dscm4} and @samp{dscm5} targets in the SCM @file{Makefile}
save images from @file{udscm4} and @file{udscm5} executables
respectively.
-Recent GNU/Linux innovations interfere with @code{dump}. For:
+@dfn{Address space layout randomization} interferes with @code{dump}.
+Here are the fixes for various operating-systems:
@table @asis
@item Fedora-Core-1
@@ -970,7 +1073,7 @@ 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:
+@url{http://jamesthornton.com/writing/emacs-compile.html}
[For FC3] combreloc has become the default for recent GNU ld, which
breaks the unexec/undump on all versions of both Emacs and
XEmacs...
@@ -978,8 +1081,8 @@ 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}
+@item Linux Kernels later than 2.6.11
+@exdent @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):
@@ -991,106 +1094,55 @@ 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.
+@item OS-X 10.6
+
+@exdent @url{http://developer.apple.com/library/mac/#documentation/Darwin/Reference/Manpages/man1/dyld.1.html}
+The dynamic linker uses the following environment variables. They
+affect any program that uses the dynamic linker.
+
+DYLD_NO_PIE
+
+Causes dyld to not randomize the load addresses of images in a process
+where the main executable was built position independent. This can be
+helpful when trying to reproduce and debug a problem in a PIE.
+
@end table
-@node Automatic C Preprocessor Definitions, Problems Compiling, Saving Images, Installing SCM
-@section Automatic C Preprocessor Definitions
+@node Installation, Troubleshooting and Testing, Saving Executable Images, Installing SCM
+@section Installation
-These @samp{#defines} are automatically provided by preprocessors of
-various C compilers. SCM uses the presence or absence of these
-definitions to configure @dfn{include file} locations and aliases for
-library functions. If the definition(s) corresponding to your system
-type is missing as your system is configured, add @code{-D@var{flag}} to
-the compilation command lines or add a @code{#define @var{flag}} line to
-@file{scmfig.h} or the beginning of @file{scmfig.h}.
+Once @code{scmlit}, @code{scm}, and @code{dlls} have been built, these
+commands will install them to the locations specified when you ran
+@samp{./configure}:
@example
-#define Platforms:
-------- ----------
-ARM_ULIB Huw Rogers free unix library for acorn archimedes
-AZTEC_C Aztec_C 5.2a
-__CYGWIN__ Cygwin
-__CYGWIN32__ Cygwin
-_DCC Dice C on AMIGA
-__GNUC__ Gnu CC (and DJGPP)
-__EMX__ Gnu C port (gcc/emx 0.8e) to OS/2 2.0
-__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
+bash$ (cd scm; make install)
+bash$ (cd slib; make install)
+@end example
-_AIX AIX operating system
-__APPLE__ Apple Darwin
-AMIGA SAS/C 5.10 or Dice C on AMIGA
-__amigaos__ Gnu CC on AMIGA
-atarist ATARI-ST under Gnu CC
-__DragonflyBSD__ DragonflyBSD
-__FreeBSD__ FreeBSD
-GNUDOS DJGPP (obsolete in version 1.08)
-__GO32__ DJGPP (future?)
-hpux HP-UX
-linux GNU/Linux
-macintosh Macintosh (THINK_C and __MWERKS__ define)
-MCH_AMIGA Aztec_c 5.2a on AMIGA
-__MACH__ Apple Darwin
-__MINGW32__ MinGW - Minimalist GNU for Windows
-MSDOS Microsoft C 5.10 and 6.00A
-_MSDOS Microsoft CLARM and CLTHUMB compilers.
-__MSDOS__ Turbo C, Borland C, and DJGPP
-__NetBSD__ NetBSD
-nosve Control Data NOS/VE
-__OpenBSD__ OpenBSD
-SVR2 System V Revision 2.
-sun SunOS
-__SVR4 SunOS
-THINK_C developement environment for the Macintosh
-ultrix VAX with ULTRIX operating system.
-unix most Unix and similar systems and DJGPP (!?)
-__unix__ Gnu CC and DJGPP
-_UNICOS Cray operating system
-vaxc VAX C compiler
-VAXC VAX C compiler
-vax11c VAX C compiler
-VAX11 VAX C compiler
-_Windows Borland C 3.1 compiling for Windows
-_WIN32 MS VisualC++ 4.2 and Cygwin (Win32 API)
-_WIN32_WCE MS Windows CE
-vms (and VMS) VAX-11 C under VMS.
+Note that installation to system directories (like @samp{/usr/bin/})
+will require that those commands be run as root:
-__alpha DEC Alpha processor
-__alpha__ DEC Alpha processor
-hp9000s800 HP RISC processor
-__ia64 GCC on IA64
-__ia64__ GCC on IA64
-_LONGLONG GCC on IA64
-__i386__ DJGPP
-i386 DJGPP
-_M_ARM Microsoft CLARM compiler defines as 4 for ARM.
-_M_ARMT Microsoft CLTHUMB compiler defines as 4 for Thumb.
-MULTIMAX Encore computer
-ppc PowerPC
-__ppc__ PowerPC
-pyr Pyramid 9810 processor
-__sgi__ Silicon Graphics Inc.
-sparc SPARC processor
-sequent Sequent computer
-tahoe CCI Tahoe processor
-vax VAX processor
-__x86_64 AMD Opteron
+@example
+bash$ (cd scm; sudo make install)
+bash$ (cd slib; sudo make install)
@end example
+@node Troubleshooting and Testing, , Installation, Installing SCM
+@section Troubleshooting and Testing
-@node Problems Compiling, Problems Linking, Automatic C Preprocessor Definitions, Installing SCM
-@section Problems Compiling
+@menu
+* Problems Compiling::
+* Problems Linking::
+* Testing::
+* Problems Starting::
+* Problems Running::
+* Reporting Problems::
+@end menu
+
+@node Problems Compiling, Problems Linking, Troubleshooting and Testing, Troubleshooting and Testing
+@subsection Problems Compiling
@multitable @columnfractions .10 .45 .45
@item FILE
@@ -1144,8 +1196,8 @@ __x86_64 AMD Opteron
@end multitable
-@node Problems Linking, Problems Running, Problems Compiling, Installing SCM
-@section Problems Linking
+@node Problems Linking, Testing, Problems Compiling, Troubleshooting and Testing
+@subsection Problems Linking
@multitable @columnfractions .5 .5
@item PROBLEM
@@ -1155,12 +1207,62 @@ __x86_64 AMD Opteron
@end multitable
-@node Problems Running, Testing, Problems Linking, Installing SCM
-@section Problems Running
+@node Testing, Problems Starting, Problems Linking, Troubleshooting and Testing
+@subsection Testing
+
+@noindent
+Loading @file{r4rstest.scm} in the distribution will run an [R4RS]
+conformance test on @code{scm}.
+
+@example
+> (load "r4rstest.scm")
+@print{}
+;loading r4rstest.scm
+SECTION(2 1)
+SECTION(3 4)
+ #<primitive-procedure boolean?>
+ #<primitive-procedure char?>
+ #<primitive-procedure null?>
+ #<primitive-procedure number?>
+@dots{}
+@end example
+
+@noindent
+Loading @file{pi.scm} in the distribution will enable you to compute
+digits of pi.
+
+@example
+> (load "pi.scm")
+;loading pi.scm
+;done loading pi.scm
+#<unspecified>
+> (pi 100 5)
+00003 14159 26535 89793 23846 26433 83279 50288 41971 69399
+37510 58209 74944 59230 78164 06286 20899 86280 34825 34211
+70679
+;Evaluation took 550 ms (60 in gc) 36976 cells work, 1548.B other
+#<unspecified>
+@end example
+
+@subheading Performance
+
+@noindent
+Loading @file{bench.scm} will compute and display performance statistics
+of SCM running @file{pi.scm}. @samp{make bench} or @samp{make benchlit}
+appends the performance report to the file @file{BenchLog}, facilitating
+tracking effects of changes to SCM on performance.
+
+
+@node Problems Starting, Problems Running, Testing, Troubleshooting and Testing
+@subsection Problems Starting
@multitable @columnfractions .5 .5
@item PROBLEM
@tab HOW TO FIX
+@item /bin/bash: scm: program not found
+@tab Is @samp{scm} in a @samp{$PATH} directory?
+@item /bin/bash: /usr/local/bin/scm: Permission denied
+@tab @code{chmod +x /usr/local/bin/scm}
@item Opening message and then machine crashes.
@tab Change memory model option to C compiler (or makefile).
@item
@@ -1194,49 +1296,8 @@ __x86_64 AMD Opteron
@end multitable
-@node Testing, Reporting Problems, Problems Running, Installing SCM
-@section Testing
-
-@noindent
-Loading @file{r4rstest.scm} in the distribution will run an [R4RS]
-conformance test on @code{scm}.
-
-@example
-> (load "r4rstest.scm")
-@print{}
-;loading "r4rstest.scm"
-SECTION(2 1)
-SECTION(3 4)
- #<primitive-procedure boolean?>
- #<primitive-procedure char?>
- #<primitive-procedure null?>
- #<primitive-procedure number?>
-@dots{}
-@end example
-
-@noindent
-Loading @file{pi.scm} in the distribution will enable you to compute
-digits of pi.
-
-@example
-> (load "pi")
-;loading "pi"
-;done loading "pi.scm"
-;Evaluation took 20 ms (0 in gc) 767 cells work, 233.B other
-#<unspecified>
-> (pi 100 5)
-00003 14159 26535 89793 23846 26433 83279 50288 41971 69399
-37510 58209 74944 59230 78164 06286 20899 86280 34825 34211
-70679
-;Evaluation took 550 ms (60 in gc) 36976 cells work, 1548.B other
-#<unspecified>
-@end example
-
-@noindent
-Loading @file{bench.scm} will compute and display performance statistics
-of SCM running @file{pi.scm}. @samp{make bench} or @samp{make benchlit}
-appends the performance report to the file @file{BenchLog}, facilitating
-tracking effects of changes to SCM on performance.
+@node Problems Running, Reporting Problems, Problems Starting, Troubleshooting and Testing
+@subsection Problems Running
@multitable @columnfractions .5 .5
@item PROBLEM
@@ -1268,27 +1329,27 @@ tracking effects of changes to SCM on performance.
@item VAX: botched longjmp.
@end multitable
-@table @asis
-@item Sparc(SUN-4) heap is growing out of control
-You are experiencing a GC problem peculiar to the Sparc. The problem
-is that SCM doesn't know how to clear register windows. Every
-location which is not reused still gets marked at GC time. This
-causes lots of stuff which should be collected to not be. This will
-be a problem with any @emph{conservative} GC until we find what
-instruction will clear the register windows. This problem is
-exacerbated by using lots of call-with-current-continuations.
-A possible fix for dynthrow() is commented out in @file{continue.c}.
-@end table
+@c @table @asis
+@c @item Sparc(SUN-4) heap is growing out of control
+@c You are experiencing a GC problem peculiar to the Sparc. The problem
+@c is that SCM doesn't know how to clear register windows. Every
+@c location which is not reused still gets marked at GC time. This
+@c causes lots of stuff which should be collected to not be. This will
+@c be a problem with any @emph{conservative} GC until we find what
+@c instruction will clear the register windows. This problem is
+@c exacerbated by using lots of call-with-current-continuations.
+@c A possible fix for dynthrow() is commented out in @file{continue.c}.
+@c @end table
-@node Reporting Problems, , Testing, Installing SCM
-@section Reporting Problems
+@node Reporting Problems, , Problems Running, Troubleshooting and Testing
+@subsection Reporting Problems
@noindent
Reported problems and solutions are grouped under Compiling, Linking,
-Running, and Testing. If you don't find your problem listed there, you
-can send a bug report to @code{agj @@ alum.mit.edu}. The bug report
-should include:
+Running, and Testing. If you don't find your problem listed there,
+you can send a bug report to @code{agj@@alum.mit.edu} or
+@code{scm-discuss@@gnu.org}. The bug report should include:
@enumerate
@item
@@ -1634,6 +1695,24 @@ terminal of the process, or #f if this information cannot be determined.
For documentation of the procedures @code{getenv} and @code{system}
@xref{System Interface, , , slib, SLIB}.
+SCM extends @code{getenv} as suggested by draft SRFI-98:
+
+@defun getenv name
+Looks up @var{name}, a string, in the program environment. If @var{name} is
+found a string of its value is returned. Otherwise, @code{#f} is returned.
+@end defun
+@defun getenv
+Returns names and values of all the environment variables as an
+association-list.
+
+@example
+(getenv) @result{}
+(("PATH" . "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin")
+ ("USERNAME" . "taro"))
+@end example
+@end defun
+
+
@defun vms-debug
If SCM is compiled under VMS this @code{vms-debug} will invoke the VMS
debugger.
@@ -1647,8 +1726,8 @@ debugger.
The value of the environment variable @code{EDITOR} (or just @code{ed}
if it isn't defined) is invoked as a command with arguments @var{arg1}
@dots{}.
-
-@defunx ed filename
+@end defun
+@defun ed filename
If SCM is compiled under VMS @code{ed} will invoke the editor with a
single the single argument @var{filename}.
@end defun
@@ -1734,7 +1813,8 @@ loads the appropriate module from SLIB if they are invoked.
@defmac trace proc1 @dots{}
Traces the top-level named procedures given as arguments.
-@defmacx trace
+@end defmac
+@defmac trace
With no arguments, makes sure that all the currently traced identifiers
are traced (even if those identifiers have been redefined) and returns a
list of the traced identifiers.
@@ -1742,7 +1822,8 @@ list of the traced identifiers.
@defmac untrace proc1 @dots{}
Turns tracing off for its arguments.
-@defmacx untrace
+@end defmac
+@defmac untrace
With no arguments, untraces all currently traced identifiers and returns
a list of these formerly traced identifiers.
@end defmac
@@ -1810,8 +1891,7 @@ offers source code debugging from
GNU Emacs. PSD runs slowly, so start by instrumenting only a few
functions at a time.
@lisp
-http://swiss.csail.mit.edu/ftpdir/scm/slib-psd1-3.tar.gz
-swiss.csail.mit.edu:/pub/scm/slib-psd1-3.tar.gz
+http://groups.csail.mit.edu/mac/ftpdir/scm/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
@end lisp
@@ -2183,6 +2263,10 @@ Scans all of SCM objects and reclaims for further use those that are
no longer accessible.
@end defun
+@defun gc #t
+Garbage-collects only the ecache.
+@end defun
+
@defun room
@defunx room #t
Prints out statistics about SCM's current use of storage. @code{(room #t)}
@@ -2206,8 +2290,8 @@ 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
+@end defun
+@defun execpath #f
@defunx execpath newpath
Sets the path to @code{#f} or @var{newpath}, respectively. The old path
is returned.
@@ -2345,7 +2429,7 @@ and MS-DOS. To implement this, I have written the MS-DOS programs:
@cindex #!
@cindex #!.bat
which are available from:
-@url{http://swiss.csail.mit.edu/ftpdir/scm/sharpbang.zip}
+@url{http://groups.csail.mit.edu/mac/ftpdir/scm/sharpbang.zip}
@noindent
With these two programs installed in a @code{PATH} directory, we have
@@ -2521,10 +2605,14 @@ Many of the optional features are supported as well.
@itemx @code{exact->inexact}
@itemx @code{inexact->exact}
@xref{Numerical operations, , , r5rs, Revised(5) Scheme}.
-@itemx @code{with-input-from-file}
+@end table
+@table @asis
+@item @code{with-input-from-file}
@itemx @code{with-output-to-file}
@xref{Ports, , , r5rs, Revised(5) Scheme}.
-@itemx @code{load}
+@end table
+@table @asis
+@item @code{load}
@itemx @code{transcript-on}
@itemx @code{transcript-off}
@xref{System interface, , , r5rs, Revised(5) Scheme}.
@@ -2677,7 +2765,7 @@ seconds.
Returns the integer time in internal time units from an unspecified
starting time. The difference of two calls to
@code{get-internal-real-time} divided by
-@code{interal-time-units-per-second} will give elapsed real time in
+@code{internal-time-units-per-second} will give elapsed real time in
seconds.
@end defun
@@ -2930,8 +3018,8 @@ not open to a file the result is unspecified.
Returns the current position of the character in @var{port} which will
next be read or written. If @var{port} is open to a non-file then
@code{#f} is returned.
-
-@defunx file-position port k
+@end defun
+@defun file-position port k
Sets the current position in @var{port} which will next be read or
written. If successful, @code{#f} is returned. If @var{port} is open
to a non-file, then @code{file-position} returns @code{#f}.
@@ -3321,8 +3409,8 @@ internal definitions) is a string, then that string is the
@defun comment string1 @dots{}
Appends @var{string1} @dots{} to the strings given as arguments to
previous calls @code{comment}.
-
-@defunx comment
+@end defun
+@defun comment
Returns the (appended) strings given as arguments to previous calls
@code{comment} and empties the current string collection.
@end defun
@@ -3345,8 +3433,8 @@ read from. The value returned by this function will be the value of
@code{#<unspecified>} in which case the expression will be treated as
whitespace. @code{#<unspecified>} is the value returned by the
expression @code{(if #f #f)}.
-
-@deffnx {Callback procedure} load:sharp c port
+@end deffn
+@deffn {Callback procedure} load:sharp c port
Dispatches like @code{read:sharp}, but only during @code{load}s. The
read-syntaxes handled by @code{load:sharp} are a superset of those
handled by @code{read:sharp}. @code{load:sharp} calls
@@ -4195,9 +4283,21 @@ The immediate integer closest to negative infinity.
The ratio of the circumference to the diameter of a circle.
@end defvr
+These procedures are in addition to those in
+@xref{Irrational Integer Functions, , , slib, SLIB}.
+
+@defun exact-round x
+@defunx exact-floor x
+@defunx exact-ceiling x
+@defunx exact-truncate x
+Return exact integers.
+@end defun
+
@noindent
These procedures augment the standard capabilities in
@ref{Numerical operations, , ,r5rs, Revised(5) Scheme}.
+Many are from
+@xref{Irrational Real Functions, , , slib, SLIB}.
@defun pi* z
@code{(* pi @var{z})}
@@ -4228,6 +4328,7 @@ Return the inverse hyperbolic sine, cosine, and tangent of @var{z}
@defunx real-asin x
@defunx real-acos x
@defunx real-atan x
+@defunx atan y x
@defunx real-sinh x
@defunx real-cosh x
@@ -4255,6 +4356,12 @@ an error if the value which should be returned by a call to @code{real-expt}
is not real.
@end defun
+@defun infinite? z
+@defunx finite? z
+All IEEE-754 numbers except positive and negative infinity and NaN
+(non-a-number) are finite.
+@end defun
+
@node Arrays, Records, Numeric, Packages
@section Arrays
@@ -4325,14 +4432,15 @@ an enclosed array will be @code{equal?} but will not in general be
enclosed array is unspecified.
examples:
+@end defun
+
@example
-(enclose-array '#3A(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{}
- #<enclosed-array (#1A(a d) #1A(b e) #1A(c f)) (#1A(1 4) #1A(2 5) #1A(3 6))>
+@exdent (enclose-array '#3A(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{}
+@exdent #<enclosed-array (#1A(a d) #1A(b e) #1A(c f)) (#1A(1 4) #1A(2 5) #1A(3 6))>
-(enclose-array '#3A(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{}
- #<enclosed-array #2A((a 1) (d 4)) #2A((b 2) (e 5)) #2A((c 3) (f 6))>
+@exdent (enclose-array '#3A(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{}
+@exdent #<enclosed-array #2A((a 1) (d 4)) #2A((b 2) (e 5)) #2A((c 3) (f 6))>
@end example
-@end defun
@defun array->list array
Returns a list consisting of all the elements, in order, of @var{array}.
@@ -4510,13 +4618,15 @@ Modifies @var{bv} by replacing each element with its negation.
@end defun
@defun bit-set*! bv uve bool
-If uve is a bit-vector @var{bv} and uve must be of the same length. If
-@var{bool} is @code{#t}, uve is OR'ed into @var{bv}; If @var{bool} is @code{#f}, the
-inversion of uve is AND'ed into @var{bv}.
+If @var{uve} is a bit-vector, then @var{bv} and @var{uve} must be of
+the same length. If @var{bool} is @code{#t}, then @var{uve} is OR'ed
+into @var{bv}; If @var{bool} is @code{#f}, the inversion of @var{uve}
+is AND'ed into @var{bv}.
-If uve is a unsigned integer vector all the elements of uve must be
-between 0 and the @code{LENGTH} of @var{bv}. The bits of @var{bv}
-corresponding to the indexes in uve are set to @var{bool}.
+If @var{uve} is a unsigned integer vector, then all the elements of
+@var{uve} must be between 0 and the @code{LENGTH} of @var{bv}. The
+bits of @var{bv} corresponding to the indexes in @var{uve} are set to
+@var{bool}.
The return value is unspecified.
@end defun
@@ -4718,12 +4828,12 @@ closed,, @code{closedir} returns a @code{#f}.
each file in @var{directory}. The dynamic order in which @var{proc} is
applied to the filenames is unspecified. The value returned by
@samp{directory-for-each} is unspecified.
-
-@defunx directory-for-each proc directory pred
+@end defun
+@defun directory-for-each proc directory pred
Applies @var{proc} only to those filenames for which the procedure
@var{pred} returns a non-false value.
-
-@defunx directory-for-each proc directory match
+@end defun
+@defun directory-for-each proc directory match
Applies @var{proc} only to those filenames for which
@code{(filename:match?? @var{match})} would return a non-false value
(@pxref{Filenames, , , slib, SLIB}).
@@ -4741,6 +4851,16 @@ Applies @var{proc} only to those filenames for which
@end example
@end defun
+@defun directory*-for-each proc path-glob
+@var{path-glob} is a pathname whose last component is a (wildcard) pattern
+(@pxref{Filenames, , , slib, SLIB}).
+@var{proc} must be a procedure taking one argument.
+@samp{directory*-for-each} applies @var{proc} to the (string) name of
+each file in the current directory. The dynamic order in which @var{proc} is
+applied to the filenames is unspecified. The value returned by
+@samp{directory*-for-each} is unspecified.
+@end defun
+
@defun mkdir path mode
The @code{mkdir} function creates a new, empty directory whose name is
@var{path}. The integer argument @var{mode} specifies the file
@@ -4775,6 +4895,12 @@ If the renaming is successful, @code{#t} is returned. Otherwise,
@code{#f} is returned.
@end defun
+@defun copy-file oldfilename newfilename
+Copies the file specified by @var{oldfilename} to @var{newfilename}.
+If the copying is successful, @code{#t} is returned. Otherwise,
+@code{#f} is returned.
+@end defun
+
@defun chmod file mode
The function @code{chmod} sets the access permission bits for the file
named by @var{file} to @var{mode}. The @var{file} argument may be a
@@ -4843,8 +4969,8 @@ as @var{command}.
If successful, this procedure does not return. Otherwise an error
message is printed and the integer @code{errno} is returned.
-
-@defunx execv command arglist
+@end defun
+@defun execv command arglist
@defunx execvp command arglist
Like @code{execl} and @code{execlp} except that the set of arguments to
@var{command} is @var{arglist}.
@@ -5123,8 +5249,8 @@ or @code{#f}, indicating that the system default should be used.
@defun setpwent #t
Rewinds the pw entry table back to the begining.
-
-@defunx setpwent #f
+@end defun
+@defun setpwent #f
@defunx setpwent
Closes the pw table.
@end defun
@@ -5151,8 +5277,8 @@ A list of (string) names of users in the group.
@defun setgrent #t
Rewinds the group entry table back to the begining.
-
-@defunx setgrent #f
+@end defun
+@defun setgrent #f
@defunx setgrent
Closes the group table.
@end defun
@@ -5385,6 +5511,8 @@ to perform one substitution.
@node Line Editing, Curses, Regular Expression Pattern Matching, Packages
@section Line Editing
+@code{(require 'edit-line)}
+
@noindent
These procedures provide input line editing and recall.
@@ -5414,9 +5542,9 @@ available from:
@end itemize
@noindent
-When @file{Iedline.scm} is loaded, if the current input port is the
-default input port and the environment variable @var{EMACS} is not
-defined, line-editing mode will be entered.
+When @code{edit-line} package is initialized, if the current input
+port is the default input port and the environment variable
+@var{EMACS} is not defined, line-editing mode will be entered.
@defun default-input-port
Returns the initial @code{current-input-port} SCM was invoked with
@@ -5435,8 +5563,8 @@ retrieval of history.
@defun line-editing
Returns the current edited line port or @code{#f}.
-
-@defunx line-editing bool
+@end defun
+@defun line-editing bool
If @var{bool} is false, exits line-editing mode and returns the previous
value of @code{(line-editing)}. If @var{bool} is true, sets the current
input and output ports to an edited line port and returns the previous
@@ -6290,8 +6418,11 @@ in 2 basic flavors, Immediates and Cells:
* Cells:: Non-Immediate types
* Header Cells:: Malloc objects
* Subr Cells:: Built-in and Compiled Procedures
+* Defining Subrs::
* Ptob Cells:: I/O ports
+* Defining Ptobs::
* Smob Cells:: Miscellaneous datatypes
+* Defining Smobs::
* Data Type Representations:: How they all fit together
@end menu
@@ -6434,8 +6565,8 @@ The number of ispcsyms and ispcsyms+isyms, respectively. Defined in
@code{letrec}, @code{or}, @code{quote}, @code{set!}, @code{#f},
@code{#t}, @code{#<undefined>}, @code{#<eof>}, @code{()}, and
@code{#<unspecified>}.
-
-@deftpx {CAR Immediate} ispcsym
+@end deftp
+@deftp {CAR Immediate} ispcsym
special symbols: syntax-checked versions of first 14 isyms
@end deftp
@@ -6561,8 +6692,8 @@ Returns the C array of @code{SCM}s holding the elements of vector
@deftp Header tc7_ssymbol
static scheme symbol (part of initial system)
-
-@deftpx Header tc7_msymbol
+@end deftp
+@deftp Header tc7_msymbol
@code{malloc}ed scheme symbol (can be GCed)
@defmac SYMBOLP x
@@ -6670,7 +6801,7 @@ Expands to the length of @var{cclo}.
@end deftp
-@node Subr Cells, Ptob Cells, Header Cells, Data Types
+@node Subr Cells, Defining Subrs, Header Cells, Data Types
@subsection Subr Cells
@noindent
@@ -6747,7 +6878,63 @@ C function of list of @code{SCM} arguments.
@end deftp
-@node Ptob Cells, Smob Cells, Subr Cells, Data Types
+@node Defining Subrs, Ptob Cells, Subr Cells, Data Types
+@subsection Defining Subrs
+
+@noindent
+If @dfn{CCLO} is @code{#define}d when compiling, the compiled closure
+feature will be enabled. It is automatically enabled if dynamic linking
+is enabled.
+
+@noindent
+The SCM interpreter directly recognizes subrs taking small numbers of
+arguments. In order to create subrs taking larger numbers of arguments
+use:
+
+@defun make_gsubr name req opt rest fcn
+returns a cclo (compiled closure) object of name @code{char *}
+@var{name} which takes @code{int} @var{req} required arguments,
+@code{int} @var{opt} optional arguments, and a list of rest arguments if
+@code{int} @var{rest} is 1 (0 for not).
+
+@code{SCM (*fcn)()} is a pointer to a C function to do the work.
+
+The C function will always be called with @var{req} + @var{opt} +
+@var{rest} arguments, optional arguments not supplied will be passed
+@code{UNDEFINED}. An error will be signaled if the subr is called with
+too many or too few arguments. Currently a total of 10 arguments may be
+specified, but increasing this limit should not be difficult.
+
+@example
+/* A silly example, taking 2 required args,
+ 1 optional, and a list of rest args */
+
+#include <scm.h>
+
+SCM gsubr_21l(req1,req2,opt,rst)
+ SCM req1,req2,opt,rst;
+@{
+ lputs("gsubr-2-1-l:\n req1: ", cur_outp);
+ display(req1,cur_outp);
+ lputs("\n req2: ", cur_outp);
+ display(req2,cur_outp);
+ lputs("\n opt: ", cur_outp);
+ display(opt,cur_outp);
+ lputs("\n rest: ", cur_outp);
+ display(rst,cur_outp);
+ newline(cur_outp);
+ return UNSPECIFIED;
+@}
+
+void init_gsubr211()
+@{
+ make_gsubr("gsubr-2-1-l", 2, 1, 1, gsubr_21l);
+@}
+@end example
+@end defun
+
+
+@node Ptob Cells, Defining Ptobs, Defining Subrs, Data Types
@subsection Ptob Cells
@noindent
@@ -6820,7 +7007,40 @@ open output-port, respectively.
@end defmac
-@node Smob Cells, Data Type Representations, Ptob Cells, Data Types
+@node Defining Ptobs, Smob Cells, Ptob Cells, Data Types
+@subsection Defining Ptobs
+
+@noindent
+@dfn{ptob}s are similar to smobs but define new types of port to which
+SCM procedures can read or write. The following functions are defined
+in the @code{ptobfuns}:
+
+@example
+typedef struct @{
+ SCM (*mark)P((SCM ptr));
+ int (*free)P((FILE *p));
+ int (*print)P((SCM exp, SCM port, int writing));
+ SCM (*equalp)P((SCM, SCM));
+ int (*fputc)P((int c, FILE *p));
+ int (*fputs)P((char *s, FILE *p));
+ sizet (*fwrite)P((char *s, sizet siz, sizet num, FILE *p));
+ int (*fflush)P((FILE *stream));
+ int (*fgetc)P((FILE *p));
+ int (*fclose)P((FILE *p));
+@} ptobfuns;
+@end example
+
+@noindent
+The @code{.free} component to the structure takes a @code{FILE *} or
+other C construct as its argument, unlike @code{.free} in a smob, which
+takes the whole smob cell. Often, @code{.free} and @code{.fclose} can be
+the same function. See @code{fptob} and @code{pipob} in @file{sys.c}
+for examples of how to define ptobs.
+Ptobs that must allocate blocks of memory should use, for example,
+@code{must_malloc} rather than @code{malloc} @xref{Allocating memory}.
+
+
+@node Smob Cells, Defining Smobs, Defining Ptobs, Data Types
@subsection Smob Cells
@noindent
@@ -6928,7 +7148,82 @@ VfixZ32, VfixN32, VfloR32, VfloR64, or VfloC64) in their @code{CDR}.
@end deftp
-@node Data Type Representations, , Smob Cells, Data Types
+@node Defining Smobs, Data Type Representations, Smob Cells, Data Types
+@subsection Defining Smobs
+
+@noindent
+Here is an example of how to add a new type named @code{@i{foo}} to SCM.
+The following lines need to be added to your code:
+
+@table @code
+@item long tc16_@i{foo};
+The type code which will be used to identify the new type.
+@item static smobfuns @i{foo}smob = @{mark@i{foo},free@i{foo},print@i{foo},equalp@i{foo}@};
+smobfuns is a structure composed of 4 functions:
+
+@example
+typedef struct @{
+ SCM (*mark)P((SCM));
+ sizet (*free)P((CELLPTR));
+ int (*print)P((SCM exp, SCM port, int writing));
+ SCM (*equalp)P((SCM, SCM));
+@} smobfuns;
+@end example
+
+@table @code
+@item smob.mark
+is a function of one argument of type @code{SCM} (the cell to mark) and
+returns type @code{SCM} which will then be marked. If no further
+objects need to be marked then return an immediate object such as
+@code{BOOL_F}. The smob cell itself will already have been marked.
+@emph{Note@:} This is different from SCM versions prior to 5c5. Only
+additional data specific to a smob type need be marked by @code{smob.mark}.
+
+ 2 functions are provided:
+
+@table @code
+@item markcdr(ptr)
+returns @code{CDR(ptr)}.
+@item mark0(ptr)
+is a no-op used for smobs containing no additional @code{SCM} data. 0
+may also be used in this case.
+@end table
+
+@item smob.free
+is a function of one argument of type @code{CELLPTR} (the cell to
+collected) and returns type @code{sizet} which is the number of
+@code{malloc}ed bytes which were freed. @code{Smob.free} should free
+any @code{malloc}ed storage associated with this object. The function
+free0(ptr) is provided which does not free any storage and returns 0.
+@item smob.print
+is 0 or a function of 3 arguments. The first, of type @code{SCM}, is
+the smob object. The second, of type @code{SCM}, is the stream on which
+to write the result. The third, of type int, is 1 if the object should
+be @code{write}n, 0 if it should be @code{display}ed, and 2 if it should
+be @code{write}n for an error report. This function should return non-zero
+if it printed, and zero otherwise (in which case a hexadecimal number will
+be printed).
+@item smob.equalp
+is 0 or a function of 2 @code{SCM} arguments. Both of these arguments
+will be of type @code{tc16@i{foo}}. This function should return
+@code{BOOL_T} if the smobs are equal, @code{BOOL_F} if they are not. If
+@code{smob.equalp} is 0, @code{equal?} will return @code{BOOL_F} if they
+are not @code{eq?}.
+@end table
+
+@item tc16_@i{foo} = newsmob(&@i{foo}smob);
+Allocates the new type with the functions from @code{@i{foo}smob}. This
+line goes in an @code{init_} routine.
+@end table
+
+@noindent
+Promises and macros in @file{eval.c} and arbiters in @file{repl.c}
+provide examples of SMOBs. There are a maximum of 256 SMOBs.
+Smobs that must allocate blocks of memory should use, for example,
+@code{must_malloc} rather than @code{malloc} @xref{Allocating memory}.
+
+
+@node Data Type Representations, , Defining Smobs, Data Types
@subsection Data Type Representations
@format
@@ -6954,20 +7249,20 @@ ssymbol .........long length....G0000101 ..........char *chars...........
msymbol .........long length....G0000111 ..........char *chars...........
string .........long length....G0001101 ..........char *chars...........
vector .........long length....G0001111 ...........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...........
+VfixN8 .........long length....G0010101 ......unsigned char *words......
+VfixZ8 .........long length....G0010111 ..........char *words...........
+VfixN16 .........long length....G0011101 ......unsigned short *words.....
+VfixZ16 .........long length....G0011111 ........ short *words...........
+VfixN32 .........long length....G0100101 ......unsigned medium *words....
+VfixZ32 .........long length....G0100111 ........medium *words...........
+VfixN64 .........long length....G0101101 ......unsigned long *words......
+VfixZ64 .........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
+Vbool .........long length....G1000101 ..........long *words...........
contin .........long length....G1001101 .............*regs..............
specfun ................xxxxxxxxG1001111 ...........SCM name.............
cclo ..short length..xxxxxx10G1001111 ...........SCM **elts...........}
@@ -7016,12 +7311,12 @@ array ...short rank..cxxxxxxxxG1111111 ............*array..............}
@menu
* Garbage Collection:: Automatically reclaims unused storage
* Memory Management for Environments::
+* Dynamic Linking Support::
+* Configure Module Catalog::
+* Automatic C Preprocessor Definitions::
* Signals::
* C Macros::
* Changing Scm::
-* Defining Subrs::
-* Defining Smobs::
-* Defining Ptobs::
* Allocating memory::
* Embedding SCM:: In other programs
* Callbacks::
@@ -7117,7 +7412,7 @@ object is freed. If the type header of smob is collected, the smob's
@end deftypefun
-@node Memory Management for Environments, Signals, Garbage Collection, Operations
+@node Memory Management for Environments, Dynamic Linking Support, Garbage Collection, Operations
@subsection Memory Management for Environments
@ifset html
@@ -7231,7 +7526,214 @@ into garbage collection techniques about which a considerable amount
of literature is available.
-@node Signals, C Macros, Memory Management for Environments, Operations
+@node Dynamic Linking Support, Configure Module Catalog, Memory Management for Environments, Operations
+@subsection Dynamic Linking Support
+
+@noindent
+Dynamic linking has not been ported to all platforms. Operating systems
+in the BSD family (a.out binary format) can usually be ported to
+@dfn{DLD}. The @dfn{dl} library (@code{#define SUN_DL} for SCM) was a
+proposed POSIX standard and may be available on other machines with
+@dfn{COFF} binary format. For notes about porting to MS-Windows and
+finishing the port to VMS @ref{VMS Dynamic Linking}.
+
+@noindent
+@dfn{DLD} is a library package of C functions that performs
+@dfn{dynamic link editing} on GNU/Linux, VAX (Ultrix), Sun 3 (SunOS
+3.4 and 4.0), SPARCstation (SunOS 4.0), Sequent Symmetry (Dynix), and
+Atari ST. It is available from:
+
+@ifclear html
+@itemize @bullet
+@item
+ftp.gnu.org:pub/gnu/dld-3.3.tar.gz
+@end itemize
+@end ifclear
+
+@ifset html
+<A HREF="ftp://ftp.gnu.org/pub/gnu/dld-3.3.tar.gz">
+ftp.gnu.org:pub/gnu/dld-3.3.tar.gz
+</A>
+@end ifset
+
+@noindent
+These notes about using libdl on SunOS are from @file{gcc.info}:
+
+@quotation
+On a Sun, linking using GNU CC fails to find a shared library and
+reports that the library doesn't exist at all.
+
+This happens if you are using the GNU linker, because it does only
+static linking and looks only for unshared libraries. If you have
+a shared library with no unshared counterpart, the GNU linker
+won't find anything.
+
+We hope to make a linker which supports Sun shared libraries, but
+please don't ask when it will be finished--we don't know.
+
+Sun forgot to include a static version of @file{libdl.a} with some
+versions of SunOS (mainly 4.1). This results in undefined symbols when
+linking static binaries (that is, if you use @samp{-static}). If you
+see undefined symbols @samp{_dlclose}, @samp{_dlsym} or @samp{_dlopen}
+when linking, compile and link against the file
+@file{mit/util/misc/dlsym.c} from the MIT version of X windows.
+@end quotation
+
+
+@node Configure Module Catalog, Automatic C Preprocessor Definitions, Dynamic Linking Support, Operations
+@subsection Configure Module Catalog
+
+@noindent
+The SLIB module @dfn{catalog} can be extended to define other
+@code{require}-able packages by adding calls to the Scheme source file
+@file{mkimpcat.scm}. Within @file{mkimpcat.scm}, the following
+procedures are defined.
+
+@defun add-link feature object-file lib1 @dots{}
+@var{feature} should be a symbol. @var{object-file} should be a string
+naming a file containing compiled @dfn{object-code}. Each @var{lib}n
+argument should be either a string naming a library file or @code{#f}.
+
+If @var{object-file} exists, the @code{add-link} procedure registers
+symbol @var{feature} so that the first time @code{require} is called
+with the symbol @var{feature} as its argument, @var{object-file} and the
+@var{lib1} @dots{} are dynamically linked into the executing SCM
+session.
+
+If @var{object-file} exists, @code{add-link} returns @code{#t},
+otherwise it returns @code{#f}.
+
+For example, to install a compiled dll @file{foo}, add these lines to
+@file{mkimpcat.scm}:
+
+@example
+ (add-link 'foo
+ (in-vicinity (implementation-vicinity) "foo"
+ link:able-suffix))
+@end example
+
+
+@end defun
+
+@defun add-alias alias feature
+@var{alias} and @var{feature} are symbols. The procedure
+@code{add-alias} registers @var{alias} as an alias for @var{feature}.
+An unspecified value is returned.
+
+@code{add-alias} causes @code{(require '@var{alias})} to behave like
+@code{(require '@var{feature})}.
+@end defun
+
+@defun add-source feature filename
+@var{feature} is a symbol. @var{filename} is a string naming a file
+containing Scheme source code. The procedure @code{add-source}
+registers @var{feature} so that the first time @code{require} is called
+with the symbol @var{feature} as its argument, the file @var{filename}
+will be @code{load}ed. An unspecified value is returned.
+@end defun
+
+@noindent
+Remember to delete the file @file{slibcat} after modifying the file
+@file{mkimpcat.scm} in order to force SLIB to rebuild its cache.
+
+
+@node Automatic C Preprocessor Definitions, Signals, Configure Module Catalog, Operations
+@subsection Automatic C Preprocessor Definitions
+
+These @samp{#defines} are automatically provided by preprocessors of
+various C compilers. SCM uses the presence or absence of these
+definitions to configure @dfn{include file} locations and aliases for
+library functions. If the definition(s) corresponding to your system
+type is missing as your system is configured, add @code{-D@var{flag}} to
+the compilation command lines or add a @code{#define @var{flag}} line to
+@file{scmfig.h} or the beginning of @file{scmfig.h}.
+
+@example
+#define Platforms:
+------- ----------
+ARM_ULIB Huw Rogers free unix library for acorn archimedes
+AZTEC_C Aztec_C 5.2a
+__CYGWIN__ Cygwin
+__CYGWIN32__ Cygwin
+_DCC Dice C on AMIGA
+__GNUC__ Gnu CC (and DJGPP)
+__EMX__ Gnu C port (gcc/emx 0.8e) to OS/2 2.0
+__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
+
+_AIX AIX operating system
+__APPLE__ Apple Darwin
+AMIGA SAS/C 5.10 or Dice C on AMIGA
+__amigaos__ Gnu CC on AMIGA
+atarist ATARI-ST under Gnu CC
+__DragonflyBSD__ DragonflyBSD
+__FreeBSD__ FreeBSD
+GNUDOS DJGPP (obsolete in version 1.08)
+__GO32__ DJGPP (future?)
+hpux HP-UX
+linux GNU/Linux
+macintosh Macintosh (THINK_C and __MWERKS__ define)
+MCH_AMIGA Aztec_c 5.2a on AMIGA
+__MACH__ Apple Darwin
+__MINGW32__ MinGW - Minimalist GNU for Windows
+MSDOS Microsoft C 5.10 and 6.00A
+_MSDOS Microsoft CLARM and CLTHUMB compilers.
+__MSDOS__ Turbo C, Borland C, and DJGPP
+__NetBSD__ NetBSD
+nosve Control Data NOS/VE
+__OpenBSD__ OpenBSD
+SVR2 System V Revision 2.
+sun SunOS
+__SVR4 SunOS
+THINK_C developement environment for the Macintosh
+ultrix VAX with ULTRIX operating system.
+unix most Unix and similar systems and DJGPP (!?)
+__unix__ Gnu CC and DJGPP
+_UNICOS Cray operating system
+vaxc VAX C compiler
+VAXC VAX C compiler
+vax11c VAX C compiler
+VAX11 VAX C compiler
+_Windows Borland C 3.1 compiling for Windows
+_WIN32 MS VisualC++ 4.2 and Cygwin (Win32 API)
+_WIN32_WCE MS Windows CE
+vms (and VMS) VAX-11 C under VMS.
+
+__alpha DEC Alpha processor
+__alpha__ DEC Alpha processor
+__hppa__ HP RISC processor
+hp9000s800 HP RISC processor
+__ia64 GCC on IA64
+__ia64__ GCC on IA64
+_LONGLONG GCC on IA64
+__i386__ DJGPP
+i386 DJGPP
+_M_ARM Microsoft CLARM compiler defines as 4 for ARM.
+_M_ARMT Microsoft CLTHUMB compiler defines as 4 for Thumb.
+MULTIMAX Encore computer
+ppc PowerPC
+__ppc__ PowerPC
+pyr Pyramid 9810 processor
+__sgi__ Silicon Graphics Inc.
+sparc SPARC processor
+sequent Sequent computer
+tahoe CCI Tahoe processor
+vax VAX processor
+__x86_64 AMD Opteron
+@end example
+
+
+@node Signals, C Macros, Automatic C Preprocessor Definitions, Operations
@subsection Signals
@cindex signals
@@ -7262,8 +7764,8 @@ 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
+@end defmac
+@defmac ALLOW_INTS
Checks the deferred variables and if set the appropriate handler is
called.
@@ -7317,7 +7819,7 @@ a call to @code{wta(arg, pos, subr)}.
@end defmac
-@node Changing Scm, Defining Subrs, C Macros, Operations
+@node Changing Scm, Allocating memory, C Macros, Operations
@subsection Changing Scm
@noindent
@@ -7488,171 +7990,7 @@ New syntax can now be added without recompiling SCM by the use of the
@xref{Syntax}.
-@node Defining Subrs, Defining Smobs, Changing Scm, Operations
-@subsection Defining Subrs
-
-@noindent
-If @dfn{CCLO} is @code{#define}d when compiling, the compiled closure
-feature will be enabled. It is automatically enabled if dynamic linking
-is enabled.
-
-@noindent
-The SCM interpreter directly recognizes subrs taking small numbers of
-arguments. In order to create subrs taking larger numbers of arguments
-use:
-
-@defun make_gsubr name req opt rest fcn
-returns a cclo (compiled closure) object of name @code{char *}
-@var{name} which takes @code{int} @var{req} required arguments,
-@code{int} @var{opt} optional arguments, and a list of rest arguments if
-@code{int} @var{rest} is 1 (0 for not).
-
-@code{SCM (*fcn)()} is a pointer to a C function to do the work.
-
-The C function will always be called with @var{req} + @var{opt} +
-@var{rest} arguments, optional arguments not supplied will be passed
-@code{UNDEFINED}. An error will be signaled if the subr is called with
-too many or too few arguments. Currently a total of 10 arguments may be
-specified, but increasing this limit should not be difficult.
-
-@example
-/* A silly example, taking 2 required args,
- 1 optional, and a list of rest args */
-
-#include <scm.h>
-
-SCM gsubr_21l(req1,req2,opt,rst)
- SCM req1,req2,opt,rst;
-@{
- lputs("gsubr-2-1-l:\n req1: ", cur_outp);
- display(req1,cur_outp);
- lputs("\n req2: ", cur_outp);
- display(req2,cur_outp);
- lputs("\n opt: ", cur_outp);
- display(opt,cur_outp);
- lputs("\n rest: ", cur_outp);
- display(rst,cur_outp);
- newline(cur_outp);
- return UNSPECIFIED;
-@}
-
-void init_gsubr211()
-@{
- make_gsubr("gsubr-2-1-l", 2, 1, 1, gsubr_21l);
-@}
-@end example
-@end defun
-
-
-@node Defining Smobs, Defining Ptobs, Defining Subrs, Operations
-@subsection Defining Smobs
-
-@noindent
-Here is an example of how to add a new type named @code{@i{foo}} to SCM.
-The following lines need to be added to your code:
-
-@table @code
-@item long tc16_@i{foo};
-The type code which will be used to identify the new type.
-@item static smobfuns @i{foo}smob = @{mark@i{foo},free@i{foo},print@i{foo},equalp@i{foo}@};
-smobfuns is a structure composed of 4 functions:
-
-@example
-typedef struct @{
- SCM (*mark)P((SCM));
- sizet (*free)P((CELLPTR));
- int (*print)P((SCM exp, SCM port, int writing));
- SCM (*equalp)P((SCM, SCM));
-@} smobfuns;
-@end example
-
-@table @code
-@item smob.mark
-is a function of one argument of type @code{SCM} (the cell to mark) and
-returns type @code{SCM} which will then be marked. If no further
-objects need to be marked then return an immediate object such as
-@code{BOOL_F}. The smob cell itself will already have been marked.
-@emph{Note@:} This is different from SCM versions prior to 5c5. Only
-additional data specific to a smob type need be marked by @code{smob.mark}.
-
- 2 functions are provided:
-
-@table @code
-@item markcdr(ptr)
-returns @code{CDR(ptr)}.
-@item mark0(ptr)
-is a no-op used for smobs containing no additional @code{SCM} data. 0
-may also be used in this case.
-@end table
-
-@item smob.free
-is a function of one argument of type @code{CELLPTR} (the cell to
-collected) and returns type @code{sizet} which is the number of
-@code{malloc}ed bytes which were freed. @code{Smob.free} should free
-any @code{malloc}ed storage associated with this object. The function
-free0(ptr) is provided which does not free any storage and returns 0.
-@item smob.print
-is 0 or a function of 3 arguments. The first, of type @code{SCM}, is
-the smob object. The second, of type @code{SCM}, is the stream on which
-to write the result. The third, of type int, is 1 if the object should
-be @code{write}n, 0 if it should be @code{display}ed, and 2 if it should
-be @code{write}n for an error report. This function should return non-zero
-if it printed, and zero otherwise (in which case a hexadecimal number will
-be printed).
-@item smob.equalp
-is 0 or a function of 2 @code{SCM} arguments. Both of these arguments
-will be of type @code{tc16@i{foo}}. This function should return
-@code{BOOL_T} if the smobs are equal, @code{BOOL_F} if they are not. If
-@code{smob.equalp} is 0, @code{equal?} will return @code{BOOL_F} if they
-are not @code{eq?}.
-@end table
-
-@item tc16_@i{foo} = newsmob(&@i{foo}smob);
-Allocates the new type with the functions from @code{@i{foo}smob}. This
-line goes in an @code{init_} routine.
-@end table
-
-@noindent
-Promises and macros in @file{eval.c} and arbiters in @file{repl.c}
-provide examples of SMOBs. There are a maximum of 256 SMOBs.
-Smobs that must allocate blocks of memory should use, for example,
-@code{must_malloc} rather than @code{malloc} @xref{Allocating memory}.
-
-
-@node Defining Ptobs, Allocating memory, Defining Smobs, Operations
-@subsection Defining Ptobs
-
-@noindent
-@dfn{ptob}s are similar to smobs but define new types of port to which
-SCM procedures can read or write. The following functions are defined
-in the @code{ptobfuns}:
-
-@example
-typedef struct @{
- SCM (*mark)P((SCM ptr));
- int (*free)P((FILE *p));
- int (*print)P((SCM exp, SCM port, int writing));
- SCM (*equalp)P((SCM, SCM));
- int (*fputc)P((int c, FILE *p));
- int (*fputs)P((char *s, FILE *p));
- sizet (*fwrite)P((char *s, sizet siz, sizet num, FILE *p));
- int (*fflush)P((FILE *stream));
- int (*fgetc)P((FILE *p));
- int (*fclose)P((FILE *p));
-@} ptobfuns;
-@end example
-
-@noindent
-The @code{.free} component to the structure takes a @code{FILE *} or
-other C construct as its argument, unlike @code{.free} in a smob, which
-takes the whole smob cell. Often, @code{.free} and @code{.fclose} can be
-the same function. See @code{fptob} and @code{pipob} in @file{sys.c}
-for examples of how to define ptobs.
-Ptobs that must allocate blocks of memory should use, for example,
-@code{must_malloc} rather than @code{malloc} @xref{Allocating memory}.
-
-
-@node Allocating memory, Embedding SCM, Defining Ptobs, Operations
+@node Allocating memory, Embedding SCM, Changing Scm, Operations
@subsection Allocating memory
SCM maintains a count of bytes allocated using malloc, and calls the
garbage collector when that number exceeds a dynamically managed limit.
@@ -8011,8 +8349,8 @@ any messages from error calls by @code{scm_addr}.
@code{scm_addr} is useful for performing C operations on strings or
other uniform arrays (@pxref{Uniform Array}).
-
-@deftypefunx unsigned long scm_base_addr(SCM @var{ra}, char *@var{s_name})
+@end deftypefun
+@deftypefun unsigned long scm_base_addr(SCM @var{ra}, char *@var{s_name})
Returns a pointer (cast to an @code{unsigned long}) to the beginning
of storage of array @var{ra}. Note that if @var{ra} is a
shared-array, the strorage accessed this way may be much larger than