diff options
| author | LaMont Jones <lamont@debian.org> | 2003-05-07 08:36:40 -0600 |
|---|---|---|
| committer | Bryan Newbold <bnewbold@robocracy.org> | 2017-02-20 00:05:27 -0800 |
| commit | e21d47d7813159bb71e0671df9b52ec0470c358d (patch) | |
| tree | 3c7770ea846123c291f599044e9f234ac17616bb /scm5d6.info | |
| parent | 8cfce36c6a4fc2e0a0ab6ef2db66a23cbe462693 (diff) | |
| parent | deda2c0fd8689349fea2a900199a76ff7ecb319e (diff) | |
| download | scm-e21d47d7813159bb71e0671df9b52ec0470c358d.tar.gz scm-e21d47d7813159bb71e0671df9b52ec0470c358d.zip | |
Import Debian changes 5d6-3.2debian/5d6-3.2
scm (5d6-3.2) unstable; urgency=low
* Fix hppa compile. Closes: #144062
scm (5d6-3.1) unstable; urgency=low
* NMU with patch from James Troup, to fix FTBFS on sparc. Closes: #191171
scm (5d6-3) unstable; urgency=low
* Add build depend on xlibs-dev (Closes: #148020)
scm (5d6-2) unstable; urgency=low
* Remove libregexx-dev from build-depends.
* Change build to use ./scmlit rather than scmlit (should fix some build
problems) (looks like alpha is mostly building)
* New release (Closes: #140175)
* Built with turtlegraphics last time (Closes: #58515)
scm (5d6-1) unstable; urgency=low
* New upstream.
* Add xlib and turtlegr to requested list of features. (closes
some bug)
* Make clean actually clean most everything up.
* Remove hacks renaming build to something else and just set build as a
.PHONY target in debian/rules.
* Add the turtlegr code.
scm (5d5-1) unstable; urgency=low
* New upstream
* Has fixes for 64 bit archs. May fix alpha compile problem. Does fix
(Closes: #140175)
* Take out -O2 arg.
scm (5d4-3) unstable; urgency=low
* Don't link with regexx, but just use libc6's regular expression
functions.
* Define (terms) to output /usr/share/common-licenses/GPL (Closes:
#119321)
scm (5d4-2) unstable; urgency=low
* Add texinfo to build depends (Closes: #107011)
scm (5d4-1) unstable; urgency=low
* New upstream release.
* Move install-info --remove to prerm.
scm (5d3-5) unstable; urgency=low
* Move scm info files to section "The Algorithmic Language Scheme" to
match up with guile.
scm (5d3-4) unstable; urgency=low
* Fix build depends (Closes: #76691)
scm (5d3-3) unstable; urgency=low
* Fix path in scm dhelp file.
scm (5d3-2) unstable; urgency=low
* Actually put the header files in the package. Oops.
scm (5d3-1) unstable; urgency=low
* New upstream. (Closes: #74761)
* Make (terms) use new license location.
* Make use libregexx rather than librx.
* Fix build depends for above.
* Using new regex lib seems to fix crash (Closes: #66787)
* Consider adding scm-dev package with headers, but instead just add the
headers to the scm package. (Closes: #70787)
* Add doc-base support.
Diffstat (limited to 'scm5d6.info')
| -rw-r--r-- | scm5d6.info | 8382 |
1 files changed, 8382 insertions, 0 deletions
diff --git a/scm5d6.info b/scm5d6.info new file mode 100644 index 0000000..7dbf40d --- /dev/null +++ b/scm5d6.info @@ -0,0 +1,8382 @@ +This is scm.info, produced by makeinfo version 4.3 from 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 +5d6 was released May 2002. 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: + +* SCM Features:: +* SCM Authors:: +* Copying:: +* Bibliography:: + + +File: scm.info, Node: SCM Features, Next: SCM Authors, Prev: Overview, 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: Copying, Prev: SCM Features, Up: Overview + +Authors +======= + +Aubrey Jaffer (jaffer @ alum.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: Copying, Next: Bibliography, Prev: SCM Authors, Up: Overview + +Copyright +========= + +Authors have assigned their SCM copyrights to: + + 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. + +SIOD copyright +============== + + + 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 + + +File: scm.info, Node: Bibliography, Prev: Copying, Up: Overview + +Bibliography +============ + +[IEEE] + `IEEE Standard 1178-1990. IEEE Standard for the Scheme + Programming Language.' IEEE, New York, 1991. + +[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. + +[SICP] + Harold Abelson and Gerald Jay Sussman with Julie Sussman. + `Structure and Interpretation of Computer Programs.' MIT Press, + Cambridge, 1985. + +[Simply] + Brian Harvey and Matthew Wright. `Simply Scheme: Introducing + Computer Science' MIT Press, 1994 ISBN 0-262-08226-8 + +[SchemePrimer] + 犬飼大(Dai Inukai) `入門Scheme' + 1999年12月初版 ISBN4-87966-954-7 + +[SLIB] + Todd R. Eigenschink, Dave Love, and Aubrey Jaffer. SLIB, The + Portable Scheme Library. Version 2c8, June 2000. + + *Note Top: (slib)Top. + +[JACAL] + Aubrey Jaffer. JACAL Symbolic Mathematics System. Version 1b0, + Sep 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'. +`build' 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, there are several ways to proceed: + + * Use the build (http://swissnet.ai.mit.edu/~jaffer/buildscm.html) + web page to create custom batch scripts for compiling SCM. + + * Use SCM on a different platform to run `build' to create a script + to build SCM; + + * Use another implementation of Scheme to run `build' to create a + script to build SCM; + + * Create your own script or `Makefile'. + + +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/slib2d4.tar.gz + + * ftp.gnu.org:/pub/gnu/jacal/slib2d4.tar.gz + + * ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib2d4.tar.gz + +Unpack SLIB (`tar xzf slib2d4.tar.gz' or `unzip -ao slib2d4.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 `Init5d6.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" loads the file "build.scm", which constructs a +relational database of how to compile and link SCM executables. +`build.scm' has information for the platforms which SCM has been ported +to (of which I have been notified). Some of this information is old, +incorrect, or incomplete. Send corrections and additions to jaffer @ +ai.mit.edu. + +* 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'. + +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' followed by command + line arguments. + +_all_ + From the SCM source directory, start `scm' or `scmlit' and type + `(load "build")'. 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 + -| + #! /bin/sh + # unix (linux) script created by SLIB/batch + # ================ Write file with C defines + rm -f scmflags.h + echo '#define IMPLINIT "Init5d6.scm"'>>scmflags.h + echo '#define BIGNUMS'>>scmflags.h + echo '#define FLOATS'>>scmflags.h + echo '#define ARRAYS'>>scmflags.h + # ================ Compile C source files + gcc -O2 -c continue.c scm.c scmmain.c findexec.c script.c time.c repl.c scl.c eval.c sys.c subr.c debug.c unif.c rope.c + # ================ Link C object files + gcc -rdynamic -o scm continue.o scm.o scmmain.o findexec.o script.o time.o repl.o scl.o eval.o sys.o subr.o debug.o unif.o rope.o -lm -lc + +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 -o scmlit -p darwin -F lit + -| + #! /bin/sh + # unix (darwin) script created by SLIB/batch + # ================ Write file with C defines + rm -f scmflags.h + echo '#define IMPLINIT "Init5d6.scm"'>>scmflags.h + # ================ Compile C source files + cc -O3 -c continue.c scm.c scmmain.c findexec.c script.c time.c repl.c scl.c eval.c sys.c subr.c debug.c unif.c rope.c + # ================ Link C object files + mv -f scmlit scmlit~ + cc -o scmlit continue.o scm.o scmmain.o findexec.o script.o time.o repl.o scl.o eval.o sys.o subr.o debug.o unif.o rope.o + + +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 + #f processor-family operating-system #f + 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 + darwin powerpc unix cc + 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 + openbsd *unknown* unix gcc + 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 `Init5d6.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 + + * amigaos (was 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/Init5d6.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/Init5d6.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 + __APPLE__ Apple Darwin + AMIGA SAS/C 5.10 or Dice C on AMIGA + __amigaos__ 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 + __MACH__ Apple Darwin + 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 + ppc PowerPC + __ppc__ PowerPC + pyr Pyramid 9810 processor + __sgi__ Silicon Graphics Inc. + sparc SPARC processor + sequent Sequent computer + tahoe CCI Tahoe processor + vax VAX processor + + +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: Init5d6.scm not found. Assign correct IMPLINIT in makefile + or scmfig.h. + Define environment variable + SCM_INIT_PATH to be the full + pathname of Init5d6.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 + Init5d6.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 ms (0 in gc) 767 cells work, 233.B other + #<unspecified> + > (pi 100 5) + 00003 14159 26535 89793 23846 26433 83279 50288 41971 69399 + 37510 58209 74944 59230 78164 06286 20899 86280 34825 34211 + 70679 + ;Evaluation took 550 ms (60 in gc) 36976 cells work, 1548.B other + #<unspecified> + +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. `Init5d6.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 @ alum.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] [-muvbiq] [-version] [-help] + [[-]-no-init-file] [-p int] [-r feature] [-h feature] + [-d filename] [-f filename] [-l filename] + [-c expression] [-e expression] [-o dumpname] + [-- | - | -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 `Init5d6.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, `Init5d6.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. + +`Init5d6.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 k + specifies that `scm' should allocate an initial heapsize of K + 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: --help + prints usage information and URI; then exit. + + - Command Option: --version + prints version information and exit. + + - Command Option: -r feature + requires FEATURE. This will load a file from [SLIB] if that + FEATURE is not already provided. If FEATURE is 2, 2rs, r2rs, 3, + 3rs, r3rs, 4, 4rs, r4rs, 5, 5rs, or r5rs; `scm' will require the + features neccessary to support [R2RS], [R3RS], [R4RS], or [R5RS], + respectively. + + - Command Option: -h feature + provides FEATURE. + + - 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: -d filename + Loads SLIB `databases' feature and opens FILENAME as a database. + + - 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: -o dumpname + saves the current SCM session as the executable program `dumpname'. + This option works only in SCM builds supporting `dump' (*note + Dump::). + + If options appear on the command line after `-o DUMPNAME', 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: -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. + + +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 `Init5d6.scm' in the source directory. + + - Environment Variable: SCHEME_LIBRARY_PATH + is the [SLIB] Scheme library directory. + + - Environment Variable: HOME + is the directory where `Init5d6.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: *syntax-rules* + 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. + + - Callback procedure: boot-tail dumped? + `boot-tail' is called by `scm_top_level' just before entering + interactive top-level. If `boot-tail' calls `quit', then + interactive top-level is not entered. + + - 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 + swissnet.ai.mit.edu:/pub/scm/slib-psd1-3.tar.gz + ftp.maths.tcd.ie:pub/bosullvn/jacal/slib-psd1-3.tar.gz + ftp.cs.indiana.edu:/pub/scheme-repository/utl/slib-psd1-3.tar.gz + + +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 `Init5d6.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 `Init5d6.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 `Init5d6.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 `Init5d6.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 `Init5d6.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 + messages bracketing file loading are printed. + + >= 3 + the CPU time is printed after each top level form evaluated; + notifications of heap growth printed. + + >= 4 + a garbage collection summary is printed after each top level + form evaluated; + + >= 5 + a message for each GC (*note Garbage Collection::) is printed; + warnings issued for top-level symbols redefined. + + - 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. `5d6') 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:: +* Line Numbers:: +* 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: (hobbit)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 and column numbers begin with 1. The + column number applies to the next character to be read; if that + character is a newline, then the column number will be one more + than the length of the 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)'. + + - Callback procedure: gc-hook ... + Allows a Scheme procedure to be run shortly after each garbage + collection. This procedure will not be run recursively. If it + runs long enough to cause a garbage collection before returning a + warning will be printed. + + - Function: add-finalizer object finalizer + OBJECT may be any garbage collected object, that is, any object + other than an immediate integer, character, or special token such + as `#f' or `#t', *Note Immediates::. FINALIZER is a thunk, or + procedure taking no arguments. + + FINALIZER will be invoked asynchronously exactly once some time + after OBJECT becomes eligible for garbage collection. A reference + to OBJECT in the environment of FINALIZER will not prevent + finalization, but will delay the reclamation of OBJECT at least + until the next garbage collection. A reference to OBJECT in some + other object's finalizer will necessarily prevent finalization + until both objects are eligible for garbage collection. + + Finalizers are not run in any predictable order. All finalizers + will be run by the time the program ends. + + This facility was based on the paper by Simon Peyton Jones, et al, + "Stretching the storage manager: weak pointers and stable names in + Haskell", Proc. 11th International Workshop on the Implementation + of Functional Languages, The Netherlands, September 7-10 1999, + Springer-Verlag LNCS. + + + +File: scm.info, Node: Process Synchronization, Next: Files and Ports, Prev: Interrupts, Up: The Language + +Process Synchronization +======================= + +An "exchanger" is a procedure of one argument regulating mutually +exclusive access to a resource. When a exchanger is called, its current +content is returned, while being replaced by its argument in an atomic +operation. + + - Function: make-exchanger obj + Returns a new exchanger with the argument OBJ as its initial + content. + + (define queue (make-exchanger (list a))) + + A queue implemented as an exchanger holding a list can be + protected from reentrant execution thus: + + (define (pop queue) + (let ((lst #f)) + (dynamic-wind + (lambda () (set! lst (queue #f))) + (lambda () (and lst (not (null? lst)) + (let ((ret (car lst))) + (set! lst (cdr lst)) + ret))) + (lambda () (and lst (queue lst)))))) + + (pop queue) => a + + (pop queue) => #f + + - 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: Line Numbers, 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. + + 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: _ionbf modestr + Returns a version of MODESTR which when `open-file' is called with + it as the second argument will return an unbuffered port. An + 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: _exclusive modestr + Returns a version of MODESTR which when `open-file' is called with + it as the second argument will return a port only if the named file + does not already exist. This functionality is provided by calling + `try-create-file' *Note I/O-Extensions::, which is not available + for all platforms. + + - Function: port-closed? port + Returns #t if PORT is closed. + + - Function: port-type obj + If OBJ is not a port returns false, otherwise returns a symbol + describing the port type, for example string or pipe. + + - Function: close-port port + Closes PORT. The same as close-input-port and close-output-port. + + - 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. + + - Function: call-with-outputs thunk proc + Calls the THUNK procedure while the current-output-port and + current-error-port are directed to string-ports. If THUNK + returns, the PROC procedure is called with the output-string, the + error-string, and the value returned by THUNK. If THUNK does not + return a value (perhaps because of error), PROC is called with + just the output-string and the error-string as arguments. + + - 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'. + + - Function: open-ports + Returns a list of all currently open ports, excluding string ports, + see *Note String Ports: (slib)String Ports. This may be useful + after a fork *Note Posix Extensions::, or for debugging. Bear in + mind that ports that would be closed by gc will be kept open by a + reference to this list. + + +File: scm.info, Node: Line Numbers, Next: Soft Ports, Prev: Files and Ports, Up: The Language + +Line Numbers +============ + +Scheme code define by load may optionally contain line number +information. Currently this information is used only for reporting +expansion time errors, but in the future run-time error messages may +also include line number information. + + - Function: try-load pathname reader + This is the primitive for loading, PATHNAME is the name of a file + containing Scheme code, and optional argument READER is a function + of one argument, a port. READER should read and return Scheme + code as list structure. The default value is `read', which is + used if READER is not supplied or is false. + +Line number objects are disjoint from integers or other Scheme types. +When evaluated or loaded as Scheme code, an s-expression containing a +line-number in the car is equivalent to the cdr of the s-expression. A +pair consisting of a line-number in the car and a vector in the cdr is +equivalent to the vector. The meaning of s-expressions with +line-numbers in other positions is undefined. + + - Function: read-numbered port + Behaves like `read', except that every s-expression read will be + replaced with a cons of a line-number object and the sexp actually + read. This replacement is done only if PORT is a tracked port See + *Note Files and Ports::. + + - Function: integer->line-number int + Returns a line-number object with value INT. INT should be an + exact non-negative integer. + + - Function: line-number->integer linum + Returns the value of line-number object LINUM as an integer. + + - Function: line-number? obj + Returns true if and only if OBJ is a line-number object. + + - Variable: *load-reader* + - Variable: *slib-load-reader* + The value of `*load-reader*' should be a value acceptable as the + second argument to `try-load' (note that #f is acceptable). This + value will be used to read code during calls to `scm:load'. The + value of `*slib-load-reader*' will similarly be used during calls + to `slib:load' and `require'. + + In order to disable all line-numbering, it is sufficient to set! + `*load-reader*' and `*slib-load-reader*' to #f. + + +File: scm.info, Node: Soft Ports, Next: Syntax Extensions, Prev: Line Numbers, 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: + + If it is necessary to explicitly close the port when it is garbage + collected, (*note add-finalizer: Interrupts.). + + (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: qase key clause1 clause2 ... + `qase' is an extension of standard Scheme `case': Each CLAUSE of a + `qase' 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 `qase' 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 `qase' clause during macro + expansion. `defconst' constants should be defined before use. + `qase' can be substituted for any correct use of `case'. + + (defconst unit '1) + (defconst semivowels '(w y)) + (qase (* 2 3) + ((2 3 5 7) 'prime) + ((,unit 4 6 8 9) 'composite)) ==> composite + (qase (car '(c d)) + ((a) 'a) + ((b) 'b)) ==> _unspecified_ + (qase (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. + +SCM `defmacro' is extended over that described for SLIB: + + (defmacro (macro-name . arguments) body) + +is equivalent to + + (defmacro macro-name arguments body) + +As in Common Lisp, an element of the formal argument list for +`defmacro' may be a possibly nested list, in which case the +corresponding actual argument must be a list with as many members as the +formal argument. Rest arguments are indicated by improper lists, as in +Scheme. It is an error if the actual argument list does not have the +tree structure required by the formal argument list. + +For example: + + (defmacro (let1 ((name value)) . body) + `((lambda (,name) ,@body) ,value)) + + (let1 ((x (foo))) (print x) x) == ((lambda (x) (print x) x) (foo)) + + (let1 not legal syntax) error--> not "does not match" ((name value)) + +SCM supports [R5RS] `syntax-rules' macros *Note Macros: (r5rs)Macros. + +The pattern language is extended by the syntax `(... <obj>)', which is +identical to `<obj>' except that ellipses in `<obj>' are treated as +ordinary identifiers in a template, or as literals in a pattern. In +particular, `(... ...)' quotes the ellipsis token `...' in a pattern or +template. + +For example: + (define-syntax check-tree + (syntax-rules () + ((_ (?pattern (... ...)) ?obj) + (let loop ((obj ?obj)) + (or (null? obj) + (and (pair? obj) + (check-tree ?pattern (car obj)) + (loop (cdr obj)))))) + ((_ (?first . ?rest) ?obj) + (let ((obj ?obj)) + (and (pair? obj) + (check-tree ?first (car obj)) + (check-tree ?rest (cdr obj))))) + ((_ ?atom ?obj) #t))) + + (check-tree ((a b) ...) '((1 2) (3 4) (5 6))) => #t + + (check-tree ((a b) ...) '((1 2) (3 4) not-a-2list) => #f + +Note that although the ellipsis is matched as a literal token in the +defined macro it is not included in the literals list for +`syntax-rules'. + +The pattern language is also extended to support identifier macros. A +reference to an identifier macro keyword that is not the first +identifier in a form may expand into Scheme code, rather than raising a +"keyword as variable" error. The pattern for expansion of such a bare +macro keyword is a single identifier, as in other syntax rules the +identifier is ignored. + +For example: + (define-syntax eight + (syntax-rules () + (_ 8))) + + (+ 3 eight) => 11 + (eight) => ERROR + (set! eight 9) => ERROR + + +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 + - Function: procedure->identifier-macro + 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: + + (defsyntax trace + (procedure->macro + (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x)))))) + + (trace foo) == (set! foo (tracef foo 'foo)). + + `PROCEDURE->IDENTIFIER-MACRO' is similar to + `PROCEDURE->MEMOIZING-MACRO' except that PROC is also called in + case the symbol bound to the macro appears in an expression but + _not_ as the first symbol, that is, when it looks like a variable + reference. In that case, the form passed to PROC is a single + identifier. + + + - Special Form: defsyntax name expr + Defines NAME as a macro keyword bound to the result of evaluating + EXPR, which should be a macro. Using `define' for this purpose + may not result in NAME being interpreted as a macro keyword. + +An "environment" is a list of frames representing lexical bindings. +Only the names and scope of the bindings are included in environments +passed to macro expanders - run-time values are not included. + +There are several types of environment frames: + +`((lambda (variable1 ...) ...) value1 ...)' +`(let ((variable1 value1) (variable2 value2) ...) ...)' +`(letrec ((variable1 value1) ...) ...)' + result in a single enviroment frame: + + (variable1 variable2 ...) + +`(let ((variable1 value1)) ...)' +`(let* ((variable1 value1) ...) ...)' + result in an environment frame for each variable: + + variable1 variable2 ... + +`(let-syntax ((key1 macro1) (key2 macro2)) ...)' +`(letrec-syntax ((key1 value1) (key2 value2)) ...)' + Lexically bound macros result in environment frames consisting of + a marker and an alist of keywords and macro objects: + + (<env-syntax-marker> (key1 . value1) (key2 . value2)) + Currently <env-syntax-marker> is the integer 6. + +`line numbers' + Line numbers (*note Line Numbers::) may be included in the + environment as frame entries to indicate the line number on which + a function is defined. They are ignored for variable lookup. + + #<line 8> + +`miscellaneous' + Debugging information is stored in environments in a plist format: + Any exact integer stored as an environment frame may be followed + by any value. The two frame entries are ignored when doing + variable lookup. Load file names, procedure names, and closure + documentation strings are stored in this format. + + <env-filename-marker> "foo.scm" <env-procedure-name-marker> foo ... + + Currently <env-filename-marker> is the integer 1 and + <env-procedure-name-marker> the integer 2. + + - 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. + + +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 (except one produced by passing the first to +`renamed-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. + +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 either be a + lexical environment passed to a macro transformer during macro + expansion or the empty list. + + 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: + +* Dynamic Linking:: +* Dump:: Create Fast-Booting Executables +* Numeric:: Numeric Language Extensions +* Arrays:: As in APL +* Records:: Define new aggregate data types +* I/O-Extensions:: i/o-extensions +* Posix Extensions:: posix +* Unix Extensions:: non-posix unix +* Regular Expression Pattern Matching:: regex +* Line Editing:: edit-line +* Curses:: Screen Control +* Sockets:: Cruise the Net + +* Menu: + +* Xlib: (Xlibscm). X Window Graphics. +* Hobbit: (hobbit). Scheme-to-C Compiler. + + +File: scm.info, Node: Dynamic Linking, Next: Dump, Prev: Packages, 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; BOOT-TAIL will be set to this procedure, + causing it to 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 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. + + - Constant: $pi + - Constant: pi + The ratio of the circumference to the diameter of a circle. + +These procedures augment the standard capabilities in *Note Numerical +operations: (r5rs)Numerical operations. + + - Function: pi* z + `(* pi Z)' + + - Function: pi/ z + `(/ pi Z)' + + - 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: Records, 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 CREATE-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-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. + +SLIB now supports uniform arrys. The primary array creation procedure +is `create-array', detailed in *Note Arrays: (slib)Arrays. + +Unshared uniform character 0-based arrays of rank 1 (dimension) are +equivalent to (and can't be distinguished from) strings. + (create-array "" 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. + (create-array '#at() 3) => #*000 + == + #At(#f #f #f) => #*000 + == + #1At(#f #f #f) => #*000 + +PROTOTYPE arguments in the following procedures are interpreted +according to the table: + + prototype type display prefix + + () conventional vector #a + +64i complex (double precision) #ac64 + 64.0 double (double precision) #ar64 + 32.0 float (single precision) #ar32 + 32 unsigned integer (32-bit) #au32 + -32 signed integer (32-bit) #as32 + -16 signed integer (16-bit) #as16 + #\a char (string) #a\ + #t boolean (bit-vector) #at + +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, `'#As32(3 5 9)' +returns a uniform vector of signed integers. + + - Function: array? obj prototype + Returns `#t' if the OBJ is an array of type corresponding to + PROTOTYPE, and `#f' if not. + + - Function: array-prototype array + Returns an object that would produce an array of the same type as + ARRAY, if used as the PROTOTYPE for `list->uniform-array'. + + - Function: list->uniform-array rank 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: dimensions->uniform-array dims prototype fill + - Function: dimensions->uniform-array dims 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 + 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 + 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: Records, Next: I/O-Extensions, Prev: Arrays, Up: Packages + +Records +======= + +SCM provides user-definable datatypes with the same interface as SLIB, +see *Note Records: (slib)Records, with the following extension. + + - Function: record-printer-set! rtd printer + Causes records of type RTD to be printed in a user-specified + format. RTD must be a record type descriptor returned by + `make-record-type', PRINTER a procedure accepting three arguments: + the record to be printed, the port to print to, and a boolean + which is true if the record is being written on behalf of `write' + and false if for `display'. If PRINTER returns #f, the default + record printer will be called. + + A PRINTER value of #f means use the default printer. + + Only the default printer will be used when printing error messages. + + +File: scm.info, Node: I/O-Extensions, Next: Posix Extensions, Prev: Records, 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: try-create-file name modes perms + If the file with name NAME already exists, return `#f', otherwise + try to create and open the file like `try-open-file', *Note Files + and Ports::. If the optional integer argument PERMS is provided, + it is used as the permissions of the new file (modified by the + current umask). + + - 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" + "Init5d6.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: Unix Extensions, 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: broken-pipe port + If this function is defined at top level, it will be called when an + output pipe is closed from the other side (this is the condition + under which a SIGPIPE is sent). The already closed PORT will be + passed so that any necessary cleanup may be done. An error is not + signaled when output to a pipe fails in this way, but any further + output to the closed pipe will cause an error to be signaled. + + - 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: getlogin + Returns the (login) name of the user logged in on the controlling + terminal of the process, or #f if this information cannot be + determined. + + - 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 normally is the exit status of the child process, + including the exit value along with flags indicating whether a + coredump was generated or the child terminated as a result of a + signal. 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'. + + +File: scm.info, Node: Unix Extensions, Next: Regular Expression Pattern Matching, Prev: Posix Extensions, Up: Packages + +Unix Extensions +=============== + +If `'unix' is provided (by linking in `unix.o'), the following +functions are defined: + +These "privileged" 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 process 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: Unix 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_svect + uniform vector of short 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 +svect .........long length....G0100111 ........ short *words........... +fvect .........long length....G0101101 .........float *words........... +dvect .........long length....G0101111 ........double *words........... +cvect .........long length....G0110101 ........double *words........... + +contin .........long length....G0111101 .............*regs.............. +specfun ................xxxxxxxxG1111111 ...........SCM name............. +cclo ..short length..xxxxxx10G1111111 ...........SCM **elts........... + 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 `Init5d6.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, and 2 if it should be `write'n for an error + report. This function should return non-zero if it printed, + and zero otherwise (in which case a hexadecimal number will + be printed). + + `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 to 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::. `must_realloc' and `must_realloc_cell' must not be called +during initialization (non-zero errjmp_bad) - the initial allocations +must be large enough. + + - 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 "Init5d6_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, 0L, 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/Init5d6.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 + `Init5d6.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 `Init5d6.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 <1>: SCM 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. +* @copy-tree: Miscellaneous Procedures. +* @macroexpand1: Syntactic Hooks for Hygienic Macros. +* _exclusive: Files and Ports. +* _ionbf: Files and Ports. +* _tracked: Files and Ports. +* abort: Internal State. +* access: I/O-Extensions. +* acct: Unix Extensions. +* acons: Miscellaneous Procedures. +* acosh: Numeric. +* add-alias: Configure Module Catalog. +* add-finalizer: Interrupts. +* 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. +* boot-tail <1>: Dump. +* boot-tail: SCM Session. +* box: Curses Miscellany. +* broken-pipe: Posix Extensions. +* call-with-outputs: Files and Ports. +* CAR: Cells. +* 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-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. +* 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. +* defmacro: Syntax Extensions. +* defsyntax: Low Level Syntactic Hooks. +* 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. +* 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-hook: Interrupts. +* gc_mark: Marking Cells. +* GCCDR: Marking Cells. +* GCTYP16: Marking Cells. +* gentemp: Syntax Extensions. +* 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. +* getlogin: Posix Extensions. +* 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. +* integer->line-number: Line Numbers. +* 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. +* line-number->integer: Line Numbers. +* line-number?: Line Numbers. +* link: Posix Extensions. +* list->uniform-array: 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: Unix Extensions. +* macroexpand: Syntax Extensions. +* macroexpand-1: Syntax 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-exchanger: Process Synchronization. +* make-shared-array: Conventional Arrays. +* make-soft-port: Soft Ports. +* make-stream-socket: Socket. +* make-stream-socketpair: Socket. +* 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: Unix 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: Unix 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-output-pipe: Posix Extensions. +* open-pipe: Posix Extensions. +* open-ports: Files and Ports. +* 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. +* pi*: Numeric. +* pi/: Numeric. +* pipe: Posix Extensions. +* port-closed?: Files and Ports. +* port-column: Miscellaneous Procedures. +* port-filename: Miscellaneous Procedures. +* port-line: Miscellaneous Procedures. +* port-type: Files and Ports. +* PORTP: Ptob Cells. +* print <1>: Miscellaneous Procedures. +* print: Debugging Scheme Code. +* print-args: Debugging Scheme Code. +* procedure->identifier-macro: Low Level Syntactic Hooks. +* 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. +* qase: Syntax Extensions. +* quit: SCM Session. +* raw: Terminal Mode Setting. +* read-char <1>: Input. +* read-char: Files and Ports. +* read-numbered: Line Numbers. +* read:sharp: Low Level Syntactic Hooks. +* read:sharp-char: Low Level Syntactic Hooks. +* readdir: I/O-Extensions. +* readlink: Unix Extensions. +* record-printer-set!: Records. +* 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: Unix Extensions. +* sync: Unix Extensions. +* syntax-quote: Syntactic Hooks for Hygienic Macros. +* syntax-rules: Syntax Extensions. +* 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-create-file: I/O-Extensions. +* try-load <1>: Line Numbers. +* 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. +* 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: + +* $pi: Numeric. +* *argv*: SCM Variables. +* *execpath: Embedding SCM. +* *interactive* <1>: Internal State. +* *interactive*: SCM Variables. +* *load-pathname*: Miscellaneous Procedures. +* *load-reader*: Line Numbers. +* *scm-version*: Internal State. +* *slib-load-reader*: Line Numbers. +* *syntax-rules*: SCM Variables. +* 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. +* pi: Numeric. +* 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_svect: Header 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. +* ecache: Memory Management for Environments. +* edit-line: Build Options. +* Embedding SCM: Embedding SCM. +* engineering-notation: Build Options. +* environments: Memory Management for Environments. +* exchanger: Process Synchronization. +* Exrename: Bibliography. +* Extending Scm: Compiling and Linking Custom Files. +* foo.c: Compiling and Linking Custom Files. +* generalized-c-arguments: Build Options. +* graphics: Packages. +* hobbit: Packages. +* i/o-extensions: Build Options. +* IEEE: Bibliography. +* inexact: Build Options. +* JACAL: Bibliography. +* lit: Build Options. +* macro: Build Options. +* memory management: Memory Management for Environments. +* mysql: Build Options. +* no-heap-shrink: Build Options. +* NO_ENV_CACHE: Memory Management for Environments. +* none: Build Options. +* posix: Build Options. +* R4RS: Bibliography. +* R5RS: Bibliography. +* reckless: Build Options. +* record: Build Options. +* regex: Build Options. +* rev2-procedures: Build Options. +* SchemePrimer: Bibliography. +* 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: Packages. +* x <1>: Packages. +* x: Build Options. +* xlib: Packages. +* Xlib: Packages. +* xlib: Build Options. +* xlibscm: Packages. +* Xlibscm: Packages. + + + +Tag Table: +Node: Top203 +Node: Overview1426 +Node: SCM Features1737 +Node: SCM Authors3749 +Node: Copying4645 +Node: Bibliography7730 +Node: Installing SCM9598 +Node: Making SCM10113 +Node: SLIB11030 +Node: Building SCM12945 +Node: Invoking Build13519 +Node: Build Options15793 +Node: Compiling and Linking Custom Files27939 +Node: Installing Dynamic Linking29902 +Node: Configure Module Catalog31686 +Node: Saving Images33683 +Node: Automatic C Preprocessor Definitions34358 +Node: Problems Compiling37629 +Node: Problems Linking39282 +Node: Problems Running39547 +Node: Testing41622 +Node: Reporting Problems44659 +Node: Operational Features45504 +Node: Invoking SCM45868 +Node: SCM Options47473 +Node: Invocation Examples51745 +Node: SCM Variables52697 +Node: SCM Session54127 +Node: Editing Scheme Code55465 +Node: Debugging Scheme Code57608 +Node: Errors61231 +Node: Memoized Expressions65459 +Node: Internal State67815 +Node: Scripting70895 +Node: Unix Scheme Scripts71189 +Node: MS-DOS Compatible Scripts74401 +Node: Unix Shell Scripts76213 +Node: The Language78403 +Node: Standards Compliance78995 +Node: Miscellaneous Procedures81409 +Node: Time84509 +Node: Interrupts85503 +Node: Process Synchronization90581 +Node: Files and Ports92118 +Node: Line Numbers97992 +Node: Soft Ports100234 +Node: Syntax Extensions102032 +Node: Low Level Syntactic Hooks111007 +Node: Syntactic Hooks for Hygienic Macros116212 +Node: Packages123186 +Node: Dynamic Linking123988 +Node: Dump128597 +Node: Numeric132606 +Node: Arrays134333 +Node: Conventional Arrays134543 +Node: Array Mapping141171 +Node: Uniform Array143397 +Node: Bit Vectors148645 +Node: Records149910 +Node: I/O-Extensions150773 +Node: Posix Extensions159362 +Node: Unix Extensions169048 +Node: Regular Expression Pattern Matching170950 +Node: Line Editing174904 +Node: Curses176250 +Node: Output Options Setting177173 +Node: Terminal Mode Setting179822 +Node: Window Manipulation182900 +Node: Output186360 +Node: Input189986 +Node: Curses Miscellany191013 +Node: Sockets192437 +Node: Host Data192761 +Node: Internet Addresses and Socket Names195909 +Node: Socket197443 +Node: The Implementation204680 +Node: Data Types204939 +Node: Immediates205760 +Node: Cells210096 +Node: Header Cells212188 +Node: Subr Cells215229 +Node: Ptob Cells217447 +Node: Smob Cells218986 +Node: Data Type Representations222182 +Node: Operations226835 +Node: Garbage Collection227421 +Node: Marking Cells228042 +Node: Sweeping the Heap230144 +Node: Memory Management for Environments231089 +Node: Signals235646 +Node: C Macros237190 +Node: Changing Scm238313 +Node: Defining Subrs242572 +Node: Defining Smobs244449 +Node: Defining Ptobs247495 +Node: Allocating memory248672 +Node: Embedding SCM250985 +Node: Callbacks258587 +Node: Type Conversions260330 +Node: Continuations263886 +Node: Evaluation268100 +Node: Program Self-Knowledge273263 +Node: File-System Habitat273509 +Node: Executable Pathname277109 +Node: Script Support278713 +Node: Improvements To Make280031 +Node: Finishing Dynamic Linking282063 +Node: Index289809 + +End Tag Table |