summaryrefslogtreecommitdiffstats
path: root/scm.info
diff options
context:
space:
mode:
authorJames LewisMoss <dres@debian.org>2000-03-12 09:04:17 -0500
committerBryan Newbold <bnewbold@robocracy.org>2017-02-20 00:05:26 -0800
commit8cfce36c6a4fc2e0a0ab6ef2db66a23cbe462693 (patch)
tree17427e4f777ca85990a449fe939fbae29770b346 /scm.info
parenta47af30d2f0e96afcd1f14b1984575c359faa3d6 (diff)
parent3278b75942bdbe706f7a0fba87729bb1e935b68b (diff)
downloadscm-8cfce36c6a4fc2e0a0ab6ef2db66a23cbe462693.tar.gz
scm-8cfce36c6a4fc2e0a0ab6ef2db66a23cbe462693.zip
Import Debian changes 5d2-3debian/5d2-3
scm (5d2-3) unstable frozen; urgency=low * Fix libncurses4-dev -> libncurses5-dev build depend (Closes: #58435) * Fix libreadline2-dev -> libreadline4-dev build depend. * Fix license location in copyright file (lintian warning) * Add tetex-bin as a build depend (needs makeinfo) (Closes: #53197) * Add -isp option to dpkg-gencontrol (lintian error) * Move scm to section interpreters. scm (5d2-2) unstable; urgency=low * Apply patch from upstream for bug in eval.c. (Picked up from comp.lang.scheme) * Add Build-Depends on slib, librx1g-dev, libncurses4-dev, libreadlineg2-dev. * Up standards version. * Correct description: this is an R5RS implementation now * Make sure no optimizations are done on m68k. (Closes: #52434) scm (5d2-1) unstable; urgency=low * New upstream. scm (5d1-2) unstable; urgency=low * Remove TAGS on clean (cut the diff back down to reasonable size). scm (5d1-1) unstable; urgency=low * New upstream. * move stuff to /usr/share. scm (5d0-3) unstable; urgency=low * Change scmlit call to ./scmlit call (missed one) (Fixes bugs #37455 and #35545) * Change man file permissions to 644 (fixes lintian warning) scm (5d0-2) unstable; urgency=low * Removed call to add_final in init_crs. lendwin doesn't do anything and scm was crashing when quit everytime in final_scm. * Changed copyright to reflect new source. scm (5d0-1) unstable; urgency=low * New upstream. * Changed (terms) to access "/usr/doc/copyright/GPL". * Changed regex to use -lrx scm (5c3-6) unstable; urgency=low * New maintainer.
Diffstat (limited to 'scm.info')
-rw-r--r--scm.info8099
1 files changed, 8099 insertions, 0 deletions
diff --git a/scm.info b/scm.info
new file mode 100644
index 0000000..421167d
--- /dev/null
+++ b/scm.info
@@ -0,0 +1,8099 @@
+This is Info file scm.info, produced by Makeinfo version 1.68 from the
+input file scm.texi.
+
+INFO-DIR-SECTION The Algorithmic Language Scheme
+START-INFO-DIR-ENTRY
+* SCM: (scm). A Scheme interpreter.
+END-INFO-DIR-ENTRY
+
+
+File: scm.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir)
+
+This manual documents the SCM Scheme implementation. SCM version |
+5d2 was released December 1999. The most recent information about SCM |
+can be found on SCM's "WWW" home page: |
+
+ `http://swissnet.ai.mit.edu/~jaffer/SCM.html'
+
+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.
+
+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.
+
+* Menu:
+
+* Overview::
+* Installing SCM::
+* Operational Features::
+* The Language:: Reference.
+* Packages:: Optional Capabilities.
+* The Implementation:: How it works.
+* Index::
+
+
+File: scm.info, Node: Overview, Next: Installing SCM, Prev: Top, Up: Top
+
+Overview
+********
+
+Scm is a portable Scheme implementation written in C. Scm provides a
+machine independent platform for [JACAL], a symbolic algebra system.
+
+* Menu:
+
+* Copying::
+* SCM Features::
+* SCM Authors::
+* Bibliography::
+
+
+File: scm.info, Node: Copying, Next: SCM Features, Prev: Overview, Up: Overview
+
+Copying
+=======
+
+ COPYRIGHT (c) 1989 BY
+
+ PARADIGM ASSOCIATES INCORPORATED, CAMBRIDGE, MASSACHUSETTS.
+
+ ALL RIGHTS RESERVED
+
+Permission to use, copy, modify, distribute and sell this software and
+its documentation for any purpose and without fee is hereby granted,
+provided that the above copyright notice appear in all copies and that
+both that copyright notice and this permission notice appear in
+supporting documentation, and that the name of Paradigm Associates Inc
+not be used in advertising or publicity pertaining to distribution of
+the software without specific, written prior permission.
+
+PARADIGM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
+EVENT SHALL PARADIGM BE LIABLE FOR ANY SPECIAL, INDIRECT OR
+CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
+USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+
+gjc@paradigm.com
+ Phone: 617-492-6079
+
+Paradigm Associates Inc
+29 Putnam Ave, Suite 6
+Cambridge, MA 02138
+
+ Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995
+
+ Free Software Foundation, Inc.
+
+ 59 Temple Place, Suite 330, Boston, MA 02111, USA
+
+Permission to use, copy, modify, distribute, and sell this software and
+its documentation for any purpose is hereby granted without fee,
+provided that the above copyright notice appear in all copies and that
+both that copyright notice and this permission notice appear in
+supporting documentation.
+
+ NO WARRANTY
+
+BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
+THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
+EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
+ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
+YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
+NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
+DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
+DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
+(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
+INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
+THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR
+OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+
+File: scm.info, Node: SCM Features, Next: SCM Authors, Prev: Copying, Up: Overview
+
+Features
+========
+
+ * Conforms to Revised^5 Report on the Algorithmic Language Scheme
+ [R5RS] and the [IEEE] P1178 specification.
+
+ * Support for [SICP], [R2RS], [R3RS], and [R5RS] scheme code.
+
+ * Runs under Amiga, Atari-ST, MacOS, MS-DOS, OS/2, NOS/VE, Unicos,
+ VMS, Unix and similar systems. Supports ASCII and EBCDIC
+ character sets.
+
+ * Is fully documented in TeXinfo form, allowing documentation to be
+ generated in info, TeX, html, nroff, and troff formats.
+
+ * Supports inexact real and complex numbers, 30 bit immediate
+ integers and large precision integers.
+
+ * Many Common Lisp functions: `logand', `logor', `logxor', `lognot',
+ `ash', `logcount', `integer-length', `bit-extract', `defmacro',
+ `macroexpand', `macroexpand1', `gentemp', `defvar', `force-output',
+ `software-type', `get-decoded-time', `get-internal-run-time',
+ `get-internal-real-time', `delete-file', `rename-file',
+ `copy-tree', `acons', and `eval'.
+
+ * `Char-code-limit', `most-positive-fixnum', `most-negative-fixnum',
+ `and internal-time-units-per-second' constants. `*Features*' and
+ `*load-pathname*' variables.
+
+ * Arrays and bit-vectors. String ports and software emulation ports.
+ I/O extensions providing ANSI C and POSIX.1 facilities.
+
+ * Interfaces to standard libraries including REGEX string regular
+ expression matching and the CURSES screen management package.
+
+ * Available add-on packages including an interactive debugger,
+ database, X-window graphics, BGI graphics, Motif, and Open-Windows
+ packages.
+
+ * A compiler (HOBBIT, available separately) and dynamic linking of
+ compiled modules.
+
+ * User definable responses to interrupts and errors,
+ Process-syncronization primitives. Setable levels of monitoring
+ and timing information printed interactively (the `verbose'
+ function). `Restart', `quit', and `exec'.
+
+
+File: scm.info, Node: SCM Authors, Next: Bibliography, Prev: SCM Features, Up: Overview
+
+Authors
+=======
+
+Aubrey Jaffer (jaffer @ ai.mit.edu)
+ Most of SCM.
+
+Radey Shouman
+ Arrays. `gsubr's, compiled closures, records, Ecache, syntax-rules
+ macros, and "safeport"s.
+
+Jerry D. Hedden
+ Real and Complex functions. Fast mixed type arithmetics.
+
+Hugh Secker-Walker
+ Syntax checking and memoization of special forms by evaluator.
+ Storage allocation strategy and parameters.
+
+George Carrette
+ "Siod", written by George Carrette, was the starting point for SCM.
+ The major innovations taken from Siod are the evaluator's use of
+ the C-stack and being able to garbage collect off the C-stack
+ (*note Garbage Collection::.).
+
+There are many other contributors to SCM. They are acknowledged in the
+file `ChangeLog', a log of changes that have been made to scm.
+
+
+File: scm.info, Node: Bibliography, Prev: SCM Authors, Up: Overview
+
+Bibliography
+============
+
+[IEEE]
+ `IEEE Standard 1178-1990. IEEE Standard for the Scheme
+ Programming Language.' IEEE, New York, 1991.
+
+[Simply]
+ Brian Harvey and Matthew Wright. `Simply Scheme: Introducing
+ Computer Science' MIT Press, 1994 ISBN 0-262-08226-8
+
+[SICP]
+ Harold Abelson and Gerald Jay Sussman with Julie Sussman.
+ `Structure and Interpretation of Computer Programs.' MIT Press,
+ Cambridge, 1985.
+
+[R4RS]
+ William Clinger and Jonathan Rees, Editors. Revised(4) Report on
+ the Algorithmic Language Scheme. `ACM Lisp Pointers' Volume IV,
+ Number 3 (July-September 1991), pp. 1-55.
+
+ *Note Top: (r4rs)Top.
+
+[R5RS]
+ Richard Kelsey and William Clinger and Jonathan (Rees, editors)
+ Revised(5) Report on the Algorithmic Language Scheme.
+ `Higher-Order and Symbolic Computation' Volume 11, Number 1 (1998),
+ pp. 7-105, and `ACM SIGPLAN Notices' 33(9), September 1998.
+
+ *Note Top: (r5rs)Top.
+
+[Exrename]
+ William Clinger Hygienic Macros Through Explicit Renaming `Lisp
+ Pointers' Volume IV, Number 4 (December 1991), pp 17-23.
+
+[GUILE]
+ Tom Lord. The Guile Architecture for Ubiquitous Computing.
+ `Usenix Symposium on Tcl/Tk', 1995.
+
+[SLIB]
+ Todd R. Eigenschink, Dave Love, and Aubrey Jaffer. SLIB, The
+ Portable Scheme Library. Version 2c5, Jan 1999.
+
+ *Note Top: (slib)Top.
+
+[JACAL]
+ Aubrey Jaffer. JACAL Symbolic Mathematics System. Version 1a9,
+ Jan 1999.
+
+ *Note Top: (jacal)Top.
+
+`scm.texi'
+`scm.info'
+ Documentation of `scm' extensions (beyond Scheme standards).
+ Documentation on the internal representation and how to extend or
+ include `scm' in other programs.
+
+`Xlibscm.texi'
+`Xlibscm.info'
+ Documentation of the Xlib - SCM Language X Interface.
+
+
+File: scm.info, Node: Installing SCM, Next: Operational Features, Prev: Overview, Up: Top
+
+Installing SCM
+**************
+
+* Menu:
+
+* Making SCM:: Bootstrapping.
+* SLIB:: REQUIREd reading.
+* 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::
+
+
+File: scm.info, Node: Making SCM, Next: SLIB, Prev: Installing SCM, Up: Installing SCM
+
+Making SCM
+==========
+
+The SCM distribution has "Makefile" which contains rules for making
+"scmlit", a "bare-bones" version of SCM sufficient for running
+`build.scm'. `build.scm' is used to compile (or create scripts to
+compile) full featured versions.
+
+Makefiles are not portable to the majority of platforms. If `Makefile'
+works for you, good; If not, I don't want to hear about it. If you
+need to compile SCM without build.scm, there are several ways to
+proceed:
+
+ * Use SCM on a different platform to run `build.scm' to create a
+ script to build SCM;
+
+ * Use another implementation of Scheme to run `build.scm' to create a
+ script to build SCM;
+
+ * Create your own script or `Makefile'.
+
+ * Buy a SCM executable from jaffer @ ai.mit.edu. See the end of the
+ `ANNOUNCE' file in the distribution for details.
+
+ * Use scmconfig (From: bos@scrg.cs.tcd.ie):
+
+ Build and install scripts using GNU "autoconf" are available from
+ `scmconfig4e3.tar.gz' in the distribution directories. See
+ `README.unix' in `scmconfig4e3.tar.gz' for further instructions.
+
+ *Note:* The last release of scmconfig (4e3) was on March 20, 1996.
+ I am moving it to the OLD subdirectory until someone submits an
+ update.
+
+
+File: scm.info, Node: SLIB, Next: Building SCM, Prev: Making SCM, Up: Installing SCM
+
+SLIB
+====
+
+[SLIB] is a portable Scheme library meant to provide compatibility and
+utility functions for all standard Scheme implementations. Although
+SLIB is not *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:
+
+ * swissnet.ai.mit.edu:/pub/scm/slib2c7.tar.gz |
+
+ * ftp.gnu.org:/pub/gnu/jacal/slib2c7.tar.gz |
+
+ * ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib2c7.tar.gz |
+
+Unpack SLIB (`tar xzf slib2c7.tar.gz' or `unzip -ao slib2c7.zip') in an |
+appropriate directory for your system; both `tar' and `unzip' will
+create the directory `slib'.
+
+Then create a file `require.scm' in the SCM "implementation-vicinity"
+(this is the same directory as where the file `Init5d2.scm' is |
+installed). `require.scm' should have the contents:
+
+ (define (library-vicinity) "/usr/local/lib/slib/")
+ (load (in-vicinity (library-vicinity) "require"))
+
+where the pathname string `/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 (*note chmod: I/O-Extensions.).
+The way to specify a relative pathname is to append it to the
+implementation-vicinity, which is absolute:
+
+ (define library-vicinity
+ (let ((lv (string-append (implementation-vicinity) "../slib/")))
+ (lambda () lv)))
+ (load (in-vicinity (library-vicinity) "require"))
+
+Alternatively, you can set the (shell) environment variable
+`SCHEME_LIBRARY_PATH' to the pathname of the SLIB directory (*note
+SCHEME_LIBRARY_PATH: SCM Variables.). If set, the environment variable
+overrides `require.scm'. Again, absolute pathnames are recommended.
+
+
+File: scm.info, Node: Building SCM, Next: Installing Dynamic Linking, Prev: SLIB, Up: Installing SCM
+
+Building SCM
+============
+
+The file "build.scm" builds and runs a relational database of how to
+compile and link SCM executables. It has information for most 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.
+
+* Menu:
+
+* Invoking Build::
+* Build Options::
+* Compiling and Linking Custom Files::
+
+
+File: scm.info, Node: Invoking Build, Next: Build Options, Prev: Building SCM, Up: Building SCM
+
+Invoking Build
+--------------
+
+The *all* method will also work for MS-DOS and unix. Use the *all*
+method if you encounter problems with `build.scm'.
+
+MS-DOS
+ From the SCM source directory, type `build' followed by up to 9
+ command line arguments.
+
+unix
+ From the SCM source directory, type `./build.scm' followed by
+ command line arguments.
+
+*all*
+ From the SCM source directory, start `scm' or `scmlit' and type
+ `(load "build.scm")'. Alternatively, start `scm' or `scmlit' with
+ the command line argument `-ilbuild'.
+
+Invoking build without the `-F' option will build or create a shell
+script with the `arrays', `inexact', and `bignums' options as defaults.
+
+ bash$ ./build.scm
+ -|
+ #!/bin/sh
+ rm -f scmflags.h
+ echo '#define IMPLINIT "/home/jaffer/scm/Init5d2.scm"'>>scmflags.h |
+ echo '#define BIGNUMS'>>scmflags.h
+ echo '#define FLOATS'>>scmflags.h
+ echo '#define ARRAYS'>>scmflags.h
+ gcc -O2 -c continue.c scm.c findexec.c script.c time.c repl.c scl.c \
+ eval.c sys.c subr.c unif.c rope.c
+ gcc -rdynamic -o scm continue.o scm.o findexec.o script.o time.o \
+ repl.o scl.o eval.o sys.o subr.o unif.o rope.o -lm -lc
+
+To cross compile for another platform, invoke build with the `-p' or
+`--platform=' option. This will create a script for the platform named
+in the `-p' or `--platform=' option.
+
+ bash$ ./build.scm -p vms
+ -|
+ $DELETE scmflags.h
+ $CREATE scmflags.h
+ $DECK
+ #define IMPLINIT "/home/jaffer/scm/Init5d2.scm" |
+ #define BIGNUMS
+ #define FLOATS
+ #define ARRAYS
+ $EOD
+ $ cc continue scm findexec script time repl scl eval sys subr unif rope
+ $ macro setjump
+ $ link continue,scm,findexec,script,time,repl,scl,eval,sys,subr,unif,rope,setjump,sys$input/opt
+ -lc,sys$share:vaxcrtl/share
+ $RENAME continue.exe scm.exe
+
+
+File: scm.info, Node: Build Options, Next: Compiling and Linking Custom Files, Prev: Invoking Build, Up: Building SCM
+
+Build Options
+-------------
+
+The options to "build" specify what, where, and how to build a SCM
+program or dynamically linked module. These options are unrelated to
+the SCM command line options.
+
+ - Build Option: -p PLATFORM-NAME
+ - Build Option: --platform=PLATFORM-NAME
+ specifies that the compilation should be for a
+ computer/operating-system combination called PLATFORM-NAME.
+ *Note:* The case of PLATFORM-NAME is distinguised. The current
+ PLATFORM-NAMEs are all lower-case.
+
+ The platforms defined by table "platform" in `build.scm' are:
+
+ Table: platform
+ name processor operating-system compiler
+ () processor-family operating-system () |
+ symbol processor-family operating-system symbol
+ symbol atom symbol symbol
+ ================= ================= ================= =================
+ *unknown* *unknown* unix cc |
+ acorn-unixlib acorn *unknown* cc |
+ aix powerpc aix cc |
+ alpha alpha osf1 cc
+ alpha-elf alpha unix cc |
+ alpha-linux alpha linux gcc
+ amiga-aztec m68000 amiga cc |
+ amiga-dice-c m68000 amiga dcc |
+ amiga-gcc m68000 amiga gcc
+ amiga-sas m68000 amiga lc |
+ atari-st-gcc m68000 atari.st gcc
+ atari-st-turbo-c m68000 atari.st tcc |
+ borland-c 8086 ms-dos bcc |
+ cygwin32 i386 unix gcc
+ djgpp i386 ms-dos gcc
+ freebsd i386 unix cc
+ gcc *unknown* unix gcc
+ highc i386 ms-dos hc386 |
+ hp-ux hp-risc hp-ux cc |
+ irix mips irix gcc
+ linux i386 linux gcc
+ linux-aout i386 linux gcc
+ microsoft-c 8086 ms-dos cl |
+ microsoft-c-nt i386 ms-dos cl |
+ microsoft-quick-c 8086 ms-dos qcl |
+ ms-dos 8086 ms-dos cc |
+ os/2-cset i386 os/2 icc |
+ os/2-emx i386 os/2 gcc
+ sunos sparc sunos cc |
+ svr4 *unknown* unix cc |
+ svr4-gcc-sun-ld sparc sunos gcc |
+ turbo-c 8086 ms-dos tcc |
+ unicos cray unicos cc |
+ unix *unknown* unix cc |
+ vms vax vms cc |
+ vms-gcc vax vms gcc
+ watcom-9.0 i386 ms-dos wcc386p |
+
+ - Build Option: -o FILENAME
+ - Build Option: --outname=FILENAME
+ specifies that the compilation should produce an executable or
+ object name of FILENAME. The default is `scm'. Executable
+ suffixes will be added if neccessary, e.g. `scm' => `scm.exe'.
+
+ - Build Option: -l LIBNAME ...
+ - Build Option: --libraries=LIBNAME
+ specifies that the LIBNAME should be linked with the executable
+ produced. If compile flags or include directories (`-I') are
+ needed, they are automatically supplied for compilations. The `c'
+ library is always included. SCM "features" specify any libraries
+ they need; so you shouldn't need this option often.
+
+ - Build Option: -D DEFINITION ...
+ - Build Option: --defines=DEFINITION
+ specifies that the DEFINITION should be made in any C source
+ compilations. If compile flags or include directories (`-I') are
+ needed, they are automatically supplied for compilations. SCM
+ "features" specify any flags they need; so you shouldn't need this
+ option often.
+
+ - Build Option: --compiler-options=FLAG
+ specifies that that FLAG will be put on compiler command-lines.
+
+ - Build Option: --linker-options=FLAG
+ specifies that that FLAG will be put on linker command-lines.
+
+ - Build Option: -s PATHNAME
+ - Build Option: --scheme-initial=PATHNAME
+ specifies that PATHNAME should be the default location of the SCM
+ initialization file `Init5d2.scm'. SCM tries several likely |
+ locations before resorting to PATHNAME (*note File-System
+ Habitat::.). If not specified, the current directory (where build
+ is building) is used.
+
+ - Build Option: -c PATHNAME ...
+ - Build Option: --c-source-files=PATHNAME
+ specifies that the C source files PATHNAME ... are to be compiled.
+
+ - Build Option: -j PATHNAME ...
+ - Build Option: --object-files=PATHNAME
+ specifies that the object files PATHNAME ... are to be linked.
+
+ - Build Option: -i CALL ...
+ - Build Option: --initialization=CALL
+ specifies that the C functions CALL ... are to be invoked during
+ initialization.
+
+ - Build Option: -t BUILD-WHAT
+ - Build Option: --type=BUILD-WHAT
+ specifies in general terms what sort of thing to build. The
+ choices are:
+ `exe'
+ executable program.
+
+ `lib'
+ library module.
+
+ `dlls'
+ archived dynamically linked library object files.
+
+ `dll'
+ dynamically linked library object file.
+
+ The default is to build an executable.
+
+ - Build Option: -h BATCH-SYNTAX
+ - Build Option: -batch-dialect=BATCH-SYNTAX
+ specifies how to build. The default is to create a batch file for
+ the host system. The SLIB file `batch.scm' knows how to create
+ batch files for:
+ * unix
+
+ * dos
+
+ * vms
+
+ * amigados
+
+ * system
+
+ This option executes the compilation and linking commands
+ through the use of the `system' procedure.
+
+ * *unknown*
+
+ This option outputs Scheme code.
+
+ - Build Option: -w BATCH-FILENAME
+ - Build Option: -script-name=BATCH-FILENAME
+ specifies where to write the build script. The default is to
+ display it on `(current-output-port)'.
+
+ - Build Option: -F FEATURE ...
+ - Build Option: --features=FEATURE
+ specifies to build the given features into the executable. The
+ defined features are:
+
+ "array" |
+ Alias for ARRAYS |
+ |
+ "array-for-each" |
+ array-map! and array-for-each (arrays must also be featured). |
+ |
+ "arrays" |
+ Use if you want arrays, uniform-arrays and uniform-vectors. |
+ |
+ "bignums" |
+ Large precision integers. |
+ |
+ "careful-interrupt-masking" |
+ Define this for extra checking of interrupt masking and some |
+ simple checks for proper use of malloc and free. This is for |
+ debugging C code in `sys.c', `eval.c', `repl.c' and makes the |
+ interpreter several times slower than usual. |
+
+ "cautious"
+ Normally, the number of arguments arguments to interpreted
+ closures (from LAMBDA) are checked if the function part of a
+ form is not a symbol or only the first time the form is
+ executed if the function part is a symbol. defining
+ `reckless' disables any checking. If you want to have SCM
+ always check the number of arguments to interpreted closures
+ define feature `cautious'.
+
+ "cheap-continuations" |
+ If you only need straight stack continuations, executables |
+ compile with this feature will run faster and use less |
+ storage than not having it. Machines with unusual stacks |
+ *need* this. Also, if you incorporate new C code into scm |
+ which uses VMS system services or library routines (which |
+ need to unwind the stack in an ordrly manner) you may need to |
+ use this feature. |
+
+ "compiled-closure" |
+ Use if you want to use compiled closures. |
+
+ "curses" |
+ For the "curses" screen management package. |
+
+ "debug" |
+ Turns on the features `cautious', |
+ `careful-interrupt-masking', and `stack-limit'; uses `-g' |
+ flags for debugging SCM source code. |
+
+ "dump" |
+ Convert a running scheme program into an executable file. |
+
+ "dynamic-linking" |
+ Be able to load compiled files while running. |
+
+ "edit-line" |
+ interface to the editline or GNU readline library. |
+
+ "engineering-notation"
+ Use if you want floats to display in engineering notation
+ (exponents always multiples of 3) instead of scientific
+ notation.
+
+ "generalized-c-arguments" |
+ `make_gsubr' for arbitrary (< 11) arguments to C functions. |
+
+ "i/o-extensions" |
+ Commonly available I/O extensions: "exec", line I/O, file |
+ positioning, file delete and rename, and directory functions. |
+
+ "inexact" |
+ Use if you want floating point numbers. |
+
+ "lit" |
+ Lightweight - no features |
+
+ "macro" |
+ C level support for hygienic and referentially transparent |
+ macros (syntax-rules macros). |
+ |
+ "mysql" |
+ Client connections to the mysql databases. |
+ |
+ "no-heap-shrink" |
+ Use if you want segments of unused heap to not be freed up |
+ after garbage collection. This may increase time in GC for |
+ *very* large working sets. |
+ |
+ "none" |
+ No features |
+ |
+ "posix" |
+ Posix functions available on all "Unix-like" systems. fork |
+ and process functions, user and group IDs, file permissions, |
+ and "link". |
+ |
+ "reckless" |
+ If your scheme code runs without any errors you can disable |
+ almost all error checking by compiling all files with |
+ `reckless'. |
+
+ "record"
+ The Record package provides a facility for user to define
+ their own record data types. See SLIB for documentation.
+
+ "regex" |
+ String regular expression matching. |
+
+ "rev2-procedures" |
+ These procedures were specified in the `Revised^2 Report on |
+ Scheme' but not in `R4RS'. |
+
+ "sicp" |
+ Use if you want to run code from: |
+
+ Harold Abelson and Gerald Jay Sussman with Julie Sussman. |
+ `Structure and Interpretation of Computer Programs.' The MIT |
+ Press, Cambridge, Massachusetts, USA, 1985. |
+
+ Differences from R5RS are: |
+ * (eq? '() '#f) |
+
+ * (define a 25) returns the symbol a. |
+
+ * (set! a 36) returns 36. |
+
+ "single-precision-only" |
+ Use if you want all inexact real numbers to be single |
+ precision. This only has an effect if SINGLES is also |
+ defined (which is the default). This does not affect complex |
+ numbers. |
+
+ "socket"
+ BSD "socket" interface.
+
+ "stack-limit" |
+ Use to enable checking for stack overflow. Define value of |
+ the C preprocessor variable STACK_LIMIT to be the size to |
+ which SCM should allow the stack to grow. STACK_LIMIT should |
+ be less than the maximum size the hardware can support, as |
+ not every routine checks the stack. |
+ |
+ "tick-interrupts" |
+ Use if you want the ticks and ticks-interrupt functions. |
+ |
+ "turtlegr" |
+ "Turtle" graphics calls for both Borland-C and X11 from |
+ sjm@ee.tut.fi. |
+
+ "unix"
+ Those unix features which have not made it into the Posix
+ specs: nice, acct, lstat, readlink, symlink, mknod and sync.
+
+ "windows"
+ Microsoft Windows executable.
+
+ "x" |
+ Alias for Xlib feature. |
+
+ "xlib" |
+ Interface to Xlib graphics routines. |
+
+
+
+File: scm.info, Node: Compiling and Linking Custom Files, Prev: Build Options, Up: Building SCM
+
+Compiling and Linking Custom Files
+----------------------------------
+
+A correspondent asks:
+
+ How can we link in our own c files to the SCM interpreter so that
+ we can add our own functionality? (e.g. we have a bunch of tcp
+ functions we want access to). Would this involve changing
+ build.scm or the Makefile or both?
+
+(*note Changing Scm::. has instructions describing the C code format).
+Suppose a C file "foo.c" has functions you wish to add to SCM. To
+compile and link your file at compile time, use the `-c' and `-i'
+options to build:
+
+ bash$ build -c foo.c -i init_foo
+ -|
+ #!/bin/sh
+ rm -f scmflags.h
+ echo '#define IMPLINIT "/home/jaffer/scm/Init5d2.scm"'>>scmflags.h |
+ echo '#define COMPILED_INITS init_foo();'>>scmflags.h
+ echo '#define BIGNUMS'>>scmflags.h
+ echo '#define FLOATS'>>scmflags.h
+ echo '#define ARRAYS'>>scmflags.h
+ gcc -O2 -c continue.c scm.c findexec.c script.c time.c repl.c scl.c \
+ eval.c sys.c subr.c unif.c rope.c foo.c
+ gcc -rdynamic -o scm continue.o scm.o findexec.o script.o time.o \
+ repl.o scl.o eval.o sys.o subr.o unif.o rope.o foo.o -lm -lc
+
+To make a dynamically loadable object file use the `-t dll' option:
+
+ bash$ build -t dll -c foo.c
+ -|
+ #!/bin/sh
+ rm -f scmflags.h
+ echo '#define IMPLINIT "/home/jaffer/scm/Init5d2.scm"'>>scmflags.h |
+ echo '#define BIGNUMS'>>scmflags.h
+ echo '#define FLOATS'>>scmflags.h
+ echo '#define ARRAYS'>>scmflags.h
+ echo '#define DLL'>>scmflags.h
+ gcc -O2 -fpic -c foo.c
+ gcc -shared -o foo.so foo.o -lm -lc
+
+Once `foo.c' compiles correctly (and your SCM build supports
+dynamic-loading), you can load the compiled file with the Scheme command
+`(load "./foo.so")'. See *Note Configure Module Catalog:: for how to
+add a compiled dll file to SLIB's catalog.
+
+
+File: scm.info, Node: Installing Dynamic Linking, Next: Configure Module Catalog, Prev: Building SCM, Up: Installing SCM
+
+Installing Dynamic Linking
+==========================
+
+Dynamic linking has not been ported to all platforms. Operating systems
+in the BSD family (a.out binary format) can usually be ported to "DLD".
+The "dl" library (`#define SUN_DL' for SCM) was a proposed POSIX
+standard and may be available on other machines with "COFF" binary
+format. For notes about porting to MS-Windows and finishing the port
+to VMS *Note Finishing Dynamic Linking::.
+
+"DLD" is a library package of C functions that performs "dynamic link
+editing" on 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:
+
+ * ftp.gnu.org:pub/gnu/dld-3.3.tar.gz
+
+These notes about using libdl on SunOS are from `gcc.info':
+
+ 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 `libdl.a' with some
+ versions of SunOS (mainly 4.1). This results in undefined symbols
+ when linking static binaries (that is, if you use `-static'). If
+ you see undefined symbols `_dlclose', `_dlsym' or `_dlopen' when
+ linking, compile and link against the file `mit/util/misc/dlsym.c'
+ from the MIT version of X windows.
+
+
+File: scm.info, Node: Configure Module Catalog, Next: Saving Images, Prev: Installing Dynamic Linking, Up: Installing SCM
+
+Configure Module Catalog
+========================
+
+The SLIB module "catalog" can be extended to define other
+`require'-able packages by adding calls to the Scheme source file
+`mkimpcat.scm'. Within `mkimpcat.scm', the following procedures are
+defined.
+
+ - Function: add-link FEATURE OBJECT-FILE LIB1 ...
+ FEATURE should be a symbol. OBJECT-FILE should be a string naming
+ a file containing compiled "object-code". Each LIBn argument
+ should be either a string naming a library file or `#f'.
+
+ If OBJECT-FILE exists, the `add-link' procedure registers symbol
+ FEATURE so that the first time `require' is called with the symbol
+ FEATURE as its argument, OBJECT-FILE and the LIB1 ... are
+ dynamically linked into the executing SCM session.
+
+ If OBJECT-FILE exists, `add-link' returns `#t', otherwise it
+ returns `#f'.
+
+ For example, to install a compiled dll `foo', add these lines to
+ `mkimpcat.scm':
+
+ (add-link 'foo
+ (in-vicinity (implementation-vicinity) "foo"
+ link:able-suffix))
+
+
+ - Function: add-alias ALIAS FEATURE
+ ALIAS and FEATURE are symbols. The procedure `add-alias'
+ registers ALIAS as an alias for FEATURE. An unspecified value is
+ returned.
+
+ `add-alias' causes `(require 'ALIAS)' to behave like `(require
+ 'FEATURE)'.
+
+ - Function: add-source FEATURE FILENAME
+ FEATURE is a symbol. FILENAME is a string naming a file
+ containing Scheme source code. The procedure `add-source'
+ registers FEATURE so that the first time `require' is called with
+ the symbol FEATURE as its argument, the file FILENAME will be
+ `load'ed. An unspecified value is returned.
+
+Remember to delete the file `slibcat' after modifying the file
+`mkimpcat.scm' in order to force SLIB to rebuild its cache.
+
+
+File: scm.info, Node: Saving Images, Next: Automatic C Preprocessor Definitions, Prev: Configure Module Catalog, Up: Installing SCM
+
+Saving Images
+=============
+
+In SCM, the ability to save running program images is called "dump"
+(*note Dump::.). In order to make `dump' available to SCM, build with
+feature `dump'. `dump'ed executables are compatible with dynamic
+linking.
+
+Most of the code for "dump" is taken from `emacs-19.34/src/unex*.c'.
+No modifications to the emacs source code were required to use
+`unexelf.c'. Dump has not been ported to all platforms. If `unexec.c'
+or `unexelf.c' don't work for you, try using the appropriate `unex*.c'
+file from emacs.
+
+
+File: scm.info, Node: Automatic C Preprocessor Definitions, Next: Problems Compiling, Prev: Saving Images, Up: Installing SCM
+
+Automatic C Preprocessor Definitions
+====================================
+
+These `#defines' are automatically provided by preprocessors of various
+C compilers. SCM uses the presence or absence of these definitions to
+configure "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 `-DFLAG' to the compilation command
+lines or add a `#define FLAG' line to `scmfig.h' or the beginning of
+`scmfig.h'.
+
+ #define Platforms:
+ ------- ----------
+ ARM_ULIB Huw Rogers free unix library for acorn archimedes
+ AZTEC_C Aztec_C 5.2a
+ __CYGWIN__ 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
+ AMIGA SAS/C 5.10 or Dice C on AMIGA
+ __amigados__ Gnu CC on AMIGA
+ atarist ATARI-ST under Gnu CC
+ __FreeBSD__ FreeBSD
+ GNUDOS DJGPP (obsolete in version 1.08)
+ __GO32__ DJGPP (future?)
+ hpux HP-UX
+ linux Linux
+ macintosh Macintosh (THINK_C and __MWERKS__ define)
+ MCH_AMIGA Aztec_c 5.2a on AMIGA
+ MSDOS Microsoft C 5.10 and 6.00A
+ __MSDOS__ Turbo C, Borland C, and DJGPP
+ nosve Control Data NOS/VE
+ SVR2 System V Revision 2.
+ __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) |
+ vms (and VMS) VAX-11 C under VMS.
+
+ __alpha DEC Alpha processor
+ __alpha__ DEC Alpha processor
+ hp9000s800 HP RISC processor
+ __i386__ DJGPP
+ i386 DJGPP
+ MULTIMAX Encore computer
+ pyr Pyramid 9810 processor
+ __sgi__ Silicon Graphics Inc.
+ sparc SPARC processor
+ sequent Sequent computer
+ tahoe CCI Tahoe processor
+ vax VAX processor
+
+
+File: scm.info, Node: Problems Compiling, Next: Problems Linking, Prev: Automatic C Preprocessor Definitions, Up: Installing SCM
+
+Problems Compiling
+==================
+
+FILE PROBLEM / MESSAGE HOW TO FIX
+*.c include file not found. Correct the status of
+ STDC_HEADERS in scmfig.h.
+ fix #include statement or add
+ #define for system type to
+ scmfig.h.
+*.c Function should return a value. Ignore.
+ Parameter is never used.
+ Condition is always false.
+ Unreachable code in function.
+scm.c assignment between incompatible Change SIGRETTYPE in scm.c.
+ types.
+time.c CLK_TCK redefined. incompatablility between
+ <stdlib.h> and <sys/types.h>.
+ Remove STDC_HEADERS in scmfig.h.
+ Edit <sys/types.h> to remove
+ incompatability.
+subr.c Possibly incorrect assignment Ignore.
+ in function lgcd.
+sys.c statement not reached. Ignore.
+ constant in conditional
+ expression.
+sys.c undeclared, outside of #undef STDC_HEADERS in scmfig.h.
+ functions.
+scl.c syntax error. #define SYSTNAME to your system
+ type in scl.c (softtype).
+
+
+File: scm.info, Node: Problems Linking, Next: Problems Running, Prev: Problems Compiling, Up: Installing SCM
+
+Problems Linking
+================
+
+PROBLEM HOW TO FIX
+_sin etc. missing. Uncomment LIBS in makefile.
+
+
+File: scm.info, Node: Problems Running, Next: Testing, Prev: Problems Linking, Up: Installing SCM
+
+Problems Running
+================
+
+PROBLEM HOW TO FIX
+Opening message and then machine Change memory model option to C
+crashes. compiler (or makefile).
+ Make sure sizet definition is
+ correct in scmfig.h.
+ Reduce the size of HEAP_SEG_SIZE in
+ setjump.h.
+Input hangs. #define NOSETBUF
+ERROR: heap: need larger initial. Increase initial heap allocation
+ using -a<kb> or INIT_HEAP_SIZE.
+ERROR: Could not allocate. Check sizet definition.
+ Use 32 bit compiler mode.
+ Don't try to run as subproccess.
+remove <FLAG> in scmfig.h and Do so and recompile files.
+recompile scm.
+add <FLAG> in scmfig.h and
+recompile scm.
+ERROR: Init5d2.scm not found. Assign correct IMPLINIT in makefile |
+ or scmfig.h.
+ Define environment variable
+ SCM_INIT_PATH to be the full
+ pathname of Init5d2.scm. |
+WARNING: require.scm not found. Define environment variable
+ SCHEME_LIBRARY_PATH to be the full
+ pathname of the scheme library
+ [SLIB].
+ Change library-vicinity in
+ Init5d2.scm to point to library or |
+ remove.
+ Make sure the value of
+ (library-vicinity) has a trailing
+ file separator (like / or \).
+
+
+File: scm.info, Node: Testing, Next: Reporting Problems, Prev: Problems Running, Up: Installing SCM
+
+Testing
+=======
+
+Loading `r4rstest.scm' in the distribution will run an [R4RS]
+conformance test on `scm'.
+
+ > (load "r4rstest.scm")
+ -|
+ ;loading "r4rstest.scm"
+ SECTION(2 1)
+ SECTION(3 4)
+ #<primitive-procedure boolean?>
+ #<primitive-procedure char?>
+ #<primitive-procedure null?>
+ #<primitive-procedure number?>
+ ...
+
+Loading `pi.scm' in the distribution will enable you to compute digits
+of pi.
+
+ > (load "pi")
+ ;loading "pi"
+ ;done loading "pi.scm"
+ ;Evaluation took 20 mSec (0 in gc) 767 cells work, 233 bytes 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 mSec (60 in gc) 36976 cells work, 1548 bytes other
+ #<unspecified>
+
+Loading `bench.scm' will compute and display performance statistics of
+SCM running `pi.scm'. `make bench' or `make benchlit' appends the
+performance report to the file `BenchLog', facilitating tracking
+effects of changes to SCM on performance.
+
+PROBLEM HOW TO FIX
+Runs some and then machine crashes. See above under machine crashes.
+Runs some and then ERROR: ... Remove optimization option to C
+(after a GC has happened). compiler and recompile.
+ #define SHORT_ALIGN in `scmfig.h'.
+Some symbol names print incorrectly. Change memory model option to C
+ compiler (or makefile).
+ Check that HEAP_SEG_SIZE fits
+ within sizet.
+ Increase size of HEAP_SEG_SIZE (or
+ INIT_HEAP_SIZE if it is smaller
+ than HEAP_SEG_SIZE).
+ERROR: Rogue pointer in Heap. See above under machine crashes.
+Newlines don't appear correctly in Check file mode (define OPEN_... in
+output files. `Init5d2.scm'). |
+Spaces or control characters appear Check character defines in
+in symbol names. `scmfig.h'.
+Negative numbers turn positive. Check SRS in `scmfig.h'.
+VMS: Couldn't unwind stack. #define CHEAP_CONTIUATIONS in
+ `scmfig.h'.
+VAX: botched longjmp.
+
+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 *conservative* GC until we find
+ what instruction will clear the register windows. This problem is
+ exacerbated by using lots of call-with-current-continuations.
+
+
+File: scm.info, Node: Reporting Problems, Prev: Testing, Up: Installing SCM
+
+Reporting Problems
+==================
+
+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 `jaffer @ ai.mit.edu'. The bug report should
+include:
+
+ 1. The version of SCM (printed when SCM is invoked with no arguments).
+
+ 2. The type of computer you are using.
+
+ 3. The name and version of your computer's operating system.
+
+ 4. The values of the environment variables `SCM_INIT_PATH' and
+ `SCHEME_LIBRARY_PATH'.
+
+ 5. The name and version of your C compiler.
+
+ 6. If you are using an executable from a distribution, the name,
+ vendor, and date of that distribution. In this case,
+ corresponding with the vendor is recommended.
+
+
+File: scm.info, Node: Operational Features, Next: The Language, Prev: Installing SCM, Up: Top
+
+Operational Features
+********************
+
+* Menu:
+
+* Invoking SCM::
+* SCM Options::
+* Invocation Examples::
+* SCM Variables::
+* SCM Session::
+* Editing Scheme Code::
+* Debugging Scheme Code::
+* Errors::
+* Memoized Expressions::
+* Internal State::
+* Scripting::
+
+
+File: scm.info, Node: Invoking SCM, Next: SCM Options, Prev: Operational Features, Up: Operational Features
+
+Invoking SCM
+============
+
+scm [-a kbytes] [-ibvqmu] [-p number]
+ [-c expression] [-e expression] [-f filename]
+ [-l filename] [-r feature] [-- | - | -s]
+ [filename] [arguments ...]
+
+Upon startup `scm' loads the file specified by by the environment
+variable SCM_INIT_PATH.
+
+If SCM_INIT_PATH is not defined or if the file it names is not present,
+`scm' tries to find the directory containing the executable file. If
+it is able to locate the executable, `scm' looks for the initialization
+file (usually `Init5d2.scm') in platform-dependent directories relative |
+to this directory. See *Note File-System Habitat:: for a blow-by-blow
+description.
+
+As a last resort (if initialization file cannot be located), the C
+compile parameter IMPLINIT (defined in the makefile or `scmfig.h') is
+tried.
+
+Unless the option `-no-init-file' or `--no-init-file' occurs in the
+command line, `Init5d2.scm' checks to see if there is file |
+`ScmInit.scm' in the path specified by the environment variable HOME
+(or in the current directory if HOME is undefined). If it finds such a
+file it is loaded.
+
+`Init5d2.scm' then looks for command input from one of three sources: |
+From an option on the command line, from a file named on the command
+line, or from standard input.
+
+This explanation applies to SCMLIT or other builds of SCM.
+
+Scheme-code files can also invoke SCM and its variants. *Note #!:
+Syntax Extensions.
+
+
+File: scm.info, Node: SCM Options, Next: Invocation Examples, Prev: Invoking SCM, Up: Operational Features
+
+Options
+=======
+
+The options are processed in the order specified on the command line.
+
+ - Command Option: -a KB
+ specifies that `scm' should allocate an initial heapsize of KB
+ kilobytes. This option, if present, must be the first on the
+ command line. If not specified, the default is `INIT_HEAP_SIZE'
+ in source file `setjump.h' which the distribution sets at
+ `25000*sizeof(cell)'.
+
+ - Command Option: -no-init-file
+ - Command Option: --no-init-file
+ Inhibits the loading of `ScmInit.scm' as described above.
+
+ - Command Option: -e EXPRESSION
+ - Command Option: -c EXPRESSION
+ specifies that the scheme expression EXPRESSION is to be
+ evaluated. These options are inspired by `perl' and `sh'
+ respectively. On Amiga systems the entire option and argument need
+ to be enclosed in quotes. For instance `"-e(newline)"'.
+
+ - Command Option: -r FEATURE
+ requires FEATURE. This will load a file from [SLIB] if that
+ FEATURE is not already supported. If FEATURE is 2, 3, 4, or 5
+ `scm' will require the features neccessary to support [R2RS],
+ [R3RS], [R4RS], or [R5RS], respectively.
+
+ - Command Option: -l FILENAME
+ - Command Option: -f FILENAME
+ loads FILENAME. `Scm' will load the first (unoptioned) file named
+ on the command line if no `-c', `-e', `-f', `-l', or `-s' option
+ preceeds it.
+
+ - Command Option: -p LEVEL
+ sets the prolixity (verboseness) to LEVEL. This is the same as the
+ `scm' command (verobse LEVEL).
+
+ - Command Option: -v
+ (verbose mode) specifies that `scm' will print prompts, evaluation
+ times, notice of loading files, and garbage collection statistics.
+ This is the same as `-p3'.
+
+ - Command Option: -q
+ (quiet mode) specifies that `scm' will print no extra information.
+ This is the same as `-p0'.
+
+ - Command Option: -m
+ specifies that subsequent loads, evaluations, and user
+ interactions will be with syntax-rules macro capability. To use a
+ specific syntax-rules macro implementation from [SLIB] (instead of
+ [SLIB]'s default) put `-r' MACROPACKAGE before `-m' on the command
+ line.
+
+ - Command Option: -u
+ specifies that subsequent loads, evaluations, and user
+ interactions will be without syntax-rules macro capability.
+ syntax-rules macro capability can be restored by a subsequent `-m'
+ on the command line or from Scheme code.
+
+ - Command Option: -i
+ specifies that `scm' should run interactively. That means that
+ `scm' will not terminate until the `(quit)' or `(exit)' command is
+ given, even if there are errors. It also sets the prolixity level
+ to 2 if it is less than 2. This will print prompts, evaluation
+ times, and notice of loading files. The prolixity level can be set
+ by subsequent options. If `scm' is started from a tty, it will
+ assume that it should be interactive unless given a subsequent `-b'
+ option.
+
+ - Command Option: -b
+ specifies that `scm' should run non-interactively. That means that
+ `scm' will terminate after processing the command line or if there
+ are errors.
+
+ - Command Option: -s
+ specifies, by analogy with `sh', that further options are to be
+ treated as program aguments.
+
+ - Command Option: -
+ - Command Option: --
+ specifies that there are no more options on the command line.
+
+ - Command Option: -d FILENAME
+ loads SLIB database-utilities and opens FILENAME as a database.
+
+ - Command Option: -o FILENAME
+ saves the current SCM session as the executable program `filename'.
+ This option works only in SCM builds supporting `dump' (*note
+ Dump::.).
+
+ If options appear on the command line after `-o FILENAME', then
+ the saved session will continue with processing those options when
+ it is invoked. Otherwise the (new) command line is processed as
+ usual when the saved image is invoked.
+
+ - Command Option: --help
+ prints usage information and URL; then exit.
+
+ - Command Option: --version
+ prints version information and exit.
+
+
+File: scm.info, Node: Invocation Examples, Next: SCM Variables, Prev: SCM Options, Up: Operational Features
+
+Invocation Examples
+===================
+
+`% scm foo.scm'
+ Loads and executes the contents of `foo.scm' and then enters
+ interactive session.
+
+`% scm -f foo.scm arg1 arg2 arg3'
+ Parameters `arg1', `arg2', and `arg3' are stored in the global
+ list `*argv*'; Loads and executes the contents of `foo.scm' and
+ exits.
+
+`% scm -s foo.scm arg1 arg2'
+ Sets *argv* to `("foo.scm" "arg1" "arg2")' and enters interactive
+ session.
+
+`% scm -e `(write (list-ref *argv* *optind*))' bar'
+ Prints `"bar"'.
+
+`% scm -rpretty-print -r format -i'
+ Loads `pretty-print' and `format' and enters interactive session.
+
+`% scm -r5'
+ Loads `dynamic-wind', `values', and syntax-rules macros and enters
+ interactive (with macros) session.
+
+`% scm -r5 -r4'
+ Like above but `rev4-optional-procedures' are also loaded.
+
+
+File: scm.info, Node: SCM Variables, Next: SCM Session, Prev: Invocation Examples, Up: Operational Features
+
+Environment Variables
+=====================
+
+ - Environment Variable: SCM_INIT_PATH
+ is the pathname where `scm' will look for its initialization code.
+ The default is the file `Init5d2.scm' in the source directory. |
+
+ - Environment Variable: SCHEME_LIBRARY_PATH
+ is the [SLIB] Scheme library directory.
+
+ - Environment Variable: HOME
+ is the directory where `Init5d2.scm' will look for the user |
+ initialization file `ScmInit.scm'.
+
+ - Environment Variable: EDITOR
+ is the name of the program which `ed' will call. If EDITOR is not
+ defined, the default is `ed'.
+
+Scheme Variables
+================
+
+ - Variable: *argv*
+ contains the list of arguments to the program. `*argv*' can change
+ during argument processing. This list is suitable for use as an
+ argument to [SLIB] `getopt'.
+
+ - Variable: *R4RS-macro*
+ controls whether loading and interaction support syntax-rules
+ macros. Define this in `ScmInit.scm' or files specified on the
+ command line. This can be overridden by subsequent `-m' and `-u'
+ options.
+
+ - Variable: *interactive*
+ controls interactivity as explained for the `-i' and `-b' options.
+ Define this in `ScmInit.scm' or files specified on the command
+ line. This can be overridden by subsequent `-i' and `-b' options.
+
+
+File: scm.info, Node: SCM Session, Next: Editing Scheme Code, Prev: SCM Variables, Up: Operational Features
+
+SCM Session
+===========
+
+ * Options, file loading and features can be specified from the
+ command line. *Note System interface: (scm)System interface.
+ *Note Require: (slib)Require.
+
+ * Typing the end-of-file character at the top level session (while
+ SCM is not waiting for parenthesis closure) causes SCM to exit.
+
+ * Typing the interrupt character aborts evaluation of the current
+ form and resumes the top level read-eval-print loop.
+
+ - Function: quit
+ - Function: quit N
+ - Function: exit
+ - Function: exit N
+ Aliases for `exit' (*note exit: (slib)System.). On many systems,
+ SCM can also tail-call another program. *Note execp:
+ I/O-Extensions.
+
+ - Function: program-arguments
+ Returns a list of strings of the arguments scm was called with.
+
+For documentation of the procedures `getenv' and `system' *Note System
+Interface: (slib)System Interface.
+
+ - Function: vms-debug
+ If SCM is compiled under VMS this `vms-debug' will invoke the VMS
+ debugger.
+
+
+File: scm.info, Node: Editing Scheme Code, Next: Debugging Scheme Code, Prev: SCM Session, Up: Operational Features
+
+Editing Scheme Code
+===================
+
+ - Function: ed ARG1 ...
+ The value of the environment variable `EDITOR' (or just `ed' if it
+ isn't defined) is invoked as a command with arguments ARG1 ....
+
+ - Function: ed FILENAME
+ If SCM is compiled under VMS `ed' will invoke the editor with a
+ single the single argument FILENAME.
+
+Gnu Emacs:
+ Editing of Scheme code is supported by emacs. Buffers holding
+ files ending in .scm are automatically put into scheme-mode.
+ EMACS for MS-DOS and MS-Windows systems is available (free) from:
+
+ `http://simtel.coast.net/SimTel/gnu/demacs.html'
+
+ If your Emacs can run a process in a buffer you can use the Emacs
+command `M-x run-scheme' with SCM. Otherwise, use the emacs command
+`M-x suspend-emacs'; or see "other systems" below.
+
+Epsilon (MS-DOS):
+ There is lisp (and scheme) mode available by use of the package
+ `LISP.E'. It offers several different indentation formats. With
+ this package, buffers holding files ending in `.L', `.LSP', `.S',
+ and `.SCM' (my modification) are automatically put into lisp-mode.
+
+ It is possible to run a process in a buffer under Epsilon. With
+ Epsilon 5.0 the command line options `-e512 -m0' are neccessary to
+ manage RAM properly. It has been reported that when compiling SCM
+ with Turbo C, you need to `#define NOSETBUF' for proper operation
+ in a process buffer with Epsilon 5.0.
+
+ One can also call out to an editor from SCM if RAM is at a
+ premium; See "under other systems" below.
+
+other systems:
+ Define the environment variable `EDITOR' to be the name of the
+ editing program you use. The SCM procedure `(ed arg1 ...)' will
+ invoke your editor and return to SCM when you exit the editor. The
+ following definition is convenient:
+
+ (define (e) (ed "work.scm") (load "work.scm"))
+
+ Typing `(e)' will invoke the editor with the file of interest.
+ After editing, the modified file will be loaded.
+
+
+File: scm.info, Node: Debugging Scheme Code, Next: Errors, Prev: Editing Scheme Code, Up: Operational Features
+
+Debugging Scheme Code
+=====================
+
+The `cautious' and `stack-limit' options of `build' (*note Build
+Options::.) support debugging in Scheme.
+
+"CAUTIOUS"
+ If SCM is built with the `CAUTIOUS' flag, then when an error
+ occurs, a "stack trace" of certain pending calls are printed as
+ part of the default error response. A (memoized) expression and
+ newline are printed for each partially evaluated combination whose
+ procedure is not builtin. See *Note Memoized Expressions:: for
+ how to read memoized expressions.
+
+ Also as the result of the `CAUTIOUS' flag, both `error' and
+ `user-interrupt' (invoked by <C-c>) to print stack traces and
+ conclude by calling `breakpoint' (*note Breakpoints:
+ (slib)Breakpoints.) instead of aborting to top level. Under
+ either condition, program execution can be resumed by `(continue)'.
+
+ In this configuration one can interrupt a running Scheme program
+ with <C-c>, inspect or modify top-level values, trace or untrace
+ procedures, and continue execution with `(continue)'.
+
+"STACK_LIMIT"
+ If SCM is built with the `STACK_LIMIT' flag, the interpreter will
+ check stack size periodically. If the size of stack exceeds a
+ certain amount (default is `HEAP_SEG_SIZE/2'), SCM generates a
+ `segment violation' interrupt.
+
+ The usefulness of `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.
+
+There are several SLIB macros which so useful that SCM automatically
+loads the appropriate module from SLIB if they are invoked.
+
+ - Macro: trace PROC1 ...
+ Traces the top-level named procedures given as arguments.
+
+ - Macro: 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.
+
+ - Macro: untrace PROC1 ...
+ Turns tracing off for its arguments.
+
+ - Macro: untrace
+ With no arguments, untraces all currently traced identifiers and
+ returns a list of these formerly traced identifiers.
+
+The routines I use most frequently for debugging are:
+
+ - Procedure: print ARG1 ...
+ `Print' writes all its arguments, separated by spaces. `Print'
+ outputs a `newline' at the end and returns the value of the last
+ argument.
+
+ One can just insert `(print '<proc-name>' and `)' around an
+ expression in order to see its value as a program operates.
+
+ - Syntax: print-args NAME1 ...
+ Writes NAME1 ... (separated by spaces) and then writes the values
+ of the closest lexical bindings enclosing the call to `Print-args'.
+
+ (define (foo a b) (print-args foo) (+ a b))
+ (foo 3 6)
+ -| In foo: a = 3; b = 6;
+ => 9
+
+Sometimes more elaborate measures are needed to print values in a useful
+manner. When the values to be printed may have very large (or infinite)
+external representations, *Note Quick Print: (slib)Quick Print, can be
+used.
+
+When `trace' is not sufficient to find program flow problems, SLIB-PSD,
+the Portable Scheme Debugger offers source code debugging from GNU
+Emacs. PSD runs slowly, so start by instrumenting only a few functions
+at a time.
+ http://swissnet.ai.mit.edu/ftpdir/scm/slib-psd1-3.tar.gz |
+ ftp.gnu.org:pub/gnu/jacal/slib-psd1-3.tar.gz
+ ftp.maths.tcd.ie:pub/bosullvn/jacal/slib-psd1-3.tar.gz
+ ftp.cs.indiana.edu:/pub/scheme-repository/utl/slib-psd1-3.tar.gz
+
+
+File: scm.info, Node: Errors, Next: Memoized Expressions, Prev: Debugging Scheme Code, Up: Operational Features
+
+Errors
+======
+
+A computer-language implementation designer faces choices of how
+reflexive to make the implementation in handling exceptions and errors;
+that is, how much of the error and exception routines should be written
+in the language itself. The design of a portable implementation is
+further constrained by the need to have (almost) all errors print
+meaningful messages, even when the implementation itself is not
+functioning correctly. Therefore, SCM implements much of its error
+response code in C.
+
+The following common error and conditions are handled by C code. Those
+with callback names after them can also be handled by Scheme code
+(*note Interrupts::.). If the callback identifier is not defined at top
+level, the default error handler (C code) is invoked. There are many
+other error messages which are not treated specially.
+
+"ARGn"
+ Wrong type in argument
+
+"ARG1"
+ Wrong type in argument 1
+
+"ARG2"
+ Wrong type in argument 2
+
+"ARG3"
+ Wrong type in argument 3
+
+"ARG4"
+ Wrong type in argument 4
+
+"ARG5"
+ Wrong type in argument 5
+
+"WNA"
+ Wrong number of args
+
+"OVFLOW"
+ numerical overflow
+
+"OUTOFRANGE"
+ Argument out of range
+
+"NALLOC"
+ `(out-of-storage)'
+
+"THRASH"
+ GC is `(thrashing)'
+
+"EXIT"
+ `(end-of-program)'
+
+"HUP_SIGNAL"
+ `(hang-up)'
+
+"INT_SIGNAL"
+ `(user-interrupt)'
+
+"FPE_SIGNAL"
+ `(arithmetic-error)'
+
+"BUS_SIGNAL"
+ bus error
+
+"SEGV_SIGNAL"
+ segment violation
+
+"ALRM_SIGNAL"
+ `(alarm-interrupt)'
+
+"VTALRM_SIGNAL"
+ `(virtual-alarm-interrupt)'
+
+"PROF_SIGNAL"
+ `(profile-alarm-interrupt)'
+
+ - Variable: errobj
+ When SCM encounters a non-fatal error, it aborts evaluation of the
+ current form, prints a message explaining the error, and resumes
+ the top level read-eval-print loop. The value of ERROBJ is the
+ offending object if appropriate. The builtin procedure `error'
+ does *not* set ERROBJ.
+
+`errno' and `perror' report ANSI C errors encountered during a call to
+a system or library function.
+
+ - Function: errno
+ - Function: errno N
+ With no argument returns the current value of the system variable
+ `errno'. When given an argument, `errno' sets the system variable
+ `errno' to N and returns the previous value of `errno'. `(errno
+ 0)' will clear outstanding errors. This is recommended after
+ `try-load' returns `#f' since this occurs when the file could not
+ be opened.
+
+ - Function: perror STRING
+ Prints on standard error output the argument STRING, a colon,
+ followed by a space, the error message corresponding to the current
+ value of `errno' and a newline. The value returned is unspecified.
+
+`warn' and `error' provide a uniform way for Scheme code to signal
+warnings and errors.
+
+ - Function: warn ARG1 ARG2 ARG3 ...
+ Alias for *Note slib:warn: (slib)System. Outputs an error message
+ containing the arguments. `warn' is defined in `Init5d2.scm'. |
+
+ - Function: error ARG1 ARG2 ARG3 ...
+ Alias for *Note slib:error: (slib)System. Outputs an error
+ message containing the arguments, aborts evaluation of the current
+ form and resumes the top level read-eval-print loop. `Error' is
+ defined in `Init5d2.scm'. |
+
+If SCM is built with the `CAUTIOUS' flag, then when an error occurs, a
+"stack trace" of certain pending calls are printed as part of the
+default error response. A (memoized) expression and newline are
+printed for each partially evaluated combination whose procedure is not
+builtin. See *Note Memoized Expressions:: for how to read memoized
+expressions.
+
+Also as the result of the `CAUTIOUS' flag, both `error' and
+`user-interrupt' (invoked by <C-c>) are defined to print stack traces
+and conclude by calling `breakpoint' (*note Breakpoints:
+(slib)Breakpoints.). This allows the user to interract with SCM as
+with Lisp systems.
+
+ - Function: stack-trace
+ Prints information describing the stack of partially evaluated
+ expressions. `stack-trace' returns `#t' if any lines were printed
+ and `#f' otherwise. See `Init5d2.scm' for an example of the use |
+ of `stack-trace'.
+
+
+File: scm.info, Node: Memoized Expressions, Next: Internal State, Prev: Errors, Up: Operational Features
+
+Memoized Expressions
+====================
+
+SCM memoizes the address of each occurence of an identifier's value when
+first encountering it in a source expression. Subsequent executions of
+that memoized expression is faster because the memoized reference
+encodes where in the top-level or local environment its value is.
+
+When procedures are displayed, the memoized locations appear in a format
+different from references which have not yet been executed. I find this
+a convenient aid to locating bugs and untested expressions.
+
+ * The names of memoized lexically bound identifiers are replaced with
+ #@<m>-<n>, where <m> is the number of binding contours back and
+ <n> is the index of the value in that binding countour.
+
+ * The names of identifiers which are not lexiallly bound but defined
+ at top-level have #@ prepended.
+
+For instance, `open-input-file' is defined as follows in `Init5d2.scm': |
+
+ (define (open-input-file str)
+ (or (open-file str OPEN_READ)
+ (and (procedure? could-not-open) (could-not-open) #f)
+ (error "OPEN-INPUT-FILE couldn't open file " str)))
+
+If `open-input-file' has not yet been used, the displayed procedure is
+similar to the original definition (lines wrapped for readability):
+
+ open-input-file =>
+ #<CLOSURE (str) (or (open-file str open_read)
+ (and (procedure? could-not-open) (could-not-open) #f)
+ (error "OPEN-INPUT-FILE couldn't open file " str))>
+
+If we open a file using `open-input-file', the sections of code used
+become memoized:
+
+ (open-input-file "r4rstest.scm") => #<input-port 3>
+ open-input-file =>
+ #<CLOSURE (str) (#@or (#@open-file #@0+0 #@open_read)
+ (and (procedure? could-not-open) (could-not-open) #f)
+ (error "OPEN-INPUT-FILE couldn't open file " str))>
+
+If we cause `open-input-file' to execute other sections of code, they
+too become memoized:
+
+ (open-input-file "foo.scm") =>
+
+ ERROR: No such file or directory
+ ERROR: OPEN-INPUT-FILE couldn't open file "foo.scm"
+
+ open-input-file =>
+ #<CLOSURE (str) (#@or (#@open-file #@0+0 #@open_read)
+ (#@and (#@procedure? #@could-not-open) (could-not-open) #f)
+ (#@error "OPEN-INPUT-FILE couldn't open file " #@0+0))>
+
+
+File: scm.info, Node: Internal State, Next: Scripting, Prev: Memoized Expressions, Up: Operational Features
+
+Internal State
+==============
+
+ - Variable: *interactive*
+ The variable *INTERACTIVE* determines whether the SCM session is
+ interactive, or should quit after the command line is processed.
+ *INTERACTIVE* is controlled directly by the command-line options
+ `-b', `-i', and `-s' (*note Invoking SCM::.). If none of these
+ options are specified, the rules to determine interactivity are
+ more complicated; see `Init5d2.scm' for details. |
+
+ - Function: abort
+ Resumes the top level Read-Eval-Print loop.
+
+ - Function: restart
+ Restarts the SCM program with the same arguments as it was
+ originally invoked. All `-l' loaded files are loaded again; If
+ those files have changed, those changes will be reflected in the
+ new session.
+
+ *Note:* When running a saved executable (*note Dump::.), `restart'
+ is redefined to be `exec-self'.
+
+ - Function: exec-self
+ Exits and immediately re-invokes the same executable with the same
+ arguments. If the executable file has been changed or replaced
+ since the beginning of the current session, the *new* executable
+ will be invoked. This differentiates `exec-self' from `restart'.
+
+ - Function: verbose N
+ Controls how much monitoring information is printed. If N is:
+
+ 0
+ no prompt or information is printed.
+
+ >= 1
+ a prompt is printed.
+
+ >= 2
+ the CPU time is printed after each top level form evaluated.
+
+ >= 3
+ messages about heap growth are printed.
+
+ >= 4
+ garbage collection (*note Garbage Collection::.) messages are
+ printed.
+
+ >= 5
+ a warning will be printed for each top-level symbol which is
+ defined more than one time.
+
+ - Function: gc
+ Scans all of SCM objects and reclaims for further use those that
+ are no longer accessible.
+
+ - Function: room
+ - Function: room #T
+ Prints out statistics about SCM's current use of storage. `(room
+ #t)' also gives the hexadecimal heap segment and stack bounds.
+
+ - Constant: *scm-version*
+ Contains the version string (e.g. `5d2') of SCM. |
+
+Executable path
+---------------
+
+In order to dump a saved executable or to dynamically-link using DLD,
+SCM must know where its executable file is. Sometimes SCM (*note
+Executable Pathname::.) guesses incorrectly the location of the
+currently running executable. In that case, the correct path can be set
+by calling `execpath' with the pathname.
+
+ - Function: execpath
+ 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.
+
+ - Function: execpath #F
+ - Function: execpath NEWPATH
+ Sets the path to `#f' or NEWPATH, respectively. The old path is
+ returned.
+
+For other configuration constants and procedures *Note Configuration:
+(slib)Configuration.
+
+
+File: scm.info, Node: Scripting, Prev: Internal State, Up: Operational Features
+
+Scripting
+=========
+
+* Menu:
+
+* Unix Scheme Scripts:: From Olin Shivers' Scheme Shell
+* MS-DOS Compatible Scripts:: Run in MS-DOS and Unix
+* Unix Shell Scripts:: Use /bin/sh to run Scheme
+
+
+File: scm.info, Node: Unix Scheme Scripts, Next: MS-DOS Compatible Scripts, Prev: Scripting, Up: Scripting
+
+Unix Scheme Scripts
+-------------------
+
+In reading this section, keep in mind that the first line of a script
+file has (different) meanings to SCM and the operating system
+(`execve').
+
+ - file: #! interpreter \ ...
+ On unix systems, a "Shell-Script" is a file (with execute
+ permissions) whose first two characters are `#!'. The INTERPRETER
+ argument must be the pathname of the program to process the rest
+ of the file. The directories named by environment variable `PATH'
+ are *not* searched to find INTERPRETER.
+
+ When executing a shell-script, the operating system invokes
+ INTERPRETER with a single argument encapsulating the rest of the
+ first line's contents (if if not just whitespace), the pathname of
+ the Scheme Script file, and then any arguments which the
+ shell-script was invoked with.
+
+ Put one space character between `#!' and the first character of
+ INTERPRETER (`/'). The INTERPRETER name is followed by ` \'; SCM
+ substitutes the second line of FILE for `\' (and the rest of the
+ line), then appends any arguments given on the command line
+ invoking this Scheme-Script.
+
+ When SCM executes the script, the Scheme variable *SCRIPT* will be
+ set to the script pathname. The last argument before `!#' on the
+ second line should be `-'; SCM will load the script file, preserve
+ the unprocessed arguments, and set *ARGV* to a list of the script
+ pathname and the unprocessed arguments.
+
+ Note that the interpreter, not the operating system, provides the
+ `\' substitution; this will only take place if INTERPRETER is a
+ SCM or SCSH interpreter.
+
+ - Read syntax: #! IGNORED !#
+ When the first two characters of the file being loaded are `#!' and
+ a `\' is present before a newline in the file, all characters up
+ to `!#' will be ignored by SCM `read'.
+
+This combination of interpretatons allows SCM source files to be used as
+POSIX shell-scripts if the first line is:
+
+ #!/usr/local/bin/scm \
+
+The following Scheme-Script prints factorial of its argument:
+
+ #! /usr/local/bin/scm \ %0 %1 %2 %3 %4 %5 %6 %7 %8 %9
+ - !#
+ ; -*-scheme-*-
+ (define (go-script)
+ (cond ((not *script*))
+ ((and (= 1 (- (length *argv*) *optind*))
+ (string->number (list-ref *argv* *optind*)))
+ => (lambda (n) (print (fact n))))
+ (else
+ (print *argv*)
+ (display "\
+ Usage: fact n
+ Returns the factorial of N.
+
+ http://swissnet.ai.mit.edu/~jaffer/SLIB.html
+ "
+ (current-error-port))
+ (exit #f))))
+
+ (define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n)))))
+ (go-script)
+
+ ./fact 32
+ =>
+ 263130836933693530167218012160000000
+
+If the wrong number of arguments is given, `fact' prints its ARGV with
+usage information.
+
+ ./fact 3 2
+ -|
+ ("./fact" "3" "2")
+ Usage: fact n
+ Returns the factorial of N.
+
+ http://swissnet.ai.mit.edu/~jaffer/SLIB.html
+
+
+File: scm.info, Node: MS-DOS Compatible Scripts, Next: Unix Shell Scripts, Prev: Unix Scheme Scripts, Up: Scripting
+
+MS-DOS Compatible Scripts
+-------------------------
+
+It turns out that we can create scheme-scripts which run both under unix
+and MS-DOS. To implement this, I have written the MS-DOS programs:
+`#!.bat' and `!#.exe'.
+
+With these two programs installed in a `PATH' directory, we have the
+following syntax for <PROGRAM>.BAT files.
+
+ - file: #! interpreter \ %0 %1 %2 %3 %4 %5 %6 %7 %8 %9
+ The first two characters of the Scheme-Script are `#!'. The
+ INTERPRETER can be either a unix style program path (using `/'
+ between filename components) or a DOS program name or path. The
+ rest of the first line of the Scheme-Script should be literally
+ `\ %0 %1 %2 %3 %4 %5 %6 %7 %8 %9', as shown.
+
+ If INTERPRETER has `/' in it, INTERPRETER is converted to a DOS
+ style filename (`/' => `\').
+
+ In looking for an executable named INTERPRETER, `#!' first checks
+ this (converted) filename; if INTERPRETER doesn't exist, it then
+ tries to find a program named like the string starting after the
+ last `\' (or `/') in INTERPRETER. When searching for executables,
+ `#!' tries all directories named by environment variable `PATH'.
+
+ Once the INTERPRETER executable path is found, arguments are
+ processed in the manner of scheme-shell, with the all the text
+ after the `\' taken as part of the meta-argument. More precisely,
+ `#!' calls INTERPRETER with any options on the second line of the
+ Scheme-Script up to `!#', the name of the Scheme-Script file, and
+ then any of at most 8 arguments given on the command line invoking
+ this Scheme-Script.
+
+The previous example Scheme-Script works in both MS-DOS and unix
+systems.
+
+
+File: scm.info, Node: Unix Shell Scripts, Prev: MS-DOS Compatible Scripts, Up: Scripting
+
+Unix Shell Scripts
+------------------
+
+Scheme-scripts suffer from two drawbacks:
+ * Some Unixes limit the length of the `#!' interpreter line to the
+ size of an object file header, which can be as small as 32 bytes.
+
+ * A full, explicit pathname must be specified, perhaps requiring
+ more than 32 bytes and making scripts vulnerable to breakage when
+ programs are moved.
+
+The following approach solves these problems at the expense of slower
+startup. Make `#!/bin/sh' the first line and prepend every subsequent
+line to be executed by the shell with `:;'. The last line to be
+executed by the shell should contain an "exec" command; `exec'
+tail-calls its argument.
+
+`/bin/sh' is thus invoked with the name of the script file, which it
+executes as a *sh script. Usually the second line starts `:;exec scm
+-f$0', which executes scm, which in turn loads the script file. When
+SCM loads the script file, it ignores the first and second lines, and
+evaluates the rest of the file as Scheme source code.
+
+The second line of the script file does not have the length restriction
+mentioned above. Also, `/bin/sh' searches the directories listed in
+the `PATH' environment variable for `scm', eliminating the need to use
+absolute locations in order to invoke a program.
+
+The following example additionally sets *SCRIPT* to the script
+argument, making it compatible with the scheme code of the previous
+example.
+
+ #! /bin/sh
+ :;exec scm -e"(set! *script* \"$0\")" -l$0 $*
+
+ (define (go-script)
+ (cond ((not *script*))
+ ((and (= 1 (- (length *argv*) *optind*))
+ (string->number (list-ref *argv* *optind*)))
+ => (lambda (n) (print (fact n))))
+ (else
+ (print *argv*)
+ (display "\
+ Usage: fact n
+ Returns the factorial of N.
+
+ http://swissnet.ai.mit.edu/~jaffer/SLIB.html
+ "
+ (current-error-port))
+ (exit #f))))
+
+ (define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n)))))
+
+ (go-script)
+
+ ./fact 6
+ => 720
+
+
+File: scm.info, Node: The Language, Next: Packages, Prev: Operational Features, Up: Top
+
+The Language
+************
+
+* Menu:
+
+* Standards Compliance:: Links to sections in [R5RS] and [SLIB]
+* Miscellaneous Procedures::
+* Time:: Both real time and processor time
+* Interrupts:: and exceptions
+* Process Synchronization:: Because interrupts are preemptive
+* Files and Ports::
+* Soft Ports:: Emulate I/O devices
+* Syntax Extensions::
+* Low Level Syntactic Hooks::
+* Syntactic Hooks for Hygienic Macros::
+
+
+File: scm.info, Node: Standards Compliance, Next: Miscellaneous Procedures, Prev: The Language, Up: The Language
+
+Standards Compliance
+====================
+
+Scm conforms to the `IEEE Standard 1178-1990. IEEE Standard for the
+Scheme Programming Language.' (*note Bibliography::.), and `Revised(5)
+Report on the Algorithmic Language Scheme'. *Note Top: (r5rs)Top. All
+the required features of these specifications are supported. Many of
+the optional features are supported as well.
+
+Optionals of [R5RS] Supported by SCM
+------------------------------------
+
+`-' and `/' of more than 2 arguments
+`exp'
+`log'
+`sin'
+`cos'
+`tan'
+`asin'
+`acos'
+`atan'
+`sqrt'
+`expt'
+`make-rectangular'
+`make-polar'
+`real-part'
+`imag-part'
+`magnitude'
+`angle'
+`exact->inexact'
+`inexact->exact'
+ *Note Numerical operations: (r5rs)Numerical operations.
+
+`with-input-from-file'
+`with-output-to-file'
+ *Note Ports: (r5rs)Ports.
+
+`load'
+`transcript-on'
+`transcript-off'
+ *Note System interface: (r5rs)System interface.
+
+Optionals of [R5RS] not Supported by SCM
+----------------------------------------
+
+`numerator'
+`denominator'
+`rationalize'
+ *Note Numerical operations: (r5rs)Numerical operations.
+
+[SLIB] Features of SCM and SCMLIT
+---------------------------------
+
+`delay'
+`full-continuation'
+`ieee-p1178'
+`object-hash'
+`rev4-report'
+`source'
+ See SLIB file `Template.scm'.
+
+`current-time'
+ *Note Time: (slib)Time.
+
+`defmacro'
+ *Note Defmacro: (slib)Defmacro.
+
+`getenv'
+`system'
+ *Note System Interface: (slib)System Interface.
+
+`hash'
+ *Note Hashing: (slib)Hashing.
+
+`logical'
+ *Note Bit-Twiddling: (slib)Bit-Twiddling.
+
+`multiarg-apply'
+ *Note Multi-argument Apply: (slib)Multi-argument Apply.
+
+`multiarg/and-'
+ *Note Multi-argument / and -: (slib)Multi-argument / and -.
+
+`rev4-optional-procedures'
+ *Note Rev4 Optional Procedures: (slib)Rev4 Optional Procedures.
+
+`string-port'
+ *Note String Ports: (slib)String Ports.
+
+`tmpnam'
+ *Note Input/Output: (slib)Input/Output.
+
+`transcript'
+ *Note Transcripts: (slib)Transcripts.
+
+`vicinity'
+ *Note Vicinity: (slib)Vicinity.
+
+`with-file'
+ *Note With-File: (slib)With-File.
+
+[SLIB] Features of SCM
+----------------------
+
+`array'
+ *Note Arrays: (slib)Arrays.
+
+`array-for-each'
+ *Note Array Mapping: (slib)Array Mapping.
+
+`bignum'
+`complex'
+`inexact'
+`rational'
+`real'
+ *Note Require: (slib)Require.
+
+
+File: scm.info, Node: Miscellaneous Procedures, Next: Time, Prev: Standards Compliance, Up: The Language
+
+Miscellaneous Procedures
+========================
+
+ - Function: try-load FILENAME
+ If the string FILENAME names an existing file, the try-load
+ procedure reads Scheme source code expressions and definitions
+ from the file and evaluates them sequentially and returns `#t'.
+ If not, try-load returns `#f'. The try-load procedure does not
+ affect the values returned by `current-input-port' and
+ `current-output-port'.
+
+ - Variable: *load-pathname*
+ Is set to the pathname given as argument to `load', `try-load',
+ and `dyn:link' (*note Compiling And Linking::.).
+ `*load-pathname*' is used to compute the value of *Note
+ program-vicinity: (slib)Vicinity.
+
+ - Function: line-number
+ Returns the current line number of the file currently being loaded.
+
+ - Function: port-filename PORT |
+ Returns the filename PORT was opened with. If PORT is not open to |
+ a file the result is unspecified. |
+ |
+ - Function: port-line PORT |
+ - Function: port-column PORT |
+ If PORT is a tracked port, return the current line (column) number, |
+ otherwise return `#f'. Line numbers begin with 1, the column |
+ number is zero if there are no characters on the current line. |
+ |
+ - Function: eval OBJ
+ Alias for *Note eval: (slib)System.
+
+ - Function: eval-string STR
+ Returns the result of reading an expression from STR and
+ evaluating it. `eval-string' does not change `*load-pathname*' or
+ `line-number'.
+
+ - Function: load-string STR
+ Reads and evaluates all the expressions from STR. As with `load',
+ the value returned is unspecified. `load-string' does not change
+ `*load-pathname*' or `line-number'.
+
+ - Function: vector-set-length! OBJECT LENGTH
+ Change the length of string, vector, bit-vector, or uniform-array
+ OBJECT to LENGTH. If this shortens OBJECT then the remaining
+ contents are lost. If it enlarges OBJECT then the contents of the
+ extended part are undefined but the original part is unchanged.
+ It is an error to change the length of literal datums. The new
+ object is returned.
+
+ - Function: copy-tree OBJ
+ - Function: @copy-tree OBJ
+ *Note copy-tree: (slib)Tree Operations. This extends the SLIB
+ version by also copying vectors. Use `@copy-tree' if you depend
+ on this feature; `copy-tree' could get redefined.
+
+ - Function: acons OBJ1 OBJ2 OBJ3
+ Returns (cons (cons obj1 obj2) obj3). The expression (set! a-list
+ (acons key datum a-list)) adds a new association to a-list.
+
+ - Function: terms
+ This command displays the GNU General Public License.
+
+ - Function: list-file FILENAME
+ Displays the text contents of FILENAME.
+
+ - Procedure: print ARG1 ...
+ `Print' writes all its arguments, separated by spaces. `Print'
+ outputs a `newline' at the end and returns the value of the last
+ argument.
+
+
+File: scm.info, Node: Time, Next: Interrupts, Prev: Miscellaneous Procedures, Up: The Language
+
+Time
+====
+
+ - Constant: internal-time-units-per-second
+ Is the integer number of internal time units in a second.
+
+ - Function: get-internal-run-time
+ Returns the integer run time in internal time units from an
+ unspecified starting time. The difference of two calls to
+ `get-internal-run-time' divided by
+ `internal-time-units-per-second' will give elapsed run time in
+ seconds.
+
+ - Function: get-internal-real-time
+ Returns the integer time in internal time units from an unspecified
+ starting time. The difference of two calls to
+ `get-internal-real-time' divided by
+ `interal-time-units-per-second' will give elapsed real time in
+ seconds.
+
+ - Function: current-time
+ Returns the time since 00:00:00 GMT, January 1, 1970, measured in
+ seconds. *Note current-time: (slib)Time. `current-time' is used
+ in *Note Time: (slib)Time.
+
+
+File: scm.info, Node: Interrupts, Next: Process Synchronization, Prev: Time, Up: The Language
+
+Interrupts
+==========
+
+ - Function: ticks N
+ Returns the number of ticks remaining till the next tick interrupt.
+ Ticks are an arbitrary unit of evaluation. Ticks can vary greatly
+ in the amount of time they represent.
+
+ If N is 0, any ticks request is canceled. Otherwise a
+ `ticks-interrupt' will be signaled N from the current time.
+ `ticks' is supported if SCM is compiled with the `ticks' flag
+ defined.
+
+ - Callback procedure: ticks-interrupt ...
+ Establishes a response for tick interrupts. Another tick
+ interrupt will not occur unless `ticks' is called again. Program
+ execution will resume if the handler returns. This procedure
+ should (abort) or some other action which does not return if it
+ does not want processing to continue.
+
+ - Function: alarm SECS
+ Returns the number of seconds remaining till the next alarm
+ interrupt. If SECS is 0, any alarm request is canceled.
+ Otherwise an `alarm-interrupt' will be signaled SECS from the
+ current time. ALARM is not supported on all systems.
+
+ - Function: milli-alarm MILLISECS INTERVAL
+ - Function: virtual-alarm MILLISECS INTERVAL
+ - Function: profile-alarm MILLISECS INTERVAL
+ `milli-alarm' is similar to `alarm', except that the first
+ argument MILLISECS, and the return value are measured in
+ milliseconds rather than seconds. If the optional argument
+ INTERVAL is supplied then alarm interrupts will be scheduled every
+ INTERVAL milliseconds until turned off by a call to `milli-alarm'
+ or `alarm'.
+
+ `virtual-alarm' and `profile-alarm' are similar. `virtual-alarm'
+ decrements process execution time rather than real time, and
+ causes `SIGVTALRM' to be signaled. `profile-alarm' decrements
+ both process execution time and system execution time on behalf
+ of the process, and causes `SIGPROF' to be signaled.
+
+ `milli-alarm', `virtual-alarm', and `profile-alarm' are supported
+ only on systems providing the `setitimer' system call.
+
+ - Callback procedure: user-interrupt ...
+ - Callback procedure: alarm-interrupt ...
+ - Callback procedure: virtual-alarm-interrupt ...
+ - Callback procedure: profile-alarm-interrupt ...
+ Establishes a response for `SIGINT' (control-C interrupt) and
+ `SIGALRM', `SIGVTALRM', and `SIGPROF' interrupts. Program
+ execution will resume if the handler returns. This procedure
+ should `(abort)' or some other action which does not return if it
+ does not want processing to continue after it returns.
+
+ Interrupt handlers are disabled during execution `system' and `ed'
+ procedures.
+
+ To unestablish a response for an interrupt set the handler symbol
+ to `#f'. For instance, `(set! user-interrupt #f)'.
+
+ - Callback procedure: out-of-storage ...
+ - Callback procedure: could-not-open ...
+ - Callback procedure: end-of-program ...
+ - Callback procedure: hang-up ...
+ - Callback procedure: arithmetic-error ...
+ Establishes a response for storage allocation error, file opening
+ error, end of program, SIGHUP (hang up interrupt) and arithmetic
+ errors respectively. This procedure should (abort) or some other
+ action which does not return if it does not want the default error
+ message to also be displayed. If no procedure is defined for
+ HANG-UP then END-OF-PROGRAM (if defined) will be called.
+
+ To unestablish a response for an error set the handler symbol to
+ `#f'. For instance, `(set! could-not-open #f)'.
+
+
+File: scm.info, Node: Process Synchronization, Next: Files and Ports, Prev: Interrupts, Up: The Language
+
+Process Synchronization
+=======================
+
+ - Function: make-arbiter NAME
+ Returns an object of type arbiter and name NAME. Its state is
+ initially unlocked.
+
+ - Function: try-arbiter ARBITER
+ Returns `#t' and locks ARBITER if ARBITER was unlocked.
+ Otherwise, returns `#f'.
+
+ - Function: release-arbiter ARBITER
+ Returns `#t' and unlocks ARBITER if ARBITER was locked.
+ Otherwise, returns `#f'.
+
+
+File: scm.info, Node: Files and Ports, Next: Soft Ports, Prev: Process Synchronization, Up: The Language
+
+Files and Ports
+===============
+
+These procedures generalize and extend the standard capabilities in
+*Note Ports: (r5rs)Ports.
+
+ - Function: open-file STRING MODES
+ - Function: try-open-file STRING MODES
+ Returns a port capable of receiving or delivering characters as
+ specified by the MODES string. If a file cannot be opened `#f' is
+ returned.
+
+ Internal functions opening files "callback" to the SCM function
+ `open-file'. You can extend `open-file' by redefining it.
+ `try-open-file' is the primitive procedure; Do not redefine
+ `try-open-file'!
+
+ - Constant: open_read
+ - Constant: open_write
+ - Constant: open_both
+ Contain modes strings specifying that a file is to be opened for
+ reading, writing, and both reading and writing respectively.
+
+ - Function: _ionbf MODESTR
+ Returns a version of MODESTR which when `open-file' is called with |
+ it as the second argument will return an unbuffered port. A
+ non-file input-port must be unbuffered in order for `char-ready?' |
+ and `wait-for-input' to work correctly on it. The initial value of |
+ `(current-input-port)' is unbuffered if the platform supports it. |
+ |
+ - Function: _tracked MODESTR |
+ Returns a version of MODESTR which when `open-file' is called with |
+ it as the second argument will return a tracked port. A tracked |
+ port maintains current line and column numbers, which may be |
+ queried with `port_line' and `port_column'. |
+
+ - Function: close-port PORT
+ Closes PORT. The same as close-input-port and close-output-port.
+
+ - Function: open-io-file FILENAME
+ - Function: close-io-port PORT
+ These functions are analogous to the standard scheme file
+ functions. The ports are open to FILENAME in read/write mode.
+ Both input and output functions can be used with io-ports. An end
+ of file must be read or a file-set-position done on the port
+ between a read operation and a write operation or vice-versa.
+
+ - Function: current-error-port
+ Returns the current port to which diagnostic output is directed.
+
+ - Function: with-error-to-file STRING THUNK
+ THUNK must be a procedure of no arguments, and string must be a
+ string naming a file. The file is opened for output, an output
+ port connected to it is made the default value returned by
+ current-error-port, and the THUNK is called with no arguments.
+ When the thunk returns, the port is closed and the previous
+ default is restored. With-error-to-file returns the value yielded
+ by THUNK.
+
+ - Function: with-input-from-port PORT THUNK
+ - Function: with-output-to-port PORT THUNK
+ - Function: with-error-to-port PORT THUNK
+ These routines differ from with-input-from-file,
+ with-output-to-file, and with-error-to-file in that the first
+ argument is a port, rather than a string naming a file.
+
+ - procedure: char-ready?
+ - procedure: char-ready? PORT
+ Returns `#t' if a character is ready on the input PORT and returns
+ `#f' otherwise. If `char-ready?' returns `#t' then the next
+ `read-char' operation on the given PORT is guaranteed not to hang.
+ If the PORT is at end of file then `char-ready?' returns `#t'.
+ PORT may be omitted, in which case it defaults to the value
+ returned by `current-input-port'.
+
+ *Rationale:* `Char-ready?' exists to make it possible for a
+ program to accept characters from interactive ports without
+ getting stuck waiting for input. Any input editors associated
+ with such ports must ensure that characters whose existence has
+ been asserted by `char-ready?' cannot be rubbed out. If
+ `char-ready?' were to return `#f' at end of file, a port at end of
+ file would be indistinguishable from an interactive port that has
+ no ready characters.
+
+ - procedure: wait-for-input X
+ - procedure: wait-for-input X PORT1 ...
+ Returns a list those ports PORT1 ... which are `char-ready?'. If
+ none of PORT1 ... become `char-ready?' within the time interval of
+ X seconds, then #f is returned. The PORT1 ... arguments may be
+ omitted, in which case they default to the list of the value
+ returned by `current-input-port'.
+
+ - Function: isatty? PORT
+ Returns `#t' if PORT is input or output to a serial non-file
+ device.
+
+ - Function: freshline PORT |
+ Outputs a newline to optional argument PORT unless the current |
+ output column number of PORT is known to be zero, ie output will |
+ start at the beginning of a new line. PORT defaults to |
+ `current-output-port'. If PORT is not a tracked port `freshline' |
+ is equivalent to `newline'. |
+ |
+
+File: scm.info, Node: Soft Ports, Next: Syntax Extensions, Prev: Files and Ports, Up: The Language
+
+Soft Ports
+==========
+
+A "soft-port" is a port based on a vector of procedures capable of
+accepting or delivering characters. It allows emulation of I/O ports.
+
+ - Function: make-soft-port VECTOR MODES
+ Returns a port capable of receiving or delivering characters as
+ specified by the MODES string (*note open-file: Files and Ports.).
+ VECTOR must be a vector of length 6. Its components are as
+ follows:
+
+ 0. procedure accepting one character for output
+
+ 1. procedure accepting a string for output
+
+ 2. thunk for flushing output
+
+ 3. thunk for getting one character
+
+ 4. thunk for closing port (not by garbage collection)
+
+ For an output-only port only elements 0, 1, 2, and 4 need be
+ procedures. For an input-only port only elements 3 and 4 need be
+ procedures. Thunks 2 and 4 can instead be `#f' if there is no
+ useful operation for them to perform.
+
+ If thunk 3 returns `#f' or an `eof-object' (*note eof-object?:
+ (r5rs)Input.) it indicates that the port has reached end-of-file.
+ For example:
+
+ (define stdout (current-output-port))
+ (define p (make-soft-port
+ (vector
+ (lambda (c) (write c stdout))
+ (lambda (s) (display s stdout))
+ (lambda () (display "." stdout))
+ (lambda () (char-upcase (read-char)))
+ (lambda () (display "@" stdout)))
+ "rw"))
+
+ (write p p) => #<input-output-soft#\space45d10#\>
+
+
+File: scm.info, Node: Syntax Extensions, Next: Low Level Syntactic Hooks, Prev: Soft Ports, Up: The Language
+
+Syntax Extensions
+=================
+
+ - procedure: procedure-documentation PROC
+ Returns the documentation string of PROC if it exists, or `#f' if
+ not.
+
+ If the body of a `lambda' (or the definition of a procedure) has
+ more than one expression, and the first expression (preceeding any
+ internal definitions) is a string, then that string is the
+ "documentation string" of that procedure.
+
+ (procedure-documentation (lambda (x) "Identity" x)) => "Identity"
+ (define (square x)
+ "Return the square of X."
+ (* x x))
+ => #<unspecified>
+ (procedure-documentation square) => "Return the square of X."
+
+ - Function: comment STRING1 ... |
+ Appends STRING1 ... to the strings given as arguments to previous |
+ calls `comment'. |
+ |
+ - Function: comment |
+ Returns the (appended) strings given as arguments to previous calls |
+ `comment' and empties the current string collection. |
+ |
+ - Read syntax: #;text-till-end-of-line |
+ Behaves as `(comment "TEXT-TILL-END-OF-LINE")'. |
+ |
+ - Read syntax: #. EXPRESSION
+ Is read as the object resulting from the evaluation of EXPRESSION.
+ This substitution occurs even inside quoted structure.
+
+ In order to allow compiled code to work with `#.' it is good
+ practice to define those symbols used inside of EXPRESSION with
+ `#.(define ...)'. For example:
+
+ #.(define foo 9) => #<unspecified>
+ '(#.foo #.(+ foo foo)) => (9 18)
+
+ - Read syntax: #+ FEATURE FORM
+ If feature is `provided?' (by `*features*') then FORM is read as a
+ scheme expression. If not, then FORM is treated as whitespace.
+
+ Feature is a boolean expression composed of symbols and `and',
+ `or', and `not' of boolean expressions.
+
+ For more information on `provided?' and `*features*', *Note
+ Require: (slib)Require.
+
+ - Read syntax: #- FEATURE FORM
+ is equivalent to `#+(not feature) expression'.
+
+ - Read syntax: #' FORM
+ is equivalent to FORM (for compatibility with common-lisp).
+
+ - Read syntax: #| ANY THING |#
+ Is a balanced comment. Everything up to the matching `|#' is
+ ignored by the `read'. Nested `#|...|#' can occur inside ANY
+ THING.
+
+A similar read syntax "#!" (exclamation rather than vertical bar) is
+supported for Posix shell-scripts (*note Scripting::.).
+
+ - Read syntax: #\token
+ If TOKEN is a sequence of two or more digits, then this syntax is
+ equivalent to `#.(integer->char (string->number token 8))'.
+
+ If TOKEN is `C-', `c-', or `^' followed by a character, then this
+ syntax is read as a control character. If TOKEN is `M-' or `m-'
+ followed by a character, then a meta character is read. `c-' and
+ `m-' prefixes may be combined.
+
+ - Special Form: defined? SYMBOL
+ Equivalent to `#t' if SYMBOL is a syntactic keyword (such as `if')
+ or a symbol with a value in the top level environment (*note
+ Variables and regions: (r5rs)Variables and regions.). Otherwise
+ equivalent to `#f'.
+
+ - Special Form: defvar IDENTIFIER INITIAL-VALUE
+ If IDENTIFIER is unbound in the top level environment, then
+ IDENTIFIER is `define'd to the result of evaluating the form
+ INITIAL-VALUE as if the `defvar' form were instead the form
+ `(define identifier initial-value)' . If IDENTIFIER already has a
+ value, then INITIAL-VALUE is *not* evaluated and IDENTIFIER's
+ value is not changed. `defconst' is valid only when used at
+ top-level.
+
+ - Special Form: defconst IDENTIFIER VALUE
+ If IDENTIFIER is unbound in the top level environment, then
+ IDENTIFIER is `define'd to the result of evaluating the form VALUE
+ as if the `defconst' form were instead the form `(define
+ identifier value)' . If IDENTIFIER already has a value, then
+ VALUE is *not* evaluated, IDENTIFIER's value is not changed, and
+ an error is signaled. `defconst' is valid only when used at
+ top-level.
+
+ - Special Form: set! (VARIABLE1 VARIABLE2 ...) <expression>
+ The identifiers VARIABLE1, VARIABLE2, ... must be bound either in
+ some region enclosing the `set!' expression or at top level.
+
+ <Expression> is evaluated, and the elements of the resulting list
+ are stored in the locations to which each corresponding VARIABLE
+ is bound. The result of the `set!' expression is unspecified.
+
+ (define x 2)
+ (define y 3)
+ (+ x y) => 5
+ (set! (x y) (list 4 5)) => *unspecified*
+ (+ x y) => 9
+
+ - Special Form: casev KEY CLAUSE1 CLAUSE2 ...
+ `casev' is an extension of standard Scheme `case': Each CLAUSE of
+ a `casev' statement must have as first element a list containing
+ elements which are:
+
+ * literal datums, or
+
+ * a comma followed by the name of a symbolic constant, or
+
+ * a comma followed by an at-sign (@) followed by the name of a
+ symbolic constant whose value is a list.
+
+ A `casev' statement is equivalent to a `case' statement in which
+ these symbolic constants preceded by commas have been replaced by
+ the values of the constants, and all symbolic constants preceded by
+ comma-at-signs have been replaced by the elements of the list
+ values of the constants. This use of comma, (or, equivalently,
+ `unquote') is similar to that of `quasiquote' except that the
+ unquoted expressions must be "symbolic constants".
+
+ Symbolic constants are defined using `defconst', their values are
+ substituted in the head of each `casev' clause during macro
+ expansion. `defconst' constants should be defined before use.
+ `casev' can be substituted for any correct use of `case'.
+
+ (defconst unit '1)
+ (defconst semivowels '(w y))
+ (casev (* 2 3)
+ ((2 3 5 7) 'prime)
+ ((,unit 4 6 8 9) 'composite)) ==> composite
+ (casev (car '(c d))
+ ((a) 'a)
+ ((b) 'b)) ==> *unspecified*
+ (casev (car '(c d))
+ ((a e i o u) 'vowel)
+ ((,@semivowels) 'semivowel)
+ (else 'consonant)) ==> consonant
+
+
+SCM also supports the following constructs from Common Lisp:
+`defmacro', `macroexpand', `macroexpand-1', and `gentemp'. *Note
+Defmacro: (slib)Defmacro.
+
+
+File: scm.info, Node: Low Level Syntactic Hooks, Next: Syntactic Hooks for Hygienic Macros, Prev: Syntax Extensions, Up: The Language
+
+Low Level Syntactic Hooks
+=========================
+
+ - Callback procedure: read:sharp C PORT
+ If a <#> followed by a character (for a non-standard syntax) is
+ encountered by `read', `read' will call the value of the symbol
+ `read:sharp' with arguments the character and the port being read
+ from. The value returned by this function will be the value of
+ `read' for this expression unless the function returns
+ `#<unspecified>' in which case the expression will be treated as
+ whitespace. `#<unspecified>' is the value returned by the
+ expression `(if #f #f)'.
+
+ - Callback procedure: read:sharp-char TOKEN
+ If the sequence <#\> followed by a non-standard character name is
+ encountered by `read', `read' will call the value of the symbol
+ `read:sharp-char' with the token (a string of length at least two)
+ as argument. If the value returned is a character, then that will
+ be the value of `read' for this expression, otherwise an error
+ will be signaled.
+
+*Note:* When adding new <#> syntaxes, have your code save the previous
+value of `read:sharp' or `read:sharp-char' when defining it. Call this
+saved value if an invocation's syntax is not recognized. This will
+allow `#+', `#-', `#!', and *Note Uniform Array::s to still be
+supported (as they use `read:sharp').
+
+ - Function: procedure->syntax PROC
+ Returns a "macro" which, when a symbol defined to this value
+ appears as the first symbol in an expression, returns the result
+ of applying PROC to the expression and the environment.
+
+ - Function: procedure->macro PROC
+ - Function: procedure->memoizing-macro PROC
+ Returns a "macro" which, when a symbol defined to this value
+ appears as the first symbol in an expression, evaluates the result
+ of applying PROC to the expression and the environment. The value
+ returned from PROC which has been passed to
+ `PROCEDURE->MEMOIZING-MACRO' replaces the form passed to PROC.
+ For example:
+
+ (define trace
+ (procedure->macro
+ (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))
+
+ (trace foo) == (set! foo (tracef foo 'foo)).
+
+ - Function: environment->tree ENV
+ An "environment" is an opaque object representing lexical bindings.
+ `environment->tree' returns a representation of the environment
+ ENV as a list of environment frames. There are 2 types of
+ environment frames:
+
+ `((lambda (variable1 ...) ...) value1 ...)'
+ `(let ((variable1 value1) (variable2 value2) ...) ...)'
+ `(letrec ((variable1 value1) ...) ...)'
+ result in a single enviroment frame:
+ ((variable1 ...) value1 ...)
+
+ `(let ((variable1 value1)) ...)'
+ `(let* ((variable1 value1) ...) ...)'
+ result in an environment frame for each variable:
+ (variable1 . value1) (variable2 . value2) ...
+
+ - Special Form: @apply PROCEDURE ARGUMENT-LIST
+ Returns the result of applying PROCEDURE to ARGUMENT-LIST.
+ `@apply' differs from `apply' when the identifiers bound by the
+ closure being applied are `set!'; setting affects ARGUMENT-LIST.
+
+ (define lst (list 'a 'b 'c))
+ (@apply (lambda (v1 v2 v3) (set! v1 (cons v2 v3))) lst)
+ lst => ((b . c) b c)
+
+ Thus a mutable environment can be treated as both a list and local
+ bindings.
+
+ - Special Form: @call-with-current-continuation PROCEDURE
+ Returns the result of applying PROCEDURE to the current
+ continuation. A "continuation" is a SCM object of type `contin'
+ (*note Continuations::.). The procedure
+ `(call-with-current-continuation PROCEDURE)' is defined to have
+ the same effect as `(@call-with-current-continuation procedure)'.
+
+
+File: scm.info, Node: Syntactic Hooks for Hygienic Macros, Prev: Low Level Syntactic Hooks, Up: The Language
+
+Syntactic Hooks for Hygienic Macros
+===================================
+
+SCM provides a synthetic identifier type for efficient implementation of
+hygienic macros (for example, `syntax-rules' *note Macros:
+(r5rs)Macros.) A synthetic identifier may be inserted in Scheme code by
+a macro expander in any context where a symbol would normally be used.
+Collectively, symbols and synthetic identifiers are *identifiers*.
+
+ - Function: identifier? OBJ
+ Returns `#t' if OBJ is a symbol or a synthetic identifier, and
+ `#f' otherwise.
+
+If it is necessary to distinguish between symbols and synthetic
+identifiers, use the predicate `symbol?'.
+
+A synthetic identifier includes two data: a parent, which is an
+identifier, and an environment, which is either `#f' or a lexical
+environment which has been passed to a "macro expander" (a procedure
+passed as an argument to `procedure->macro',
+`procedure->memoizing-macro', or `procedure->syntax').
+
+ - Function: renamed-identifier PARENT ENV
+ Returns a synthetic identifier. PARENT must be an identifier, and
+ ENV must either be `#f' or a lexical environment passed to a macro
+ expander. `renamed-identifier' returns a distinct object for each
+ call, even if passed identical arguments.
+
+There is no direct way to access all of the data internal to a synthetic
+identifier, those data are used during variable lookup. If a synthetic
+identifier is inserted as quoted data then during macro expansion it
+will be repeatedly replaced by its parent, until a symbol is obtained.
+
+ - Function: identifier->symbol ID
+ Returns the symbol obtained by recursively extracting the parent of
+ ID, which must be an identifier.
+
+Use of synthetic identifiers
+----------------------------
+
+`renamed-identifier' may be used as a replacement for `gentemp':
+ (define gentemp
+ (let ((name (string->symbol "An unlikely variable")))
+ (lambda ()
+ (renamed-identifier name #f))))
+
+If an identifier returned by this version of `gentemp' is inserted in a
+binding position as the name of a variable then it is guaranteed that
+no other identifier may denote that variable. If an identifier
+returned by `gentemp' is inserted free, then it will denote the
+top-level value bound to its parent, the symbol named "An unlikely
+variable". This behavior, of course, is meant to be put to good use:
+
+ (define top-level-foo
+ (procedure->memoizing-macro
+ (lambda (exp env)
+ (renamed-identifier 'foo #f))))
+
+Defines a macro which may always be used to refer to the top-level
+binding of `foo'.
+
+ (define foo 'top-level)
+ (let ((foo 'local))
+ (top-level-foo)) => top-level
+
+In other words, we can avoid capturing `foo'.
+
+If a lexical environment is passed as the second argument to
+`renamed-identifier' then if the identifier is inserted free its parent
+will be looked up in that environment, rather than in the top-level
+environment. The use of such an identifier *must* be restricted to the
+lexical scope of its environment.
+
+There is another restriction imposed for implementation convenience:
+Macros passing their lexical environments to `renamed-identifier' may
+be lexically bound only by the special forms `@let-syntax' or
+`@letrec-syntax'. No error is signaled if this restriction is not met,
+but synthetic identifier lookup will not work properly.
+
+ - Special Form: @let-syntax
+ - Special Form: @letrec-syntax
+ Behave as `let' and `letrec', but may also put extra information
+ in the lexical environment so that `renamed-identifier' will work
+ properly during expansion of the macros bound by these forms.
+
+In order to maintain referential transparency it is necessary to
+determine whether two identifiers have the same denotation. With
+synthetic identifiers it is not necessary that two identifiers be `eq?'
+in order to denote the same binding.
+
+ - Function: identifier-equal? ID1 ID2 ENV
+ Returns `#t' if identifiers ID1 and ID2 denote the same binding in
+ lexical environment ENV, and `#f' otherwise. ENV must be a
+ lexical environment passed to a macro transformer during macro
+ expansion.
+
+ For example,
+ (define top-level-foo?
+ (procedure->memoizing-macro
+ (let ((foo-name (renamed-identifier 'foo #f)))
+ (lambda (exp env)
+ (identifier-equal? (cadr exp) foo-name env)))))
+
+ (top-level-foo? foo) => #t
+
+ (let ((foo 'local))
+ (top-level-foo? foo)) => #f
+
+ - Function: @macroexpand1 EXPR ENV
+ If the `car' of EXPR denotes a macro in ENV, then if that macro is
+ a primitive, EXPR will be returned, if the macro was defined in
+ Scheme, then a macro expansion will be returned. If the `car' of
+ EXPR does not denote a macro, the `#f' is returned.
+
+ - Function: extended-environment NAMES VALUES ENV
+ Returns a new environment object, equivalent to ENV, which must
+ either be an environment object or null, extended by one frame.
+ NAMES must be an identifier, or an improper list of identifiers,
+ usable as a formals list in a `lambda' expression. VALUES must be
+ a list of objects long enough to provide a binding for each of the
+ identifiers in NAMES. If NAMES is an identifier or an improper
+ list then VALS may be, respectively, any object or an improper
+ list of objects.
+
+ - Special Form: syntax-quote OBJ
+ Synthetic identifiers are converted to their parent symbols by
+ `quote' and `quasiquote' so that literal data in macro definitions
+ will be properly transcribed. `syntax-quote' behaves like
+ `quote', but preserves synthetic identifier intact.
+
+ - Special Form: the-macro MAC
+ `the-macro' is the simplest of all possible macro transformers:
+ MAC may be a syntactic keyword (macro name) or an expression
+ evaluating to a macro, otherwise an error is signaled. MAC is
+ evaluated and returned once only, after which the same memoizied
+ value is returned.
+
+ `the-macro' may be used to protect local copies of macros against
+ redefinition, for example:
+ (@let-syntax ((let (the-macro let)))
+ ;; code that will continue to work even if LET is redefined.
+ ...)
+
+ - Special Form: renaming-transformer PROC
+ A low-level "explicit renaming" macro facility very similar to that
+ proposed by W. Clinger [Exrename] is supported. Syntax may be
+ defined in `define-syntax', `let-syntax', and `letrec-syntax'
+ using `renaming-transformer' instead of `syntax-rules'. PROC
+ should evaluate to a procedure accepting three arguments: EXPR,
+ RENAME, and COMPARE. EXPR is a representation of Scheme code to be
+ expanded, as list structure. RENAME is a procedure accepting an
+ identifier and returning an identifier renamed in the definition
+ environment of the new syntax. COMPARE accepts two identifiers
+ and returns true if and only if both denote the same binding in
+ the usage environment of the new syntax.
+
+
+File: scm.info, Node: Packages, Next: The Implementation, Prev: The Language, Up: Top
+
+Packages
+********
+
+* Menu:
+
+* Compiling And Linking:: Hobbit
+* Dynamic Linking::
+* Dump:: Create Fast-Booting Executables
+* Numeric:: Numeric Language Extensions
+* Arrays:: As in APL
+* I/O-Extensions:: i/o-extensions
+* Posix Extensions:: posix
+* Regular Expression Pattern Matching:: regex
+* Line Editing:: edit-line
+* Curses:: Screen Control
+* Sockets:: Cruise the Net
+
+* Menu:
+
+* Xlib: (Xlibscm). X Window Graphics.
+
+
+File: scm.info, Node: Compiling And Linking, Next: Dynamic Linking, Prev: Packages, Up: Packages
+
+Compiling And Linking
+=====================
+
+ - Function: compile-file NAME1 NAME2 ...
+ If the HOBBIT compiler is installed in the
+ `(implementation-vicinity)', compiles the files NAME1 NAME2 ... to
+ an object file name NAME1<object-suffix>, where <object-suffix> is
+ the object file suffix for your computer (for instance, `.o').
+ NAME1 must be in the current directory; NAME2 ... can be in other
+ directories.
+
+ - Function: link-named-scm NAME MODULE1 ...
+ Creates a new SCM executable with name NAME. NAME will include
+ the object modules MODULE1 ... which can be produced with
+ `compile-file'.
+
+ cd ~/scm/
+ scm -e'(link-named-scm"cute""cube")'
+ (delete-file "scmflags.h")
+ (call-with-output-file
+ "scmflags.h"
+ (lambda (fp)
+ (for-each
+ (lambda (string) (write-line string fp))
+ '("#define IMPLINIT \"/home/jaffer/scm/Init5d2.scm\"" |
+ "#define COMPILED_INITS init_cube();"
+ "#define BIGNUMS"
+ "#define FLOATS"
+ "#define ARRAYS"))))
+ (system "gcc -Wall -O2 -c continue.c findexec.c time.c
+ repl.c scl.c eval.c sys.c subr.c unif.c rope.c scm.c")
+ ...
+ scm.c: In function `scm_init_extensions':
+ scm.c:95: warning: implicit declaration of function `init_cube'
+ scm.c: In function `scm_cat_path':
+ scm.c:589: warning: implicit declaration of function `realloc'
+ scm.c:594: warning: implicit declaration of function `malloc'
+ scm.c: In function `scm_try_path':
+ scm.c:612: warning: implicit declaration of function `free'
+ (system "cc -o cute continue.o findexec.o time.o repl.o scl.o
+ eval.o sys.o subr.o unif.o rope.o scm.o cube.o -lm -lc")
+
+ Compilation finished at Sun Jul 21 00:59:17
+
+
+File: scm.info, Node: Dynamic Linking, Next: Dump, Prev: Compiling And Linking, Up: Packages
+
+Dynamic Linking
+===============
+
+If SCM has been compiled with `dynl.c' then the additional properties
+of load and ([SLIB]) require specified here are supported. The
+`require' form is preferred.
+
+ - Function: require FEATURE
+ If the symbol FEATURE has not already been given as an argument to
+ `require', then the object and library files associated with
+ FEATURE will be dynamically-linked, and an unspecified value
+ returned. If FEATURE is not found in `*catalog*', then an error
+ is signaled.
+
+ - Function: usr:lib LIB
+ Returns the pathname of the C library named LIB. For example:
+ `(usr:lib "m")' returns `"/usr/lib/libm.a"', the path of the C
+ math library.
+
+ - Function: x:lib LIB
+ Returns the pathname of the X library named LIB. For example:
+ `(x:lib "X11")' returns `"/usr/X11/lib/libX11.sa"', the path of
+ the X11 library.
+
+ - Function: load FILENAME LIB1 ...
+ In addition to the [R5RS] requirement of loading Scheme
+ expressions if FILENAME is a Scheme source file, `load' will also
+ dynamically load/link object files (produced by `compile-file', for
+ instance). The object-suffix need not be given to load. For
+ example,
+
+ (load (in-vicinity (implementation-vicinity) "sc2"))
+ or (load (in-vicinity (implementation-vicinity) "sc2.o"))
+ or (require 'rev2-procedures)
+ or (require 'rev3-procedures)
+
+ will load/link `sc2.o' if it exists.
+
+ The LIB1 ... pathnames specify additional libraries which may be
+ needed for object files not produced by the Hobbit compiler. For
+ instance, crs is linked on Linux by
+
+ (load (in-vicinity (implementation-vicinity) "crs.o")
+ (usr:lib "ncurses") (usr:lib "c"))
+ or (require 'curses)
+
+ Turtlegr graphics library is linked by:
+
+ (load (in-vicinity (implementation-vicinity) "turtlegr")
+ (usr:lib "X11") (usr:lib "c") (usr:lib "m"))
+ or (require 'turtle-graphics)
+
+ And the string regular expression (*note Regular Expression
+ Pattern Matching::.) package is linked by:
+
+ (load (in-vicinity (implementation-vicinity) "rgx") (usr:lib "c"))
+ or
+ (require 'regex)
+
+The following functions comprise the low-level Scheme interface to
+dynamic linking. See the file `Link.scm' in the SCM distribution for
+an example of their use.
+
+ - Function: dyn:link FILENAME
+ FILENAME should be a string naming an "object" or "archive" file,
+ the result of C-compiling. The `dyn:link' procedure links and
+ loads FILENAME into the current SCM session. If successfull,
+ `dyn:link' returns a "link-token" suitable for passing as the
+ second argument to `dyn:call'. If not successful, `#f' is
+ returned.
+
+ - Function: dyn:call NAME LINK-TOKEN
+ LINK-TOKEN should be the value returned by a call to `dyn:link'.
+ NAME should be the name of C function of no arguments defined in
+ the file named FILENAME which was succesfully `dyn:link'ed in the
+ current SCM session. The `dyn:call' procedure calls the C
+ function corresponding to NAME. If successful, `dyn:call' returns
+ `#t'; If not successful, `#f' is returned.
+
+ `dyn:call' is used to call the "init_..." function after loading
+ SCM object files. The init_... function then makes the
+ identifiers defined in the file accessible as Scheme procedures.
+
+ - Function: dyn:main-call NAME LINK-TOKEN ARG1 ...
+ LINK-TOKEN should be the value returned by a call to `dyn:link'.
+ NAME should be the name of C function of 2 arguments, `(int argc,
+ char **argv)', defined in the file named FILENAME which was
+ succesfully `dyn:link'ed in the current SCM session. The
+ `dyn:main-call' procedure calls the C function corresponding to
+ NAME with `argv' style arguments, such as are given to C `main'
+ functions. If successful, `dyn:main-call' returns the integer
+ returned from the call to NAME.
+
+ `dyn:main-call' can be used to call a `main' procedure from SCM.
+ For example, I link in and `dyn:main-call' a large C program, the
+ low level routines of which callback (*note Callbacks::.) into SCM
+ (which emulates PCI hardware).
+
+ - Function: dyn:unlink LINK-TOKEN
+ LINK-TOKEN should be the value returned by a call to `dyn:link'.
+ The `dyn:unlink' procedure removes the previously loaded file from
+ the current SCM session. If successful, `dyn:unlink' returns
+ `#t'; If not successful, `#f' is returned.
+
+
+File: scm.info, Node: Dump, Next: Numeric, Prev: Dynamic Linking, Up: Packages
+
+Dump
+====
+
+"Dump", (also known as "unexec"), saves the continuation of an entire
+SCM session to an executable file, which can then be invoked as a
+program. Dumped executables start very quickly, since no Scheme code
+has to be loaded.
+
+There are constraints on which sessions are savable using `dump'
+
+ * Saved continuations are invalid in subsequent invocations; they
+ cause segmentation faults and other unpleasant side effects.
+
+ * Although DLD (*note Dynamic Linking::.) can be used to load
+ compiled modules both before and after dumping, `SUN_DL' ELF
+ systems can load compiled modules only after dumping. This can be
+ worked around by compiling in those features you wish to `dump'.
+
+ * Ports (other than `current-input-port', `current-output-port',
+ `current-error-port'), X windows, etc. are invalid in subsequent
+ invocations.
+
+ This restriction could be removed; *Note Improvements To Make::.
+
+ * `Dump' should only be called from a loading file when the call to
+ dump is the last expression in that file.
+
+ * `Dump' can be called from the command line.
+
+ - Function: dump NEWPATH
+ - Function: dump NEWPATH #F
+ - Function: dump NEWPATH #T
+ - Function: dump NEWPATH THUNK
+ * Calls `gc'.
+
+ * Creates an executable program named NEWPATH which continues
+ the state of the current SCM session when invoked. The
+ optional argument THUNK, if provided, should be a procedure
+ of no arguments. This procedure will be called in the
+ restored executable.
+
+ If the optional argument is missing or a boolean, SCM's
+ standard command line processing will be called in the
+ restored executable.
+
+ If the second argument to `dump' is `#t', argument processing
+ will continue from the command line passed to the dumping
+ session. If the second argument is missing or `#f' then the
+ command line arguments of the restoring invocation will be
+ processed.
+
+ * Resumes the top level Read-Eval-Print loop. This is done
+ instead of continuing normally to avoid creating a saved
+ continuation in the dumped executable.
+
+ `dump' may set the values of `boot-tail', `*argv*', `restart', and
+ *INTERACTIVE*. `dump' returns an unspecified value.
+
+When a dumped executable is invoked, the variable *INTERACTIVE* (*note
+Internal State::.) has the value it possessed when `dump' created it.
+Calling `dump' with a single argument sets *INTERACTIVE* to `#f', which
+is the state it has at the beginning of command line processing.
+
+The procedure `program-arguments' returns the command line arguments
+for the curent invocation. More specifically, `program-arguments' for
+the restored session are *not* saved from the dumping session. Command
+line processing is done on the value of the identifier `*argv*'.
+
+The thunk `boot-tail' is called by SCM to process command line
+arguments. `dump' sets `boot-tail' to the THUNK it is called with.
+
+The following example shows how to create `rscm', which is like regular
+scm, but which loads faster and has the `random' package alreadly
+provided.
+
+ bash$ scm -rrandom
+ > (dump "rscm")
+ #<unspecified>
+ > (quit)
+ bash$ ./rscm -lpi.scm -e"(pi (random 200) 5)"
+ 00003 14159 26535 89793 23846 26433 83279 50288 41971 69399
+ 37510 58209 74944 59230 78164 06286 20899 86280 34825 34211
+ 70679 82148 08651 32823 06647 09384 46095 50582 23172 53594
+ 08128 48111 74502 84102 70193 85211 05559 64462 29489
+ bash$
+
+This task can also be accomplished using the `-o' command line option
+(*note SCM Options::.).
+
+ bash$ scm -rrandom -o rscm
+ > (quit)
+ bash$ ./rscm -lpi.scm -e"(pi (random 200) 5)"
+ 00003 14159 26535 89793 23846 26433 83279 50288 41971 69399
+ 37510 58209 74944 59230 78164 06286 20899 86280 34825 34211
+ 70679 82148 08651 32823 06647 09384 46095 50582 23172 53594
+ 08128 48111 74502 84102 70193 85211 05559 64462 29489
+ bash$
+
+
+File: scm.info, Node: Numeric, Next: Arrays, Prev: Dump, Up: Packages
+
+Numeric
+=======
+
+ - Constant: most-positive-fixnum
+ The immediate integer closest to positive infinity. *Note
+ Configuration: (slib)Configuration.
+
+ - Constant: most-negative-fixnum
+ The immediate integer closest to negative infinity.
+
+These procedures augment the standard capabilities in *Note Numerical
+operations: (r5rs)Numerical operations.
+
+ - Function: sinh Z
+ - Function: cosh Z
+ - Function: tanh Z
+ Return the hyperbolic sine, cosine, and tangent of Z
+
+ - Function: asinh Z
+ - Function: acosh Z
+ - Function: atanh Z
+ Return the inverse hyperbolic sine, cosine, and tangent of Z
+
+ - Function: $sqrt X
+ - Function: $abs X
+ - Function: $exp X
+ - Function: $log X
+ - Function: $sin X
+ - Function: $cos X
+ - Function: $tan X
+ - Function: $asin X
+ - Function: $acos X
+ - Function: $atan X
+ - Function: $sinh X
+ - Function: $cosh X
+ - Function: $tanh X
+ - Function: $asinh X
+ - Function: $acosh X
+ - Function: $atanh X
+ Real-only versions of these popular functions. The argument X
+ must be a real number. It is an error if the value which should be
+ returned by a call to these procedures is *not* real.
+
+ - Function: $log10 X
+ Real-only base 10 logarithm.
+
+ - Function: $atan2 Y X
+ Computes `(angle (make-rectangular x y))' for real numbers Y and X.
+
+ - Function: $expt X1 X2
+ Returns real number X1 raised to the real power X2. It is an
+ error if the value which should be returned by a call to `$expt'
+ is not real.
+
+
+File: scm.info, Node: Arrays, Next: I/O-Extensions, Prev: Numeric, Up: Packages
+
+Arrays
+======
+
+* Menu:
+
+* Conventional Arrays::
+* Array Mapping:: array-for-each
+* Uniform Array::
+* Bit Vectors::
+
+
+File: scm.info, Node: Conventional Arrays, Next: Array Mapping, Prev: Arrays, Up: Arrays
+
+Conventional Arrays
+-------------------
+
+"Arrays" read and write as a `#' followed by the "rank" (number of
+dimensions) followed by the character #\a or #\A and what appear as
+lists (of lists) of elements. The lists must be nested to the depth of
+the rank. For each depth, all lists must be the same length.
+ (make-array 'ho 3 3) =>
+ #2A((ho ho ho) (ho ho ho) (ho ho ho))
+
+The rank may be elided, in which case it is read as one.
+ '#A(a b c) == '#(a b c)
+
+Unshared conventional (not uniform) 0-based arrays of rank 1 (dimension)
+are equivalent to (and can't be distinguished from) vectors.
+ (make-array 'ho 3) => #(ho ho ho)
+
+When constructing an array, BOUND is either an inclusive range of
+indices expressed as a two element list, or an upper bound expressed as
+a single integer. So
+ (make-array 'foo 3 3) == (make-array 'foo '(0 2) '(0 2))
+
+ - Function: array? OBJ
+ Returns `#t' if the OBJ is an array, and `#f' if not.
+
+ - Function: make-array INITIAL-VALUE BOUND1 BOUND2 ...
+ Creates and returns an array that has as many dimensions as there
+ are BOUNDs and fills it with INITIAL-VALUE.
+
+ - Function: array-ref ARRAY INDEX1 INDEX2 ...
+ Returns the INDEX1, INDEX2, ...'th element of ARRAY.
+
+ - Function: array-in-bounds? ARRAY INDEX1 INDEX2 ...
+ Returns `#t' if its arguments would be acceptable to ARRAY-REF.
+
+ - Function: array-set! ARRAY NEW-VALUE INDEX1 INDEX2 ...
+ Sets the INDEX1, INDEX2, ...'th element of ARRAY to NEW-VALUE.
+ The value returned by `array-set!' is unspecified.
+
+ - Function: make-shared-array ARRAY MAPPER BOUND1 BOUND2 ...
+ `make-shared-array' can be used to create shared subarrays of other
+ arrays. The MAPPER is a function that translates coordinates in
+ the new array into coordinates in the old array. A MAPPER must be
+ linear, and its range must stay within the bounds of the old
+ array, but it can be otherwise arbitrary. A simple example:
+ (define fred (make-array #f 8 8))
+ (define freds-diagonal
+ (make-shared-array fred (lambda (i) (list i i)) 8))
+ (array-set! freds-diagonal 'foo 3)
+ (array-ref fred 3 3) => foo
+ (define freds-center
+ (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))
+ (array-ref freds-center 0 0) => foo
+
+ - Function: transpose-array ARRAY DIM0 DIM1 ...
+ Returns an array sharing contents with ARRAY, but with dimensions
+ arranged in a different order. There must be one DIM argument for
+ each dimension of ARRAY. DIM0, DIM1, ... should be integers
+ between 0 and the rank of the array to be returned. Each integer
+ in that range must appear at least once in the argument list.
+
+ The values of DIM0, DIM1, ... correspond to dimensions in the
+ array to be returned, their positions in the argument list to
+ dimensions of ARRAY. Several DIMs may have the same value, in
+ which case the returned array will have smaller rank than ARRAY.
+
+ examples:
+ (transpose-array '#2A((a b) (c d)) 1 0) => #2A((a c) (b d))
+ (transpose-array '#2A((a b) (c d)) 0 0) => #1A(a d)
+ (transpose-array '#3A(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) =>
+ #2A((a 4) (b 5) (c 6))
+
+ - Function: enclose-array ARRAY DIM0 DIM1 ...
+ DIM0, DIM1 ... should be nonnegative integers less than the rank
+ of ARRAY. ENCLOSE-ARRAY returns an array resembling an array of
+ shared arrays. The dimensions of each shared array are the same
+ as the DIMth dimensions of the original array, the dimensions of
+ the outer array are the same as those of the original array that
+ did not match a DIM.
+
+ An enclosed array is not a general Scheme array. Its elements may
+ not be set using `array-set!'. Two references to the same element
+ of an enclosed array will be `equal?' but will not in general be
+ `eq?'. The value returned by ARRAY-PROTOTYPE when given an
+ enclosed array is unspecified.
+
+ examples:
+ (enclose-array '#3A(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) =>
+ #<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) =>
+ #<enclosed-array #2A((a 1) (d 4)) #2A((b 2) (e 5)) #2A((c 3) (f 6))>
+
+ - Function: array-shape ARRAY
+ Returns a list of inclusive bounds of integers.
+ (array-shape (make-array 'foo '(-1 3) 5)) => ((-1 3) (0 4))
+
+ - Function: array-dimensions ARRAY
+ `Array-dimensions' is similar to `array-shape' but replaces
+ elements with a `0' minimum with one greater than the maximum. So:
+ (array-dimensions (make-array 'foo '(-1 3) 5)) => ((-1 3) 5)
+
+ - Function: array-rank OBJ
+ Returns the number of dimensions of OBJ. If OBJ is not an array,
+ `0' is returned.
+
+ - Function: array->list ARRAY
+ Returns a list consisting of all the elements, in order, of ARRAY.
+ In the case of a rank-0 array, returns the single element.
+
+ - Function: array-copy! SOURCE DESTINATION
+ Copies every element from vector or array SOURCE to the
+ corresponding element of DESTINATION. DESTINATION must have the
+ same rank as SOURCE, and be at least as large in each dimension.
+ The order of copying is unspecified.
+
+ - Function: serial-array-copy! SOURCE DESTINATION
+ Same as `array-copy!' but guaranteed to copy in row-major order.
+
+ - Function: array-fill! ARRAY FILL
+ Stores FILL in every element of ARRAY. The value returned is
+ unspecified.
+
+ - Function: array-equal? ARRAY0 ARRAY1 ...
+ Returns `#t' iff all arguments are arrays with the same shape, the
+ same type, and have corresponding elements which are either
+ `equal?' or `array-equal?'. This function differs from `equal?'
+ in that a one dimensional shared array may be ARRAY-EQUAL? but not
+ EQUAL? to a vector or uniform vector.
+
+ - Function: array-contents ARRAY
+ - Function: array-contents ARRAY STRICT
+ If ARRAY may be "unrolled" into a one dimensional shared array
+ without changing their order (last subscript changing fastest),
+ then `array-contents' returns that shared array, otherwise it
+ returns `#f'. All arrays made by MAKE-ARRAY and
+ MAKE-UNIFORM-ARRAY may be unrolled, some arrays made by
+ MAKE-SHARED-ARRAY may not be.
+
+ If the optional argument STRICT is provided, a shared array will
+ be returned only if its elements are stored internally contiguous
+ in memory.
+
+
+File: scm.info, Node: Array Mapping, Next: Uniform Array, Prev: Conventional Arrays, Up: Arrays
+
+Array Mapping
+-------------
+
+`(require 'array-for-each)'
+
+ - Function: array-map! ARRAY0 PROC ARRAY1 ...
+ If ARRAY1, ... are arrays, they must have the same number of
+ dimensions as ARRAY0 and have a range for each index which
+ includes the range for the corresponding index in ARRAY0. If they
+ are scalars, that is, not arrays, vectors, or strings, then they
+ will be converted internally to arrays of the appropriate shape.
+ PROC is applied to each tuple of elements of ARRAY1 ... and the
+ result is stored as the corresponding element in ARRAY0. The
+ value returned is unspecified. The order of application is
+ unspecified.
+
+
+ - Function: serial-array-map! ARRAY0 PROC ARRAY1 ...
+ Same as ARRAY-MAP!, but guaranteed to apply PROC in row-major
+ order.
+
+ - Function: array-for-each PROC ARRAY0 ...
+ PROC is applied to each tuple of elements of ARRAY0 ... in
+ row-major order. The value returned is unspecified.
+
+ - Function: array-index-map! ARRAY PROC
+ applies PROC to the indices of each element of ARRAY in turn,
+ storing the result in the corresponding element. The value
+ returned and the order of application are unspecified.
+
+ One can implement ARRAY-INDEXES as
+ (define (array-indexes array)
+ (let ((ra (apply make-array #f (array-shape array))))
+ (array-index-map! ra (lambda x x))
+ ra))
+ Another example:
+ (define (apl:index-generator n)
+ (let ((v (make-uniform-vector n 1)))
+ (array-index-map! v (lambda (i) i))
+ v))
+
+ - Function: scalar->array SCALAR ARRAY PROTOTYPE
+ Returns a uniform array of the same shape as ARRAY, having only
+ one shared element, which is `eqv?' to SCALAR. If the optional
+ argument PROTOTYPE is supplied it will be used as the prototype
+ for the returned array. Otherwise the returned array will be of
+ the same type as `array' if that is possible, and a conventional
+ array if it is not. This function is used internally by
+ `array-map!' and friends to handle scalar arguments.
+
+
+File: scm.info, Node: Uniform Array, Next: Bit Vectors, Prev: Array Mapping, Up: Arrays
+
+Uniform Array
+-------------
+
+"Uniform Arrays" and vectors are arrays whose elements are all of the
+same type. Uniform vectors occupy less storage than conventional
+vectors. Uniform Array procedures also work on vectors,
+uniform-vectors, bit-vectors, and strings.
+
+PROTOTYPE arguments in the following procedures are interpreted
+according to the table:
+
+ prototype type display prefix
+
+ #t boolean (bit-vector) #At
+ #\a char (string) #A\
+ integer >0 unsigned integer #Au
+ integer <0 signed integer #Ae
+ 1.0 float (single precision) #Aif
+ 1/3 double (double precision float) #Aid
+ +i complex (double precision) #Aic
+ () conventional vector #A
+
+Unshared uniform character 0-based arrays of rank 1 (dimension) are
+equivalent to (and can't be distinguished from) strings.
+ (make-uniform-array #\a 3) => "$q2"
+
+Unshared uniform boolean 0-based arrays of rank 1 (dimension) are
+equivalent to (and can't be distinguished from) *Note bit-vectors: Bit
+Vectors.
+ (make-uniform-array #t 3) => #*000
+ ==
+ #At(#f #f #f) => #*000
+ ==
+ #1At(#f #f #f) => #*000
+
+Other uniform vectors are written in a form similar to that of general
+arrays, except that one or more modifying characters are put between
+the #\A character and the contents list. For example, `'#Ae(3 5 9)'
+returns a uniform vector of signed integers.
+
+ - Function: uniform-vector-ref UVE INDEX
+ Returns the element at the INDEX element in UVE.
+
+ - Function: uniform-vector-set! UVE INDEX NEW-VALUE
+ Sets the element at the INDEX element in UVE to NEW-VALUE. The
+ value returned by `uniform-vector-set!' is unspecified.
+
+ - Function: array? OBJ PROTOTYPE
+ Returns `#t' if the OBJ is an array of type corresponding to
+ PROTOTYPE, and `#f' if not.
+
+ - Function: make-uniform-array PROTOTYPE BOUND1 BOUND2 ...
+ Creates and returns a uniform array of type corresponding to
+ PROTOTYPE that has as many dimensions as there are BOUNDs.
+
+ - Function: array-prototype ARRAY
+ Returns an object that would produce an array of the same type as
+ ARRAY, if used as the PROTOTYPE for `make-uniform-array'.
+
+ - Function: list->uniform-array RANK PROT LST
+ - Function: list->uniform-vector PROT LST
+ Returns a uniform array of the type indicated by prototype PROT
+ with elements the same as those of LST. Elements must be of the
+ appropriate type, no coercions are done.
+
+ In, for example, the case of a rank-2 array, LST must be a list of
+ lists, all of the same length. The length of LST will be the
+ first dimension of the result array, and the length of each
+ element the second dimension.
+
+ If RANK is zero, LST, which need not be a list, is the single
+ element of the returned array.
+
+ - Function: uniform-vector-fill! UVE FILL
+ Stores FILL in every element of UVE. The value returned is
+ unspecified.
+
+ - Function: uniform-vector-length UVE
+ Returns the number of elements in UVE.
+
+ - Function: dimensions->uniform-array DIMS PROTOTYPE FILL
+ - Function: dimensions->uniform-array DIMS PROTOTYPE
+ - Function: make-uniform-vector LENGTH PROTOTYPE FILL
+ - Function: make-uniform-vector LENGTH PROTOTYPE
+ Creates and returns a uniform array or vector of type
+ corresponding to PROTOTYPE with dimensions DIMS or length LENGTH.
+ If the FILL argument is supplied, the returned array is filled with
+ this value.
+
+ - Function: uniform-array-read! URA
+ - Function: uniform-array-read! URA PORT
+ - Function: uniform-vector-read! UVE
+ - Function: uniform-vector-read! UVE PORT
+ Attempts to read all elements of URA, in lexicographic order, as
+ binary objects from PORT. If an end of file is encountered during
+ uniform-array-read! the objects up to that point only are put into
+ URA (starting at the beginning) and the remainder of the array is
+ unchanged.
+
+ `uniform-array-read!' returns the number of objects read. PORT
+ may be omitted, in which case it defaults to the value returned by
+ `(current-input-port)'.
+
+ - Function: uniform-array-write URA
+ - Function: uniform-array-write URA PORT
+ - Function: uniform-vector-write UVE
+ - Function: uniform-vector-write UVE PORT
+ Writes all elements of URA as binary objects to PORT. The number
+ of of objects actually written is returned. PORT may be omitted,
+ in which case it defaults to the value returned by
+ `(current-output-port)'.
+
+ - Function: logaref ARRAY INDEX1 INDEX2 ...
+ If an INDEX is provided for each dimension of ARRAY returns the
+ INDEX1, INDEX2, ...'th element of ARRAY. If one more INDEX is
+ provided, then the last index specifies bit position of the
+ twos-complement representation of the array element indexed by the
+ other INDEXs returning `#t' if the bit is 1, and `#f' if 0. It is
+ an error if this element is not an exact integer.
+
+ (logaref '#(#b1101 #b0010) 0) => #b1101
+ (logaref '#(#b1101 #b0010) 0 1) => #f
+ (logaref '#2((#b1101 #b0010)) 0 0) => #b1101
+
+ - Function: logaset! ARRAY VAL INDEX1 INDEX2 ...
+ If an INDEX is provided for each dimension of ARRAY sets the
+ INDEX1, INDEX2, ...'th element of ARRAY to VAL. If one more INDEX
+ is provided, then the last index specifies bit position of the
+ twos-complement representation of an exact integer array element,
+ setting the bit to 1 if VAL is `#t' and to 0 if VAL is `#f'. In
+ this case it is an error if the array element is not an exact
+ integer or if VAL is not boolean.
+
+
+File: scm.info, Node: Bit Vectors, Prev: Uniform Array, Up: Arrays
+
+Bit Vectors
+-----------
+
+Bit vectors can be written and read as a sequence of `0's and `1's
+prefixed by `#*'.
+
+ #At(#f #f #f #t #f #t #f) => #*0001010
+
+Some of these operations will eventually be generalized to other
+uniform-arrays.
+
+ - Function: bit-count BOOL BV
+ Returns the number occurrences of BOOL in BV.
+
+ - Function: bit-position BOOL BV K
+ Returns the minimum index of an occurrence of BOOL in BV which is
+ at least K. If no BOOL occurs within the specified range `#f' is
+ returned.
+
+ - Function: bit-invert! BV
+ Modifies BV by replacing each element with its negation.
+
+ - Function: bit-set*! BV UVE BOOL
+ If uve is a bit-vector BV and uve must be of the same length. If
+ BOOL is `#t', uve is OR'ed into BV; If BOOL is `#f', the inversion
+ of uve is AND'ed into BV.
+
+ If uve is a unsigned integer vector all the elements of uve must be
+ between 0 and the `LENGTH' of BV. The bits of BV corresponding to
+ the indexes in uve are set to BOOL.
+
+ The return value is unspecified.
+
+ - Function: bit-count* BV UVE BOOL
+ Returns
+ (bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t).
+ BV is not modified.
+
+
+File: scm.info, Node: I/O-Extensions, Next: Posix Extensions, Prev: Arrays, Up: Packages
+
+I/O-Extensions
+==============
+
+If `'i/o-extensions' is provided (by linking in `ioext.o'), *Note Line
+I/O: (slib)Line I/O, and the following functions are defined:
+
+ - Function: stat <PORT-OR-STRING>
+ Returns a vector of integers describing the argument. The argument
+ can be either a string or an open input port. If the argument is an
+ open port then the returned vector describes the file to which the
+ port is opened; If the argument is a string then the returned
+ vector describes the file named by that string. If there exists
+ no file with the name string, or if the file cannot be accessed
+ `#f' is returned. The elements of the returned vector are as
+ follows:
+
+ 0 st_dev
+ ID of device containing a directory entry for this file
+
+ 1 st_ino
+ Inode number
+
+ 2 st_mode
+ File type, attributes, and access control summary
+
+ 3 st_nlink
+ Number of links
+
+ 4 st_uid
+ User ID of file owner
+
+ 5 st_gid
+ Group ID of file group
+
+ 6 st_rdev
+ Device ID; this entry defined only for char or blk spec files
+
+ 7 st_size
+ File size (bytes)
+
+ 8 st_atime
+ Time of last access
+
+ 9 st_mtime
+ Last modification time
+
+ 10 st_ctime
+ Last file status change time
+
+ - Function: getpid
+ Returns the process ID of the current process.
+
+ - Function: file-position PORT
+ Returns the current position of the character in PORT which will
+ next be read or written. If PORT is not open to a file the result
+ is unspecified.
+
+ - Function: file-set-position PORT INTEGER
+ Sets the current position in PORT which will next be read or
+ written. If PORT is not open to a file the action of
+ `file-set-position' is unspecified. The result of
+ `file-set-position' is unspecified.
+
+ - Function: reopen-file FILENAME MODES PORT
+ Closes port PORT and reopens it with FILENAME and MODES.
+ `reopen-file' returns `#t' if successful, `#f' if not.
+
+ - Function: duplicate-port PORT MODES
+ Creates and returns a "duplicate" port from PORT. Duplicate
+ *unbuffered* ports share one file position. MODES are as for
+ *Note open-file: Files and Ports.
+
+ - Function: redirect-port! FROM-PORT TO-PORT
+ Closes TO-PORT and makes TO-PORT be a duplicate of FROM-PORT.
+ `redirect-port!' returns TO-PORT if successful, `#f' if not. If
+ unsuccessful, TO-PORT is not closed.
+
+ - Function: opendir DIRNAME
+ Returns a "directory" object corresponding to the file system
+ directory named DIRNAME. If unsuccessful, returns `#f'.
+
+ - Function: readdir DIR
+ Returns the string name of the next entry from the directory DIR.
+ If there are no more entries in the directory, `readdir' returns a
+ `#f'.
+
+ - Function: rewinddir DIR
+ Reinitializes DIR so that the next call to `readdir' with DIR will
+ return the first entry in the directory again.
+
+ - Function: closedir DIR
+ Closes DIR and returns `#t'. If DIR is already closed,,
+ `closedir' returns a `#f'.
+
+ - Function: directory-for-each PROC DIRECTORY
+ The LISTs must be lists, and PROC must be a procedure taking one
+ argument. `Directory-For-Each' applies PROC to the (string) name
+ of each file in DIRECTORY. The dynamic order in which PROC is
+ applied to the elements of the LISTs is unspecified. The value
+ returned by `directory-for-each' is unspecified.
+
+ - Function: directory-for-each PROC DIRECTORY PRED
+ Applies PROC only to those filenames for which the procedure PRED
+ returns a non-false value.
+
+ - Function: directory-for-each PROC DIRECTORY MATCH
+ Applies PROC only to those filenames for which `(filename:match??
+ MATCH)' would return a non-false value (*note Filenames:
+ (slib)Filenames.).
+
+ (require 'directory-for-each)
+ (directory-for-each print "." "[A-Z]*.scm")
+ -|
+ "Init.scm"
+ "Iedline.scm"
+ "Link.scm"
+ "Macro.scm"
+ "Transcen.scm"
+ "Init5d2.scm" |
+
+ - Function: mkdir PATH MODE
+ The `mkdir' function creates a new, empty directory whose name is
+ PATH. The integer argument MODE specifies the file permissions
+ for the new directory. *Note The Mode Bits for Access Permission:
+ (libc)The Mode Bits for Access Permission, for more information
+ about this.
+
+ `mkdir' returns if successful, `#f' if not.
+
+ - Function: rmdir PATH
+ The `rmdir' function deletes the directory PATH. The directory
+ must be empty before it can be removed. `rmdir' returns if
+ successful, `#f' if not.
+
+ - Function: chdir FILENAME
+ Changes the current directory to FILENAME. If FILENAME does not
+ exist or is not a directory, `#f' is returned. Otherwise, `#t' is
+ returned.
+
+ - Function: getcwd
+ The function `getcwd' returns a string containing the absolute file
+ name representing the current working directory. If this string
+ cannot be obtained, `#f' is returned.
+
+ - Function: rename-file OLDFILENAME NEWFILENAME
+ Renames the file specified by OLDFILENAME to NEWFILENAME. If the
+ renaming is successful, `#t' is returned. Otherwise, `#f' is
+ returned.
+
+ - Function: chmod FILE MODE
+ The function `chmod' sets the access permission bits for the file
+ named by FILE to MODE. The FILE argument may be a string
+ containing the filename or a port open to the file.
+
+ `chmod' returns if successful, `#f' if not.
+
+ - Function: utime PATHNAME ACCTIME MODTIME
+ Sets the file times associated with the file named PATHNAME to
+ have access time ACCTIME and modification time MODTIME. `utime'
+ returns if successful, `#f' if not.
+
+ - Function: umask MODE
+ The function `umask' sets the file creation mask of the current
+ process to MASK, and returns the previous value of the file
+ creation mask.
+
+ - Function: fileno PORT
+ Returns the integer file descriptor associated with the port PORT.
+ If an error is detected, `#f' is returned.
+
+ - Function: access PATHNAME HOW
+ Returns `#t' if the file named by PATHNAME can be accessed in the
+ way specified by the HOW argument. The HOW argument can be the
+ `logior' of the flags:
+
+ 0. File-exists?
+
+ 1. File-is-executable?
+
+ 2. File-is-writable?
+
+ 4. File-is-readable?
+
+ Or the HOW argument can be a string of 0 to 3 of the following
+ characters in any order. The test performed is the `and' of the
+ associated tests and `file-exists?'.
+
+ <x>
+ File-is-executable?
+
+ <w>
+ File-is-writable?
+
+ <r>
+ File-is-readable?
+
+ - Function: execl COMMAND ARG0 ...
+ - Function: execlp COMMAND ARG0 ...
+ Transfers control to program COMMAND called with arguments ARG0
+ .... For `execl', COMMAND must be an exact pathname of an
+ executable file. `execlp' searches for COMMAND in the list of
+ directories specified by the environment variable PATH. The
+ convention is that ARG0 is the same name as COMMAND.
+
+ If successful, this procedure does not return. Otherwise an error
+ message is printed and the integer `errno' is returned.
+
+ - Function: execv COMMAND ARGLIST
+ - Function: execvp COMMAND ARGLIST
+ Like `execl' and `execlp' except that the set of arguments to
+ COMMAND is ARGLIST.
+
+ - Function: putenv STRING
+ adds or removes definitions from the "environment". If the STRING
+ is of the form `NAME=VALUE', the definition is added to the
+ environment. Otherwise, the STRING is interpreted as the name of
+ an environment variable, and any definition for this variable in
+ the environment is removed.
+
+ Names of environment variables are case-sensitive and must not
+ contain the character `='. System-defined environment variables
+ are invariably uppercase.
+
+ `Putenv' is used to set up the environment before calls to
+ `execl', `execlp', `execv', `execvp', `system', or `open-pipe'
+ (*note open-pipe: Posix Extensions.).
+
+ To access environment variables, use `getenv' (*note getenv:
+ (slib)System Interface.).
+
+
+File: scm.info, Node: Posix Extensions, Next: Regular Expression Pattern Matching, Prev: I/O-Extensions, Up: Packages
+
+Posix Extensions
+================
+
+If `'posix' is provided (by linking in `posix.o'), the following
+functions are defined:
+
+ - Function: open-pipe STRING MODES
+ If the string MODES contains an <r>, returns an input port capable
+ of delivering characters from the standard output of the system
+ command STRING. Otherwise, returns an output port capable of
+ receiving characters which become the standard input of the system
+ command STRING. If a pipe cannot be created `#f' is returned.
+
+ - Function: open-input-pipe STRING
+ Returns an input port capable of delivering characters from the
+ standard output of the system command STRING. If a pipe cannot be
+ created `#f' is returned.
+
+ - Function: open-output-pipe STRING
+ Returns an output port capable of receiving characters which become
+ the standard input of the system command STRING. If a pipe cannot
+ be created `#f' is returned.
+
+ - Function: close-port PIPE
+ Closes the PIPE, rendering it incapable of delivering or accepting
+ characters. This routine has no effect if the pipe has already
+ been closed. The value returned is unspecified.
+
+ - Function: pipe
+ Returns `(cons RD WD)' where RD and WD are the read and write
+ (port) ends of a "pipe" respectively.
+
+ - Function: fork
+ Creates a copy of the process calling `fork'. Both processes
+ return from `fork', but the calling ("parent") process's `fork'
+ returns the "child" process's ID whereas the child process's
+ `fork' returns 0.
+
+For a discussion of "ID"s *Note Process Persona: (GNU C Library)Process
+Persona.
+
+ - Function: getppid
+ Returns the process ID of the parent of the current process. For
+ a process's own ID *Note getpid: I/O-Extensions.
+
+ - Function: getuid
+ Returns the real user ID of this process.
+
+ - Function: getgid
+ Returns the real group ID of this process.
+
+ - Function: getegid
+ Returns the effective group ID of this process.
+
+ - Function: geteuid
+ Returns the effective user ID of this process.
+
+ - Function: setuid ID
+ Sets the real user ID of this process to ID. Returns `#t' if
+ successful, `#f' if not.
+
+ - Function: setgid ID
+ Sets the real group ID of this process to ID. Returns `#t' if
+ successful, `#f' if not.
+
+ - Function: setegid ID
+ Sets the effective group ID of this process to ID. Returns `#t'
+ if successful, `#f' if not.
+
+ - Function: seteuid ID
+ Sets the effective user ID of this process to ID. Returns `#t' if
+ successful, `#f' if not.
+
+ - Function: kill PID SIG
+ The `kill' function sends the signal SIGNUM to the process or
+ process group specified by PID. Besides the signals listed in
+ *Note Standard Signals: (libc)Standard Signals, SIGNUM can also
+ have a value of zero to check the validity of the PID.
+
+ The PID specifies the process or process group to receive the
+ signal:
+
+ > 0
+ The process whose identifier is PID.
+
+ 0
+ All processes in the same process group as the sender. The
+ sender itself does not receive the signal.
+
+ -1
+ If the process is privileged, send the signal to all
+ processes except for some special system processes.
+ Otherwise, send the signal to all processes with the same
+ effective user ID.
+
+ < -1
+ The process group whose identifier is `(abs PID)'.
+
+ A process can send a signal to itself with `(kill (getpid)
+ SIGNUM)'. If `kill' is used by a process to send a signal to
+ itself, and the signal is not blocked, then `kill' delivers at
+ least one signal (which might be some other pending unblocked
+ signal instead of the signal SIGNUM) to that process before it
+ returns.
+
+ The return value from `kill' is zero if the signal can be sent
+ successfully. Otherwise, no signal is sent, and a value of `-1' is
+ returned. If PID specifies sending a signal to several processes,
+ `kill' succeeds if it can send the signal to at least one of them.
+ There's no way you can tell which of the processes got the signal
+ or whether all of them did.
+
+ - Function: waitpid PID OPTIONS
+ The `waitpid' function suspends execution of the current process
+ until a child as specified by the PID argument has exited, or
+ until a signal is delivered whose action is to terminate the
+ current process or to call a signal handling function. If a child
+ as requested by PID has already exited by the time of the call (a
+ so-called "zombie" process), the function returns immediately.
+ Any system resources used by the child are freed.
+
+ The value of PID can be:
+
+ < -1
+ which means to wait for any child process whose process group
+ ID is equal to the absolute value of PID.
+
+ -1
+ which means to wait for any child process; this is the same
+ behaviour which wait exhibits.
+
+ 0
+ which means to wait for any child process whose process group
+ ID is equal to that of the calling process.
+
+ > 0
+ which means to wait for the child whose process ID is equal
+ to the value of PID.
+
+ The value of OPTIONS is one of the following:
+
+ 0. Nothing special.
+
+ 1. (`WNOHANG') which means to return immediately if no child is
+ there to be waited for.
+
+ 2. (`WUNTRACED') which means to also return for children which
+ are stopped, and whose status has not been reported.
+
+ 3. Which means both of the above.
+
+ The return value is normally the process ID of the child process
+ whose status is reported. If the `WNOHANG' option was specified
+ and no child process is waiting to be noticed, the value is zero.
+ A value of `#f' is returned in case of error and `errno' is set.
+ For information about the `errno' codes *Note Process Completion:
+ (GNU C Library)Process Completion.
+
+ - Function: uname
+ You can use the `uname' procedure to find out some information
+ about the type of computer your program is running on.
+
+ Returns a vector of strings. These strings are:
+
+ 0. The name of the operating system in use.
+
+ 1. The network name of this particular computer.
+
+ 2. The current release level of the operating system
+ implementation.
+
+ 3. The current version level within the release of the operating
+ system.
+
+ 4. Description of the type of hardware that is in use.
+
+ Some examples are `"i386-ANYTHING"', `"m68k-hp"',
+ `"sparc-sun"', `"m68k-sun"', `"m68k-sony"' and `"mips-dec"'.
+
+ - Function: getpw NAME
+ - Function: getpw UID
+ - Function: getpw
+ Returns a vector of information for the entry for `NAME', `UID',
+ or the next entry if no argument is given. The information is:
+
+ 0. The user's login name.
+
+ 1. The encrypted password string.
+
+ 2. The user ID number.
+
+ 3. The user's default group ID number.
+
+ 4. A string typically containing the user's real name, and
+ possibly other information such as a phone number.
+
+ 5. The user's home directory, initial working directory, or
+ `#f', in which case the interpretation is system-dependent.
+
+ 6. The user's default shell, the initial program run when the
+ user logs in, or `#f', indicating that the system default
+ should be used.
+
+ - Function: setpwent #T
+ Rewinds the pw entry table back to the begining.
+
+ - Function: setpwent #F
+ - Function: setpwent
+ Closes the pw table.
+
+ - Function: getgr NAME
+ - Function: getgr UID
+ - Function: getgr
+ Returns a vector of information for the entry for `NAME', `UID',
+ or the next entry if no argument is given. The information is:
+
+ 0. The name of the group.
+
+ 1. The encrypted password string.
+
+ 2. The group ID number.
+
+ 3. A list of (string) names of users in the group.
+
+ - Function: setgrent #T
+ Rewinds the group entry table back to the begining.
+
+ - Function: setgrent #F
+ - Function: setgrent
+ Closes the group table.
+
+ - Function: getgroups
+ Returns a vector of all the supplementary group IDs of the process.
+
+ - Function: link OLDNAME NEWNAME
+ The `link' function makes a new link to the existing file named by
+ OLDNAME, under the new name NEWNAME.
+
+ `link' returns a value of `#t' if it is successful and `#f' on
+ failure.
+
+ - Function: chown FILENAME OWNER GROUP
+ The `chown' function changes the owner of the file FILENAME to
+ OWNER, and its group owner to GROUP.
+
+ `chown' returns a value of `#t' if it is successful and `#f' on
+ failure.
+
+ - Function: ttyname PORT
+ If port PORT is associated with a terminal device, returns a
+ string containing the file name of termainal device; otherwise
+ `#f'.
+
+Unix Extensions
+===============
+
+If `'unix' is provided (by linking in `unix.o'), the following
+functions are defined:
+
+These "priveledged" and symbolic link functions are not in Posix:
+
+ - Function: symlink OLDNAME NEWNAME
+ The `symlink' function makes a symbolic link to OLDNAME named
+ NEWNAME.
+
+ `symlink' returns a value of `#t' if it is successful and `#f' on
+ failure.
+
+ - Function: readlink FILENAME
+ Returns the value of the symbolic link FILENAME or `#f' for
+ failure.
+
+ - Function: lstat FILENAME
+ The `lstat' function is like `stat', except that it does not
+ follow symbolic links. If FILENAME is the name of a symbolic
+ link, `lstat' returns information about the link itself; otherwise,
+ `lstat' works like `stat'. *Note I/O-Extensions::.
+
+ - Function: nice INCREMENT
+ Increment the priority of the current process by INCREMENT.
+ `chown' returns a value of `#t' if it is successful and `#f' on
+ failure.
+
+ - Function: acct FILENAME
+ When called with the name of an exisitng file as argument,
+ accounting is turned on, records for each terminating pro-cess are
+ appended to FILENAME as it terminates. An argument of `#f' causes
+ accounting to be turned off.
+
+ `acct' returns a value of `#t' if it is successful and `#f' on
+ failure.
+
+ - Function: mknod FILENAME MODE DEV
+ The `mknod' function makes a special file with name FILENAME and
+ modes MODE for device number DEV.
+
+ `mknod' returns a value of `#t' if it is successful and `#f' on
+ failure.
+
+ - Function: sync
+ `sync' first commits inodes to buffers, and then buffers to disk.
+ sync() only schedules the writes, so it may return before the
+ actual writing is done. The value returned is unspecified.
+
+
+File: scm.info, Node: Regular Expression Pattern Matching, Next: Line Editing, Prev: Posix Extensions, Up: Packages
+
+Regular Expression Pattern Matching
+===================================
+
+These functions are defined in `rgx.c' using a POSIX or GNU "regex"
+library. If your computer does not support regex, a package is
+available via ftp from `ftp.gnu.org:/pub/gnu/regex-0.12.tar.gz'. For a
+description of regular expressions, *Note syntax: (regex)syntax.
+
+ - Function: regcomp PATTERN [FLAGS]
+ Compile a "regular expression". Return a compiled regular
+ expression, or an integer error code suitable as an argument to
+ `regerror'.
+
+ FLAGS in `regcomp' is a string of option letters used to control
+ the compilation of the regular expression. The letters may consist
+ of:
+
+ `n'
+ newlines won't be matched by `.' or hat lists; ( `[^...]' )
+
+ `i'
+ ignore case.
+ only when compiled with _GNU_SOURCE:
+ `0'
+ allows dot to match a null character.
+
+ `f'
+ enable GNU fastmaps.
+
+ - Function: regerror ERRNO
+ Returns a string describing the integer ERRNO returned when
+ `regcomp' fails.
+
+ - Function: regexec RE STRING
+ Returns `#f' or a vector of integers. These integers are in
+ doublets. The first of each doublet is the index of STRING of the
+ start of the matching expression or sub-expression (delimited by
+ parentheses in the pattern). The last of each doublet is index of
+ STRING of the end of that expression. `#f' is returned if the
+ string does not match.
+
+ - Function: regmatch? RE STRING
+ Returns `#t' if the PATTERN such that REGEXP = (regcomp PATTERN)
+ matches STRING as a POSIX extended regular expressions. Returns
+ `#f' otherwise.
+
+ - Function: regsearch RE STRING [START [LEN]]
+ - Function: regsearchv RE STRING [START [LEN]]
+ - Function: regmatch RE STRING [START [LEN]]
+ - Function: regmatchv RE STRING [START [LEN]]
+ `Regsearch' searches for the pattern within the string.
+
+ `Regmatch' anchors the pattern and begins matching it against
+ string.
+
+ `Regsearch' returns the character position where RE starts, or
+ `#f' if not found.
+
+ `Regmatch' returns the number of characters matched, `#f' if not
+ matched.
+
+ `Regsearchv' and `regmatchv' return the match vector is returned
+ if RE is found, `#f' otherwise.
+
+ RE
+ may be either:
+ 1. a compiled regular expression returned by `regcomp';
+
+ 2. a string representing a regular expression;
+
+ 3. a list of a string and a set of option letters.
+
+ STRING
+ The string to be operated upon.
+
+ START
+ The character position at which to begin the search or match.
+ If absent, the default is zero.
+
+ *Compiled _GNU_SOURCE and using GNU libregex only:*
+ When searching, if START is negative, the absolute value of
+ START will be used as the start location and reverse searching
+ will be performed.
+
+ LEN
+ The search is allowed to examine only the first LEN
+ characters of STRING. If absent, the entire string may be
+ examined.
+
+ - Function: string-split RE STRING
+ - Function: string-splitv RE STRING
+ `String-split' splits a string into substrings that are separated
+ by RE, returning a vector of substrings.
+
+ `String-splitv' returns a vector of string positions that indicate
+ where the substrings are located.
+
+ - Function: string-edit RE EDIT-SPEC STRING [COUNT]
+ Returns the edited string.
+
+ EDIT-SPEC
+ Is a string used to replace occurances of RE. Backquoted
+ integers in the range of 1-9 may be used to insert
+ subexpressions in RE, as in `sed'.
+
+ COUNT
+ The number of substitutions for `string-edit' to perform. If
+ `#t', all occurances of RE will be replaced. The default is
+ to perform one substitution.
+
+
+File: scm.info, Node: Line Editing, Next: Curses, Prev: Regular Expression Pattern Matching, Up: Packages
+
+Line Editing
+============
+
+These procedures provide input line editing and recall.
+
+These functions are defined in `edline.c' and `Iedline.scm' using the
+"editline" or GNU "readline" (*note Overview: (readline)Top.) libraries
+available from:
+
+ * `ftp.sys.toronto.edu:/pub/rc/editline.shar'
+
+ * `ftp.gnu.org:/pub/gnu/readline-2.0.tar.gz'
+
+When `Iedline.scm' is loaded, if the current input port is the default
+input port and the environment variable EMACS is not defined,
+line-editing mode will be entered.
+
+ - Function: default-input-port
+ Returns the initial `current-input-port' SCM was invoked with
+ (stdin).
+
+ - Function: default-output-port
+ Returns the initial `current-output-port' SCM was invoked with
+ (stdout).
+
+ - Function: make-edited-line-port
+ Returns an input/output port that allows command line editing and
+ retrieval of history.
+
+ - Function: line-editing
+ Returns the current edited line port or `#f'.
+
+ - Function: line-editing BOOL
+ If BOOL is false, exits line-editing mode and returns the previous
+ value of `(line-editing)'. If BOOL is true, sets the current
+ input and output ports to an edited line port and returns the
+ previous value of `(line-editing)'.
+
+
+File: scm.info, Node: Curses, Next: Sockets, Prev: Line Editing, Up: Packages
+
+Curses
+======
+
+These functions are defined in `crs.c' using the "curses" library.
+Unless otherwise noted these routines return `#t' for successful
+completion and `#f' for failure.
+
+ - Function: initscr
+ Returns a port for a full screen window. This routine must be
+ called to initialize curses.
+
+ - Function: endwin
+ A program should call `endwin' before exiting or escaping from
+ curses mode temporarily, to do a system call, for example. This
+ routine will restore termio modes, move the cursor to the lower
+ left corner of the screen and reset the terminal into the proper
+ non-visual mode. To resume after a temporary escape, call *Note
+ refresh: Window Manipulation.
+
+* Menu:
+
+* Output Options Setting::
+* Terminal Mode Setting::
+* Window Manipulation::
+* Output::
+* Input::
+* Curses Miscellany::
+
+
+File: scm.info, Node: Output Options Setting, Next: Terminal Mode Setting, Prev: Curses, Up: Curses
+
+Output Options Setting
+----------------------
+
+These routines set options within curses that deal with output. All
+options are initially `#f', unless otherwise stated. It is not
+necessary to turn these options off before calling `endwin'.
+
+ - Function: clearok WIN BF
+ If enabled (BF is `#t'), the next call to `force-output' or
+ `refresh' with WIN will clear the screen completely and redraw the
+ entire screen from scratch. This is useful when the contents of
+ the screen are uncertain, or in some cases for a more pleasing
+ visual effect.
+
+ - Function: idlok WIN BF
+ If enabled (BF is `#t'), curses will consider using the hardware
+ "insert/delete-line" feature of terminals so equipped. If
+ disabled (BF is `#f'), curses will very seldom use this feature.
+ The "insert/delete-character" feature is always considered. This
+ option should be enabled only if your application needs
+ "insert/delete-line", for example, for a screen editor. It is
+ disabled by default because
+
+ "insert/delete-line" tends to be visually annoying when used in
+ applications where it is not really needed. If
+ "insert/delete-line" cannot be used, curses will redraw the
+ changed portions of all lines.
+
+ - Function: leaveok WIN BF
+ Normally, the hardware cursor is left at the location of the window
+ cursor being refreshed. This option allows the cursor to be left
+ wherever the update happens to leave it. It is useful for
+ applications where the cursor is not used, since it reduces the
+ need for cursor motions. If possible, the cursor is made
+ invisible when this option is enabled.
+
+ - Function: scrollok WIN BF
+ This option controls what happens when the cursor of window WIN is
+ moved off the edge of the window or scrolling region, either from a
+ newline on the bottom line, or typing the last character of the
+ last line. If disabled (BF is `#f'), the cursor is left on the
+ bottom line at the location where the offending character was
+ entered. If enabled (BF is `#t'), `force-output' is called on the
+ window WIN, and then the physical terminal and window WIN are
+ scrolled up one line.
+
+ *Note:* in order to get the physical scrolling effect on the
+ terminal, it is also necessary to call `idlok'.
+
+ - Function: nodelay WIN BF
+ This option causes wgetch to be a non-blocking call. If no input
+ is ready, wgetch will return an eof-object. If disabled, wgetch
+ will hang until a key is pressed.
+
+
+File: scm.info, Node: Terminal Mode Setting, Next: Window Manipulation, Prev: Output Options Setting, Up: Curses
+
+Terminal Mode Setting
+---------------------
+
+These routines set options within curses that deal with input. The
+options involve using ioctl(2) and therefore interact with curses
+routines. It is not necessary to turn these options off before calling
+`endwin'. The routines in this section all return an unspecified value.
+
+ - Function: cbreak
+ - Function: nocbreak
+ These two routines put the terminal into and out of `CBREAK' mode,
+ respectively. In `CBREAK' mode, characters typed by the user are
+ immediately available to the program and erase/kill character
+ processing is not performed. When in `NOCBREAK' mode, the tty
+ driver will buffer characters typed until a <LFD> or <RET> is
+ typed. Interrupt and flowcontrol characters are unaffected by
+ this mode. Initially the terminal may or may not be in `CBREAK'
+ mode, as it is inherited, therefore, a program should call
+ `cbreak' or `nocbreak' explicitly. Most interactive programs
+ using curses will set `CBREAK' mode.
+
+ *Note:* `cbreak' overrides `raw'. For a discussion of how these
+ routines interact with `echo' and `noecho' *Note read-char: Input.
+
+ - Function: raw
+ - Function: noraw
+ The terminal is placed into or out of `RAW' mode. `RAW' mode is
+ similar to `CBREAK' mode, in that characters typed are immediately
+ passed through to the user program. The differences are that in
+ `RAW' mode, the interrupt, quit, suspend, and flow control
+ characters are passed through uninterpreted, instead of generating
+ a signal. `RAW' mode also causes 8-bit input and output. The
+ behavior of the `BREAK' key depends on other bits in the terminal
+ driver that are not set by curses.
+
+ - Function: echo
+ - Function: noecho
+ These routines control whether characters typed by the user are
+ echoed by `read-char' as they are typed. Echoing by the tty
+ driver is always disabled, but initially `read-char' is in `ECHO'
+ mode, so characters typed are echoed. Authors of most interactive
+ programs prefer to do their own echoing in a controlled area of
+ the screen, or not to echo at all, so they disable echoing by
+ calling `noecho'. For a discussion of how these routines interact
+ with `echo' and `noecho' *Note read-char: Input.
+
+ - Function: nl
+ - Function: nonl
+ These routines control whether <LFD> is translated into <RET> and
+ `LFD' on output, and whether <RET> is translated into <LFD> on
+ input. Initially, the translations do occur. By disabling these
+ translations using `nonl', curses is able to make better use of
+ the linefeed capability, resulting in faster cursor motion.
+
+ - Function: resetty
+ - Function: savetty
+ These routines save and restore the state of the terminal modes.
+ `savetty' saves the current state of the terminal in a buffer and
+ `resetty' restores the state to what it was at the last call to
+ `savetty'.
+
+
+File: scm.info, Node: Window Manipulation, Next: Output, Prev: Terminal Mode Setting, Up: Curses
+
+Window Manipulation
+-------------------
+
+ - Function: newwin NLINES NCOLS BEGY BEGX
+ Create and return a new window with the given number of lines (or
+ rows), NLINES, and columns, NCOLS. The upper left corner of the
+ window is at line BEGY, column BEGX. If either NLINES or NCOLS is
+ 0, they will be set to the value of `LINES'-BEGY and `COLS'-BEGX.
+ A new full-screen window is created by calling `newwin(0,0,0,0)'.
+
+ - Function: subwin ORIG NLINES NCOLS BEGY BEGX
+ Create and return a pointer to a new window with the given number
+ of lines (or rows), NLINES, and columns, NCOLS. The window is at
+ position (BEGY, BEGX) on the screen. This position is relative to
+ the screen, and not to the window ORIG. The window is made in the
+ middle of the window ORIG, so that changes made to one window will
+ affect both windows. When using this routine, often it will be
+ necessary to call `touchwin' or `touchline' on ORIG before calling
+ `force-output'.
+
+ - Function: close-port WIN
+ Deletes the window WIN, freeing up all memory associated with it.
+ In the case of sub-windows, they should be deleted before the main
+ window WIN.
+
+ - Function: refresh
+ - Function: force-output WIN
+ These routines are called to write output to the terminal, as most
+ other routines merely manipulate data structures. `force-output'
+ copies the window WIN to the physical terminal screen, taking into
+ account what is already there in order to minimize the amount of
+ information that's sent to the terminal (called optimization).
+ Unless `leaveok' has been enabled, the physical cursor of the
+ terminal is left at the location of window WIN's cursor. With
+ `refresh', the number of characters output to the terminal is
+ returned.
+
+ - Function: mvwin WIN Y X
+ Move the window WIN so that the upper left corner will be at
+ position (Y, X). If the move would cause the window WIN to be off
+ the screen, it is an error and the window WIN is not moved.
+
+ - Function: overlay SRCWIN DSTWIN
+ - Function: overwrite SRCWIN DSTWIN
+ These routines overlay SRCWIN on top of DSTWIN; that is, all text
+ in SRCWIN is copied into DSTWIN. SRCWIN and DSTWIN need not be
+ the same size; only text where the two windows overlap is copied.
+ The difference is that `overlay' is non-destructive (blanks are
+ not copied), while `overwrite' is destructive.
+
+ - Function: touchwin WIN
+ - Function: touchline WIN START COUNT
+ Throw away all optimization information about which parts of the
+ window WIN have been touched, by pretending that the entire window
+ WIN has been drawn on. This is sometimes necessary when using
+ overlapping windows, since a change to one window will affect the
+ other window, but the records of which lines have been changed in
+ the other window will not reflect the change. `touchline' only
+ pretends that COUNT lines have been changed, beginning with line
+ START.
+
+ - Function: wmove WIN Y X
+ The cursor associated with the window WIN is moved to line (row) Y,
+ column X. This does not move the physical cursor of the terminal
+ until `refresh' (or `force-output') is called. The position
+ specified is relative to the upper left corner of the window WIN,
+ which is (0, 0).
+
+
+File: scm.info, Node: Output, Next: Input, Prev: Window Manipulation, Up: Curses
+
+Output
+------
+
+These routines are used to "draw" text on windows
+
+ - Function: display CH WIN
+ - Function: display STR WIN
+ - Function: wadd WIN CH
+ - Function: wadd WIN STR
+ The character CH or characters in STR are put into the window WIN
+ at the current cursor position of the window and the position of
+ WIN's cursor is advanced. At the right margin, an automatic
+ newline is performed. At the bottom of the scrolling region, if
+ scrollok is enabled, the scrolling region will be scrolled up one
+ line.
+
+ If CH is a <TAB>, <LFD>, or backspace, the cursor will be moved
+ appropriately within the window WIN. A <LFD> also does a
+ `wclrtoeol' before moving. <TAB> characters are considered to be
+ at every eighth column. If CH is another control character, it
+ will be drawn in the `C-x' notation. (Calling `winch' after
+ adding a control character will not return the control character,
+ but instead will return the representation of the control
+ character.)
+
+ Video attributes can be combined with a character by or-ing them
+ into the parameter. This will result in these attributes also
+ being set. The intent here is that text, including attributes,
+ can be copied from one place to another using inch and display.
+ See `standout', below.
+
+ *Note:* For `wadd' CH can be an integer and will insert the
+ character of the corresponding value.
+
+ - Function: werase WIN
+ This routine copies blanks to every position in the window WIN.
+
+ - Function: wclear WIN
+ This routine is like `werase', but it also calls *Note clearok:
+ Output Options Setting, arranging that the screen will be cleared
+ completely on the next call to `refresh' or `force-output' for
+ window WIN, and repainted from scratch.
+
+ - Function: wclrtobot WIN
+ All lines below the cursor in window WIN are erased. Also, the
+ current line to the right of the cursor, inclusive, is erased.
+
+ - Function: wclrtoeol WIN
+ The current line to the right of the cursor, inclusive, is erased.
+
+ - Function: wdelch WIN
+ The character under the cursor in the window WIN is deleted. All
+ characters to the right on the same line are moved to the left one
+ position and the last character on the line is filled with a
+ blank. The cursor position does not change. This does not imply
+ use of the hardware "delete-character" feature.
+
+ - Function: wdeleteln WIN
+ The line under the cursor in the window WIN is deleted. All lines
+ below the current line are moved up one line. The bottom line WIN
+ is cleared. The cursor position does not change. This does not
+ imply use of the hardware "deleteline" feature.
+
+ - Function: winsch WIN CH
+ The character CH is inserted before the character under the
+ cursor. All characters to the right are moved one <SPC> to the
+ right, possibly losing the rightmost character of the line. The
+ cursor position does not change . This does not imply use of the
+ hardware "insertcharacter" feature.
+
+ - Function: winsertln WIN
+ A blank line is inserted above the current line and the bottom
+ line is lost. This does not imply use of the hardware
+ "insert-line" feature.
+
+ - Function: scroll WIN
+ The window WIN is scrolled up one line. This involves moving the
+ lines in WIN's data structure. As an optimization, if WIN is
+ stdscr and the scrolling region is the entire window, the physical
+ screen will be scrolled at the same time.
+
+
+File: scm.info, Node: Input, Next: Curses Miscellany, Prev: Output, Up: Curses
+
+Input
+-----
+
+ - Function: read-char WIN
+ A character is read from the terminal associated with the window
+ WIN. Depending on the setting of `cbreak', this will be after one
+ character (`CBREAK' mode), or after the first newline (`NOCBREAK'
+ mode). Unless `noecho' has been set, the character will also be
+ echoed into WIN.
+
+ When using `read-char', do not set both `NOCBREAK' mode
+ (`nocbreak') and `ECHO' mode (`echo') at the same time. Depending
+ on the state of the terminal driver when each character is typed,
+ the program may produce undesirable results.
+
+ - Function: winch WIN
+ The character, of type chtype, at the current position in window
+ WIN is returned. If any attributes are set for that position,
+ their values will be OR'ed into the value returned.
+
+ - Function: getyx WIN
+ A list of the y and x coordinates of the cursor position of the
+ window WIN is returned
+
+
+File: scm.info, Node: Curses Miscellany, Prev: Input, Up: Curses
+
+Curses Miscellany
+-----------------
+
+ - Function: wstandout WIN
+ - Function: wstandend WIN
+ These functions set the current attributes of the window WIN. The
+ current attributes of WIN are applied to all characters that are
+ written into it. Attributes are a property of the character, and
+ move with the character through any scrolling and insert/delete
+ line/character operations. To the extent possible on the
+ particular terminal, they will be displayed as the graphic
+ rendition of characters put on the screen.
+
+ `wstandout' sets the current attributes of the window WIN to be
+ visibly different from other text. `wstandend' turns off the
+ attributes.
+
+ - Function: box WIN VERTCH HORCH
+ A box is drawn around the edge of the window WIN. VERTCH and
+ HORCH are the characters the box is to be drawn with. If VERTCH
+ and HORCH are 0, then appropriate default characters, `ACS_VLINE'
+ and `ACS_HLINE', will be used.
+
+ *Note:* VERTCH and HORCH can be an integers and will insert the
+ character (with attributes) of the corresponding values.
+
+ - Function: unctrl C
+ This macro expands to a character string which is a printable
+ representation of the character C. Control characters are
+ displayed in the `C-x' notation. Printing characters are displayed
+ as is.
+
+
+File: scm.info, Node: Sockets, Prev: Curses, Up: Packages
+
+Sockets
+=======
+
+These procedures (defined in `socket.c') provide a Scheme interface to
+most of the C "socket" library. For more information on sockets, *Note
+Sockets: (libc)Sockets.
+
+* Menu:
+
+* Host Data::
+* Internet Addresses and Socket Names::
+* Socket::
+
+
+File: scm.info, Node: Host Data, Next: Internet Addresses and Socket Names, Prev: Sockets, Up: Sockets
+
+Host Data, Network, Protocol, and Service Inquiries
+---------------------------------------------------
+
+ - Constant: af_inet
+ - Constant: af_unix
+ Integer family codes for Internet and Unix sockets, respectively.
+
+ - Function: gethost HOST-SPEC
+ - Function: gethost
+ Returns a vector of information for the entry for `HOST-SPEC' or
+ the next entry if `HOST-SPEC' isn't given. The information is:
+
+ 0. host name string
+
+ 1. list of host aliases strings
+
+ 2. integer address type (`AF_INET')
+
+ 3. integer size of address entries (in bytes)
+
+ 4. list of integer addresses
+
+ - Function: sethostent STAY-OPEN
+ - Function: sethostent
+ Rewinds the host entry table back to the begining if given an
+ argument. If the argument STAY-OPEN is `#f' queries will be be
+ done using `UDP' datagrams. Otherwise, a connected `TCP' socket
+ will be used. When called without an argument, the host table is
+ closed.
+
+ - Function: getnet NAME-OR-NUMBER
+ - Function: getnet
+ Returns a vector of information for the entry for NAME-OR-NUMBER or
+ the next entry if an argument isn't given. The information is:
+
+ 0. official network name string
+
+ 1. list of network aliases strings
+
+ 2. integer network address type (`AF_INET')
+
+ 3. integer network number
+
+ - Function: setnetent STAY-OPEN
+ - Function: setnetent
+ Rewinds the network entry table back to the begining if given an
+ argument. If the argument STAY-OPEN is `#f' the table will be
+ closed between calls to getnet. Otherwise, the table stays open.
+ When called without an argument, the network table is closed.
+
+ - Function: getproto NAME-OR-NUMBER
+ - Function: getproto
+ Returns a vector of information for the entry for NAME-OR-NUMBER or
+ the next entry if an argument isn't given. The information is:
+
+ 1. official protocol name string
+
+ 2. list of protocol aliases strings
+
+ 3. integer protocol number
+
+ - Function: setprotoent STAY-OPEN
+ - Function: setprotoent
+ Rewinds the protocol entry table back to the begining if given an
+ argument. If the argument STAY-OPEN is `#f' the table will be
+ closed between calls to getproto. Otherwise, the table stays
+ open. When called without an argument, the protocol table is
+ closed.
+
+ - Function: getserv NAME-OR-PORT-NUMBER PROTOCOL
+ - Function: getserv
+ Returns a vector of information for the entry for
+ NAME-OR-PORT-NUMBER and PROTOCOL or the next entry if arguments
+ aren't given. The information is:
+
+ 0. official service name string
+
+ 1. list of service aliases strings
+
+ 2. integer port number
+
+ 3. protocol
+
+ - Function: setservent STAY-OPEN
+ - Function: setservent
+ Rewinds the service entry table back to the begining if given an
+ argument. If the argument STAY-OPEN is `#f' the table will be
+ closed between calls to getserv. Otherwise, the table stays open.
+ When called without an argument, the service table is closed.
+
+
+File: scm.info, Node: Internet Addresses and Socket Names, Next: Socket, Prev: Host Data, Up: Sockets
+
+Internet Addresses and Socket Names
+-----------------------------------
+
+ - Function: inet:string->address STRING
+ Returns the host address number (integer) for host STRING or `#f'
+ if not found.
+
+ - Function: inet:address->string ADDRESS
+ Converts an internet (integer) address to a string in numbers and
+ dots notation.
+
+ - Function: inet:network ADDRESS
+ Returns the network number (integer) specified from ADDRESS or
+ `#f' if not found.
+
+ - Function: inet:local-network-address ADDRESS
+ Returns the integer for the address of ADDRESS within its local
+ network or `#f' if not found.
+
+ - Function: inet:make-address NETWORK LOCAL-ADDRESS
+ Returns the Internet address of LOCAL-ADDRESS in NETWORK.
+
+The type "socket-name" is used for inquiries about open sockets in the
+following procedures:
+
+ - Function: getsockname SOCKET
+ Returns the socket-name of SOCKET. Returns `#f' if unsuccessful
+ or SOCKET is closed.
+
+ - Function: getpeername SOCKET
+ Returns the socket-name of the socket connected to SOCKET.
+ Returns `#f' if unsuccessful or SOCKET is closed.
+
+ - Function: socket-name:family SOCKET-NAME
+ Returns the integer code for the family of SOCKET-NAME.
+
+ - Function: socket-name:port-number SOCKET-NAME
+ Returns the integer port number of SOCKET-NAME.
+
+ - Function: socket-name:address SOCKET-NAME
+ Returns the integer Internet address for SOCKET-NAME.
+
+
+File: scm.info, Node: Socket, Prev: Internet Addresses and Socket Names, Up: Sockets
+
+Socket
+------
+
+When a port is returned from one of these calls it is unbuffered. This
+allows both reading and writing to the same port to work. If you want
+buffered ports you can (assuming sock-port is a socket i/o port):
+ (require 'i/o-extensions)
+ (define i-port (duplicate-port sock-port "r"))
+ (define o-port (duplicate-port sock-port "w"))
+
+ - Function: make-stream-socket FAMILY
+ - Function: make-stream-socket FAMILY PROTOCOL
+ Returns a `SOCK_STREAM' socket of type FAMILY using PROTOCOL. If
+ FAMILY has the value `AF_INET', `SO_REUSEADDR' will be set. The
+ integer argument PROTOCOL corresponds to the integer protocol
+ numbers returned (as vector elements) from `(getproto)'. If the
+ PROTOCOL argument is not supplied, the default (0) for the
+ specified FAMILY is used. SCM sockets look like ports opened for
+ neither reading nor writing.
+
+ - Function: make-stream-socketpair FAMILY
+ - Function: make-stream-socketpair FAMILY PROTOCOL
+ Returns a pair (cons) of connected `SOCK_STREAM' (socket) ports of
+ type FAMILY using PROTOCOL. Many systems support only socketpairs
+ of the `af-unix' FAMILY. The integer argument PROTOCOL
+ corresponds to the integer protocol numbers returned (as vector
+ elements) from (getproto). If the PROTOCOL argument is not
+ supplied, the default (0) for the specified FAMILY is used.
+
+ - Function: socket:shutdown SOCKET HOW
+ Makes SOCKET no longer respond to some or all operations depending
+ on the integer argument HOW:
+
+ 0. Further input is disallowed.
+
+ 1. Further output is disallowed.
+
+ 2. Further input or output is disallowed.
+
+ `Socket:shutdown' returns SOCKET if successful, `#f' if not.
+
+ - Function: socket:connect INET-SOCKET HOST-NUMBER PORT-NUMBER
+ - Function: socket:connect UNIX-SOCKET PATHNAME
+ Returns SOCKET (changed to a read/write port) connected to the
+ Internet socket on host HOST-NUMBER, port PORT-NUMBER or the Unix
+ socket specified by PATHNAME. Returns `#f' if not successful.
+
+ - Function: socket:bind INET-SOCKET PORT-NUMBER
+ - Function: socket:bind UNIX-SOCKET PATHNAME
+ Returns INET-SOCKET bound to the integer PORT-NUMBER or the
+ UNIX-SOCKET bound to new socket in the file system at location
+ PATHNAME. Returns `#f' if not successful. Binding a UNIX-SOCKET
+ creates a socket in the file system that must be deleted by the
+ caller when it is no longer needed (using `delete-file').
+
+ - Function: socket:listen SOCKET BACKLOG
+ The bound (*note bind: Socket.) SOCKET is readied to accept
+ connections. The positive integer BACKLOG specifies how many
+ pending connections will be allowed before further connection
+ requests are refused. Returns SOCKET (changed to a read-only
+ port) if successful, `#f' if not.
+
+ - Function: char-ready? LISTEN-SOCKET
+ The input port returned by a successful call to `socket:listen' can
+ be polled for connections by `char-ready?' (*note char-ready?:
+ Files and Ports.). This avoids blocking on connections by
+ `socket:accept'.
+
+ - Function: socket:accept SOCKET
+ Accepts a connection on a bound, listening SOCKET. Returns an
+ input/output port for the connection.
+
+The following example is not too complicated, yet shows the use of
+sockets for multiple connections without input blocking.
+
+ ;;;; Scheme chat server
+
+ ;;; This program implements a simple `chat' server which accepts
+ ;;; connections from multiple clients, and sends to all clients any
+ ;;; characters received from any client.
+
+ ;;; To connect to chat `telnet localhost 8001'
+
+ (require 'socket)
+ (require 'i/o-extensions)
+
+ (let ((listener-socket (socket:bind (make-stream-socket af_inet) 8001))
+ (connections '()))
+ (socket:listen listener-socket 5)
+ (do () (#f)
+ (let ((actives (or (apply wait-for-input 5 listener-socket connections)
+ '())))
+ (cond ((null? actives))
+ ((memq listener-socket actives)
+ (set! actives (cdr (memq listener-socket actives)))
+ (let ((con (socket:accept listener-socket)))
+ (display "accepting connection from ")
+ (display (getpeername con))
+ (newline)
+ (set! connections (cons con connections))
+ (display "connected" con)
+ (newline con))))
+ (set! connections
+ (let next ((con-list connections))
+ (cond ((null? con-list) '())
+ (else
+ (let ((con (car con-list)))
+ (cond ((memq con actives)
+ (let ((c (read-char con)))
+ (cond ((eof-object? c)
+ (display "closing connection from ")
+ (display (getpeername con))
+ (newline)
+ (close-port con)
+ (next (cdr con-list)))
+ (else
+ (for-each (lambda (con)
+ (file-set-position con 0)
+ (write-char c con)
+ (file-set-position con 0))
+ connections)
+ (cons con (next (cdr con-list)))))))
+ (else (cons con (next (cdr con-list)))))))))))))
+
+You can use `telnet localhost 8001' to connect to the chat server, or
+you can use a client written in scheme:
+
+ ;;;; Scheme chat client
+
+ ;;; this program connects to socket 8001. It then sends all
+ ;;; characters from current-input-port to the socket and sends all
+ ;;; characters from the socket to current-output-port.
+
+ (require 'socket)
+ (require 'i/o-extensions)
+
+ (define con (make-stream-socket af_inet))
+ (set! con (socket:connect con (inet:string->address "localhost") 8001))
+
+ (define (go)
+ (define actives (wait-for-input (* 30 60) con (current-input-port)))
+ (let ((cs (and actives (memq con actives) (read-char con)))
+ (ct (and actives (memq (current-input-port) actives) (read-char))))
+ (cond ((or (eof-object? cs) (eof-object? ct)) (close-port con))
+ (else (cond (cs (display cs)))
+ (cond (ct (file-set-position con 0)
+ (display ct con)
+ (file-set-position con 0)))
+ (go)))))
+ (cond (con (display "Connecting to ")
+ (display (getpeername con))
+ (newline)
+ (go))
+ (else (display "Server not listening on port 8001")
+ (newline)))
+
+
+File: scm.info, Node: The Implementation, Next: Index, Prev: Packages, Up: Top
+
+The Implementation
+******************
+
+* Menu:
+
+* Data Types::
+* Operations::
+* Program Self-Knowledge:: What SCM needs to know about itself.
+* Improvements To Make::
+
+
+File: scm.info, Node: Data Types, Next: Operations, Prev: The Implementation, Up: The Implementation
+
+Data Types
+==========
+
+In the descriptions below it is assumed that `long int's are 32 bits in
+length. Acutally, SCM is written to work with any `long int' size
+larger than 31 bits. With some modification, SCM could work with word
+sizes as small as 24 bits.
+
+All SCM objects are represented by type "SCM". Type `SCM' come in 2
+basic flavors, Immediates and Cells:
+
+* Menu:
+
+* Immediates::
+* Cells:: Non-Immediate types
+* Header Cells:: Malloc objects
+* Subr Cells:: Built-in and Compiled Procedures
+* Ptob Cells:: I/O ports
+* Smob Cells:: Miscellaneous datatypes
+* Data Type Representations:: How they all fit together
+
+
+File: scm.info, Node: Immediates, Next: Cells, Prev: Data Types, Up: Data Types
+
+Immediates
+----------
+
+An "immediate" is a data type contained in type `SCM' (`long int').
+The type codes distinguishing immediate types from each other vary in
+length, but reside in the low order bits.
+
+ - Macro: IMP X
+ - Macro: NIMP X
+ Return non-zero if the `SCM' object X is an immediate or
+ non-immediate type, respectively.
+
+ - Immediate: inum
+ immediate 30 bit signed integer. An INUM is flagged by a `1' in
+ the second to low order bit position. The high order 30 bits are
+ used for the integer's value.
+
+ - Macro: INUMP X
+ - Macro: NINUMP X
+ Return non-zero if the `SCM' X is an immediate integer or not
+ an immediate integer, respectively.
+
+ - Macro: INUM X
+ Returns the C `long integer' corresponding to `SCM' X.
+
+ - Macro: MAKINUM X
+ Returns the `SCM' inum corresponding to C `long integer' x.
+
+ - Immediate Constant: INUM0
+ is equivalent to `MAKINUM(0)'.
+
+ Computations on INUMs are performed by converting the arguments to
+ C integers (by a shift), operating on the integers, and converting
+ the result to an inum. The result is checked for overflow by
+ converting back to integer and checking the reverse operation.
+
+ The shifts used for conversion need to be signed shifts. If the C
+ implementation does not support signed right shift this fact is
+ detected in a #if statement in `scmfig.h' and a signed right shift,
+ `SRS', is constructed in terms of unsigned right shift.
+
+ - Immediate: ichr
+ characters.
+
+ - Macro: ICHRP X
+ Return non-zero if the `SCM' object X is a character.
+
+ - Macro: ICHR X
+ Returns corresponding `unsigned char'.
+
+ - Macro: MAKICHR X
+ Given `char' X, returns `SCM' character.
+
+
+ - Immediate: iflags
+ These are frequently used immediate constants.
+
+ - Immediate Constant: SCM BOOL_T
+ `#t'
+
+ - Immediate Constant: SCM BOOL_F
+ `#f'
+
+ - Immediate Constant: SCM EOL
+ `()'. If `SICP' is `#define'd, `EOL' is `#define'd to be
+ identical with `BOOL_F'. In this case, both print as `#f'.
+
+ - Immediate Constant: SCM EOF_VAL
+ end of file token, `#<eof>'.
+
+ - Immediate Constant: SCM UNDEFINED
+ `#<undefined>' used for variables which have not been defined
+ and absent optional arguments.
+
+ - Immediate Constant: SCM UNSPECIFIED
+ `#<unspecified>' is returned for those procedures whose return
+ values are not specified.
+
+
+ - Macro: IFLAGP N
+ Returns non-zero if N is an ispcsym, isym or iflag.
+
+ - Macro: ISYMP N
+ Returns non-zero if N is an ispcsym or isym.
+
+ - Macro: ISYMNUM N
+ Given ispcsym, isym, or iflag N, returns its index in the C array
+ `isymnames[]'.
+
+ - Macro: ISYMCHARS N
+ Given ispcsym, isym, or iflag N, returns its `char *'
+ representation (from `isymnames[]').
+
+ - Macro: MAKSPCSYM N
+ Returns `SCM' ispcsym N.
+
+ - Macro: MAKISYM N
+ Returns `SCM' iisym N.
+
+ - Macro: MAKIFLAG N
+ Returns `SCM' iflag N.
+
+ - Variable: isymnames
+ An array of strings containing the external representations of all
+ the ispcsym, isym, and iflag immediates. Defined in `repl.c'.
+
+ - Constant: NUM_ISPCSYM
+ - Constant: NUM_ISYMS
+ The number of ispcsyms and ispcsyms+isyms, respectively. Defined
+ in `scm.h'.
+
+ - Immediate: isym
+ `and', `begin', `case', `cond', `define', `do', `if', `lambda',
+ `let', `let*', `letrec', `or', `quote', `set!', `#f', `#t',
+ `#<undefined>', `#<eof>', `()', and `#<unspecified>'.
+
+ - CAR Immediate: ispcsym
+ special symbols: syntax-checked versions of first 14 isyms
+
+ - CAR Immediate: iloc
+ indexes to a variable's location in environment
+
+ - CAR Immediate: gloc
+ pointer to a symbol's value cell
+
+ - Immediate: CELLPTR
+ pointer to a cell (not really an immediate type, but here for
+ completeness). Since cells are always 8 byte aligned, a pointer
+ to a cell has the low order 3 bits `0'.
+
+ There is one exception to this rule, *CAR Immediate*s, described
+ next.
+
+A "CAR Immediate" is an Immediate point which can only occur in the
+`CAR's of evaluated code (as a result of `ceval''s memoization process).
+
+
+File: scm.info, Node: Cells, Next: Header Cells, Prev: Immediates, Up: Data Types
+
+Cells
+-----
+
+"Cell"s represent all SCM objects other than immediates. A cell has a
+`CAR' and a `CDR'. Low-order bits in `CAR' identify the type of
+object. The rest of `CAR' and `CDR' hold object data. The number
+after `tc' specifies how many bits are in the type code. For instance,
+`tc7' indicates that the type code is 7 bits.
+
+ - Macro: NEWCELL X
+ Allocates a new cell and stores a pointer to it in `SCM' local
+ variable X.
+
+ Care needs to be taken that stores into the new cell pointed to by
+ X do not create an inconsistent object. *Note Signals::.
+
+All of the C macros decribed in this section assume that their argument
+is of type `SCM' and points to a cell (`CELLPTR').
+
+ - Macro: CAR X
+ - Macro: CDR X
+ Returns the `car' and `cdr' of cell X, respectively.
+
+ - Macro: TYP3 X
+ - Macro: TYP7 X
+ - Macro: TYP16 X
+ Returns the 3, 7, and 16 bit type code of a cell.
+
+ - Cell: tc3_cons
+ scheme cons-cell returned by (cons arg1 arg2).
+
+ - Macro: CONSP X
+ - Macro: NCONSP X
+ Returns non-zero if X is a `tc3_cons' or isn't, respectively.
+
+ - Cell: tc3_closure
+ applicable object returned by (lambda (args) ...). `tc3_closure's
+ have a pointer to the body of the procedure in the `CAR' and a
+ pointer to the environment in the `CDR'. Bits 1 and 2
+ (zero-based) in the `CDR' indicate a lower bound on the number of
+ required arguments to the closure, which is used to avoid
+ allocating rest argument lists in the environment cache. This
+ encoding precludes an immediate value for the `CDR': In the case
+ of an empty environment all bits above 2 in the `CDR' are zero.
+
+ - Macro: CLOSUREP X
+ Returns non-zero if X is a `tc3_closure'.
+
+ - Macro: CODE X
+ - Macro: ENV X
+ Returns the code body or environment of closure X,
+ respectively.
+
+ - Macro: ARGC X
+ Returns the a lower bound on the number of required arguments
+ to closure X, it cannot exceed 3.
+
+
+
+File: scm.info, Node: Header Cells, Next: Subr Cells, Prev: Cells, Up: Data Types
+
+Header Cells
+------------
+
+"Header"s are Cells whose `CDR's point elsewhere in memory, such as to
+memory allocated by `malloc'.
+
+ - Header: spare
+ spare `tc7' type code
+
+ - Header: tc7_vector
+ scheme vector.
+
+ - Macro: VECTORP X
+ - Macro: NVECTORP X
+ Returns non-zero if X is a `tc7_vector' or if not,
+ respectively.
+
+ - Macro: VELTS X
+ - Macro: LENGTH X
+ Returns the C array of `SCM's holding the elements of vector
+ X or its length, respectively.
+
+ - Header: tc7_ssymbol
+ static scheme symbol (part of initial system)
+
+ - Header: tc7_msymbol
+ `malloc'ed scheme symbol (can be GCed)
+
+ - Macro: SYMBOLP X
+ Returns non-zero if X is a `tc7_ssymbol' or `tc7_msymbol'.
+
+ - Macro: CHARS X
+ - Macro: UCHARS X
+ - Macro: LENGTH X
+ Returns the C array of `char's or as `unsigned char's holding
+ the elements of symbol X or its length, respectively.
+
+ - Header: tc7_string
+ scheme string
+
+ - Macro: STRINGP X
+ - Macro: NSTRINGP X
+ Returns non-zero if X is a `tc7_string' or isn't,
+ respectively.
+
+ - Macro: CHARS X
+ - Macro: UCHARS X
+ - Macro: LENGTH X
+ Returns the C array of `char's or as `unsigned char's holding
+ the elements of string X or its length, respectively.
+
+ - Header: tc7_bvect
+ uniform vector of booleans (bit-vector)
+
+ - Header: tc7_ivect
+ uniform vector of integers
+
+ - Header: tc7_uvect
+ uniform vector of non-negative integers
+
+ - Header: tc7_fvect
+ uniform vector of short inexact real numbers
+
+ - Header: tc7_dvect
+ uniform vector of double precision inexact real numbers
+
+ - Header: tc7_cvect
+ uniform vector of double precision inexact complex numbers
+
+ - Header: tc7_contin
+ applicable object produced by call-with-current-continuation
+
+ - Header: tc7_specfun
+ subr that is treated specially within the evaluator
+
+ `apply' and `call-with-current-continuation' are denoted by these
+ objects. Their behavior as functions is built into the evaluator;
+ they are not directly associated with C functions. This is
+ necessary in order to make them properly tail recursive.
+
+ tc16_cclo is a subtype of tc7_specfun, a cclo is similar to a
+ vector (and is GCed like one), but can be applied as a function:
+
+ 1. the cclo itself is consed onto the head of the argument list
+
+ 2. the first element of the cclo is applied to that list. Cclo
+ invocation is currently not tail recursive when given 2 or
+ more arguments.
+
+ - Function: makcclo PROC LEN
+ makes a closure from the *subr* PROC with LEN-1 extra
+ locations for `SCM' data. Elements of a CCLO are referenced
+ using `VELTS(cclo)[n]' just as for vectors.
+
+ - Macro: CCLO_LENGTH CCLO
+ Expands to the length of CCLO.
+
+
+File: scm.info, Node: Subr Cells, Next: Ptob Cells, Prev: Header Cells, Up: Data Types
+
+Subr Cells
+----------
+
+A "Subr" is a header whose `CDR' points to a C code procedure. Scheme
+primitive procedures are subrs. Except for the arithmetic `tc7_cxr's,
+the C code procedures will be passed arguments (and return results) of
+type `SCM'.
+
+ - Subr: tc7_asubr
+ associative C function of 2 arguments. Examples are `+', `-',
+ `*', `/', `max', and `min'.
+
+ - Subr: tc7_subr_0
+ C function of no arguments.
+
+ - Subr: tc7_subr_1
+ C function of one argument.
+
+ - Subr: tc7_cxr
+ These subrs are handled specially. If inexact numbers are
+ enabled, the `CDR' should be a function which takes and returns
+ type `double'. Conversions are handled in the interpreter.
+
+ `floor', `ceiling', `truncate', `round', `$sqrt', `$abs', `$exp',
+ `$log', `$sin', `$cos', `$tan', `$asin', `$acos', `$atan',
+ `$sinh', `$cosh', `$tanh', `$asinh', `$acosh', `$atanh', and
+ `exact->inexact' are defined this way.
+
+ If the `CDR' is `0' (`NULL'), the name string of the procedure is
+ used to control traversal of its list structure argument.
+
+ `car', `cdr', `caar', `cadr', `cdar', `cddr', `caaar', `caadr',
+ `cadar', `caddr', `cdaar', `cdadr', `cddar', `cdddr', `caaaar',
+ `caaadr', `caadar', `caaddr', `cadaar', `cadadr', `caddar',
+ `cadddr', `cdaaar', `cdaadr', `cdadar', `cdaddr', `cddaar',
+ `cddadr', `cdddar', and `cddddr' are defined this way.
+
+ - Subr: tc7_subr_3
+ C function of 3 arguments.
+
+ - Subr: tc7_subr_2
+ C function of 2 arguments.
+
+ - Subr: tc7_rpsubr
+ transitive relational predicate C function of 2 arguments. The C
+ function should return either `BOOL_T' or `BOOL_F'.
+
+ - Subr: tc7_subr_1o
+ C function of one optional argument. If the optional argument is
+ not present, `UNDEFINED' is passed in its place.
+
+ - Subr: tc7_subr_2o
+ C function of 1 required and 1 optional argument. If the optional
+ argument is not present, `UNDEFINED' is passed in its place.
+
+ - Subr: tc7_lsubr_2
+ C function of 2 arguments and a list of (rest of) `SCM' arguments.
+
+ - Subr: tc7_lsubr
+ C function of list of `SCM' arguments.
+
+
+File: scm.info, Node: Ptob Cells, Next: Smob Cells, Prev: Subr Cells, Up: Data Types
+
+Ptob Cells
+----------
+
+A "ptob" is a port object, capable of delivering or accepting
+characters. *Note Ports: (r5rs)Ports. Unlike the types described so
+far, new varieties of ptobs can be defined dynamically (*note Defining
+Ptobs::.). These are the initial ptobs:
+
+ - ptob: tc16_inport
+ input port.
+
+ - ptob: tc16_outport
+ output port.
+
+ - ptob: tc16_ioport
+ input-output port.
+
+ - ptob: tc16_inpipe
+ input pipe created by `popen()'.
+
+ - ptob: tc16_outpipe
+ output pipe created by `popen()'.
+
+ - ptob: tc16_strport
+ String port created by `cwos()' or `cwis()'.
+
+ - ptob: tc16_sfport
+ Software (virtual) port created by `mksfpt()' (*note Soft
+ Ports::.).
+
+ - Macro: PORTP X
+ - Macro: OPPORTP X
+ - Macro: OPINPORTP X
+ - Macro: OPOUTPORTP X
+ - Macro: INPORTP X
+ - Macro: OUTPORTP X
+ Returns non-zero if X is a port, open port, open input-port, open
+ output-port, input-port, or output-port, respectively.
+
+ - Macro: OPENP X
+ - Macro: CLOSEDP X
+ Returns non-zero if port X is open or closed, respectively.
+
+ - Macro: STREAM X
+ Returns the `FILE *' stream for port X.
+
+Ports which are particularly well behaved are called "fport"s.
+Advanced operations like `file-position' and `reopen-file' only work
+for fports.
+
+ - Macro: FPORTP X
+ - Macro: OPFPORTP X
+ - Macro: OPINFPORTP X
+ - Macro: OPOUTFPORTP X
+ Returns non-zero if X is a port, open port, open input-port, or
+ open output-port, respectively.
+
+
+File: scm.info, Node: Smob Cells, Next: Data Type Representations, Prev: Ptob Cells, Up: Data Types
+
+Smob Cells
+----------
+
+A "smob" is a miscellaneous datatype. The type code and GCMARK bit
+occupy the lower order 16 bits of the `CAR' half of the cell. The rest
+of the `CAR' can be used for sub-type or other information. The `CDR'
+contains data of size long and is often a pointer to allocated memory.
+
+Like ptobs, new varieties of smobs can be defined dynamically (*note
+Defining Smobs::.). These are the initial smobs:
+
+ - smob: tc_free_cell
+ unused cell on the freelist.
+
+ - smob: tc16_flo
+ single-precision float.
+
+ Inexact number data types are subtypes of type `tc16_flo'. If the
+ sub-type is:
+
+ 0. a single precision float is contained in the `CDR'.
+
+ 1. `CDR' is a pointer to a `malloc'ed double.
+
+ 3. `CDR' is a pointer to a `malloc'ed pair of doubles.
+
+ - smob: tc_dblr
+ double-precision float.
+
+ - smob: tc_dblc
+ double-precision complex.
+
+ - smob: tc16_bigpos
+ - smob: tc16_bigneg
+ positive and negative bignums, respectively.
+
+ Scm has large precision integers called bignums. They are stored
+ in sign-magnitude form with the sign occuring in the type code of
+ the SMOBs bigpos and bigneg. The magnitude is stored as a
+ `malloc'ed array of type `BIGDIG' which must be an unsigned
+ integral type with size smaller than `long'. `BIGRAD' is the
+ radix associated with `BIGDIG'.
+
+ `NUMDIGS_MAX' (defined in `scmfig.h') limits the number of digits
+ of a bignum to 1000. These digits are base `BIGRAD', which is
+ typically 65536, giving 4816 decimal digits.
+
+ Why only 4800 digits? The simple multiplication algorithm SCM
+ uses is O(n^2); this means the number of processor instructions
+ required to perform a multiplication is *some multiple* of the
+ product of the number of digits of the two multiplicands.
+
+ digits * digits ==> operations
+ 5 x
+ 50 100 * x
+ 500 10000 * x
+ 5000 1000000 * x
+
+ To calculate numbers larger than this, FFT multiplication
+ [O(n*log(n))] and other specialized algorithms are required. You
+ should obtain a package which specializes in number-theoretical
+ calculations:
+
+ `ftp://megrez.math.u-bordeaux.fr/pub/pari/'
+
+
+ - smob: tc16_promise
+ made by DELAY. *Note Control features: (r5rs)Control features.
+
+ - smob: tc16_arbiter
+ synchronization object. *Note Process Synchronization::.
+
+ - smob: tc16_macro
+ macro expanding function. *Note Low Level Syntactic Hooks::.
+
+ - smob: tc16_array
+ multi-dimensional array. *Note Arrays::.
+
+ This type implements both conventional arrays (those with
+ arbitrary data as elements *note Conventional Arrays::.) and
+ uniform arrays (those with elements of a uniform type *note
+ Uniform Array::.).
+
+ Conventional Arrays have a pointer to a vector for their `CDR'.
+ Uniform Arrays have a pointer to a Uniform Vector type (string,
+ bvect, ivect, uvect, fvect, dvect, or cvect) in their `CDR'.
+
+
+File: scm.info, Node: Data Type Representations, Prev: Smob Cells, Up: Data Types
+
+Data Type Representations
+-------------------------
+
+IMMEDIATE: B,D,E,F=data bit, C=flag code, P=pointer address bit
+ ................................
+inum BBBBBBBBBBBBBBBBBBBBBBBBBBBBBB10
+ichr BBBBBBBBBBBBBBBBBBBBBBBB11110100
+iflag CCCCCCC101110100
+isym CCCCCCC001110100
+ IMCAR: only in car of evaluated code, cdr has cell's GC bit
+ispcsym 000CCCC00CCCC100
+iloc 0DDDDDDDDDDDEFFFFFFFFFFF11111100
+pointer PPPPPPPPPPPPPPPPPPPPPPPPPPPPP000
+gloc PPPPPPPPPPPPPPPPPPPPPPPPPPPPP001
+
+ HEAP CELL: G=gc_mark; 1 during mark, 0 other times.
+ 1s and 0s here indicate type. G missing means sys (not GC'd)
+ SIMPLE:
+cons ..........SCM car..............0 ...........SCM cdr.............G
+closure ..........SCM code...........011 ...........SCM env...........CCG
+ HEADERs:
+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
+ spare G0100111
+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...........
+ PTOBs:
+ port 0bwroxxxxxxxxG0110111 ..........FILE *stream..........
+ socket ttttttt 00001xxxxxxxxG0110111 ..........FILE *stream..........
+ inport uuuuuuuuuuU00011xxxxxxxxG0110111 ..........FILE *stream..........
+outport 0000000000000101xxxxxxxxG0110111 ..........FILE *stream..........
+ ioport uuuuuuuuuuU00111xxxxxxxxG0110111 ..........FILE *stream..........
+fport 00 00000000G0110111 ..........FILE *stream..........
+pipe 00 00000001G0110111 ..........FILE *stream..........
+strport 00 00000010G0110111 ..........FILE *stream..........
+sfport 00 00000011G0110111 ..........FILE *stream..........
+ SUBRs:
+ spare 010001x1
+ spare 010011x1
+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)()...........
+subr_2 ..........int hpoff.....01100101 ...........SCM (*f)()...........
+asubr ..........int hpoff.....01100111 ...........SCM (*f)()...........
+subr_1o ..........int hpoff.....01101101 ...........SCM (*f)()...........
+subr_2o ..........int hpoff.....01101111 ...........SCM (*f)()...........
+lsubr_2 ..........int hpoff.....01110101 ...........SCM (*f)()...........
+lsubr ..........int hpoff.....01110111 ...........SCM (*f)()...........
+rpsubr ..........int hpoff.....01111101 ...........SCM (*f)()...........
+ SMOBs:
+free_cell
+ 000000000000000000000000G1111111 ...........*free_cell........000
+flo 000000000000000000000001G1111111 ...........float num............
+dblr 000000000000000100000001G1111111 ..........double *real..........
+dblc 000000000000001100000001G1111111 .........complex *cmpx..........
+bignum ...int length...0000001 G1111111 .........short *digits..........
+bigpos ...int length...00000010G1111111 .........short *digits..........
+bigneg ...int length...00000011G1111111 .........short *digits..........
+ xxxxxxxx = code assigned by newsmob();
+promise 000000000000000fxxxxxxxxG1111111 ...........SCM val..............
+arbiter 000000000000000lxxxxxxxxG1111111 ...........SCM name.............
+macro 000000000000000mxxxxxxxxG1111111 ...........SCM name.............
+array ...short rank..cxxxxxxxxG1111111 ............*array..............
+
+
+File: scm.info, Node: Operations, Next: Program Self-Knowledge, Prev: Data Types, Up: The Implementation
+
+Operations
+==========
+
+* Menu:
+
+* Garbage Collection:: Automatically reclaims unused storage
+* Memory Management for Environments::
+* Signals::
+* C Macros::
+* Changing Scm::
+* Defining Subrs::
+* Defining Smobs::
+* Defining Ptobs::
+* Allocating memory::
+* Embedding SCM:: In other programs
+* Callbacks::
+* Type Conversions:: For use with C code.
+* Continuations:: For C and SCM
+* Evaluation:: Why SCM is fast
+
+
+File: scm.info, Node: Garbage Collection, Next: Memory Management for Environments, Prev: Operations, Up: Operations
+
+Garbage Collection
+------------------
+
+The garbage collector is in the latter half of `sys.c'. The primary
+goal of "garbage collection" (or "GC") is to recycle those cells no
+longer in use. Immediates always appear as parts of other objects, so
+they are not subject to explicit garbage collection.
+
+All cells reside in the "heap" (composed of "heap segments"). Note
+that this is different from what Computer Science usually defines as a
+heap.
+
+* Menu:
+
+* Marking Cells::
+* Sweeping the Heap::
+
+
+File: scm.info, Node: Marking Cells, Next: Sweeping the Heap, Prev: Garbage Collection, Up: Garbage Collection
+
+Marking Cells
+.............
+
+The first step in garbage collection is to "mark" all heap objects in
+use. Each heap cell has a bit reserved for this purpose. For pairs
+(cons cells) the lowest order bit (0) of the CDR is used. For other
+types, bit 8 of the CAR is used. The GC bits are never set except
+during garbage collection. Special C macros are defined in `scm.h' to
+allow easy manipulation when GC bits are possibly set. `CAR', `TYP3',
+and `TYP7' can be used on GC marked cells as they are.
+
+ - Macro: GCCDR X
+ Returns the CDR of a cons cell, even if that cell has been GC
+ marked.
+
+ - Macro: GCTYP16 X
+ Returns the 16 bit type code of a cell.
+
+We need to (recursively) mark only a few objects in order to assure that
+all accessible objects are marked. Those objects are `sys_protects[]'
+(for example, `dynwinds'), the current C-stack and the hash table for
+symbols, "symhash".
+
+ - Function: void gc_mark (SCM OBJ)
+ The function `gc_mark()' is used for marking SCM cells. If OBJ is
+ marked, `gc_mark()' returns. If OBJ is unmarked, gc_mark sets the
+ mark bit in OBJ, then calls `gc_mark()' on any SCM components of
+ OBJ. The last call to `gc_mark()' is tail-called (looped).
+
+ - Function: void mark_locations (STACKITEM X[], sizet LEN))
+ The function `mark_locations' is used for marking segments of
+ C-stack or saved segments of C-stack (marked continuations). The
+ argument LEN is the size of the stack in units of size
+ `(STACKITEM)'.
+
+ Each longword in the stack is tried to see if it is a valid cell
+ pointer into the heap. If it is, the object itself and any
+ objects it points to are marked using `gc_mark'. If the stack is
+ word rather than longword aligned `(#define WORD_ALIGN)', both
+ alignments are tried. This arrangement will occasionally mark an
+ object which is no longer used. This has not been a problem in
+ practice and the advantage of using the c-stack far outweighs it.
+
+
+File: scm.info, Node: Sweeping the Heap, Prev: Marking Cells, Up: Garbage Collection
+
+Sweeping the Heap
+.................
+
+After all found objects have been marked, the heap is swept.
+
+The storage for strings, vectors, continuations, doubles, complexes, and
+bignums is managed by malloc. There is only one pointer to each malloc
+object from its type-header cell in the heap. This allows malloc
+objects to be freed when the associated heap object is garbage
+collected.
+
+ - Function: static void gc_sweep ()
+ The function `gc_sweep' scans through all heap segments. The mark
+ bit is cleared from marked cells. Unmarked cells are spliced into
+ FREELIST, where they can again be returned by invocations of
+ `NEWCELL'.
+
+ If a type-header cell pointing to malloc space is unmarked, the
+ malloc object is freed. If the type header of smob is collected,
+ the smob's `free' procedure is called to free its storage.
+
+
+File: scm.info, Node: Memory Management for Environments, Next: Signals, Prev: Garbage Collection, Up: Operations
+
+Memory Management for Environments
+----------------------------------
+
+ * "Ecache" was designed and implemented by Radey Shouman.
+
+ * This documentation of ecache was written by Tom Lord.
+
+The memory management component of SCM contains special features which
+optimize the allocation and garbage collection of environments.
+
+The optimizations are based on certain facts and assumptions:
+
+The SCM evaluator creates many environments with short lifetimes and
+these account of a *large portion* of the total number of objects
+allocated.
+
+The general purpose allocator allocates objects from a freelist, and
+collects using a mark/sweep algorithm. Research into garbage
+collection suggests that such an allocator is sub-optimal for object
+populations containing a large portion of short-lived members and that
+allocation strategies involving a copying collector are more
+appropriate.
+
+It is a property of SCM, reflected throughout the source code, that a
+simple copying collector can not be used as the general purpose memory
+manager: much code assumes that the run-time stack can be treated as a
+garbage collection root set using "conservative garbage collection"
+techniques, which are incompatible with objects that change location.
+
+Nevertheless, it is possible to use a mostly-separate
+copying-collector, just for environments. Roughly speaking, cons pairs
+making up environments are initially allocated from a small heap that
+is collected by a precise copying collector. These objects must be
+handled specially for the collector to work. The (presumably) small
+number of these objects that survive one collection of the copying heap
+are copied to the general purpose heap, where they will later be
+collected by the mark/sweep collector. The remaining pairs are more
+rapidly collected than they would otherwise be and all of this
+collection is accomplished without having to mark or sweep any other
+segment of the heap.
+
+Allocating cons pairs for environments from this special heap is a
+heuristic that approximates the (unachievable) goal:
+
+ allocate all short-lived objects from the copying-heap, at no
+ extra cost in allocation time.
+
+Implementation Details
+......................
+
+A separate heap (`ecache_v') is maintained for the copying collector.
+Pairs are allocated from this heap in a stack-like fashion. Objects in
+this heap may be protected from garbage collection by:
+
+ 1. Pushing a reference to the object on a stack specially maintained
+ for that purpose. This stack (`scm_estk') is used in place of the
+ C run-time stack by the SCM evaluator to hold local variables
+ which refer to the copying heap.
+
+ 2. Saving a reference to every object in the mark/sweep heap which
+ directly references the copying heap in a root set that is
+ specially maintained for that purpose (`scm_egc_roots'). If no
+ object in the mark/sweep heap directly references an object from
+ the copying heap, that object can be preserved by storing a direct
+ reference to it in the copying-collector root set.
+
+ 3. Keeping no other references to these objects, except references
+ between the objects themselves, during copying collection.
+
+When the copying heap or root-set becomes full, the copying collector is
+invoked. All protected objects are copied to the mark-sweep heap. All
+references to those objects are updated. The copying collector root-set
+and heap are emptied.
+
+References to pairs allocated specificly for environments are
+inaccessible to the Scheme procedures evaluated by SCM. These pairs
+are manipulated by only a small number of code fragments in the
+interpreter. To support copying collection, those code fragments
+(mostly in `eval.c') have been modified to protect environments from
+garbage collection using the three rules listed above.
+
+During a mark-sweep collection, the copying collector heap is marked
+and swept almost like any ordinary segment of the general purpose heap.
+The only difference is that pairs from the copying heap that become
+free during a sweep phase are not added to the freelist.
+
+The environment cache is disabled by adding `#define NO_ENV_CACHE' to
+`eval.c'; all environment cells are then allocated from the regular
+heap.
+
+Relation to Other Work
+......................
+
+This work seems to build upon a considerable amount of previous work
+into garbage collection techniques about which a considerable amount of
+literature is available.
+
+
+File: scm.info, Node: Signals, Next: C Macros, Prev: Memory Management for Environments, Up: Operations
+
+Signals
+-------
+
+ - Function: init_signals
+ (in `scm.c') initializes handlers for `SIGINT' and `SIGALRM' if
+ they are supported by the C implementation. All of the signal
+ handlers immediately reestablish themselves by a call to
+ `signal()'.
+
+ - Function: int_signal SIG
+ - Function: alrm_signal SIG
+ The low level handlers for `SIGINT' and `SIGALRM'.
+
+If an interrupt handler is defined when the interrupt is received, the
+code is interpreted. If the code returns, execution resumes from where
+the interrupt happened. `Call-with-current-continuation' allows the
+stack to be saved and restored.
+
+SCM does not use any signal masking system calls. These are not a
+portable feature. However, code can run uninterrupted by use of the C
+macros `DEFER_INTS' and `ALLOW_INTS'.
+
+ - Macro: DEFER_INTS
+ sets the global variable `ints_disabled' to 1. If an interrupt
+ occurs during a time when `ints_disabled' is 1, then
+ `deferred_proc' is set to non-zero, one of the global variables
+ `SIGINT_deferred' or `SIGALRM_deferred' is set to 1, and the
+ handler returns.
+
+ - Macro: ALLOW_INTS
+ Checks the deferred variables and if set the appropriate handler is
+ called.
+
+ Calls to `DEFER_INTS' can not be nested. An `ALLOW_INTS' must
+ happen before another `DEFER_INTS' can be done. In order to check
+ that this constraint is satisfied `#define CAREFUL_INTS' in
+ `scmfig.h'.
+
+
+File: scm.info, Node: C Macros, Next: Changing Scm, Prev: Signals, Up: Operations
+
+C Macros
+--------
+
+ - Macro: ASSERT COND ARG POS SUBR
+ signals an error if the expression (COND) is 0. ARG is the
+ offending object, SUBR is the string naming the subr, and POS
+ indicates the position or type of error. POS can be one of
+
+ * `ARGn' (> 5 or unknown ARG number)
+
+ * `ARG1'
+
+ * `ARG2'
+
+ * `ARG3'
+
+ * `ARG4'
+
+ * `ARG5'
+
+ * `WNA' (wrong number of args)
+
+ * `OVFLOW'
+
+ * `OUTOFRANGE'
+
+ * `NALLOC'
+
+ * `EXIT'
+
+ * `HUP_SIGNAL'
+
+ * `INT_SIGNAL'
+
+ * `FPE_SIGNAL'
+
+ * `BUS_SIGNAL'
+
+ * `SEGV_SIGNAL'
+
+ * `ALRM_SIGNAL'
+
+ * a C string `(char *)'
+
+ Error checking is not done by `ASSERT' if the flag `RECKLESS' is
+ defined. An error condition can still be signaled in this case
+ with a call to `wta(arg, pos, subr)'.
+
+ - Macro: ASRTGO COND LABEL
+ `goto' LABEL if the expression (COND) is 0. Like `ASSERT',
+ `ASRTGO' does is not active if the flag `RECKLESS' is defined.
+
+
+File: scm.info, Node: Changing Scm, Next: Defining Subrs, Prev: C Macros, Up: Operations
+
+Changing Scm
+------------
+
+When writing C-code for SCM, a precaution is recommended. If your
+routine allocates a non-cons cell which will *not* be incorporated into
+a `SCM' object which is returned, you need to make sure that a `SCM'
+variable in your routine points to that cell as long as part of it
+might be referenced by your code.
+
+In order to make sure this `SCM' variable does not get optimized out
+you can put this assignment after its last possible use:
+
+ SCM_dummy1 = foo;
+
+or put this assignment somewhere in your routine:
+
+ SCM_dummy1 = (SCM) &foo;
+
+`SCM_dummy' variables are not currently defined. Passing the address
+of the local `SCM' variable to *any* procedure also protects it. The
+procedure `scm_protect_temp' is provided for this purpose.
+
+Also, if you maintain a static pointer to some (non-immediate) `SCM'
+object, you must either make your pointer be the value cell of a symbol
+(see `errobj' for an example) or make your pointer be one of the
+`sys_protects' (see `dynwinds' for an example). The former method is
+prefered since it does not require any changes to the SCM distribution.
+
+To add a C routine to scm:
+
+ 1. choose the appropriate subr type from the type list.
+
+ 2. write the code and put into `scm.c'.
+
+ 3. add a `make_subr' or `make_gsubr' call to `init_scm'. Or put an
+ entry into the appropriate `iproc' structure.
+
+To add a package of new procedures to scm (see `crs.c' for example):
+
+ 1. create a new C file (`foo.c').
+
+ 2. at the front of `foo.c' put declarations for strings for your
+ procedure names.
+
+ static char s_twiddle_bits[]="twiddle-bits!";
+ static char s_bitsp[]="bits?";
+
+ 3. choose the appropriate subr types from the type list in `code.doc'.
+
+ 4. write the code for the procedures and put into `foo.c'
+
+ 5. create one `iproc' structure for each subr type used in `foo.c'
+
+ static iproc subr3s[]= {
+ {s_twiddle-bits,twiddle-bits},
+ {s_bitsp,bitsp},
+ {0,0} };
+
+ 6. create an `init_<name of file>' routine at the end of the file
+ which calls `init_iprocs' with the correct type for each of the
+ `iproc's created in step 5.
+
+ void init_foo()
+ {
+ init_iprocs(subr1s, tc7_subr_1);
+ init_iprocs(subr3s, tc7_subr_3);
+ }
+
+ If your package needs to have a "finalization" routine called to
+ free up storage, close files, etc, then also have a line in
+ `init_foo' like:
+
+ add_final(final_foo);
+
+ `final_foo' should be a (void) procedure of no arguments. The
+ finals will be called in opposite order from their definition.
+
+ The line:
+
+ add_feature("foo");
+
+ will append a symbol `'foo' to the (list) value of `*features*'.
+
+ 7. put any scheme code which needs to be run as part of your package
+ into `Ifoo.scm'.
+
+ 8. put an `if' into `Init5d2.scm' which loads `Ifoo.scm' if your |
+ package is included:
+
+ (if (defined? twiddle-bits!)
+ (load (in-vicinity (implementation-vicinity)
+ "Ifoo"
+ (scheme-file-suffix))))
+
+ or use `(provided? 'foo)' instead of `(defined? twiddle-bits!)'
+ if you have added the feature.
+
+ 9. put documentation of the new procedures into `foo.doc'
+
+ 10. add lines to your `Makefile' to compile and link SCM with your
+ object file. Add a `init_foo\(\)\;' to the `INITS=...' line at
+ the beginning of the makefile.
+
+These steps should allow your package to be linked into SCM with a
+minimum of difficulty. Your package should also work with dynamic
+linking if your SCM has this capability.
+
+Special forms (new syntax) can be added to scm.
+
+ 1. define a new `MAKISYM' in `scm.h' and increment `NUM_ISYMS'.
+
+ 2. add a string with the new name in the corresponding place in
+ `isymnames' in `repl.c'.
+
+ 3. add `case:' clause to `ceval()' near `i_quasiquote' (in `eval.c').
+
+New syntax can now be added without recompiling SCM by the use of the
+`procedure->syntax', `procedure->macro', `procedure->memoizing-macro',
+and `defmacro'. For details, *Note Syntax Extensions::.
+
+
+File: scm.info, Node: Defining Subrs, Next: Defining Smobs, Prev: Changing Scm, Up: Operations
+
+Defining Subrs
+--------------
+
+If "CCLO" is `#define'd when compiling, the compiled closure feature
+will be enabled. It is automatically enabled if dynamic linking is
+enabled.
+
+The SCM interpreter directly recognizes subrs taking small numbers of
+arguments. In order to create subrs taking larger numbers of arguments
+use:
+
+ - Function: make_gsubr NAME REQ OPT REST FCN
+ returns a cclo (compiled closure) object of name `char *' NAME
+ which takes `int' REQ required arguments, `int' OPT optional
+ arguments, and a list of rest arguments if `int' REST is 1 (0 for
+ not).
+
+ `SCM (*fcn)()' is a pointer to a C function to do the work.
+
+ The C function will always be called with REQ + OPT + REST
+ arguments, optional arguments not supplied will be passed
+ `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.
+
+ /* 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);
+ }
+
+
+File: scm.info, Node: Defining Smobs, Next: Defining Ptobs, Prev: Defining Subrs, Up: Operations
+
+Defining Smobs
+--------------
+
+Here is an example of how to add a new type named `foo' to SCM. The
+following lines need to be added to your code:
+
+`long tc16_foo;'
+ The type code which will be used to identify the new type.
+
+`static smobfuns foosmob = {markfoo,freefoo,printfoo,equalpfoo};'
+ smobfuns is a structure composed of 4 functions:
+
+ 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;
+
+ `smob.mark'
+ is a function of one argument of type `SCM' (the cell to
+ mark) and returns type `SCM' which will then be marked. If
+ no further objects need to be marked then return an immediate
+ object such as `BOOL_F'. The smob cell itself will already
+ have been marked. *Note:* This is different from SCM
+ versions prior to 5c5. Only additional data specific to a
+ smob type need be marked by `smob.mark'.
+
+ 2 functions are provided:
+
+ `markcdr(ptr)'
+ returns `CDR(ptr)'.
+
+ `mark0(ptr)'
+ is a no-op used for smobs containing no additional `SCM'
+ data. 0 may also be used in this case.
+
+ `smob.free'
+ is a function of one argument of type `CELLPTR' (the cell to
+ collected) and returns type `sizet' which is the number of
+ `malloc'ed bytes which were freed. `Smob.free' should free
+ any `malloc'ed storage associated with this object. The
+ function free0(ptr) is provided which does not free any
+ storage and returns 0.
+
+ `smob.print'
+ is 0 or a function of 3 arguments. The first, of type `SCM',
+ is the smob object. The second, of type `SCM', is the stream
+ on which to write the result. The third, of type int, is 1
+ if the object should be `write'n, 0 if it should be
+ `display'ed. This function should return non-zero if it
+ printed, and zero otherwise (in which case a hexadecimal
+ number will be printed).
+
+ `smob.equalp'
+ is 0 or a function of 2 `SCM' arguments. Both of these
+ arguments will be of type `tc16foo'. This function should
+ return `BOOL_T' if the smobs are equal, `BOOL_F' if they are
+ not. If `smob.equalp' is 0, `equal?' will return `BOOL_F' if
+ they are not `eq?'.
+
+`tc16_foo = newsmob(&foosmob);'
+ Allocates the new type with the functions from `foosmob'. This
+ line goes in an `init_' routine.
+
+Promises and macros in `eval.c' and arbiters in `repl.c' provide
+examples of SMOBs. There are a maximum of 256 SMOBs. Smobs that must
+allocate blocks of memory should use, for example, `must_malloc' rather
+than `malloc' *Note Allocating memory::.
+
+
+File: scm.info, Node: Defining Ptobs, Next: Allocating memory, Prev: Defining Smobs, Up: Operations
+
+Defining Ptobs
+--------------
+
+"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 `ptobfuns':
+
+ 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;
+
+The `.free' component to the structure takes a `FILE *' or other C
+construct as its argument, unlike `.free' in a smob, which takes the
+whole smob cell. Often, `.free' and `.fclose' can be the same
+function. See `fptob' and `pipob' in `sys.c' for examples of how to
+define ptobs. Ptobs that must allocate blocks of memory should use,
+for example, `must_malloc' rather than `malloc' *Note Allocating
+memory::.
+
+
+File: scm.info, Node: Allocating memory, Next: Embedding SCM, Prev: Defining Ptobs, Up: Operations
+
+Allocating memory
+-----------------
+
+SCM maintains a count of bytes allocated using malloc, and calls the
+garbage collector when that number exceeds a dynamically managed limit.
+In order for this to work properly, `malloc' and `free' should not be
+called directly to manage memory freeable by garbage collection. The
+following functions are provided for that purpose:
+
+ - Function: SCM must_malloc_cell (long LEN, SCM C, char *WHAT)
+ - Function: char * must_malloc (long LEN, char *WHAT)
+ LEN is the number of bytes that should be allocated, WHAT is a
+ string to be used in error or gc messages. `must_malloc' returns
+ a pointer to newly allocated memory. `must_malloc_cell' returns a
+ newly allocated cell whose `car' is C and whose `cdr' is a pointer
+ to newly allocated memory.
+
+ - Function: void must_realloc_cell (SCM Z, long OLEN, long LEN, char
+ *WHAT)
+ - Function: char * must_realloc (char *WHERE, long OLEN, long LEN,
+ char *WHAT)
+ `must_realloc_cell' takes as argument Z a cell whose `cdr' should
+ be a pointer to a block of memory of length OLEN allocated with
+ `must_malloc_cell' and modifies the `cdr' to point to a block of
+ memory of length LEN. `must_realloc' takes as argument WHERE the
+ address of a block of memory of length OLEN allocated by
+ `must_malloc' and returns the address of a block of length LEN.
+
+ The contents of the reallocated block will be unchanged up the the
+ minimum of the old and new sizes.
+
+ WHAT is a pointer to a string used for error and gc messages.
+
+`must_malloc', `must_malloc_cell', `must_realloc', and
+`must_realloc_cell' must be called with interrupts deferred *Note
+Signals::.
+
+ - Function: void must_free (char *PTR, sizet LEN)
+ `must_free' is used to free a block of memory allocated by the
+ above functions and pointed to by PTR. LEN is the length of the
+ block in bytes, but this value is used only for debugging purposes.
+ If it is difficult or expensive to calculate then zero may be used
+ instead.
+
+
+File: scm.info, Node: Embedding SCM, Next: Callbacks, Prev: Allocating memory, Up: Operations
+
+Embedding SCM
+-------------
+
+The file `scmmain.c' contains the definition of main(). When SCM is
+compiled as a library `scmmain.c' is not included in the library; a
+copy of `scmmain.c' can be modified to use SCM as an embedded library
+module.
+
+ - Function: int main (int ARGC, char **ARGV)
+ This is the top level C routine. The value of the ARGC argument
+ is the number of command line arguments. The ARGV argument is a
+ vector of C strings; its elements are the individual command line
+ argument strings. A null pointer always follows the last element:
+ `ARGV[ARGC]' is this null pointer.
+
+ - Variable: char *execpath
+ This string is the pathname of the executable file being run. This
+ variable can be examined and set from Scheme (*note Internal
+ State::.). EXECPATH must be set to executable's path in order to
+ use DUMP (*note Dump::.) or DLD.
+
+Rename main() and arrange your code to call it with an ARGV which sets
+up SCM as you want it.
+
+If you need more control than is possible through ARGV, here are
+descriptions of the functions which main() calls.
+
+ - Function: void init_sbrk (void)
+ Call this before SCM calls malloc(). Value returned from sbrk()
+ is used to gauge how much storage SCM uses.
+
+ - Function: char * scm_find_execpath (int ARGC, char **ARGV, char
+ *SCRIPT_ARG)
+ ARGC and ARGV are as described in main(). SCRIPT_ARG is the
+ pathname of the SCSH-style script (*note Scripting::.) being
+ invoked; 0 otherwise. `scm_find_execpath' returns the pathname of
+ the executable being run; if `scm_find_execpath' cannot determine
+ the pathname, then it returns 0.
+
+`scm_find_implpath' is defined in `scmmain.c'. Preceeding this are
+definitions ofGENERIC_NAME and INIT_GETENV. These, along with IMPLINIT
+and DIRSEP control scm_find_implpath()'s operation.
+
+If your application has an easier way to locate initialization code for
+SCM, then you can replace `scm_find_implpath'.
+
+ - Function: char * scm_find_implpath (char *EXECPATH)
+ Returns the full pathname of the Scheme initialization file or 0
+ if it cannot find it.
+
+ The string value of the preprocessor variable INIT_GETENV names an
+ environment variable (default `"SCM_INIT_PATH"'). If this
+ environment variable is defined, its value will be returned from
+ `scm_find_implpath'. Otherwise find_impl_file() is called with the
+ arguments EXECPATH, GENERIC_NAME (default "scm"), INIT_FILE_NAME
+ (default "Init5d2_scm"), and the directory separator string |
+ DIRSEP. If find_impl_file() returns 0 and IMPLINIT is defined,
+ then a copy of the string IMPLINIT is returned.
+
+ - Function: int init_buf0 (FILE *INPORT)
+ Tries to determine whether INPORT (usually stdin) is an
+ interactive input port which should be used in an unbuffered mode.
+ If so, INPORT is set to unbuffered and non-zero is returned.
+ Otherwise, 0 is returned.
+
+ `init_buf0' should be called before any input is read from INPORT.
+ Its value can be used as the last argument to
+ scm_init_from_argv().
+
+ - Function: void scm_init_from_argv (int ARGC, char **ARGV, char
+ *SCRIPT_ARG, int IVERBOSE, int BUF0STDIN)
+ Initializes SCM storage and creates a list of the argument strings
+ PROGRAM-ARGUMENTS from ARGV. ARGC and ARGV must already be
+ processed to accomodate Scheme Scripts (if desired). The scheme
+ variable *SCRIPT* is set to the string SCRIPT_ARG, or #f if
+ SCRIPT_ARG is 0. IVERBOSE is the initial prolixity level. If
+ BUF0STDIN is non-zero, stdin is treated as an unbuffered port.
+
+Call `init_signals' and `restore_signals' only if you want SCM to
+handle interrupts and signals.
+
+ - Function: void init_signals (void)
+ Initializes handlers for `SIGINT' and `SIGALRM' if they are
+ supported by the C implementation. All of the signal handlers
+ immediately reestablish themselves by a call to `signal()'.
+
+ - Function: void restore_signals (void)
+ Restores the handlers in effect when `init_signals' was called.
+
+ - Function: SCM scm_top_level (char *INITPATH, SCM (*toplvl_fun)())
+ This is SCM's top-level. Errors longjmp here. TOPLVL_FUN is a
+ callback function of zero arguments that is called by
+ `scm_top_level' to do useful work - if zero, then `repl', which
+ implements a read-eval-print loop, is called.
+
+ If TOPLVL_FUN returns, then `scm_top_level' will return as well.
+ If the return value of TOPLVL_FUN is an immediate integer then it
+ will be used as the return value of `scm_top_level'. In the main
+ function supplied with SCM, this return value is the exit status
+ of the process.
+
+ If the first character of string INITPATH is `;', `(' or
+ whitespace, then scm_ldstr() is called with INITPATH to initialize
+ SCM; otherwise INITPATH names a file of Scheme code to be loaded
+ to initialize SCM.
+
+ When a Scheme error is signaled; control will pass into
+ `scm_top_level' by `longjmp', error messages will be printed to
+ `current-error-port', and then TOPLVL_FUN will be called again.
+ TOPLVL_FUN must maintain enough state to prevent errors from being
+ resignalled. If `toplvl_fun' can not recover from an error
+ situation it may simply return.
+
+ - Function: void final_scm (int FREEALL)
+ Calls all finalization routines registered with add_final(). If
+ FREEALL is non-zero, then all memory which SCM allocated with
+ malloc() will be freed.
+
+You can call indivdual Scheme procedures from C code in the TOPLVL_FUN
+argument passed to scm_top_level(), or from module subrs (registered by
+an `init_' function, *note Changing Scm::.).
+
+Use `apply' to call Scheme procedures from your C code. For example:
+
+ /* If this apply fails, SCM will catch the error */
+ apply(CDR(intern("srv:startup",sizeof("srv:startup")-1)),
+ mksproc(srvproc),
+ listofnull);
+
+ func = CDR(intern(rpcname,strlen(rpcname)));
+ retval = apply(func, cons(mksproc(srvproc), args), EOL);
+
+Functions for loading Scheme files and evaluating Scheme code given as
+C strings are described in the next section, (*note Callbacks::.).
+
+Here is a minimal embedding program `libtest.c':
+
+ /* gcc -o libtest libtest.c libscm.a -ldl -lm -lc */
+ #include "scm.h"
+ /* include patchlvl.h for SCM's INIT_FILE_NAME. */
+ #include "patchlvl.h"
+
+ void init_user_scm()
+ {
+ fputs("This is init_user_scm\n", stderr); fflush(stderr);
+ sysintern("*the-string*", makfrom0str("hello world\n"));
+ }
+
+ SCM user_main()
+ {
+ static int done = 0;
+ if (done++) return MAKINUM(EXIT_FAILURE);
+ scm_ldstr("(display *the-string*)");
+ return MAKINUM(EXIT_SUCCESS);
+ }
+
+ int main(argc, argv)
+ int argc;
+ char **argv;
+ {
+ SCM retval;
+ char *implpath, *execpath;
+
+ execpath = dld_find_executable(argv[0]);
+ fprintf(stderr, "dld_find_executable(%s): %s\n", argv[0], execpath);
+ implpath = find_impl_file(execpath, "scm", INIT_FILE_NAME, dirsep);
+ fprintf(stderr, "implpath: %s\n", implpath);
+ scm_init_from_argv(argc, argv, 0, 0);
+
+ retval = scm_top_level(implpath, user_main);
+
+ final_scm(!0);
+ return (int)INUM(retval);
+ }
+
+ -|
+ dld_find_executable(./libtest): /home/jaffer/scm/libtest
+ implpath: /home/jaffer/scm/Init5d2.scm |
+ This is init_user_scm
+ hello world
+
+
+File: scm.info, Node: Callbacks, Next: Type Conversions, Prev: Embedding SCM, Up: Operations
+
+Callbacks
+---------
+
+SCM now has routines to make calling back to Scheme procedures easier.
+The source code for these routines are found in `rope.c'.
+
+ - Function: int scm_ldfile (char *FILE)
+ Loads the Scheme source file FILE. Returns 0 if successful, non-0
+ if not. This function is used to load SCM's initialization file
+ `Init5d2.scm'. |
+
+ - Function: int scm_ldprog (char *FILE)
+ Loads the Scheme source file `(in-vicinity (program-vicinity)
+ FILE)'. Returns 0 if successful, non-0 if not.
+
+ This function is useful for compiled code init_ functions to load
+ non-compiled Scheme (source) files. `program-vicinity' is the
+ directory from which the calling code was loaded (*note Vicinity:
+ (slib)Vicinity.).
+
+ - Function: SCM scm_evstr (char *STR)
+ Returns the result of reading an expression from STR and
+ evaluating it.
+
+ - Function: void scm_ldstr (char *STR)
+ Reads and evaluates all the expressions from STR.
+
+If you wish to catch errors during execution of Scheme code, then you
+can use a wrapper like this for your Scheme procedures:
+
+ (define (srv:protect proc)
+ (lambda args
+ (define result #f) ; put default value here
+ (call-with-current-continuation
+ (lambda (cont)
+ (dynamic-wind (lambda () #t)
+ (lambda ()
+ (set! result (apply proc args))
+ (set! cont #f))
+ (lambda ()
+ (if cont (cont #f))))))
+ result))
+
+Calls to procedures so wrapped will return even if an error occurs.
+
+
+File: scm.info, Node: Type Conversions, Next: Continuations, Prev: Callbacks, Up: Operations
+
+Type Conversions
+----------------
+
+These type conversion functions are very useful for connecting SCM and C
+code. Most are defined in `rope.c'.
+
+ - Function: SCM long2num (long N)
+ - Function: SCM ulong2num (unsigned long N)
+ Return an object of type `SCM' corresponding to the `long' or
+ `unsigned long' argument N. If N cannot be converted, `BOOL_F' is
+ returned. Which numbers can be converted depends on whether SCM
+ was compiled with the `BIGDIG' or `FLOATS' flags.
+
+ To convert integer numbers of smaller types (`short' or `char'),
+ use the macro `MAKINUM(n)'.
+
+ - Function: long num2long (SCM NUM, char *POS, char *S_CALLER)
+ - Function: unsigned long num2ulong (SCM NUM, char *POS, char
+ *S_CALLER)
+ - Function: unsigned short num2ushort (SCM NUM, char *POS, char
+ *S_CALLER)
+ - Function: unsigned char num2uchar (SCM NUM, char *POS, char
+ *S_CALLER)
+ These functions are used to check and convert `SCM' arguments to
+ the named C type. The first argument NUM is checked to see it it
+ is within the range of the destination type. If so, the converted
+ number is returned. If not, the `ASSERT' macro calls `wta' with
+ NUM and strings POS and S_CALLER. For a listing of useful
+ predefined POS macros, *Note C Macros::.
+
+ *Note:* Inexact numbers are accepted only by `num2long' and
+ `num2ulong' (for when `SCM' is compiled without bignums). To
+ convert inexact numbers to exact numbers, *Note inexact->exact:
+ (r5rs)Numerical operations.
+
+ - Function: unsigned long scm_addr (SCM ARGS, char *S_NAME)
+ Returns a pointer (cast to an `unsigned long') to the storage
+ corresponding to the location accessed by
+ `aref(CAR(args),CDR(args))'. The string S_NAME is used in any
+ messages from error calls by `scm_addr'.
+
+ `scm_addr' is useful for performing C operations on strings or
+ other uniform arrays (*note Uniform Array::.).
+
+ *Note:* While you use a pointer returned from `scm_addr' you must
+ keep a pointer to the associated `SCM' object in a stack allocated
+ variable or GC-protected location in order to assure that SCM does
+ not reuse that storage before you are done with it.
+
+ - Function: SCM makfrom0str (char *SRC)
+ - Function: SCM makfromstr (char *SRC, sizet LEN)
+ Return a newly allocated string `SCM' object copy of the
+ null-terminated string SRC or the string SRC of length LEN,
+ respectively.
+
+ - Function: SCM makfromstrs (int ARGC, char **ARGV)
+ Returns a newly allocated `SCM' list of strings corresponding to
+ the ARGC length array of null-terminated strings ARGV. If ARGV is
+ less than `0', ARGV is assumed to be `NULL' terminated.
+ `makfromstrs' is used by `scm_init_from_argv' to convert the
+ arguments SCM was called with to a `SCM' list which is the value
+ of SCM procedure calls to `program-arguments' (*note
+ program-arguments: SCM Session.).
+
+ - Function: char ** makargvfrmstrs (SCM ARGS, char *S_NAME)
+ Returns a `NULL' terminated list of null-terminated strings copied
+ from the `SCM' list of strings ARGS. The string S_NAME is used in
+ messages from error calls by `makargvfrmstrs'.
+
+ `makargvfrmstrs' is useful for constructing argument lists suitable
+ for passing to `main' functions.
+
+ - Function: void must_free_argv (char **ARGV)
+ Frees the storage allocated to create ARGV by a call to
+ `makargvfrmstrs'.
+
+
+File: scm.info, Node: Continuations, Next: Evaluation, Prev: Type Conversions, Up: Operations
+
+Continuations
+-------------
+
+The source files `continue.h' and `continue.c' are designed to function
+as an independent resource for programs wishing to use continuations,
+but without all the rest of the SCM machinery. The concept of
+continuations is explained in *Note call-with-current-continuation:
+(r5rs)Control features.
+
+The C constructs `jmp_buf', `setjmp', and `longjmp' implement escape
+continuations. On VAX and Cray platforms, the setjmp provided does not
+save all the registers. The source files `setjump.mar', `setjump.s',
+and `ugsetjump.s' provide implementations which do meet this criteria.
+
+SCM uses the names `jump_buf', `setjump', and `longjump' in lieu of
+`jmp_buf', `setjmp', and `longjmp' to prevent name and declaration
+conflicts.
+
+ - Data type: CONTINUATION jmpbuf length stkbse other parent
+ is a `typedef'ed structure holding all the information needed to
+ represent a continuation. The OTHER slot can be used to hold any
+ data the user wishes to put there by defining the macro
+ `CONTINUATION_OTHER'.
+
+ - Macro: SHORT_ALIGN
+ If `SHORT_ALIGN' is `#define'd (in `scmfig.h'), then the it is
+ assumed that pointers in the stack can be aligned on `short int'
+ boundaries.
+
+ - Data type: STACKITEM
+ is a pointer to objects of the size specified by `SHORT_ALIGN'
+ being `#define'd or not.
+
+ - Macro: CHEAP_CONTINUATIONS
+ If `CHEAP_CONTINUATIONS' is `#define'd (in `scmfig.h') each
+ `CONTINUATION' has size `sizeof CONTINUATION'. Otherwise, all but
+ "root" `CONTINUATION's have additional storage (immediately
+ following) to contain a copy of part of the stack.
+
+ *Note:* On systems with nonlinear stack disciplines (multiple
+ stacks or non-contiguous stack frames) copying the stack will not
+ work properly. These systems need to #define
+ `CHEAP_CONTINUATIONS' in `scmfig.h'.
+
+ - Macro: STACK_GROWS_UP
+ Expresses which way the stack grows by its being `#define'd or not.
+
+ - Variable: long thrown_value
+ Gets set to the VALUE passed to `throw_to_continuation'.
+
+ - Function: long stack_size (STACKITEM *START)
+ Returns the number of units of size `STACKITEM' which fit between
+ START and the current top of stack. No check is done in this
+ routine to ensure that START is actually in the current stack
+ segment.
+
+ - Function: CONTINUATION * make_root_continuation (STACKITEM
+ *STACK_BASE)
+ Allocates (`malloc') storage for a `CONTINUATION' of the current
+ extent of stack. This newly allocated `CONTINUATION' is returned
+ if successful, `0' if not. After `make_root_continuation'
+ returns, the calling routine still needs to
+ `setjump(NEW_CONTINUATION->jmpbuf)' in order to complete the
+ capture of this continuation.
+
+ - Function: CONTINUATION * make_continuation (CONTINUATION
+ *PARENT_CONT)
+ Allocates storage for the current `CONTINUATION', copying (or
+ encapsulating) the stack state from `PARENT_CONT->stkbse' to the
+ current top of stack. The newly allocated `CONTINUATION' is
+ returned if successful, `0'q if not. After `make_continuation'
+ returns, the calling routine still needs to
+ `setjump(NEW_CONTINUATION->jmpbuf)' in order to complete the
+ capture of this continuation.
+
+ - Function: void free_continuation (CONTINUATION *CONT)
+ Frees the storage pointed to by CONT. Remember to free storage
+ pointed to by `CONT->other'.
+
+ - Function: void throw_to_continuation (CONTINUATION *CONT, long
+ VALUE, CONTINUATION *ROOT_CONT)
+ Sets `thrown_value' to VALUE and returns from the continuation
+ CONT.
+
+ If `CHEAP_CONTINUATIONS' is `#define'd, then
+ `throw_to_continuation' does `longjump(CONT->jmpbuf, val)'.
+
+ If `CHEAP_CONTINUATIONS' is not `#define'd, the CONTINUATION CONT
+ contains a copy of a portion of the C stack (whose bound must be
+ `CONT(ROOT_CONT)->stkbse'). Then:
+
+ * the stack is grown larger than the saved stack, if neccessary.
+
+ * the saved stack is copied back into it's original position.
+
+ * `longjump(CONT->jmpbuf, val)';
+
+
+File: scm.info, Node: Evaluation, Prev: Continuations, Up: Operations
+
+Evaluation
+----------
+
+SCM uses its type representations to speed evaluation. All of the
+`subr' types (*note Subr Cells::.) are `tc7' types. Since the `tc7'
+field is in the low order bit position of the `CAR' it can be retrieved
+and dispatched on quickly by dereferencing the SCM pointer pointing to
+it and masking the result.
+
+All the SCM "Special Forms" get translated to immediate symbols
+(`isym') the first time they are encountered by the interpreter
+(`ceval'). The representation of these immediate symbols is engineered
+to occupy the same bits as `tc7'. All the `isym's occur only in the
+`CAR' of lists.
+
+If the `CAR' of a expression to evaluate is not immediate, then it may
+be a symbol. If so, the first time it is encountered it will be
+converted to an immediate type `ILOC' or `GLOC' (*note Immediates::.).
+The codes for `ILOC' and `GLOC' lower 7 bits distinguish them from all
+the other types we have discussed.
+
+Once it has determined that the expression to evaluate is not immediate,
+`ceval' need only retrieve and dispatch on the low order 7 bits of the
+`CAR' of that cell, regardless of whether that cell is a closure,
+header, or subr, or a cons containing `ILOC' or `GLOC'.
+
+In order to be able to convert a SCM symbol pointer to an immediate
+`ILOC' or `GLOC', the evaluator must be holding the pointer to the list
+in which that symbol pointer occurs. Turning this requirement to an
+advantage, `ceval' does not recursively call itself to evaluate symbols
+in lists; It instead calls the macro "EVALCAR". `EVALCAR' does symbol
+lookup and memoization for symbols, retrieval of values for `ILOC's and
+`GLOC's, returns other immediates, and otherwise recursively calls
+itself with the `CAR' of the list.
+
+`ceval' inlines evaluation (using `EVALCAR') of almost all procedure
+call arguments. When `ceval' needs to evaluate a list of more than
+length 3, the procedure `eval_args' is called. So `ceval' can be said
+to have one level lookahead. The avoidance of recursive invocations of
+`ceval' for the most common cases (special forms and procedure calls)
+results in faster execution. The speed of the interpreter is currently
+limited on most machines by interpreter size, probably having to do
+with its cache footprint. In order to keep the size down, certain
+`EVALCAR' calls which don't need to be fast (because they rarely occur
+or because they are part of expensive operations) are instead calls to
+the C function `evalcar'.
+
+ - Variable: symhash
+ Top level symbol values are stored in the `symhash' table.
+ `symhash' is an array of lists of `ISYM's and pairs of symbols and
+ values.
+
+ - Immediate: ILOC
+ Whenever a symbol's value is found in the local environment the
+ pointer to the symbol in the code is replaced with an immediate
+ object (`ILOC') which specifies how many environment frames down
+ and how far in to go for the value. When this immediate object is
+ subsequently encountered, the value can be retrieved quickly.
+
+`ILOC's work up to a maximum depth of 4096 frames or 4096 identifiers
+in a frame. Radey Shouman added "FARLOC" to handle cases exceeding
+these limits. A `FARLOC' consists of a pair whose CAR is the immediate
+type `IM_FARLOC_CAR' or `IM_FARLOC_CDR', and whose CDR is a pair of
+INUMs specifying the frame and distance with a larger range than
+`ILOC's span.
+
+Adding `#define TEST_FARLOC' to `eval.c' causes `FARLOC's to be
+generated for all local identifiers; this is useful only for testing
+memoization.
+
+ - Immediate: GLOC
+ Pointers to symbols not defined in local environments are changed
+ to one plus the value cell address in symhash. This incremented
+ pointer is called a `GLOC'. The low order bit is normally
+ reserved for GCmark; But, since references to variables in the
+ code always occur in the `CAR' position and the GCmark is in the
+ `CDR', there is no conflict.
+
+If the compile FLAG `CAUTIOUS' is #defined then the number of arguments
+is always checked for application of closures. If the compile FLAG
+`RECKLESS' is #defined then they are not checked. Otherwise, number of
+argument checks for closures are made only when the function position
+(whose value is the closure) of a combination is not an `ILOC' or
+`GLOC'. When the function position of a combination is a symbol it
+will be checked only the first time it is evaluated because it will
+then be replaced with an `ILOC' or `GLOC'.
+
+ - Macro: EVAL EXPRESSION ENV
+ - Macro: SIDEVAL EXPRESSION ENV
+ `EVAL' Returns the result of evaluating EXPRESSION in ENV.
+ `SIDEVAL' evaluates EXPRESSION in ENV when the value of the
+ expression is not used.
+
+ Both of these macros alter the list structure of EXPRESSION as it
+ is memoized and hence should be used only when it is known that
+ EXPRESSION will not be referenced again. The C function `eval' is
+ safe from this problem.
+
+ - Function: SCM eval (SCM EXPRESSION)
+ Returns the result of evaluating EXPRESSION in the top-level
+ environment. `eval' copies `expression' so that memoization does
+ not modify `expression'.
+
+
+File: scm.info, Node: Program Self-Knowledge, Next: Improvements To Make, Prev: Operations, Up: The Implementation
+
+Program Self-Knowledge
+======================
+
+* Menu:
+
+* File-System Habitat::
+* Executable Pathname::
+* Script Support::
+
+
+File: scm.info, Node: File-System Habitat, Next: Executable Pathname, Prev: Program Self-Knowledge, Up: Program Self-Knowledge
+
+File-System Habitat
+-------------------
+
+Where should software reside? Although individually a minor annoyance,
+cumulatively this question represents many thousands of frustrated user
+hours spent trying to find support files or guessing where packages need
+to be installed. Even simple programs require proper habitat; games
+need to find their score files.
+
+Aren't there standards for this? Some Operating Systems have devised
+regimes of software habitats - only to have them violated by large
+software packages and imports from other OS varieties.
+
+In some programs, the expected locations of support files are fixed at
+time of compilation. This means that the program may not run on
+configurations unanticipated by the authors. Compiling locations into a
+program also can make it immovable - necessitating recompilation to
+install it.
+
+ Programs of the world unite! You have nothing to lose but loss
+ itself.
+
+The function `find_impl_file' in `scm.c' is an attempt to create a
+utility (for inclusion in programs) which will hide the details of
+platform-dependent file habitat conventions. It takes as input the
+pathname of the executable file which is running. If there are systems
+for which this information is either not available or unrelated to the
+locations of support files, then a higher level interface will be
+needed.
+
+ - Function: char * find_impl_file (char *EXEC_PATH, char
+ *GENERIC_NAME, char *INITNAME, char *SEP)
+ Given the pathname of this executable (EXEC_PATH), test for the
+ existence of INITNAME in the implementation-vicinity of this
+ program. Return a newly allocated string of the path if
+ successful, 0 if not. The SEP argument is a *null-terminated
+ string* of the character used to separate directory components.
+
+ * One convention is to install the support files for an executable
+ program in the same directory as the program. This possibility is
+ tried first, which satisfies not only programs using this
+ convention, but also uninstalled builds when testing new releases,
+ etc.
+
+ * Another convention is to install the executables in a directory
+ named `bin', `BIN', `exe', or `EXE' and support files in a
+ directroy named `lib', which is a peer the executable directory.
+ This arrangement allows multiple executables can be stored in a
+ single directory. For example, the executable might be in
+ `/usr/local/bin/' and initialization file in `/usr/local/lib/'.
+
+ If the executable directory name matches, the peer directroy `lib'
+ is tested for INITNAME.
+
+ * Sometimes `lib' directories become too crowded. So we look in any
+ subdirectories of `lib' or `src' having the name (sans type suffix
+ such as `.EXE') of the program we are running. For example, the
+ executable might be `/usr/local/bin/foo' and initialization file
+ in `/usr/local/lib/foo/'.
+
+ * But the executable name may not be the usual program name; So also
+ look in any GENERIC_NAME subdirectories of `lib' or `src' peers.
+
+ * Finally, if the name of the executable file being run has a (system
+ dependent) suffix which is not needed to invoke the program, then
+ look in a subdirectory (of the one containing the executable file)
+ named for the executable (without the suffix); And look in a
+ GENERIC_NAME subdirectory. For example, the executable might be
+ `C:\foo\bar.exe' and the initialization file in `C:\foo\bar\'.
+
+
+File: scm.info, Node: Executable Pathname, Next: Script Support, Prev: File-System Habitat, Up: Program Self-Knowledge
+
+Executable Pathname
+-------------------
+
+For purposes of finding `Init5d2.scm', dumping an executable, and |
+dynamic linking, a SCM session needs the pathname of its executable
+image.
+
+When a program is executed by MS-DOS, the full pathname of that
+executable is available in `argv[0]'. This value can be passed
+directly to `find_impl_file' (*note File-System Habitat::.).
+
+In order to find the habitat for a unix program, we first need to know
+the full pathname for the associated executable file.
+
+ - Function: char * dld_find_executable (const char *COMMAND)
+ `dld_find_executable' returns the absolute path name of the file
+ that would be executed if COMMAND were given as a command. It
+ looks up the environment variable PATH, searches in each of the
+ directory listed for COMMAND, and returns the absolute path name
+ for the first occurrence. Thus, it is advisable to invoke
+ `dld_init' as:
+
+ main (int argc, char **argv)
+ {
+ ...
+ if (dld_init (dld_find_executable (argv[0]))) {
+ ...
+ }
+ ...
+ }
+
+ *Note:* If the current process is executed using the `execve'
+ call without passing the correct path name as argument 0,
+ `dld_find_executable (argv[0]) ' will also fail to locate the
+ executable file.
+
+ `dld_find_executable' returns zero if `command' is not found in
+ any of the directories listed in `PATH'.
+
+
+File: scm.info, Node: Script Support, Prev: Executable Pathname, Up: Program Self-Knowledge
+
+Script Support
+--------------
+
+Source code for these C functions is in the file `script.c'. *Note
+Scripting:: for a description of script argument processing.
+
+`script_find_executable' is only defined on unix systems.
+
+ - Function: char * script_find_executable (const char *NAME)
+ `script_find_executable' returns the path name of the executable
+ which is invoked by the script file NAME; NAME if it is a binary
+ executable (not a script); or 0 if NAME does not exist or is not
+ executable.
+
+ - Function: char ** script_process_argv (int ARGC; char **ARGV)
+ Given an "main" style argument vector ARGV and the number of
+ arguments, ARGC, `script_process_argv' returns a newly allocated
+ argument vector in which the second line of the script being
+ invoked is substituted for the corresponding meta-argument.
+
+ If the script does not have a meta-argument, or if the file named
+ by the argument following a meta-argument cannot be opened for
+ reading, then 0 is returned.
+
+ `script_process_argv' correctly processes argument vectors of
+ nested script invocations.
+
+ - Function: int script_count_argv (char **ARGV)
+ Returns the number of argument strings in ARGV.
+
+
+File: scm.info, Node: Improvements To Make, Prev: Program Self-Knowledge, Up: The Implementation
+
+Improvements To Make
+====================
+
+ * Allow users to set limits for `malloc()' storage.
+
+ * Prefix and make more uniform all C function, variable, and constant
+ names. Provide a file full of #define's to provide backward
+ compatability.
+
+ * `lgcd()' *needs* to generate at most one bignum, but currently
+ generates more.
+
+ * `divide()' could use shifts instead of multiply and divide when
+ scaling.
+
+ * Currently, `dump'ing an executable does not preserve ports. When
+ loading a `dump'ed executable, disk files could be reopened to the
+ same file and position as they had when the executable was dumped.
+
+ * Copying all of the stack is wasteful of storage. Any time a
+ call-with-current-continuation is called the stack could be
+ re-rooted with a frame which calls the contin just created. This
+ in combination with checking stack depth could also be used to
+ allow stacks deeper than 64K on the IBM PC.
+
+ * In the quest for speed, there has been some discussion about a
+ "Forth" style Scheme interpreter.
+
+ Provided there is still type code space available in SCM, if
+ we devote some of the IMCAR codes to "inlined" operations, we
+ should get a significant performance boost. What is
+ eliminated is the having to look up a `GLOC' or `ILOC' and
+ then dispatch on the subr type. The IMCAR operation would be
+ dispatched to directly. Another way to view this is that we
+ make available special form versions of `CAR', `CDR', etc.
+ Since the actual operation code is localized in the
+ interpreter, it is much easier than uncompilation and then
+ recompilation to handle `(trace car)'; For instance a switch
+ gets set which tells the interpreter to instead always look
+ up the values of the associated symbols.
+
+* Menu:
+
+* Finishing Dynamic Linking::
+
+
+File: scm.info, Node: Finishing Dynamic Linking, Prev: Improvements To Make, Up: Improvements To Make
+
+Finishing Dynamic Linking
+-------------------------
+
+Scott Schwartz <schwartz@galapagos.cse.psu.edu> suggests: One way to
+tidy up the dynamic loading stuff would be to grab the code from perl5.
+
+VMS
+...
+
+George Carrette (gjc@mitech.com) outlines how to dynamically link on
+VMS. There is already some code in `dynl.c' to do this, but someone
+with a VMS system needs to finish and debug it.
+
+ 1. Say you have this `main.c' program:
+
+ main()
+ {init_lisp();
+ lisp_repl();}
+
+ 2. and you have your lisp in files `repl.c', `gc.c', `eval.c' and
+ there are some toplevel non-static variables in use called
+ `the_heap', `the_environment', and some read-only toplevel
+ structures, such as `the_subr_table'.
+
+ $ LINK/SHARE=LISPRTL.EXE/DEBUG REPL.OBJ,GC.OBJ,EVAL.OBJ,LISPRTL.OPT/OPT
+
+ 3. where `LISPRTL.OPT' must contain at least this:
+
+ SYS$LIBRARY:VAXCRTL/SHARE
+ UNIVERSAL=init_lisp
+ UNIVERSAL=lisp_repl
+ PSECT_ATTR=the_subr_table,SHR,NOWRT,LCL
+ PSECT_ATTR=the_heap,NOSHR,LCL
+ PSECT_ATTR=the_environment,NOSHR,LCL
+
+ *Notice:* The "psect" (Program Section) attributes.
+ `LCL'
+ means to keep the name local to the shared library. You
+ almost always want to do that for a good clean library.
+
+ `SHR,NOWRT'
+ means shared-read-only. Which is the default for code, and
+ is also good for efficiency of some data structures.
+
+ `NOSHR,LCL'
+ is what you want for everything else.
+
+ Note: If you do not have a handy list of all these toplevel
+ variables, do not dispair. Just do your link with the
+ /MAP=LISPRTL.MAP/FULL and then search the map file,
+
+ $SEARCH/OUT=LISPRTL.LOSERS LISPRTL.MAP ", SHR,NOEXE, RD, WRT"
+
+ And use an emacs keyboard macro to muck the result into the proper
+ form. Of course only the programmer can tell if things can be
+ made read-only. I have a DCL command procedure to do this if you
+ want it.
+
+ 4. Now MAIN.EXE would be linked thusly:
+
+ $ DEFINE LISPRTL USER$DISK:[JAFFER]LISPRTL.EXE
+
+ $LINK MAIN.OBJ,SYS$INPUT:/OPT
+ SYS$LIBRARY:VAXCRTL/SHARE
+ LISPRTL/SHARE
+
+ Note the definition of the `LISPRTL' logical name. Without such a
+ definition you will need to copy `LISPRTL.EXE' over to
+ `SYS$SHARE:' (aka `SYS$LIBRARY:') in order to invoke the main
+ program once it is linked.
+
+ 5. Now say you have a file of optional subrs, `MYSUBRS.C'. And there
+ is a routine `INIT_MYSUBRS' that must be called before using it.
+
+ $ CC MYSUBRS.C
+ $ LINK/SHARE=MYSUBRS.EXE MYSUBRS.OBJ,SYS$INPUT:/OPT
+ SYS$LIBRARY:VAXCRTL/SHARE
+ LISPRTL/SHARE
+ UNIVERSAL=INIT_MYSUBRS
+
+ Ok. Another hint is that you can avoid having to add the `PSECT'
+ declaration of `NOSHR,LCL' by declaring variables `status' in the
+ C language source. That works great for most things.
+
+ 6. Then the dynamic loader would have to do this:
+
+ {void (*init_fcn)();
+ long retval;
+ retval = lib$find_image_symbol("MYSUBRS","INIT_MYSUBRS",&init_fcn,
+ "SYS$DISK:[].EXE");
+ if (retval != SS$_NORMAL) error(...);
+ (*init_fcn)();}
+
+ But of course all string arguments must be `(struct dsc$descriptor
+ *)' and the last argument is optional if `MYSUBRS' is defined as a
+ logical name or if `MYSUBRS.EXE' has been copied over to
+ `SYS$SHARE'. The other consideration is that you will want to turn
+ off <C-c> or other interrupt handling while you are inside most
+ `lib$' calls.
+
+ As far as the generation of all the `UNIVERSAL=...' declarations.
+ Well, you could do well to have that automatically generated from
+ the public `LISPRTL.H' file, of course.
+
+ VMS has a good manual called the `Guide to Writing Modular
+ Procedures' or something like that, which covers this whole area
+ rather well, and also talks about advanced techniques, such as a
+ way to declare a program section with a pointer to a procedure
+ that will be automatically invoked whenever any shared image is
+ dynamically activated. Also, how to set up a handler for normal
+ or abnormal program exit so that you can clean up side effects
+ (such as opening a database). But for use with `LISPRTL' you
+ probably don't need that hair.
+
+ One fancier option that is useful under VMS for `LISPLIB.EXE' is to
+ define all your exported procedures through an "call vector"
+ instead of having them just be pointers into random places in the
+ image, which is what you get by using `UNIVERSAL'.
+
+ If you set up the call vector thing correctly it will allow you to
+ modify and relink `LISPLIB.EXE' without having to relink programs
+ that have been linked against it.
+
+Windows NT
+..........
+
+George Carrette (gjc@mitech.com) outlines how to dynamically link on
+Windows NT:
+
+ * The Software Developers Kit has a sample called SIMPLDLL. Here is
+ the gist of it, following along the lines of the VMS description
+ above (contents of a makefile for the SDK NMAKE)
+
+ LISPLIB.exp:
+ LISPLIB.lib: LISPLIB.def
+ $(implib) -machine:$(CPU) -def:LISPLIB.def -out:LISPLIB.lib
+
+ LISPLIB.DLL : $(LISPLIB_OBJS) LISPLIB.EXP
+ $(link) $(linkdebug) \
+ -dll \
+ -out:LISPLIB.DLL \
+ LISPLIB.EXP $(LISPLIB_OBJS) $(conlibsdll)
+
+ * The `LISPDEF.DEF' file has this:
+
+ LIBRARY lisplib
+ EXPORT
+ init_lisp
+ init_repl
+
+ * And `MAIN.EXE' using:
+
+ CLINK = $(link) $(ldebug) $(conflags) -out:$*.exe $** $(conlibsdll)
+
+ MAIN.EXE : MAIN.OBJ LISPLIB.LIB
+ $(CLINK)
+
+ * And `MYSUBRS.DLL' is produced using:
+
+ mysubrs.exp:
+ mysubrs.lib: mysubrs.def
+ $(implib) -machine:$(CPU) -def:MYSUBRS.def -out:MYSUBRS.lib
+
+ mysubrs.dll : mysubrs.obj mysubrs.exp mysubrs.lib
+ $(link) $(linkdebug) \
+ -dll \
+ -out:mysubrs.dll \
+ MYSUBRS.OBJ MYSUBRS.EXP LISPLIB.LIB $(conlibsdll)
+
+ * Where `MYSUBRS.DEF' has
+
+ LIBRARY mysubrs
+ EXPORT
+ INIT_MYSUBRS
+
+ * And the dynamic loader looks something like this, calling the two
+ procedures `LoadLibrary' and `GetProcAddress'.
+
+ LISP share_image_load(LISP fname)
+ {long iflag;
+ LISP retval,(*fcn)(void);
+ HANDLE hLib;
+ DWORD err;
+ char *libname,fcnname[64];
+ iflag = nointerrupt(1);
+ libname = c_string(fname);
+ _snprintf(fcnname,sizeof(fcnname),"INIT_%s",libname);
+ if (!(hLib = LoadLibrary(libname)))
+ {err = GetLastError();
+ retval = list2(fname,LSPNUM(err));
+ serror1("library failed to load",retval);}
+ if (!(fcn = (LISP (*)(void)) GetProcAddress(hLib,fcnname)))
+ {err = GetLastError();
+ retval = list2(fname,LSPNUM(err));
+ serror1("could not find library init procedure",retval);}
+ retval = (*fcn)();
+ nointerrupt(iflag);
+ return(retval);}
+
+ * *Note:* in VMS the linker and dynamic loader is case sensitive, but
+ all the language compilers, including C, will by default upper-case
+ external symbols for use by the linker, although the debugger gets
+ its own symbols and case sensitivity is language mode dependant.
+ In Windows NT things are case sensitive generally except for file
+ and device names, which are case canonicalizing like in the
+ Symbolics filesystem.
+
+ * *Also:* All this WINDOWS NT stuff will work in MS-DOS MS-Windows
+ 3.1 too, by a method of compiling and linking under Windows NT,
+ and then copying various files over to MS-DOS/WINDOWS.
+
+
+File: scm.info, Node: Index, Prev: The Implementation, Up: Top
+
+Procedure and Macro Index
+*************************
+
+This is an alphabetical list of all the procedures and macros in SCM.
+
+* Menu:
+
+* #!: Unix Scheme Scripts.
+* #': Syntax Extensions.
+* #+: Syntax Extensions.
+* #-: Syntax Extensions.
+* #.: Syntax Extensions.
+* #;text-till-end-of-line: Syntax Extensions. |
+* #\token: Syntax Extensions.
+* #|: Syntax Extensions.
+* $abs: Numeric.
+* $acos: Numeric.
+* $acosh: Numeric.
+* $asin: Numeric.
+* $asinh: Numeric.
+* $atan: Numeric.
+* $atan2: Numeric.
+* $atanh: Numeric.
+* $cos: Numeric.
+* $cosh: Numeric.
+* $exp: Numeric.
+* $expt: Numeric.
+* $log: Numeric.
+* $log10: Numeric.
+* $sin: Numeric.
+* $sinh: Numeric.
+* $sqrt: Numeric.
+* $tan: Numeric.
+* $tanh: Numeric.
+* -: SCM Options.
+* ---: SCM Options.
+* ---c-source-files=: Build Options.
+* ---compiler-options=: Build Options.
+* ---defines=: Build Options.
+* ---features=: Build Options.
+* ---help: SCM Options.
+* ---initialization=: Build Options.
+* ---libraries=: Build Options.
+* ---linker-options=: Build Options.
+* ---no-init-file: SCM Options.
+* ---object-files=: Build Options.
+* ---outname=: Build Options.
+* ---platform=: Build Options.
+* ---scheme-initial=: Build Options.
+* ---type=: Build Options.
+* ---version: SCM Options.
+* --batch-dialect=: Build Options.
+* --script-name=: Build Options.
+* -a: SCM Options.
+* -b: SCM Options.
+* -c <1>: SCM Options.
+* -c: Build Options.
+* -d: SCM Options.
+* -D: Build Options.
+* -e: SCM Options.
+* -f: SCM Options.
+* -F: Build Options.
+* -h: Build Options.
+* -i <1>: SCM Options.
+* -i: Build Options.
+* -j: Build Options.
+* -l <1>: SCM Options.
+* -l: Build Options.
+* -m: SCM Options.
+* -no-init-file: SCM Options.
+* -o <1>: SCM Options.
+* -o: Build Options.
+* -p <1>: SCM Options.
+* -p: Build Options.
+* -q: SCM Options.
+* -r: SCM Options.
+* -s <1>: SCM Options.
+* -s: Build Options.
+* -t: Build Options.
+* -u: SCM Options.
+* -v: SCM Options.
+* -w: Build Options.
+* @apply: Low Level Syntactic Hooks.
+* @call-with-current-continuation: Low Level Syntactic Hooks.
+* @copy-tree: Miscellaneous Procedures.
+* @let-syntax: Syntactic Hooks for Hygienic Macros.
+* @letrec-syntax: Syntactic Hooks for Hygienic Macros.
+* @macroexpand1: Syntactic Hooks for Hygienic Macros.
+* _ionbf: Files and Ports.
+* _tracked: Files and Ports. |
+* abort: Internal State.
+* access: I/O-Extensions.
+* acct: Posix Extensions.
+* acons: Miscellaneous Procedures.
+* acosh: Numeric.
+* add-alias: Configure Module Catalog.
+* add-link: Configure Module Catalog.
+* add-source: Configure Module Catalog.
+* alarm: Interrupts.
+* alarm-interrupt: Interrupts.
+* ALLOW_INTS: Signals.
+* alrm_signal: Signals.
+* ARGC: Cells.
+* arithmetic-error: Interrupts.
+* array->list: Conventional Arrays.
+* array-contents: Conventional Arrays.
+* array-copy!: Conventional Arrays.
+* array-dimensions: Conventional Arrays.
+* array-equal?: Conventional Arrays.
+* array-fill!: Conventional Arrays.
+* array-for-each: Array Mapping.
+* array-in-bounds?: Conventional Arrays.
+* array-index-map!: Array Mapping.
+* array-map!: Array Mapping.
+* array-prototype: Uniform Array.
+* array-rank: Conventional Arrays.
+* array-ref: Conventional Arrays.
+* array-set!: Conventional Arrays.
+* array-shape: Conventional Arrays.
+* array? <1>: Uniform Array.
+* array?: Conventional Arrays.
+* asinh: Numeric.
+* ASRTGO: C Macros.
+* ASSERT: C Macros.
+* atanh: Numeric.
+* bit-count: Bit Vectors.
+* bit-count*: Bit Vectors.
+* bit-invert!: Bit Vectors.
+* bit-position: Bit Vectors.
+* bit-set*!: Bit Vectors.
+* box: Curses Miscellany.
+* CAR: Cells.
+* casev: Syntax Extensions.
+* cbreak: Terminal Mode Setting.
+* CCLO_LENGTH: Header Cells.
+* CDR: Cells.
+* char: Type Conversions.
+* char-ready: Files and Ports.
+* char-ready? <1>: Socket.
+* char-ready?: Files and Ports.
+* CHARS: Header Cells.
+* chdir: I/O-Extensions.
+* CHEAP_CONTINUATIONS: Continuations.
+* chmod: I/O-Extensions.
+* chown: Posix Extensions.
+* clearok: Output Options Setting.
+* close-io-port: Files and Ports.
+* close-port <1>: Window Manipulation.
+* close-port <2>: Posix Extensions.
+* close-port: Files and Ports.
+* closedir: I/O-Extensions.
+* CLOSEDP: Ptob Cells.
+* CLOSUREP: Cells.
+* CODE: Cells.
+* comment: Syntax Extensions. |
+* compile-file: Compiling And Linking.
+* CONSP: Cells.
+* copy-tree: Miscellaneous Procedures.
+* cosh: Numeric.
+* could-not-open: Interrupts.
+* current-error-port: Files and Ports.
+* current-input-port: Files and Ports.
+* current-time: Time.
+* default-input-port: Line Editing.
+* default-output-port: Line Editing.
+* defconst: Syntax Extensions.
+* DEFER_INTS: Signals.
+* defined?: Syntax Extensions.
+* defvar: Syntax Extensions.
+* dimensions->uniform-array: Uniform Array.
+* directory-for-each: I/O-Extensions.
+* display: Output.
+* dld_find_executable: Executable Pathname.
+* dump: Dump.
+* duplicate-port: I/O-Extensions.
+* dyn:call: Dynamic Linking.
+* dyn:link: Dynamic Linking.
+* dyn:main-call: Dynamic Linking.
+* dyn:unlink: Dynamic Linking.
+* echo: Terminal Mode Setting.
+* ed: Editing Scheme Code.
+* enclose-array: Conventional Arrays.
+* end-of-program: Interrupts.
+* endwin: Curses.
+* ENV: Cells.
+* environment->tree: Low Level Syntactic Hooks.
+* errno: Errors.
+* error: Errors.
+* eval: Evaluation.
+* EVAL: Evaluation.
+* eval: Miscellaneous Procedures.
+* eval-string: Miscellaneous Procedures.
+* exec-self: Internal State.
+* execl: I/O-Extensions.
+* execlp: I/O-Extensions.
+* execpath: Internal State.
+* execv: I/O-Extensions.
+* execvp: I/O-Extensions.
+* exit: SCM Session.
+* extended-environment: Syntactic Hooks for Hygienic Macros.
+* file-position: I/O-Extensions.
+* file-set-position: I/O-Extensions.
+* fileno: I/O-Extensions.
+* final_scm: Embedding SCM.
+* find_impl_file: File-System Habitat.
+* force-output: Window Manipulation.
+* fork: Posix Extensions.
+* FPORTP: Ptob Cells.
+* free_continuation: Continuations.
+* freshline: Files and Ports. |
+* gc: Internal State.
+* gc_mark: Marking Cells.
+* GCCDR: Marking Cells.
+* GCTYP16: Marking Cells.
+* get-internal-real-time: Time.
+* get-internal-run-time: Time.
+* getcwd: I/O-Extensions.
+* getegid: Posix Extensions.
+* geteuid: Posix Extensions.
+* getgid: Posix Extensions.
+* getgr: Posix Extensions.
+* getgroups: Posix Extensions.
+* gethost: Host Data.
+* getnet: Host Data.
+* getpeername: Internet Addresses and Socket Names.
+* getpid: I/O-Extensions.
+* getppid: Posix Extensions.
+* getproto: Host Data.
+* getpw: Posix Extensions.
+* getserv: Host Data.
+* getsockname: Internet Addresses and Socket Names.
+* getuid: Posix Extensions.
+* getyx: Input.
+* hang-up: Interrupts.
+* ICHR: Immediates.
+* ICHRP: Immediates.
+* identifier->symbol: Syntactic Hooks for Hygienic Macros.
+* identifier-equal?: Syntactic Hooks for Hygienic Macros.
+* identifier?: Syntactic Hooks for Hygienic Macros.
+* idlok: Output Options Setting.
+* IFLAGP: Immediates.
+* IMP: Immediates.
+* inet:address->string: Internet Addresses and Socket Names.
+* inet:local-network-address: Internet Addresses and Socket Names.
+* inet:make-address: Internet Addresses and Socket Names.
+* inet:network: Internet Addresses and Socket Names.
+* inet:string->address: Internet Addresses and Socket Names.
+* init_buf0: Embedding SCM.
+* init_sbrk: Embedding SCM.
+* init_signals <1>: Embedding SCM.
+* init_signals: Signals.
+* initscr: Curses.
+* INPORTP: Ptob Cells.
+* int_signal: Signals.
+* INUM: Immediates.
+* INUMP: Immediates.
+* isatty?: Files and Ports.
+* ISYMCHARS: Immediates.
+* ISYMNUM: Immediates.
+* ISYMP: Immediates.
+* kill: Posix Extensions.
+* leaveok: Output Options Setting.
+* LENGTH: Header Cells.
+* line-editing: Line Editing.
+* line-number: Miscellaneous Procedures.
+* link: Posix Extensions.
+* link-named-scm: Compiling And Linking.
+* list->uniform-array: Uniform Array.
+* list->uniform-vector: Uniform Array.
+* list-file: Miscellaneous Procedures.
+* load: Dynamic Linking.
+* load-string: Miscellaneous Procedures.
+* logaref: Uniform Array.
+* logaset!: Uniform Array.
+* long: Type Conversions.
+* long2num: Type Conversions.
+* lstat: Posix Extensions.
+* main: Embedding SCM.
+* makargvfrmstrs: Type Conversions.
+* makcclo: Header Cells.
+* make-arbiter: Process Synchronization.
+* make-array: Conventional Arrays.
+* make-edited-line-port: Line Editing.
+* make-shared-array: Conventional Arrays.
+* make-soft-port: Soft Ports.
+* make-stream-socket: Socket.
+* make-stream-socketpair: Socket.
+* make-uniform-array: Uniform Array.
+* make-uniform-vector: Uniform Array.
+* make_continuation: Continuations.
+* make_gsubr: Defining Subrs.
+* make_root_continuation: Continuations.
+* makfrom0str: Type Conversions.
+* makfromstr: Type Conversions.
+* makfromstrs: Type Conversions.
+* MAKICHR: Immediates.
+* MAKIFLAG: Immediates.
+* MAKINUM: Immediates.
+* MAKISYM: Immediates.
+* MAKSPCSYM: Immediates.
+* mark_locations: Marking Cells.
+* milli-alarm: Interrupts.
+* mkdir: I/O-Extensions.
+* mknod: Posix Extensions.
+* must_free: Allocating memory.
+* must_free_argv: Type Conversions.
+* must_malloc: Allocating memory.
+* must_malloc_cell: Allocating memory.
+* must_realloc: Allocating memory.
+* must_realloc_cell: Allocating memory.
+* mvwin: Window Manipulation.
+* NCONSP: Cells.
+* NEWCELL: Cells.
+* newwin: Window Manipulation.
+* nice: Posix Extensions.
+* NIMP: Immediates.
+* NINUMP: Immediates.
+* nl: Terminal Mode Setting.
+* nocbreak: Terminal Mode Setting.
+* nodelay: Output Options Setting.
+* noecho: Terminal Mode Setting.
+* nonl: Terminal Mode Setting.
+* noraw: Terminal Mode Setting.
+* NSTRINGP: Header Cells.
+* num2long: Type Conversions.
+* NVECTORP: Header Cells.
+* open-file: Files and Ports.
+* open-input-pipe: Posix Extensions.
+* open-io-file: Files and Ports.
+* open-output-pipe: Posix Extensions.
+* open-pipe: Posix Extensions.
+* opendir: I/O-Extensions.
+* OPENP: Ptob Cells.
+* OPFPORTP: Ptob Cells.
+* OPINFPORTP: Ptob Cells.
+* OPINPORTP: Ptob Cells.
+* OPOUTFPORTP: Ptob Cells.
+* OPOUTPORTP: Ptob Cells.
+* OPPORTP: Ptob Cells.
+* out-of-storage: Interrupts.
+* OUTPORTP: Ptob Cells.
+* overlay: Window Manipulation.
+* overwrite: Window Manipulation.
+* perror: Errors.
+* pipe: Posix Extensions.
+* port-column: Miscellaneous Procedures. |
+* port-filename: Miscellaneous Procedures. |
+* port-line: Miscellaneous Procedures. |
+* PORTP: Ptob Cells.
+* print <1>: Miscellaneous Procedures.
+* print: Debugging Scheme Code.
+* print-args: Debugging Scheme Code.
+* procedure->macro: Low Level Syntactic Hooks.
+* procedure->memoizing-macro: Low Level Syntactic Hooks.
+* procedure->syntax: Low Level Syntactic Hooks.
+* procedure-documentation: Syntax Extensions.
+* profile-alarm: Interrupts.
+* profile-alarm-interrupt: Interrupts.
+* program-arguments: SCM Session.
+* putenv: I/O-Extensions.
+* quit: SCM Session.
+* raw: Terminal Mode Setting.
+* read-char <1>: Input.
+* read-char: Files and Ports.
+* read:sharp: Low Level Syntactic Hooks.
+* read:sharp-char: Low Level Syntactic Hooks.
+* readdir: I/O-Extensions.
+* readlink: Posix Extensions.
+* redirect-port!: I/O-Extensions.
+* refresh: Window Manipulation.
+* regcomp: Regular Expression Pattern Matching.
+* regerror: Regular Expression Pattern Matching.
+* regexec: Regular Expression Pattern Matching.
+* regmatch: Regular Expression Pattern Matching.
+* regmatch?: Regular Expression Pattern Matching.
+* regmatchv: Regular Expression Pattern Matching.
+* regsearch: Regular Expression Pattern Matching.
+* regsearchv: Regular Expression Pattern Matching.
+* release-arbiter: Process Synchronization.
+* rename-file: I/O-Extensions.
+* renamed-identifier: Syntactic Hooks for Hygienic Macros.
+* renaming-transformer: Syntactic Hooks for Hygienic Macros.
+* reopen-file: I/O-Extensions.
+* require: Dynamic Linking.
+* resetty: Terminal Mode Setting.
+* restart: Internal State.
+* restore_signals: Embedding SCM.
+* rewinddir: I/O-Extensions.
+* rmdir: I/O-Extensions.
+* room: Internal State.
+* savetty: Terminal Mode Setting.
+* scalar->array: Array Mapping.
+* scm_evstr: Callbacks.
+* scm_find_execpath: Embedding SCM.
+* scm_find_implpath: Embedding SCM.
+* scm_init_from_argv: Embedding SCM.
+* scm_ldfile: Callbacks.
+* scm_ldprog: Callbacks.
+* scm_ldstr: Callbacks.
+* scm_top_level: Embedding SCM.
+* script_count_argv: Script Support.
+* script_find_executable: Script Support.
+* script_process_argv: Script Support.
+* scroll: Output.
+* scrollok: Output Options Setting.
+* serial-array-copy!: Conventional Arrays.
+* serial-array-map!: Array Mapping.
+* set!: Syntax Extensions.
+* setegid: Posix Extensions.
+* seteuid: Posix Extensions.
+* setgid: Posix Extensions.
+* setgrent: Posix Extensions.
+* sethostent: Host Data.
+* setnetent: Host Data.
+* setprotoent: Host Data.
+* setpwent: Posix Extensions.
+* setservent: Host Data.
+* setuid: Posix Extensions.
+* short: Type Conversions.
+* SHORT_ALIGN: Continuations.
+* SIDEVAL: Evaluation.
+* sinh: Numeric.
+* socket-name:address: Internet Addresses and Socket Names.
+* socket-name:family: Internet Addresses and Socket Names.
+* socket-name:port-number: Internet Addresses and Socket Names.
+* socket:accept: Socket.
+* socket:bind: Socket.
+* socket:connect: Socket.
+* socket:listen: Socket.
+* socket:shutdown: Socket.
+* stack-trace: Errors.
+* STACK_GROWS_UP: Continuations.
+* stack_size: Continuations.
+* stat: I/O-Extensions.
+* STREAM: Ptob Cells.
+* string-edit: Regular Expression Pattern Matching.
+* string-split: Regular Expression Pattern Matching.
+* string-splitv: Regular Expression Pattern Matching.
+* STRINGP: Header Cells.
+* subwin: Window Manipulation.
+* SYMBOLP: Header Cells.
+* symlink: Posix Extensions.
+* sync: Posix Extensions.
+* syntax-quote: Syntactic Hooks for Hygienic Macros.
+* tanh: Numeric.
+* terms: Miscellaneous Procedures.
+* the-macro: Syntactic Hooks for Hygienic Macros.
+* throw_to_continuation: Continuations.
+* ticks: Interrupts.
+* ticks-interrupt: Interrupts.
+* touchline: Window Manipulation.
+* touchwin: Window Manipulation.
+* trace: Debugging Scheme Code.
+* transpose-array: Conventional Arrays.
+* try-arbiter: Process Synchronization.
+* try-load: Miscellaneous Procedures.
+* try-open-file: Files and Ports.
+* ttyname: Posix Extensions.
+* TYP16: Cells.
+* TYP3: Cells.
+* TYP7: Cells.
+* UCHARS: Header Cells.
+* ulong2num: Type Conversions.
+* umask: I/O-Extensions.
+* uname: Posix Extensions.
+* unctrl: Curses Miscellany.
+* uniform-array-read!: Uniform Array.
+* uniform-array-write: Uniform Array.
+* uniform-vector-fill!: Uniform Array.
+* uniform-vector-length: Uniform Array.
+* uniform-vector-read!: Uniform Array.
+* uniform-vector-ref: Uniform Array.
+* uniform-vector-set!: Uniform Array.
+* uniform-vector-write: Uniform Array.
+* untrace: Debugging Scheme Code.
+* user-interrupt: Interrupts.
+* usr:lib: Dynamic Linking.
+* utime: I/O-Extensions.
+* vector-set-length!: Miscellaneous Procedures.
+* VECTORP: Header Cells.
+* VELTS: Header Cells.
+* verbose: Internal State.
+* virtual-alarm: Interrupts.
+* virtual-alarm-interrupt: Interrupts.
+* vms-debug: SCM Session.
+* void: Sweeping the Heap.
+* wadd: Output.
+* wait-for-input: Files and Ports.
+* waitpid: Posix Extensions.
+* warn: Errors.
+* wclear: Output.
+* wclrtobot: Output.
+* wclrtoeol: Output.
+* wdelch: Output.
+* wdeleteln: Output.
+* werase: Output.
+* winch: Input.
+* winsch: Output.
+* winsertln: Output.
+* with-error-to-file: Files and Ports.
+* with-error-to-port: Files and Ports.
+* with-input-from-port: Files and Ports.
+* with-output-to-port: Files and Ports.
+* wmove: Window Manipulation.
+* wstandend: Curses Miscellany.
+* wstandout: Curses Miscellany.
+* x:lib: Dynamic Linking.
+
+Variable Index
+**************
+
+This is an alphabetical list of all the global variables in SCM.
+
+* Menu:
+
+* *argv*: SCM Variables.
+* *execpath: Embedding SCM.
+* *interactive* <1>: Internal State.
+* *interactive*: SCM Variables.
+* *load-pathname*: Miscellaneous Procedures.
+* *R4RS-macro*: SCM Variables.
+* *scm-version*: Internal State.
+* af_inet: Host Data.
+* af_unix: Host Data.
+* BOOL_F: Immediates.
+* BOOL_T: Immediates.
+* EDITOR: SCM Variables.
+* EOF_VAL: Immediates.
+* EOL: Immediates.
+* errobj: Errors.
+* HOME: SCM Variables.
+* internal-time-units-per-second: Time.
+* INUM0: Immediates.
+* isymnames: Immediates.
+* most-negative-fixnum: Numeric.
+* most-positive-fixnum: Numeric.
+* NUM_ISPCSYM: Immediates.
+* NUM_ISYMS: Immediates.
+* open_both: Files and Ports.
+* open_read: Files and Ports.
+* open_write: Files and Ports.
+* SCHEME_LIBRARY_PATH: SCM Variables.
+* SCM_INIT_PATH: SCM Variables.
+* symhash: Evaluation.
+* thrown_value: Continuations.
+* UNDEFINED: Immediates.
+* UNSPECIFIED: Immediates.
+
+Type Index
+**********
+
+This is an alphabetical list of data types and feature names in SCM.
+
+* Menu:
+
+* #! <1>: MS-DOS Compatible Scripts.
+* #!: Unix Scheme Scripts.
+* array-for-each: Array Mapping.
+* CELLPTR: Immediates.
+* CONTINUATION: Continuations.
+* curses: Dynamic Linking.
+* dump: Dump.
+* FARLOC: Evaluation.
+* GLOC: Evaluation.
+* gloc: Immediates.
+* i/o-extensions: Socket.
+* ichr: Immediates.
+* iflags: Immediates.
+* ILOC: Evaluation.
+* iloc: Immediates.
+* inum: Immediates.
+* ispcsym: Immediates.
+* isym: Immediates.
+* meta-argument <1>: Script Support.
+* meta-argument: Unix Scheme Scripts.
+* ptob: Ptob Cells.
+* regex: Dynamic Linking.
+* rev2-procedures: Dynamic Linking.
+* rev3-procedures: Dynamic Linking.
+* Scheme Script <1>: MS-DOS Compatible Scripts.
+* Scheme Script: Unix Scheme Scripts.
+* Scheme-Script <1>: MS-DOS Compatible Scripts.
+* Scheme-Script: Unix Scheme Scripts.
+* smob: Smob Cells.
+* socket: Socket.
+* spare: Header Cells.
+* STACKITEM: Continuations.
+* tc16_arbiter: Smob Cells.
+* tc16_array: Smob Cells.
+* tc16_bigneg: Smob Cells.
+* tc16_bigpos: Smob Cells.
+* tc16_flo: Smob Cells.
+* tc16_inpipe: Ptob Cells.
+* tc16_inport: Ptob Cells.
+* tc16_ioport: Ptob Cells.
+* tc16_macro: Smob Cells.
+* tc16_outpipe: Ptob Cells.
+* tc16_outport: Ptob Cells.
+* tc16_promise: Smob Cells.
+* tc16_sfport: Ptob Cells.
+* tc16_strport: Ptob Cells.
+* tc3_closure: Cells.
+* tc3_cons: Cells.
+* tc7_asubr: Subr Cells.
+* tc7_bvect: Header Cells.
+* tc7_contin: Header Cells.
+* tc7_cvect: Header Cells.
+* tc7_cxr: Subr Cells.
+* tc7_dvect: Header Cells.
+* tc7_fvect: Header Cells.
+* tc7_ivect: Header Cells.
+* tc7_lsubr: Subr Cells.
+* tc7_lsubr_2: Subr Cells.
+* tc7_msymbol: Header Cells.
+* tc7_rpsubr: Subr Cells.
+* tc7_specfun: Header Cells.
+* tc7_ssymbol: Header Cells.
+* tc7_string: Header Cells.
+* tc7_subr_0: Subr Cells.
+* tc7_subr_1: Subr Cells.
+* tc7_subr_1o: Subr Cells.
+* tc7_subr_2: Subr Cells.
+* tc7_subr_2o: Subr Cells.
+* tc7_subr_3: Subr Cells.
+* tc7_uvect: Header Cells.
+* tc7_vector: Header Cells.
+* tc_dblc: Smob Cells.
+* tc_dblr: Smob Cells.
+* tc_free_cell: Smob Cells.
+* turtle-graphics: Dynamic Linking.
+* unexec: Dump.
+
+This is an alphabetical list of concepts introduced in this manual.
+
+Concept Index
+*************
+
+* Menu:
+
+* !#: MS-DOS Compatible Scripts. |
+* !#.exe: MS-DOS Compatible Scripts. |
+* #!: MS-DOS Compatible Scripts. |
+* #!.bat: MS-DOS Compatible Scripts. |
+* array <1>: Conventional Arrays. |
+* array: Build Options. |
+* array-for-each: Build Options. |
+* arrays: Build Options. |
+* bignums: Build Options. |
+* callbacks: Callbacks.
+* careful-interrupt-masking: Build Options. |
+* cautious: Build Options. |
+* cheap-continuations: Build Options. |
+* compiled-closure: Build Options. |
+* continuations: Continuations.
+* curses: Build Options. |
+* debug: Build Options. |
+* documentation string: Syntax Extensions.
+* dump: Build Options. |
+* dynamic-linking: Build Options. |
+* edit-line: Build Options. |
+* Embedding SCM: Embedding SCM.
+* engineering-notation: Build Options. |
+* Exrename: Bibliography. |
+* Extending Scm: Compiling and Linking Custom Files.
+* foo.c: Compiling and Linking Custom Files.
+* generalized-c-arguments: Build Options. |
+* GUILE: Bibliography. |
+* i/o-extensions: Build Options. |
+* IEEE: Bibliography. |
+* inexact: Build Options. |
+* JACAL: Bibliography. |
+* lit: Build Options. |
+* macro: Build Options. |
+* mysql: Build Options. |
+* no-heap-shrink: Build Options. |
+* none: Build Options. |
+* posix: Build Options. |
+* R4RS: Bibliography. |
+* R5RS: Bibliography. |
+* reckless: Build Options. |
+* record: Build Options. |
+* regex: Build Options. |
+* rev2-procedures: Build Options. |
+* SICP: Build Options. |
+* sicp: Build Options. |
+* SICP: Bibliography. |
+* signals: Signals.
+* Simply: Bibliography. |
+* single-precision-only: Build Options. |
+* SLIB: Bibliography. |
+* socket: Build Options. |
+* stack-limit: Build Options. |
+* tick-interrupts: Build Options. |
+* turtlegr: Build Options. |
+* unix: Build Options. |
+* windows: Build Options. |
+* x: Build Options. |
+* xlib: Build Options. |
+
+
+
+Tag Table:
+Node: Top229
+Node: Overview1521
+Node: Copying1832
+Node: SCM Features4894
+Node: SCM Authors6905
+Node: Bibliography7805
+Node: Installing SCM9676
+Node: Making SCM10191
+Node: SLIB11531
+Node: Building SCM13549
+Node: Invoking Build14091
+Node: Build Options16112
+Node: Compiling and Linking Custom Files33008
+Node: Installing Dynamic Linking34986
+Node: Configure Module Catalog36770
+Node: Saving Images38767
+Node: Automatic C Preprocessor Definitions39443
+Node: Problems Compiling42659
+Node: Problems Linking44785
+Node: Problems Running45087
+Node: Testing47643
+Node: Reporting Problems50980
+Node: Operational Features51823
+Node: Invoking SCM52187
+Node: SCM Options53748
+Node: Invocation Examples57904
+Node: SCM Variables58856
+Node: SCM Session60306
+Node: Editing Scheme Code61429
+Node: Debugging Scheme Code63563
+Node: Errors67202
+Node: Memoized Expressions71502
+Node: Internal State73866
+Node: Scripting76918
+Node: Unix Scheme Scripts77212
+Node: MS-DOS Compatible Scripts80423
+Node: Unix Shell Scripts82236
+Node: The Language84425
+Node: Standards Compliance85000
+Node: Miscellaneous Procedures87415
+Node: Time90765
+Node: Interrupts91759
+Node: Process Synchronization95369
+Node: Files and Ports95909
+Node: Soft Ports101092
+Node: Syntax Extensions102768
+Node: Low Level Syntactic Hooks109753
+Node: Syntactic Hooks for Hygienic Macros113664
+Node: Packages120817
+Node: Compiling And Linking121493
+Node: Dynamic Linking123530
+Node: Dump128154
+Node: Numeric132264
+Node: Arrays133820
+Node: Conventional Arrays134037
+Node: Array Mapping140675
+Node: Uniform Array142909
+Node: Bit Vectors148821
+Node: I/O-Extensions150086
+Node: Posix Extensions158379
+Node: Regular Expression Pattern Matching169109
+Node: Line Editing173064
+Node: Curses174410
+Node: Output Options Setting175333
+Node: Terminal Mode Setting177981
+Node: Window Manipulation181059
+Node: Output184519
+Node: Input188145
+Node: Curses Miscellany189172
+Node: Sockets190596
+Node: Host Data190920
+Node: Internet Addresses and Socket Names194068
+Node: Socket195602
+Node: The Implementation202838
+Node: Data Types203097
+Node: Immediates203918
+Node: Cells208254
+Node: Header Cells210346
+Node: Subr Cells213327
+Node: Ptob Cells215545
+Node: Smob Cells217091
+Node: Data Type Representations220290
+Node: Operations224909
+Node: Garbage Collection225495
+Node: Marking Cells226116
+Node: Sweeping the Heap228218
+Node: Memory Management for Environments229163
+Node: Signals233720
+Node: C Macros235264
+Node: Changing Scm236387
+Node: Defining Subrs240660
+Node: Defining Smobs242537
+Node: Defining Ptobs245521
+Node: Allocating memory246698
+Node: Embedding SCM248860
+Node: Callbacks256514
+Node: Type Conversions258317
+Node: Continuations261874
+Node: Evaluation266088
+Node: Program Self-Knowledge271253
+Node: File-System Habitat271499
+Node: Executable Pathname275099
+Node: Script Support276718
+Node: Improvements To Make278036
+Node: Finishing Dynamic Linking280067
+Node: Index287814
+
+End Tag Table