diff options
| author | Steve Langasek <vorlon@debian.org> | 2004-12-07 23:23:48 -0800 |
|---|---|---|
| committer | Bryan Newbold <bnewbold@robocracy.org> | 2017-02-20 00:05:28 -0800 |
| commit | 37f2f5e0bb11a18deecf48c7ad6bcbf7bd932db2 (patch) | |
| tree | 692caebb60ec5f80ce528a403b69351ca756d530 /scm5d6.info | |
| parent | e21d47d7813159bb71e0671df9b52ec0470c358d (diff) | |
| parent | c7d035ae1a729232579a0fe41ed5affa131d3623 (diff) | |
| download | scm-37f2f5e0bb11a18deecf48c7ad6bcbf7bd932db2.tar.gz scm-37f2f5e0bb11a18deecf48c7ad6bcbf7bd932db2.zip | |
Import Debian changes 5d9-4.1debian/5d9-4.1
scm (5d9-4.1) unstable; urgency=high
* Non-maintainer upload.
* High-urgency upload for sarge-targetted RC bugfix.
* Revert upstream "CAUTIOUS" define, which causes the scm build to
fail its test suite on alpha (and, it appears, powerpc as well).
Closes: #245810.
scm (5d9-4) unstable; urgency=low
* Apply patch from 144062 to fix hppa build (Closes: #144062)
* Change scm.1 section from Jan 4 200 to 1. (lintian)
scm (5d9-3) unstable; urgency=low
* Properly clean up info files.
* Make and install Xlibscm.info.
scm (5d9-2) unstable; urgency=low
* Fix path problem in slibcat. Hack at mklibcat.scm. (Closes: #241510)
scm (5d9-1) unstable; urgency=low
* New upstream release
* Merge NMU sparc changes (Closes: #191171, #191356)
* SHORT_INT is defined for ia64 upstream (Closes: #141928)
* Scheme imps now grouped in info file (has been for a while)
(Closes: #115452)
Diffstat (limited to 'scm5d6.info')
| -rw-r--r-- | scm5d6.info | 8382 |
1 files changed, 0 insertions, 8382 deletions
diff --git a/scm5d6.info b/scm5d6.info deleted file mode 100644 index 7dbf40d..0000000 --- a/scm5d6.info +++ /dev/null @@ -1,8382 +0,0 @@ -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 |